plugin

Documentation

Index

• Constants
• Variables
• func FormatSQLValue(v interface{}) string
• func IsNullValue(value *structpb.Value) bool
• func MakeTestBlob(vals map[string]string) string
• func NewValueMap(values map[string]interface{}) (map[string]*structpb.Value, error)
• func SQLArgFromValue(value *structpb.Value) (interface{}, error)
• func ServeCLI(s pluginpb.PluginServiceServer)
• func ValidateManifest(manifest Manifest, expectedID string) error
• type AuthField
• type AuthForm
• type AuthFormsRequest
• type AuthFormsResponse
• type Column
• type ColumnSchema
• type CredentialBlob
  • func ParseCredentialBlob(connection map[string]string) (CredentialBlob, error)
• type DescribeSchemaRequest
• type DescribeSchemaResponse
• type DocumentResult
• type DriverType
• type ExecRequest
• type ExecResponse
• type ExecResult
• type FieldInfo
• type GetCompletionFieldsRequest
• type GetCompletionFieldsResponse
• type IndexSchema
• type InfoResponse
• type KeyValueResult
• type Limits
• type Manifest
• type MutateRowRequest
• type MutateRowResponse
• type OperationType
• type PermissionDecl
• type ResourceAction
• type ResourceField
• type ResourceGraphProvider
• type ResourceGraphRequest
• type ResourceGraphResponse
• type ResourceNode
• type Row
• type RuntimeSpec
• type SqlResult
• type TableSchema
• type TestConnectionRequest
• type TestConnectionResponse

Constants

const (
	ManifestFileSuffix = ".manifest.json"

	RuntimeKindLocal = "local"
)

const (
	TypeDriver DriverType = pluginpb.PluginV1_DRIVER

	AuthFieldText     = pluginpb.PluginV1_AuthField_TEXT
	AuthFieldNumber   = pluginpb.PluginV1_AuthField_NUMBER
	AuthFieldPassword = pluginpb.PluginV1_AuthField_PASSWORD
	AuthFieldSelect   = pluginpb.PluginV1_AuthField_SELECT
	AuthFieldCheckbox = pluginpb.PluginV1_AuthField_CHECKBOX
	AuthFieldFilePath = pluginpb.PluginV1_AuthField_FILE_PATH
)

const (
	ResourceActionSelect         = "select"
	ResourceActionDescribe       = "describe"
	ResourceActionCreateDatabase = "create-database"
	ResourceActionDropDatabase   = "drop-database"
	ResourceActionCreateTable    = "create-table"
	ResourceActionDropTable      = "drop-table"

	ResourceKindDatabase   = "database"
	ResourceKindTable      = "table"
	ResourceKindColumn     = "column"
	ResourceKindSchema     = "schema"
	ResourceKindView       = "view"
	ResourceKindAction     = "action"
	ResourceKindCollection = "collection"
	ResourceKindKey        = "key"
	ResourceKindGroup      = "group"
)

Variables

var SupportedCapabilitiesV1 = map[string]struct{}{
	"connection.test":   {},
	"query.execute":     {},
	"query.explain":     {},
	"resource.graph":    {},
	"row.mutate":        {},
	"row.mutate.delete": {},
	"row.mutate.edit":   {},
	"schema.inspect":    {},
	"stream.read":       {},
}

Functions

func FormatSQLValue

func FormatSQLValue(v interface{}) string

result-specific helpers. Exported for plugin authors and tests. FormatSQLValue translates a value returned by `database/sql` Row.Scan into a human-readable string suitable for presenting in the host UI. The built-in drivers often return []byte for text columns, so we convert those to strings rather than letting fmt.Sprintf render them as numeric byte slices. A nil value becomes the empty string.

func IsNullValue

func IsNullValue(value *structpb.Value) bool

func MakeTestBlob

func MakeTestBlob(vals map[string]string) string

MakeTestBlob returns a JSON-encoded credential blob string from the given key-value pairs. It is intended only for use in tests.

func NewValueMap

func NewValueMap(values map[string]interface{}) (map[string]*structpb.Value, error)

NewValueMap converts general JSON-like values from the app boundary into protobuf Value messages for plugin transport.

