plugin

package
v0.2.23 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 28, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source
const (
	DefaultInvokeTimeoutMS   = 10_000
	DefaultInvokeStdoutBytes = 1 << 20
	DefaultInvokeStderrBytes = 1 << 20
	DefaultInvokeHostCalls   = 64

	HostMaxInvokeTimeoutMS   = 30_000
	HostMaxInvokeStdoutBytes = 8 << 20
	HostMaxInvokeStderrBytes = 1 << 20
	HostMaxInvokeHostCalls   = 64
)
View Source
const (
	HostMethodRPCCall        = "rpc.call"
	HostMethodHTTPDo         = "http.do"
	HostMethodHTTPOperatorDo = "http.operator.do"
	HostMethodKVGet          = "kv.get"
	HostMethodKVPut          = "kv.put"
	HostMethodNotifySend     = "notify.send"
	HostMethodLogWrite       = "log.write"
	HostMethodSecretGet      = "secret.get"
	HostMethodSecretPut      = "secret.put"
	HostMethodSecretDelete   = "secret.delete"
	// DefaultMaxHostResponsePayloadBytes is the maximum decoded
	// host_response.result payload.
	DefaultMaxHostResponsePayloadBytes = 4 << 20
	// DefaultMaxHostResponseBytes is the compatibility alias used by
	// HostClientOptions.MaxResponseBytes.
	DefaultMaxHostResponseBytes = DefaultMaxHostResponsePayloadBytes
	// DefaultMaxHostResponseFrameOverheadBytes independently bounds the
	// correlation envelope around a maximum result payload.
	DefaultMaxHostResponseFrameOverheadBytes = 4 << 10
	// DefaultMaxHostResponseFrameBytes excludes the JSONL delimiter.
	DefaultMaxHostResponseFrameBytes = DefaultMaxHostResponseBytes + DefaultMaxHostResponseFrameOverheadBytes
)
View Source
const (
	TypeSystem = "system"
	TypeWasm   = "wasm"
	TypeWorker = "worker"

	ManifestSchemaV2           = "lattice.plugin.manifest.v2"
	BundleFormatTarGzip        = "tar+gzip"
	RuntimeProtocolStdioJSONV1 = "stdio-json-v1"
	RuntimeProtocolStdioJSONV2 = "stdio-json-v2"
	UIRuntimeModeSandbox       = "sandbox"
	UIBridgeVersion1           = "1"

	InterfaceEffectRead  = "read"
	InterfaceEffectWrite = "write"
	InterfaceEffectPlan  = "plan"

	BackingRuntime = "runtime"
	BackingCore    = "core"
)
View Source
const (
	CapabilityAuditRead          = "audit:read"
	CapabilityHTTPEgress         = "http:egress"
	CapabilityHTTPOperatorTarget = "http:operator-target"
	CapabilityKVRead             = "kv:read"
	CapabilityKVWrite            = "kv:write"
	CapabilityLogWrite           = "log:write"
	CapabilityMonitorRead        = "monitor:read"
	CapabilityMonitorAdmin       = "monitor:admin"
	CapabilityNetguardRead       = "netguard:read"
	CapabilityNetguardAdmin      = "netguard:admin"
	CapabilityNetpolicyRead      = "netpolicy:read"
	CapabilityNetpolicyAdmin     = "netpolicy:admin"
	CapabilityNetworkApply       = "network:apply"
	CapabilityNetworkPlan        = "network:plan"
	CapabilityNodeRead           = "node:read"
	CapabilityNodeAdmin          = "node:admin"
	CapabilityNotifySend         = "notify:send"
	CapabilityRPCCall            = "rpc:call"
	CapabilityRPCExpose          = "rpc:expose"
	CapabilitySecretRead         = "secret:read"
	CapabilitySecretWrite        = "secret:write"
	CapabilityStaticRead         = "static:read"
	CapabilityStaticWrite        = "static:write"
	CapabilityTaskRead           = "task:read"
	CapabilityTaskRun            = "task:run"
	CapabilityTunnelAdmin        = "tunnel:admin"
	CapabilityWorkerRoute        = "worker:route"
	CapabilityDDNSAdmin          = "ddns:admin"
)
View Source
const (
	ActionDescribe = "describe"
	ActionHealth   = "health"
	ActionPlan     = "plan"
	ActionCall     = "call"
	ActionExecute  = "execute"

	DefaultMaxRequestBytes = 1 << 20
	FeatureStderrFramesV1  = "stderr_frames_v1"
)

Variables

