plugin

Documentation

Index

• type ErrMissingCapability
  • func (e *ErrMissingCapability) Error() string
• type EventSink
• type FieldError
• type Loader
  • func NewLoader() *Loader
  • func (l *Loader) Close(ctx context.Context) error
  • func (l *Loader) Current() *Registry
  • func (l *Loader) LoadDir(ctx context.Context, dir string) (*Registry, error)
• type Plugin
• type PluginInfo
  • func (p PluginInfo) Snapshot() wire.PluginSchema
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Close() error
  • func (r *Registry) EventSchema(fqn string) *wire.EventSpec
  • func (r *Registry) InitAll(ctx context.Context, pluginConfigs map[string]map[string]any) error
  • func (r *Registry) Lookup(proto wire.Protocol) Plugin
  • func (r *Registry) Register(p Plugin) error
  • func (r *Registry) Snapshot() []wire.PluginSchema
• type TestInput
• type TestOutput
• type WASMPlugin
  • func (p *WASMPlugin) Close() error
  • func (p *WASMPlugin) Execute(ctx context.Context, input TestInput, emit EventSink) (*TestOutput, error)
  • func (p *WASMPlugin) Info() PluginInfo
  • func (p *WASMPlugin) Init(ctx context.Context, config map[string]any) error
  • func (p *WASMPlugin) Validate(input TestInput) []FieldError
• type WASMRuntime
  • func NewWASMRuntime(ctx context.Context) (*WASMRuntime, error)
  • func (w *WASMRuntime) Close(ctx context.Context) error
  • func (w *WASMRuntime) LoadPlugin(ctx context.Context, name string, wasmBytes []byte) (*WASMPlugin, error)

Types

type ErrMissingCapability

type ErrMissingCapability struct {
	Plugin     string
	Capability string
}

ErrMissingCapability is returned when a plugin declares a capability the engine does not provide.

func (*ErrMissingCapability) Error

func (e *ErrMissingCapability) Error() string

type EventSink

type EventSink func(wire.PluginEvent)

EventSink receives plugin events emitted during Execute. The runner provides a sink that fans events out to the engine's EventHandler and into the dataflow store so they can be referenced by later tests.

type FieldError

type FieldError struct {
	Field   string `json:"field"`
	Message string `json:"message"`
}

FieldError reports a validation problem on a specific manifest field.

type Loader

type Loader struct {
	// contains filtered or unexported fields
}

Loader manages plugin discovery and caching for an Engine.

The cache is keyed by (pluginDir, fileName, mtime). A second LoadDir() call for the same directory whose files have not changed reuses the existing runtime and Registry; otherwise the runtime is rebuilt.

func NewLoader

func NewLoader() *Loader

NewLoader returns an empty Loader.

func (*Loader) Close

func (l *Loader) Close(ctx context.Context) error

Close releases the cached registry and runtime, if any.

func (*Loader) Current

func (l *Loader) Current() *Registry

Current returns the most-recently loaded Registry, or nil if LoadDir has never been called. Used by Engine for introspection without requiring a context or pluginDir.

func (*Loader) LoadDir

func (l *Loader) LoadDir(ctx context.Context, dir string) (*Registry, error)

LoadDir scans dir for *.wasm files, instantiates each plugin, and returns the populated Registry. If dir is unchanged since the previous call, the cached Registry is reused.

dir == "" returns an empty Registry without scanning. Missing directory returns an error.

type Plugin

type Plugin interface {
	Info() PluginInfo
	Init(ctx context.Context, config map[string]any) error
	Validate(input TestInput) []FieldError
	Execute(ctx context.Context, input TestInput, emit EventSink) (*TestOutput, error)
	Close() error
}

Plugin is the host-side view of a loaded plugin. Implementations include the wazero-backed WASM adapter (wasm.go) and in-process fakes used in tests.

type PluginInfo

type PluginInfo struct {
	Name         string                    `json:"name"`
	Version      string                    `json:"version"`
	Description  string                    `json:"description"`
	Protocols    []wire.Protocol           `json:"protocols"`
	Capabilities []string                  `json:"capabilities,omitempty"`
	Fields       map[string]wire.FieldSpec `json:"fields,omitempty"`
	Events       map[string]wire.EventSpec `json:"events,omitempty"`
}

PluginInfo mirrors the metadata a WASM plugin returns from plugin_info(). For built-in/fake plugins, the host constructs it directly.

func (PluginInfo) Snapshot

func (p PluginInfo) Snapshot() wire.PluginSchema

Snapshot converts a PluginInfo into the public introspection shape.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds loaded plugins indexed by protocol. A Registry is safe for concurrent reads after Register; mutating operations (Register, Close) take a write lock.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty Registry.