func SQLArgFromValue

func SQLArgFromValue(value *structpb.Value) (interface{}, error)

SQLArgFromValue converts a protobuf Value into a database/sql argument. JSON containers are encoded as compact JSON strings because SQL drivers bind scalar values, not arbitrary Go maps/slices.

func ServeCLI

func ServeCLI(s pluginpb.PluginServiceServer)

ServeCLI runs a protobuf-based service implementation over stdin/stdout. Plugins written in any language can implement the service; the helper simply invokes the corresponding RPC-style methods on the provided server object.

Supported commands are identical to the previous Go-only helper but now use protojson for marshalling so communication is language-agnostic.

func ValidateManifest

func ValidateManifest(manifest Manifest, expectedID string) error

Types

type AuthField

type AuthField = pluginpb.PluginV1_AuthField

Aliases for the new AuthForms protobuf messages

type AuthForm

type AuthForm = pluginpb.PluginV1_AuthForm

type AuthFormsRequest

type AuthFormsRequest = pluginpb.PluginV1_AuthFormsRequest

type AuthFormsResponse

type AuthFormsResponse = pluginpb.PluginV1_AuthFormsResponse

type Column

type Column = pluginpb.PluginV1_Column

type ColumnSchema

type ColumnSchema = pluginpb.PluginV1_ColumnSchema

type CredentialBlob

type CredentialBlob struct {
	Form   string            `json:"form"`
	Values map[string]string `json:"values"`
}

CredentialBlob represents the JSON structure stored under the "credential_blob" key in the connection map. All plugins that accept form-based authentication share this shape.

func ParseCredentialBlob

func ParseCredentialBlob(connection map[string]string) (CredentialBlob, error)

ParseCredentialBlob extracts and decodes the "credential_blob" entry from a connection map. Returns an error if the key is missing/empty or the JSON is malformed.

type DescribeSchemaRequest

type DescribeSchemaRequest = pluginpb.PluginV1_DescribeSchemaRequest

Schema descriptions – returned by the DescribeSchema RPC.

type DescribeSchemaResponse

type DescribeSchemaResponse = pluginpb.PluginV1_DescribeSchemaResponse

type DocumentResult

type DocumentResult = pluginpb.PluginV1_DocumentResult

type DriverType

type DriverType = pluginpb.PluginV1_Type

DriverType reuse from protobuf enum

type ExecRequest

type ExecRequest = pluginpb.PluginV1_ExecRequest

type ExecResponse

type ExecResponse = pluginpb.PluginV1_ExecResponse

ExecResponse now contains a typed ExecResult which can represent SQL rows, document lists, or key/value maps. Plugins should return one of those payloads rather than a flat string.

type ExecResult

type ExecResult = pluginpb.PluginV1_ExecResult

type FieldInfo

type FieldInfo = pluginpb.PluginV1_FieldInfo

type GetCompletionFieldsRequest

type GetCompletionFieldsRequest = pluginpb.PluginV1_GetCompletionFieldsRequest

Type aliases for the GetCompletionFields protobuf messages so plugin authors can import a single stable package (`pkg/plugin`) without referencing the generated rpc package directly.

type GetCompletionFieldsResponse

type GetCompletionFieldsResponse = pluginpb.PluginV1_GetCompletionFieldsResponse

type IndexSchema

type IndexSchema = pluginpb.PluginV1_IndexSchema

type InfoResponse

type InfoResponse = pluginpb.PluginV1_InfoResponse

Reuse proto-derived types (aliases) so plugin authors import a single stable package (`github.com/felixdotgo/querybox/rpc/contracts/plugin/v1`) if they prefer. These aliases keep the existing `pkg/plugin` API stable while aligning it with the .proto.

type KeyValueResult

type KeyValueResult = pluginpb.PluginV1_KeyValueResult

type Limits

type Limits struct {
	TimeoutSeconds int      `json:"timeout_seconds,omitempty"`
	MaxOutputBytes int      `json:"max_output_bytes,omitempty"`
	WorkingDir     string   `json:"working_dir,omitempty"`
	EnvAllowlist   []string `json:"env_allowlist,omitempty"`
}