View Source
var ErrHostClientExpired = errors.New("invocation host client expired")
View Source
var ErrHostUnavailable = errors.New("host response fd unavailable")
View Source
var ErrV2Protocol = fmt.Errorf("invalid stdio-json-v2 lifecycle")

Functions

func InvocationStderr added in v0.2.19

func InvocationStderr(ctx context.Context) io.Writer

InvocationStderr returns the invocation-scoped diagnostic stream. Writes are serialized as correlated v2 stderr_chunk frames and rejected after the handler returns. Raw os.Stderr is process-scoped only and the host continuously drains it into bounded counters without attribution or external disclosure; InvocationStderr is the only invocation diagnostic channel. Use stdio-json-v1 when process isolation is required.

func Serve

func Serve(ctx context.Context, handler Handler) error

func ValidateInvokeBudgetSpec

func ValidateInvokeBudgetSpec(b InvokeBudgetSpec) error

Types

type BundleSpec

type BundleSpec struct {
	Format       string `json:"format"`
	DigestSHA256 string `json:"digest_sha256"`
}

type CallPayload

type CallPayload struct {
	Service string          `json:"service"`
	Method  string          `json:"method"`
	Payload json.RawMessage `json:"payload,omitempty"`
}

type CompatibilitySpec

type CompatibilitySpec struct {
	Server          string `json:"server"`
	DashboardHost   string `json:"dashboard_host"`
	RuntimeProtocol string `json:"runtime_protocol"`
}

type HTTPRequest

type HTTPRequest struct {
	Method string
	URL    string
	Header map[string]string
	Body   []byte
}

type HTTPResponse

type HTTPResponse struct {
	StatusCode int
	Header     map[string]string
	Body       []byte
}

type Handler

type Handler interface {
	HandlePluginRequest(ctx context.Context, req Request, host *HostClient) Response
}

type HandlerFunc

type HandlerFunc func(ctx context.Context, req Request, host *HostClient) Response

func (HandlerFunc) HandlePluginRequest

func (f HandlerFunc) HandlePluginRequest(ctx context.Context, req Request, host *HostClient) Response

type HostAccessSpec

type HostAccessSpec struct {
	RPC []RPCDependency `json:"rpc,omitempty"`
}

type HostClient

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

func NewHostClient

func NewHostClient(opts HostClientOptions) *HostClient

func NewHostClientFromEnv

func NewHostClientFromEnv(output io.Writer) (*HostClient, func())

func NewInvocationHostClient added in v0.2.19

func NewInvocationHostClient(opts HostClientOptions, generation uint64, invocationID string) *HostClient

NewInvocationHostClient creates a lease-scoped facade. Expire it before the worker emits invoke_ready so late plugin calls cannot reach the host.

func (*HostClient) Abort added in v0.2.19

func (c *HostClient) Abort()

Abort revokes admission and poisons the shared response transport to unblock a stalled call. It is terminal; normal completion uses Expire.

func (*HostClient) Available

func (c *HostClient) Available() bool

func (*HostClient) Call

func (c *HostClient) Call(ctx context.Context, method string, params any) (json.RawMessage, error)

func (*HostClient) Expire added in v0.2.19

func (c *HostClient) Expire()

func (*HostClient) HTTPDo

func (c *HostClient) HTTPDo(ctx context.Context, req HTTPRequest) (HTTPResponse, error)

func (*HostClient) HTTPOperatorDo

func (c *HostClient) HTTPOperatorDo(ctx context.Context, req HTTPRequest) (HTTPResponse, error)

func (*HostClient) KVGet

func (c *HostClient) KVGet(ctx context.Context, key string) ([]byte, bool, error)

func (*HostClient) KVPut

func (c *HostClient) KVPut(ctx context.Context, key string, value []byte) error

func (*HostClient) LogWrite

func (c *HostClient) LogWrite(ctx context.Context, entry LogEntry) error

func (*HostClient) NotifySend

func (c *HostClient) NotifySend(ctx context.Context, title, body string) error

func (*HostClient) RPCCall

func (c *HostClient) RPCCall(ctx context.Context, service, method string, request any) (json.RawMessage, error)

func (*HostClient) RPCCallRaw

func (c *HostClient) RPCCallRaw(ctx context.Context, service, method string, request json.RawMessage) (json.RawMessage, error)

func (*HostClient) SecretDelete

func (c *HostClient) SecretDelete(ctx context.Context, key string) error

func (*HostClient) SecretGet

func (c *HostClient) SecretGet(ctx context.Context, key string) ([]byte, bool, error)

func (*HostClient) SecretGetString

func (c *HostClient) SecretGetString(ctx context.Context, key string) (string, bool, error)

func (*HostClient) SecretPut

