plugin

package
v4.0.0-alpha.7 Latest Latest
Warning

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

 Go to latest Published: Jul 17, 2026 License: MPL-2.0 Imports: 34 Imported by: 0

Documentation

Overview

Package plugin implements the Agent-side lifecycle boundary for official plugins. It intentionally owns control work only; data-plane traffic remains inside a plugin process or the kernel networking stack.

Index

Constants

View Source 
const (
	PluginInstallAPIVersion = "anixops.io/plugin-install/v1alpha1"
)

Variables

This section is empty.

Functions

func CanonicalManifest 

func CanonicalManifest(manifest Manifest) ([]byte, error)

func ParseOfficialPublicKey 

func ParseOfficialPublicKey(encoded string) (ed25519.PublicKey, error)

Types

type CleanupRunner 

type CleanupRunner interface {
	Cleanup(context.Context, string, string, string, string) error
}

type CommandRunner 

type CommandRunner struct {
	ExtraArgs []string
}

CommandRunner starts one signed plugin binary. Plugin binaries must expose the standard gRPC health service on the supplied Unix socket.

func (CommandRunner) Cleanup 

func (r CommandRunner) Cleanup(ctx context.Context, binaryPath, socketPath, configPath, statePath string) error

func (CommandRunner) Start 

func (r CommandRunner) Start(ctx context.Context, binaryPath, socketPath, configPath string) (Process, error)

func (CommandRunner) StartWithState 

func (r CommandRunner) StartWithState(ctx context.Context, binaryPath, socketPath, configPath, statePath string) (Process, error)

type Config 

type Config struct {
	RootDir   string
	SocketDir string
	PublicKey ed25519.PublicKey
	Runner    Runner
	Health    HealthChecker
	Now       func() time.Time
}

type GRPCHealthChecker 

type GRPCHealthChecker struct {
	Service string
	Timeout time.Duration
}

func (GRPCHealthChecker) Check 

func (h GRPCHealthChecker) Check(ctx context.Context, socketPath string) error

type HealthChecker 

type HealthChecker interface {
	Check(context.Context, string) error
}

type InstallRequest 

type InstallRequest struct {
	ManifestJSON string
	Signature    string
	Artifact     []byte
}

type InstallRequestLoader 

type InstallRequestLoader func(context.Context) (InstallRequest, error)

type JournalEntry 

type JournalEntry struct {
	OperationID    string          `json:"operation_id"`
	IdempotencyKey string          `json:"idempotency_key"`
	SessionID      string          `json:"session_id"`
	Kind           string          `json:"kind"`
	PluginID       string          `json:"plugin_id"`
	TargetVersion  string          `json:"target_version"`
	ConfigHash     string          `json:"config_hash"`
	Revision       uint64          `json:"revision"`
	State          string          `json:"state"`
	Result         json.RawMessage `json:"result,omitempty"`
	Error          string          `json:"error,omitempty"`
	UpdatedAt      time.Time       `json:"updated_at"`
}

type Manifest 

type Manifest struct {
	ID             string            `json:"id"`
	Name           string            `json:"name"`
	Version        string            `json:"version"`
	APIVersion     string            `json:"api_version"`
	Publisher      string            `json:"publisher"`
	Targets        []string          `json:"targets"`
	Architectures  []string          `json:"architectures"`
	ArtifactSHA256 string            `json:"artifact_sha256"`
	Capabilities   []string          `json:"capabilities"`
	Dependencies   []string          `json:"dependencies"`
	Conflicts      []string          `json:"conflicts"`
	Permissions    []string          `json:"permissions"`
	ConfigSchema   json.RawMessage   `json:"config_schema"`
	SecretFields   []string          `json:"secret_fields"`
	Entrypoints    map[string]string `json:"entrypoints"`
	Migration      int64             `json:"migration_version"`
	ControlRoutes  []string          `json:"control_routes"`
	FrontendSHA256 string            `json:"frontend_sha256"`
	WebUI          *PluginWebUI      `json:"webui,omitempty"`
}

func VerifyManifest 

func VerifyManifest(manifestJSON, signature string, publicKey ed25519.PublicKey) (*Manifest, error)

func (Manifest) Validate 

func (m Manifest) Validate() error

type PluginState 