func (*Registry) Close

func (r *Registry) Close() error

Close shuts down every registered plugin and marks the registry closed. Returns the first error encountered; remaining plugins are still closed.

func (*Registry) EventSchema

func (r *Registry) EventSchema(fqn string) *wire.EventSpec

EventSchema looks up an event by fully-qualified name "<plugin>.<kind>". Returns nil if not found.

func (*Registry) InitAll

func (r *Registry) InitAll(ctx context.Context, pluginConfigs map[string]map[string]any) error

InitAll runs Init on every registered plugin with its config from pluginConfigs[name] (nil-safe lookup yields nil config).

func (*Registry) Lookup

func (r *Registry) Lookup(proto wire.Protocol) Plugin

Lookup returns the plugin for the given protocol, or nil if none.

func (*Registry) Register

func (r *Registry) Register(p Plugin) error

Register installs the plugin in the registry. The plugin's Info() is cached and indexed by name and by every protocol it claims.

Returns an error on duplicate name, duplicate protocol, or after Close.

func (*Registry) Snapshot

func (r *Registry) Snapshot() []wire.PluginSchema

Snapshot returns a stable, sorted slice of plugin metadata for introspection.

type TestInput

type TestInput struct {
	Method   string            `json:"method,omitempty"`
	Resource string            `json:"resource,omitempty"`
	Target   string            `json:"target"`
	Headers  map[string]string `json:"headers,omitempty"`
	Timeout  string            `json:"timeout,omitempty"`
	Fields   map[string]any    `json:"fields,omitempty"`
}

TestInput is what the host passes to Execute.

Method and Resource are core fields readable by every plugin (HTTP method, gRPC method-name, GraphQL operation, SQL query name, etc.). Plugin-specific data lives in Fields.

type TestOutput

type TestOutput struct {
	Status     any                `json:"status"`
	Headers    map[string]string  `json:"headers,omitempty"`
	Body       any                `json:"body,omitempty"`
	DurationMs int64              `json:"duration_ms"`
	Error      string             `json:"error,omitempty"`
	Metadata   map[string]any     `json:"metadata,omitempty"`
	Events     []wire.PluginEvent `json:"events,omitempty"`
}

TestOutput is what Execute returns.

Events carries plugin events accumulated during a single Execute call; streaming plugins also emit via EventSink during the call (both paths feed the same downstream sinks).

type WASMPlugin

type WASMPlugin struct {
	// contains filtered or unexported fields
}

WASMPlugin implements Plugin against a wazero-instantiated WASM module.

func (*WASMPlugin) Close

func (p *WASMPlugin) Close() error

Close releases the underlying module. The runtime is closed by WASMRuntime.

func (*WASMPlugin) Execute

func (p *WASMPlugin) Execute(ctx context.Context, input TestInput, emit EventSink) (*TestOutput, error)

Execute calls execute with the input. Events emitted via host_emit_event during the call are routed through emit; events embedded in the returned TestOutput are also forwarded for parity.

func (*WASMPlugin) Info

func (p *WASMPlugin) Info() PluginInfo

Info returns the cached PluginInfo from plugin_info.

func (*WASMPlugin) Init

func (p *WASMPlugin) Init(ctx context.Context, config map[string]any) error

Init calls plugin_init with the JSON-encoded config.

func (*WASMPlugin) Validate

func (p *WASMPlugin) Validate(input TestInput) []FieldError

Validate calls validate and decodes the result as []FieldError.

type WASMRuntime

type WASMRuntime struct {
	// contains filtered or unexported fields
}

WASMRuntime owns the wazero runtime and host module for one or more plugins. Multiple plugins share the same host module, instantiated once at runtime creation.

func NewWASMRuntime

func NewWASMRuntime(ctx context.Context) (*WASMRuntime, error)

NewWASMRuntime returns a runtime preloaded with WASI Preview 1 and the universal "apiqube" host module containing every supported host function.

func (*WASMRuntime) Close

func (w *WASMRuntime) Close(ctx context.Context) error

Close releases all plugins and the underlying runtime.

func (*WASMRuntime) LoadPlugin

func (w *WASMRuntime) LoadPlugin(ctx context.Context, name string, wasmBytes []byte) (*WASMPlugin, error)

LoadPlugin compiles and instantiates one .wasm module on this runtime. Capabilities declared by the plugin are validated against the engine's supported set; an unsupported capability returns *ErrMissingCapability.

Plugins are expected to be WASI reactor modules (e.g. TinyGo's `-buildmode=c-shared`) that export `_initialize` for runtime setup but do not call proc_exit. We try `_initialize` first; if absent, fall back to the default `_start` (command mode).