func (c *HostClient) SecretPut(ctx context.Context, key string, value []byte) error

func (*HostClient) SecretPutString

func (c *HostClient) SecretPutString(ctx context.Context, key, value string) error

type HostClientOptions

type HostClientOptions struct {
	Output           io.Writer
	Responses        io.Reader
	MaxResponseBytes int
}

type InterfaceContract

type InterfaceContract struct {
	Service     string            `json:"service"`
	Methods     []string          `json:"-"`
	MethodSpecs []InterfaceMethod `json:"-"`
	Scopes      []string          `json:"scopes,omitempty"`
	Backing     string            `json:"backing,omitempty"`
	// contains filtered or unexported fields
}

func (InterfaceContract) EffectiveBacking

func (c InterfaceContract) EffectiveBacking() string

func (InterfaceContract) EffectiveMethodScopes

func (c InterfaceContract) EffectiveMethodScopes(name string) ([]string, bool)

func (InterfaceContract) MarshalJSON

func (c InterfaceContract) MarshalJSON() ([]byte, error)

func (InterfaceContract) MethodContract

func (c InterfaceContract) MethodContract(name string) (InterfaceMethod, bool)

func (InterfaceContract) MethodContracts

func (c InterfaceContract) MethodContracts() []InterfaceMethod

func (InterfaceContract) TypedMethods

func (c InterfaceContract) TypedMethods() bool

func (*InterfaceContract) UnmarshalJSON

func (c *InterfaceContract) UnmarshalJSON(data []byte) error

type InterfaceMethod

type InterfaceMethod struct {
	Name                 string            `json:"name"`
	Effect               string            `json:"effect"`
	Scopes               []string          `json:"scopes,omitempty"`
	OperatorTargetFields []string          `json:"operator_target_fields,omitempty"`
	Budget               *InvokeBudgetSpec `json:"budget,omitempty"`
}

type InvokeBudgetSpec

type InvokeBudgetSpec struct {
	TimeoutMS   int `json:"timeout_ms"`
	StdoutBytes int `json:"stdout_bytes"`
	StderrBytes int `json:"stderr_bytes"`
	HostCalls   int `json:"host_calls"`
}

InvokeBudgetSpec is signed method-level runtime data. Absent budgets stay additive on the host and resolve to the old global defaults.

func DefaultInvokeBudgetSpec

func DefaultInvokeBudgetSpec() InvokeBudgetSpec

func (InvokeBudgetSpec) MarshalJSON

func (b InvokeBudgetSpec) MarshalJSON() ([]byte, error)

func (*InvokeBudgetSpec) UnmarshalJSON

func (b *InvokeBudgetSpec) UnmarshalJSON(data []byte) error

type LogEntry

type LogEntry struct {
	Level   string            `json:"level"`
	Message string            `json:"message"`
	Fields  map[string]string `json:"fields,omitempty"`
}

type Manifest

type Manifest struct {
	Schema           string              `json:"schema,omitempty"`
	ID               string              `json:"id"`
	Name             string              `json:"name"`
	Type             string              `json:"type"`
	Capabilities     []string            `json:"capabilities"`
	Version          string              `json:"version,omitempty"`
	Entrypoint       string              `json:"entrypoint,omitempty"`
	Publisher        string              `json:"publisher,omitempty"`
	DigestSHA256     string              `json:"digest_sha256,omitempty"`
	SignatureEd25519 string              `json:"signature_ed25519,omitempty"`
	Bundle           *BundleSpec         `json:"bundle,omitempty"`
	Runtime          *RuntimeSpec        `json:"runtime,omitempty"`
	UIRuntime        *UIRuntimeSpec      `json:"ui_runtime,omitempty"`
	Compatibility    *CompatibilitySpec  `json:"compatibility,omitempty"`
	MinServer        string              `json:"min_server,omitempty"`
	HostAccess       *HostAccessSpec     `json:"host_access,omitempty"`
	UI               *ManifestUI         `json:"ui,omitempty"`
	Interfaces       []InterfaceContract `json:"interfaces,omitempty"`
}

func DecodeManifest

func DecodeManifest(data []byte) (Manifest, error)

func (Manifest) InterfaceFor

func (m Manifest) InterfaceFor(service string) (InterfaceContract, bool)

type ManifestUI

type ManifestUI struct {
	Nav   []NavContribution  `json:"nav,omitempty"`
	Views []ViewContribution `json:"views,omitempty"`
}
type NavContribution struct {
	Section      string   `json:"section"`
	SectionTitle string   `json:"section_title,omitempty"`
	Title        string   `json:"title"`
	Route        string   `json:"route"`
	Icon         string   `json:"icon,omitempty"`
	Scopes       []string `json:"scopes,omitempty"`
}