type PluginState struct {
	ID               string    `json:"id"`
	DesiredVersion   string    `json:"desired_version"`
	ObservedVersion  string    `json:"observed_version"`
	PreviousVersion  string    `json:"previous_version"`
	Enabled          bool      `json:"enabled"`
	Health           string    `json:"health"`
	ConfigHash       string    `json:"config_hash"`
	DesiredRevision  uint64    `json:"desired_revision"`
	ObservedRevision uint64    `json:"observed_revision"`
	LastError        string    `json:"last_error"`
	CleanupPending   bool      `json:"cleanup_pending,omitempty"`
	CleanupVersion   string    `json:"cleanup_version,omitempty"`
	UpdatedAt        time.Time `json:"updated_at"`
}

type PluginWebUI 

type PluginWebUI struct {
	Bundle      PluginWebUIBundle  `json:"bundle"`
	Permissions []string           `json:"permissions"`
	Menus       []PluginWebUIMenu  `json:"menus"`
	Routes      []PluginWebUIRoute `json:"routes"`
}

type PluginWebUIBundle 

type PluginWebUIBundle struct {
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
}

type PluginWebUIMenu 

type PluginWebUIMenu struct {
	ID         string `json:"id"`
	Parent     string `json:"parent"`
	Label      string `json:"label"`
	Icon       string `json:"icon"`
	Route      string `json:"route"`
	Permission string `json:"permission"`
	Order      int    `json:"order"`
}

type PluginWebUIRoute 

type PluginWebUIRoute struct {
	ID         string `json:"id"`
	Path       string `json:"path"`
	Export     string `json:"export"`
	Permission string `json:"permission"`
}

type Process 

type Process interface {
	Stop(context.Context) error
	PID() int
}

type ProcessExitWatcher 

type ProcessExitWatcher interface {
	Exited() <-chan error
}

ProcessExitWatcher is optional so test and embedded runners remain small. CommandRunner implements it to let the Supervisor fail closed when a plugin exits without an explicit lifecycle operation.

type RemoteInstaller 

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

func NewRemoteInstaller 

func NewRemoteInstaller(config RemoteInstallerConfig) (*RemoteInstaller, error)

func (*RemoteInstaller) Handle 

func (i *RemoteInstaller) Handle(ctx context.Context, envelope *agent.OperationEnvelope) (json.RawMessage, error)

type RemoteInstallerConfig 

type RemoteInstallerConfig struct {
	Supervisor *Supervisor
	BaseURL    string
	APIKey     string
	HTTPClient *http.Client
}

type Runner 

type Runner interface {
	Start(context.Context, string, string, string) (Process, error)
}

type StatefulRunner 

type StatefulRunner interface {
	StartWithState(context.Context, string, string, string, string) (Process, error)
}

type Supervisor 

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

func NewSupervisor 

func NewSupervisor(config Config) (*Supervisor, error)

func (*Supervisor) Close 

func (s *Supervisor) Close(ctx context.Context) error

func (*Supervisor) Handle 

func (s *Supervisor) Handle(ctx context.Context, kind string, envelope *agent.OperationEnvelope) (json.RawMessage, error)

Handle executes an already validated plugin operation. It journals every result before returning it so stream retries cannot restart a process.

func (*Supervisor) HandleInstall 

func (s *Supervisor) HandleInstall(ctx context.Context, envelope *agent.OperationEnvelope, loader InstallRequestLoader) (json.RawMessage, error)

HandleInstall keeps the remote fetch lazy: a completed replay returns its journaled result without downloading the package again.

func (*Supervisor) Install 

func (s *Supervisor) Install(ctx context.Context, request InstallRequest) (*PluginState, error)

Install verifies a signed artifact, writes it into an Agent-owned directory, and retains existing versions for explicit rollback.

func (*Supervisor) PluginObservations 

func (s *Supervisor) PluginObservations(ctx context.Context) ([]*agentv1pb.PluginObservedState, error)

PluginObservations returns only signed, enabled plugin evidence suitable for the Agent Control heartbeat. Supervisor state supplies the version, revisions, config hash, and authoritative process health; plugins can only contribute the fixed ruleset fingerprint and counters from their private observation file.

func (*Supervisor) TelemetryMetrics 

func (s *Supervisor) TelemetryMetrics(ctx context.Context) (map[string]float64, error)

TelemetryMetrics returns namespaced scalar metrics from enabled official plugins. It never returns untrusted plugin keys directly into the control protocol and keeps useful partial results when another plugin is unhealthy.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.