type Manifest

type Manifest struct {
	ID           string            `json:"id"`
	Type         int               `json:"type"`
	Name         string            `json:"name,omitempty"`
	Description  string            `json:"description,omitempty"`
	Version      string            `json:"version"`
	URL          string            `json:"url,omitempty"`
	Author       string            `json:"author,omitempty"`
	Runtime      RuntimeSpec       `json:"runtime"`
	Capabilities []string          `json:"capabilities"`
	Permissions  []PermissionDecl  `json:"permissions,omitempty"`
	Limits       Limits            `json:"limits"`
	Tags         []string          `json:"tags,omitempty"`
	License      string            `json:"license,omitempty"`
	IconURL      string            `json:"icon_url,omitempty"`
	Contact      string            `json:"contact,omitempty"`
	Metadata     map[string]string `json:"metadata,omitempty"`
	Settings     map[string]string `json:"settings,omitempty"`
}

type MutateRowRequest

type MutateRowRequest = pluginpb.PluginV1_MutateRowRequest

MutateRow aliases – request, response, and operation enum. These mirror the protobuf definitions and are provided for convenience so plugin authors can reference them from the stable `pkg/plugin` import path without directly depending on the generated package.

OperationType corresponds to the MutateRowRequest.OperationType enum.

type MutateRowResponse

type MutateRowResponse = pluginpb.PluginV1_MutateRowResponse

type OperationType

type OperationType = pluginpb.PluginV1_MutateRowRequest_OperationType

type PermissionDecl

type PermissionDecl struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`
}

type ResourceAction

type ResourceAction struct {
	ID       string            `json:"id,omitempty"`
	Kind     string            `json:"kind,omitempty"`
	Title    string            `json:"title,omitempty"`
	Query    string            `json:"query,omitempty"`
	NewTab   bool              `json:"new_tab,omitempty"`
	Fields   []*ResourceField  `json:"fields,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type ResourceField

type ResourceField struct {
	Name        string `json:"name,omitempty"`
	Label       string `json:"label,omitempty"`
	Placeholder string `json:"placeholder,omitempty"`
	Required    bool   `json:"required,omitempty"`
}

type ResourceGraphProvider

type ResourceGraphProvider interface {
	ResourceGraph(ctx context.Context, req *ResourceGraphRequest) (*ResourceGraphResponse, error)
}

ResourceGraphProvider is implemented by plugins that expose a generic browse tree via the resource-graph CLI command.

type ResourceGraphRequest

type ResourceGraphRequest struct {
	Connection map[string]string `json:"connection,omitempty"`
	ResourceID string            `json:"resource_id,omitempty"`
	Depth      int               `json:"depth,omitempty"`
}

type ResourceGraphResponse

type ResourceGraphResponse struct {
	Nodes []*ResourceNode `json:"nodes,omitempty"`
}

type ResourceNode

type ResourceNode struct {
	ID       string            `json:"id,omitempty"`
	Name     string            `json:"name,omitempty"`
	Kind     string            `json:"kind,omitempty"`
	Path     string            `json:"path,omitempty"`
	Actions  []*ResourceAction `json:"actions,omitempty"`
	Children []*ResourceNode   `json:"children,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type Row

type Row = pluginpb.PluginV1_Row

type RuntimeSpec

type RuntimeSpec struct {
	Kind       string   `json:"kind"`
	Entrypoint string   `json:"entrypoint,omitempty"`
	Args       []string `json:"args,omitempty"`
}

type SqlResult

type SqlResult = pluginpb.PluginV1_SqlResult

type TableSchema

type TableSchema = pluginpb.PluginV1_TableSchema

type TestConnectionRequest

type TestConnectionRequest = pluginpb.PluginV1_TestConnectionRequest

TestConnectionRequest / TestConnectionResponse are type aliases for the proto-package types defined in rpc/contracts/plugin/v1. When protoc regenerates plugin.pb.go these will resolve to the fully-registered proto structs; until then they resolve to the hand-maintained plain structs in plugin_test_connection.go in the same package.

type TestConnectionResponse

type TestConnectionResponse = pluginpb.PluginV1_TestConnectionResponse