type RPCDependency

type RPCDependency struct {
	Service string   `json:"service"`
	Methods []string `json:"methods"`
}

type Request

type Request struct {
	Action  string          `json:"action"`
	Service string          `json:"service,omitempty"`
	Method  string          `json:"method,omitempty"`
	Payload json.RawMessage `json:"payload,omitempty"`
}

func (Request) CallPayload

func (r Request) CallPayload() (CallPayload, error)

type ResolvedInvokeBudget

type ResolvedInvokeBudget struct {
	Timeout     time.Duration
	StdoutBytes int
	StderrBytes int
	HostCalls   int
	Declared    bool
}

func ResolveInvokeBudget

func ResolveInvokeBudget(spec *InvokeBudgetSpec, defaults InvokeBudgetSpec) ResolvedInvokeBudget

type Response

type Response struct {
	OK       bool            `json:"ok"`
	Plan     string          `json:"plan,omitempty"`
	Message  string          `json:"message,omitempty"`
	Result   json.RawMessage `json:"result,omitempty"`
	Error    string          `json:"error,omitempty"`
	Warnings []string        `json:"warnings,omitempty"`
}

func ErrorResponse

func ErrorResponse(err error) Response

func MessageResponse

func MessageResponse(message string) Response

func PlanResponse

func PlanResponse(plan, message string) Response

func RawResultResponse

func RawResultResponse(result json.RawMessage, message string) Response

func ResultResponse

func ResultResponse(result any, message string) Response

type Runtime

type Runtime struct {
	In              io.Reader
	Out             io.Writer
	Host            *HostClient
	MaxRequestBytes int
	// contains filtered or unexported fields
}

func NewRuntime

func NewRuntime(opts RuntimeOptions) *Runtime

func (*Runtime) Close

func (rt *Runtime) Close()

func (*Runtime) Serve

func (rt *Runtime) Serve(ctx context.Context, handler Handler) error

func (*Runtime) ServeV2 added in v0.2.19

func (rt *Runtime) ServeV2(ctx context.Context, handler Handler, generation uint64) error

ServeV2 processes correlated pooled-worker frames. It never accepts v1 request envelopes, allowing hosts to select v2 explicitly without a silent downgrade.

func (*Runtime) WriteResponse

func (rt *Runtime) WriteResponse(resp Response) error

type RuntimeOptions

type RuntimeOptions struct {
	In              io.Reader
	Out             io.Writer
	Host            *HostClient
	MaxRequestBytes int
	OpenHostFromEnv bool
}

type RuntimeSpec

type RuntimeSpec struct {
	Protocol    string            `json:"protocol"`
	Entrypoints map[string]string `json:"entrypoints"`
}

type UIRuntimeSpec

type UIRuntimeSpec struct {
	Mode          string `json:"mode"`
	Entrypoint    string `json:"entrypoint"`
	BridgeVersion string `json:"bridge_version"`
}

type V2Session added in v0.2.19

type V2Session struct {
	Generation uint64
	// contains filtered or unexported fields
}

V2Session validates the ordered, single-invocation stdio-json-v2 lifecycle. It is intentionally small and transport-agnostic so hosts can reject bad frames before dispatching plugin code.

func NewV2Session added in v0.2.19

func NewV2Session(generation uint64) *V2Session

func (*V2Session) Accept added in v0.2.19

func (s *V2Session) Accept(kind string, generation uint64, invocation string) error

type ViewAction

type ViewAction struct {
	Label     string          `json:"label"`
	Interface string          `json:"interface"`
	Method    string          `json:"method"`
	Form      []ViewFormField `json:"form,omitempty"`
	Scopes    []string        `json:"scopes,omitempty"`
}

type ViewColumn

type ViewColumn struct {
	Key    string `json:"key"`
	Label  string `json:"label"`
	Render string `json:"render,omitempty"`
}

type ViewContribution

type ViewContribution struct {
	Route   string       `json:"route"`
	Title   string       `json:"title"`
	Kind    string       `json:"kind"`
	Source  *ViewSource  `json:"source,omitempty"`
	Columns []ViewColumn `json:"columns,omitempty"`
	Actions []ViewAction `json:"actions,omitempty"`
}

type ViewFormField

type ViewFormField struct {
	Key     string   `json:"key"`
	Label   string   `json:"label,omitempty"`
	Kind    string   `json:"kind"`
	Options []string `json:"options,omitempty"`
}

type ViewSource

type ViewSource struct {
	Interface string `json:"interface"`
	Method    string `json:"method"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL