Documentation
¶
Overview ¶
Package plugins implements VORTEX's WebAssembly plugin system (build plan M6): a sandboxed wazero runtime, a request/response hook chain, WASM-backed hooks, and a plugin registry. Plugins run with no filesystem or network access and a bounded memory and CPU-time budget, so untrusted modules cannot escape the sandbox. wazero is pure Go (no CGO).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrPluginNotFound = errors.New("plugins: plugin not found")
ErrPluginNotFound indicates the named plugin is not installed in the registry. Callers can distinguish "not installed" (skippable) from other errors such as a corrupt manifest or unreadable file via errors.Is.
Functions ¶
This section is empty.
Types ¶
type Hook ¶
type Hook interface {
Name() string
Type() HookType
Execute(ctx context.Context, in HookInput) (HookOutput, error)
}
Hook is a single request/response interceptor.
type HookChain ¶
type HookChain struct {
// contains filtered or unexported fields
}
HookChain runs a set of hooks in sequence. When priority ordering is enabled, hooks run in ascending priority order; otherwise in registration order. It is safe for concurrent registration and execution.
func NewHookChain ¶
NewHookChain creates a HookChain. With priority=true hooks execute in priority order (lowest first); otherwise in registration order.
func (*HookChain) Execute ¶
Execute runs the chain against in. It stops and returns a deny as soon as any hook returns Allow=false. Header modifications from all executed hooks are merged into the result; the first non-zero Status override wins. The final output's Allow is true only if every hook allowed.
type HookInput ¶
type HookInput struct {
Type HookType `json:"type"`
Method string `json:"method"`
Path string `json:"path"`
Headers map[string][]string `json:"headers"`
Body []byte `json:"body"` // first 64KB only
Remote string `json:"remote"`
Route string `json:"route"`
}
HookInput is the data passed to a hook for one event.
type HookOutput ¶
type HookOutput struct {
Allow bool `json:"allow"`
Modified bool `json:"modified"`
Headers map[string][]string `json:"headers"` // headers to add/override
Status int `json:"status"` // override status; 0 = no override
}
HookOutput is a hook's decision and modifications.
type HookType ¶
type HookType string
HookType identifies when in the request lifecycle a hook fires.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is a loaded, instantiated WASM module ready to invoke.
type PluginManifest ¶
type PluginManifest struct {
Name string `json:"name"`
Version string `json:"version"` // semver: MAJOR.MINOR.PATCH
Description string `json:"description"`
HookTypes []HookType `json:"hook_types"`
Checksum string `json:"checksum"` // SHA-256 hex of the WASM bytes
Signature string `json:"signature"` // ed25519 signature (future use)
}
PluginManifest describes an installed plugin.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry stores installed plugins on disk under storePath, laid out as <name>/<version>/{plugin.wasm,manifest.json}.
func NewRegistry ¶
NewRegistry opens (creating if needed) a plugin store at storePath.
func (*Registry) Get ¶
func (r *Registry) Get(name, version string) ([]byte, *PluginManifest, error)
Get loads the WASM bytes and manifest for name@version. The special version "latest" resolves to the highest installed semver.
func (*Registry) Install ¶
func (r *Registry) Install(manifest PluginManifest, wasm []byte) error
Install validates the manifest checksum against wasm and stores both. A mismatched checksum is rejected.
func (*Registry) List ¶
func (r *Registry) List() []PluginManifest
List returns the manifests of all installed plugin versions.
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime is a sandboxed wazero runtime hosting compiled plugins. It is safe for concurrent use.
func NewRuntime ¶
func NewRuntime(ctx context.Context, cfg RuntimeConfig) (*Runtime, error)
NewRuntime creates a sandboxed runtime. Memory is capped per cfg (default 64 MB) and module execution is interruptible so a per-call context deadline can terminate runaway plugins.
type RuntimeConfig ¶
type RuntimeConfig struct {
MaxMemoryMB int // per-plugin memory cap; default 64 MB
MaxCPUTime time.Duration // per-call CPU-time budget; default 100ms
}
RuntimeConfig bounds plugin resource use.
type WASMHook ¶
type WASMHook struct {
// contains filtered or unexported fields
}
WASMHook is a Hook backed by a WebAssembly module loaded into the sandboxed runtime. The module must export:
memory — linear memory
alloc(size i32) i32 — allocate `size` bytes, return the pointer
handle(ptr i32, len i32) i64 — process the JSON HookInput at [ptr,len) and
return a packed result: (outPtr<<32)|outLen,
pointing at a JSON HookOutput in memory.
Input is the JSON-encoded HookInput; output is the JSON-encoded HookOutput.
func NewWASMHook ¶
NewWASMHook loads wasm into runtime under name and returns a Hook of the given type. The module is validated to export the required functions.
Source Files