capabilities

Documentation

Overview

Package capabilities provides the host-side functions WASM plugins import to interact with the outside world.

All host functions live in a single import namespace ("apiqube") and are registered once per runtime. Plugins import only what they need; unused imports are inert. PluginInfo.Capabilities documents which logical capabilities a plugin uses, but the host module itself is not partitioned.

Sinks (logger, event handler, HTTP client) are passed per-call via context using WithSinks/sinksFrom. This keeps host-module instantiation a one-time cost per Engine while supporting concurrent Run() calls each with their own sinks.

Index

• Constants
• func EmitEventLogic(data []byte, sink func(wire.PluginEvent)) error
• func HTTPRequestLogic(ctx context.Context, client HTTPClient, reqJSON []byte) []byte
• func InstantiateHostModule(ctx context.Context, rt wazero.Runtime) error
• func IsSupported(name string) bool
• func SupportedCapabilities() []string
• func WithSinks(ctx context.Context, s *Sinks) context.Context
• type HTTPClient
• type HTTPRequest
• type HTTPResponse
• type LogLevel
  • func (l LogLevel) String() string
• type LogSink
• type LogSinkFunc
  • func (f LogSinkFunc) Log(l LogLevel, m string)
• type Sinks

Constants

const HostNamespace = "apiqube"

HostNamespace is the WASM import namespace used by all host functions. Plugins target it via //go:wasmimport "apiqube" host_X.

Functions

func EmitEventLogic

func EmitEventLogic(data []byte, sink func(wire.PluginEvent)) error

EmitEventLogic decodes a single event from JSON bytes and forwards it. Exposed for unit testing without a WASM module.

func HTTPRequestLogic

func HTTPRequestLogic(ctx context.Context, client HTTPClient, reqJSON []byte) []byte

HTTPRequestLogic performs the HTTP request described by reqJSON and returns the JSON bytes of the response. Pure function — no WASM dependency.

func InstantiateHostModule

func InstantiateHostModule(ctx context.Context, rt wazero.Runtime) error

InstantiateHostModule registers the universal host module on rt with every supported host function. Call once per runtime, before instantiating any plugin module.

func IsSupported

func IsSupported(name string) bool

IsSupported reports whether the named capability is implemented.

func SupportedCapabilities

func SupportedCapabilities() []string

SupportedCapabilities lists the logical capability names this build provides. The plugin loader uses this to validate PluginInfo.Capabilities before running a plugin.

func WithSinks

func WithSinks(ctx context.Context, s *Sinks) context.Context

WithSinks returns a context carrying the given Sinks. Capability functions read the sinks from this context value.

Types

type HTTPClient

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient is the abstraction host_http_request uses to perform HTTP calls. It is satisfied by *http.Client; tests inject fakes.

type HTTPRequest

type HTTPRequest struct {
	Method          string            `json:"method"`
	URL             string            `json:"url"`
	Headers         map[string]string `json:"headers,omitempty"`
	Body            []byte            `json:"body,omitempty"`
	TimeoutMs       int64             `json:"timeout_ms,omitempty"`
	FollowRedirects *bool             `json:"follow_redirects,omitempty"`
	MaxRedirects    int               `json:"max_redirects,omitempty"`
}

HTTPRequest is the wire-level shape host_http_request consumes.

type HTTPResponse

type HTTPResponse struct {
	Status     int               `json:"status"`
	Headers    map[string]string `json:"headers,omitempty"`
	Body       []byte            `json:"body,omitempty"`
	DurationMs int64             `json:"duration_ms"`
	Error      string            `json:"error,omitempty"`
}

HTTPResponse is the wire-level shape returned to the plugin.

type LogLevel

type LogLevel int

LogLevel classifies a host_log message.

const (
	LogDebug LogLevel = iota
	LogInfo
	LogWarn
	LogError
)

func (LogLevel) String

func (l LogLevel) String() string

String returns the canonical name for a log level.

type LogSink

type LogSink interface {
	Log(level LogLevel, message string)
}

LogSink receives log records emitted by plugins via host_log.

type LogSinkFunc

type LogSinkFunc func(LogLevel, string)

LogSinkFunc adapts a function to LogSink.

func (LogSinkFunc) Log

func (f LogSinkFunc) Log(l LogLevel, m string)

Log implements LogSink.

type Sinks

type Sinks struct {
	Logger LogSink
	Now    func() int64
	Events func(wire.PluginEvent)
	HTTP   HTTPClient
}

Sinks holds dynamic per-call dependencies a host function needs.