Documentation
¶
Index ¶
- Constants
- Variables
- func InvocationStderr(ctx context.Context) io.Writer
- func Serve(ctx context.Context, handler Handler) error
- func ValidateInvokeBudgetSpec(b InvokeBudgetSpec) error
- type BundleSpec
- type CallPayload
- type CompatibilitySpec
- type HTTPRequest
- type HTTPResponse
- type Handler
- type HandlerFunc
- type HostAccessSpec
- type HostClient
- func (c *HostClient) Abort()
- func (c *HostClient) Available() bool
- func (c *HostClient) Call(ctx context.Context, method string, params any) (json.RawMessage, error)
- func (c *HostClient) Expire()
- func (c *HostClient) HTTPDo(ctx context.Context, req HTTPRequest) (HTTPResponse, error)
- func (c *HostClient) HTTPOperatorDo(ctx context.Context, req HTTPRequest) (HTTPResponse, error)
- func (c *HostClient) KVGet(ctx context.Context, key string) ([]byte, bool, error)
- func (c *HostClient) KVPut(ctx context.Context, key string, value []byte) error
- func (c *HostClient) LogWrite(ctx context.Context, entry LogEntry) error
- func (c *HostClient) NotifySend(ctx context.Context, title, body string) error
- func (c *HostClient) RPCCall(ctx context.Context, service, method string, request any) (json.RawMessage, error)
- func (c *HostClient) RPCCallRaw(ctx context.Context, service, method string, request json.RawMessage) (json.RawMessage, error)
- func (c *HostClient) SecretDelete(ctx context.Context, key string) error
- func (c *HostClient) SecretGet(ctx context.Context, key string) ([]byte, bool, error)
- func (c *HostClient) SecretGetString(ctx context.Context, key string) (string, bool, error)
- func (c *HostClient) SecretPut(ctx context.Context, key string, value []byte) error
- func (c *HostClient) SecretPutString(ctx context.Context, key, value string) error
- type HostClientOptions
- type InterfaceContract
- func (c InterfaceContract) EffectiveBacking() string
- func (c InterfaceContract) EffectiveMethodScopes(name string) ([]string, bool)
- func (c InterfaceContract) MarshalJSON() ([]byte, error)
- func (c InterfaceContract) MethodContract(name string) (InterfaceMethod, bool)
- func (c InterfaceContract) MethodContracts() []InterfaceMethod
- func (c InterfaceContract) TypedMethods() bool
- func (c *InterfaceContract) UnmarshalJSON(data []byte) error
- type InterfaceMethod
- type InvokeBudgetSpec
- type LogEntry
- type Manifest
- type ManifestUI
- type NavContribution
- type RPCDependency
- type Request
- type ResolvedInvokeBudget
- type Response
- type Runtime
- type RuntimeOptions
- type RuntimeSpec
- type UIRuntimeSpec
- type V2Session
- type ViewAction
- type ViewColumn
- type ViewContribution
- type ViewFormField
- type ViewSource
Constants ¶
const ( DefaultInvokeTimeoutMS = 10_000 DefaultInvokeStdoutBytes = 1 << 20 DefaultInvokeStderrBytes = 1 << 20 DefaultInvokeHostCalls = 64 HostMaxInvokeTimeoutMS = 30_000 HostMaxInvokeStdoutBytes = 8 << 20 HostMaxInvokeStderrBytes = 1 << 20 HostMaxInvokeHostCalls = 64 )
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 )
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" )
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" )
const ( ActionDescribe = "describe" ActionHealth = "health" ActionPlan = "plan" ActionCall = "call" ActionExecute = "execute" DefaultMaxRequestBytes = 1 << 20 FeatureStderrFramesV1 = "stderr_frames_v1" )
Variables ¶
var ErrHostClientExpired = errors.New("invocation host client expired")
var ErrV2Protocol = fmt.Errorf("invalid stdio-json-v2 lifecycle")
Functions ¶
func InvocationStderr ¶ added in v0.2.19
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 ValidateInvokeBudgetSpec ¶
func ValidateInvokeBudgetSpec(b InvokeBudgetSpec) error
Types ¶
type BundleSpec ¶
type CallPayload ¶
type CallPayload struct {
Service string `json:"service"`
Method string `json:"method"`
Payload json.RawMessage `json:"payload,omitempty"`
}
type CompatibilitySpec ¶
type HTTPRequest ¶
type HTTPResponse ¶
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) 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) SecretGetString ¶
func (*HostClient) SecretPutString ¶
func (c *HostClient) SecretPutString(ctx context.Context, key, value string) error
type HostClientOptions ¶
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 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 (Manifest) InterfaceFor ¶
func (m Manifest) InterfaceFor(service string) (InterfaceContract, bool)
type ManifestUI ¶
type ManifestUI struct {
Views []ViewContribution `json:"views,omitempty"`
}
type NavContribution ¶
type NavContribution struct {
}
type RPCDependency ¶
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 MessageResponse ¶
func PlanResponse ¶
func RawResultResponse ¶
func RawResultResponse(result json.RawMessage, message string) Response
func ResultResponse ¶
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) ServeV2 ¶ added in v0.2.19
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 ¶
type RuntimeOptions ¶
type RuntimeSpec ¶
type UIRuntimeSpec ¶
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
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 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"`
}