plugin

package
v0.2.18 Latest Latest
Warning

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

Go to latest
Published: Jul 26, 2026 License: MIT Imports: 13 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"
	DefaultMaxHostResponseBytes = 1 << 20
)
View Source
const (
	TypeSystem = "system"
	TypeWasm   = "wasm"
	TypeWorker = "worker"

	ManifestSchemaV2           = "lattice.plugin.manifest.v2"
	BundleFormatTarGzip        = "tar+gzip"
	RuntimeProtocolStdioJSONV1 = "stdio-json-v1"
	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
)

Variables

View Source
var ErrHostUnavailable = errors.New("host response fd unavailable")

Functions

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 (*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) 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) 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 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