plugin

type ABIMismatchError ¶

type ABIMismatchError struct {
	Want, Got string
}

ABIMismatchError signals an ABI-version mismatch between runtime and plugin.

func (e *ABIMismatchError) Error() string

type BudgetedPlugin ¶

type BudgetedPlugin interface {
	Plugin
	Budget() ResourceBudget
}

BudgetedPlugin is the optional interface a plugin implements to declare its resource budget. The loader detects this via type assertion so the stable Plugin interface (ABI v1) does not break for plugins that don't opt in.

type DefaultOpener ¶

type DefaultOpener struct{}

DefaultOpener loads a plugin artefact via Go's stdlib plugin package. Available on linux + darwin only; other platforms get the noop opener that always errors out (see opener_unsupported.go).

func (DefaultOpener) Open(artefactPath string) (Plugin, error)

type Discovered ¶

type Discovered struct {
	Dir      string   // absolute path to the plugin directory
	Manifest Manifest // identity + provenance subset of the disk manifest
	ABI      string   // declared ABI version (validated against ABIVersion at load time)
	Artifact string   // absolute path to the plugin artefact file
}

Discovered is one validated plugin found on disk. The runtime consumes this list at startup, verifies signatures (follow-up task), then loads each artefact and calls plugin.Load.

type DiscoveryError ¶

type DiscoveryError struct {
	Dir string
	Err error
}

DiscoveryError carries a per-plugin failure surfaced by Discover. The scan continues past these so a single bad plugin cannot hide healthy siblings.

func (e *DiscoveryError) Error() string

func (e *DiscoveryError) Unwrap() error

type DiscoveryResult ¶

type DiscoveryResult struct {
	Plugins []Discovered
	Errors  []DiscoveryError
}

DiscoveryResult separates clean plugins from per-plugin errors so callers can decide whether to fail-closed (any error aborts startup) or fail-open (log errors, register healthy plugins).

func Discover(root string) (DiscoveryResult, error)

type DiskManifest ¶

type DiskManifest struct {
	Manifest
	ABI      string `json:"abi"`
	Artifact string `json:"artifact"`
}

DiskManifest is the on-disk manifest schema. It extends the in-process Manifest with deployment metadata: the ABI version the plugin was built against and the artefact filename relative to the plugin directory.

type Identity ¶ added in v0.2.0

type Identity struct {
	SubjectGlob string
	Issuer      string
}

Identity is one allowed (subject, issuer) pair. SubjectGlob accepts a literal SAN value or a single-asterisk suffix wildcard ("https://github.com/felixgeelhaar/*"). Issuer is matched literally against the OIDC issuer extension.

type KeylessVerifier ¶ added in v0.2.0

type KeylessVerifier struct {
	FulcioRoots       []*x509.Certificate
	Intermediates     []*x509.Certificate
	TrustedIdentities []Identity
	Now               func() time.Time
}

KeylessVerifier holds the trust policy for Fulcio-issued plugin signatures. Zero value is unusable: callers must populate at least FulcioRoots and TrustedIdentities before VerifyKeyless will succeed.

FulcioRoots is the operator's pinned root bundle (typically the production Sigstore root + any private Fulcio instance). Intermediates is optional — `cosign sign-blob` already attaches the chain inside the leaf cert when present.

TrustedIdentities is the allowlist that gates which build identities may produce loadable plugins. Any cert whose (SAN, issuer) pair fails to match every entry is rejected with ErrIdentityMismatch.

Now is injected so tests can pin a deterministic clock; production callers leave it nil for time.Now.

type LoadEvent ¶

type LoadEvent struct {
	Name        string
	Version     string
	ABI         string
	Dir         string
	ArtifactSHA string
	Result      string
	Err         error
}

LoadEvent reports a single plugin's load outcome with enough metadata for /metrics labelling and `praxis plugins list` rendering. Phase 4.

type LoadHooks ¶

type LoadHooks struct {
	// WrapHandler runs against every Registration's handler after the
	// optional Sandboxed wrap. The plugin's Manifest is supplied so the
	// caller can record per-plugin state. Returning the same handler
	// unchanged is the no-op default.
	WrapHandler func(manifest Manifest, h capability.Handler) capability.Handler

	// OnLoaded fires once after every Registration has been forwarded
	// to the Loader, with the plugin instance and the (possibly
	// wrapped) registrations the runtime now sees. Used by the Manager
	// to wire Watchable crash detection and record per-plugin
	// capability names. Phase 4 out-of-process loader.
	OnLoaded func(p Plugin, regs []Registration)
}

LoadHooks lets callers (the Manager) wrap handlers post-sandbox and post-budgeting. A nil LoadHooks reduces to the original Load behaviour. Phase 4 graceful rollover.

type Loader ¶

type Loader interface {
	Register(reg Registration) error
}

Loader is the runtime interface that registers a plugin's capabilities. Implemented by cmd/praxis at startup; tested in this package against a fake plugin to lock down the contract.

type Manager ¶

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

Manager owns the runtime state of loaded plugins. It serialises load and reload calls so a watcher event and a SIGHUP-driven full re-scan don't race against each other.

func NewManager(cfg ManagerConfig) *Manager

func (m *Manager) Drain(ctx context.Context, name string) error

func (m *Manager) LoadAll(ctx context.Context) (PipelineResult, error)

func (m *Manager) ReloadOne(ctx context.Context, name string) error

func (m *Manager) Snapshot() []LoadEvent

type ManagerConfig ¶

type ManagerConfig struct {
	Dir         string
	TrustedKeys []*ecdsa.PublicKey
	Keyless     *KeylessVerifier
	Loader      Loader
	Opener      Opener
	Unregister  func(capName string)
	OnEvent     func(LoadEvent)
}

ManagerConfig parameters the plugin Manager. Loader, Opener, and Dir are required; TrustedKeys may be empty (the load pipeline will then reject every plugin via ErrNoTrustedKeys, which is the safe default).

Unregister, when set, is invoked for every capability name the Manager needs to remove from the runtime registry on a plugin crash. The host wires this to capability.Registry.Unregister so the in-process registry stays consistent with the Manager's snapshot of loaded plugins.

type Manifest ¶

type Manifest struct {
	Name        string `json:"name"`
	Version     string `json:"version"`
	Author      string `json:"author,omitempty"`
	Description string `json:"description,omitempty"`
	Homepage    string `json:"homepage,omitempty"`
	License     string `json:"license,omitempty"`
}

Manifest describes the plugin's identity and build provenance. Required fields: Name, Version. Optional fields surface in audit detail.

type Opener ¶

type Opener interface {
	Open(artefactPath string) (Plugin, error)
}

Opener loads a plugin artefact from disk and returns its exported Plugin symbol. The default implementation (DefaultOpener) wraps Go's stdlib `plugin` package and is build-tagged to Linux+macOS only — platforms where Go plugin loading is supported. Tests inject a fake Opener to exercise the pipeline without producing real .so artefacts.

type PipelineConfig ¶

type PipelineConfig struct {
	Dir         string
	TrustedKeys []*ecdsa.PublicKey
	// Keyless, when populated with at least one Fulcio root, switches
	// the pipeline to keyless verification for any plugin that ships a
	// `<artifact>.cert` file. Plugins that do not ship a certificate
	// fall back to TrustedKeys (PEM-key path) so the two modes coexist
	// during a migration.
	Keyless *KeylessVerifier
	Loader  Loader
	Opener  Opener
	// LoadHooks is forwarded to LoadWithHooks for every plugin loaded
	// through the pipeline. Optional; nil reduces to the unhookable
	// Load path.
	LoadHooks *LoadHooks
}

PipelineConfig parameters the runtime plugin-load pipeline. Dir, Loader and Opener are required; TrustedKeys is required as soon as any plugin is discovered (the pipeline fail-closes when it finds a plugin with no trust bundle to verify against, even if Strict is false).

type PipelineError ¶

type PipelineError struct {
	Dir string
	Err error
}

PipelineError pairs a discovered plugin's directory with the reason it failed to load. Wraps the underlying error so errors.Is/As works against the sentinel set (ErrSignatureMissing, ErrSignatureInvalid, ErrNoTrustedKeys, ABIMismatchError, dlopen and Capabilities errors).

func (e *PipelineError) Error() string

func (e *PipelineError) Unwrap() error

type PipelineResult ¶

type PipelineResult struct {
	Loaded []Discovered
	Errors []PipelineError
}

PipelineResult describes the outcome of one Pipeline run. Loaded is the set of plugins that successfully reached the registry; Errors captures every per-plugin failure so the caller can decide whether to log, fail-soft, or abort.

func RunPipeline(ctx context.Context, cfg PipelineConfig) (PipelineResult, error)

type Plugin ¶

type Plugin interface {
	// ABI reports the ABI version this plugin was built against. Plugins
	// MUST return ABIVersion (the constant in this package as compiled at
	// build time). The runtime refuses to load plugins whose ABI does not
	// match the runtime's ABIVersion.
	ABI() string

	// Manifest returns identity + provenance metadata. Authors set Name
	// and Version; the runtime validates Name uniqueness against already-
	// registered capabilities and surfaces Version in audit detail.
	Manifest() Manifest

	// Capabilities returns one or more (descriptor, handler) pairs for
	// registration. A plugin may expose multiple capabilities — convenient
	// when one vendor has several related actions (e.g. github_create_issue
	// + github_add_comment).
	Capabilities(ctx context.Context) ([]Registration, error)
}

Plugin is the symbol every plugin must export. The runtime calls Capabilities() at load time and registers each returned descriptor + handler with the registry.

type ProcessOpener ¶

type ProcessOpener struct {
	Binary string
	Budget ResourceBudget

	// CgroupParent, when non-empty, names a cgroup v2 subtree under
	// which each spawned plugin host runs. Phase 5: when the host
	// detects cgroup v2 availability the bootstrap sets this to
	// /sys/fs/cgroup/praxis so memory.max + cpu.max enforce the
	// declared budget. Empty falls back to the setrlimit-only path.
	CgroupParent string

	// OnUsageReport, when set, receives the cgroup-recorded high-water
	// memory peak and cumulative CPU time for the plugin just before
	// the cgroup is reclaimed on Close. Bootstrap wires this to the
	// praxis_plugin_memory_peak_bytes / praxis_plugin_cpu_seconds_total
	// metrics. Phase 5 t-cgroup-v2-usage-metrics.
	OnUsageReport func(pluginName string, peakBytes uint64, cpuNs uint64)

	// SpawnFn is the test seam: production uses exec.Command, tests
	// supply a custom transport pair without touching the OS.
	SpawnFn func(ctx context.Context, artefactPath string) (io.WriteCloser, io.ReadCloser, func() error, error)
	// contains filtered or unexported fields
}

ProcessOpener is an Opener implementation that spawns a praxis-pluginhost child process per plugin and proxies the Plugin interface over IPC. Phase 4 out-of-process loader.

The Binary field is the absolute path to the praxis-pluginhost binary; tests inject their own command for round-tripping the protocol against an in-process echo server. Budget, when non-zero, is forwarded to the child via PRAXIS_PLUGIN_BUDGET_* env vars and the child applies setrlimit at startup.

func (o *ProcessOpener) Open(artefactPath string) (Plugin, error)

type Registration ¶

type Registration struct {
	Capability domain.Capability
	Handler    capability.Handler
}

Registration pairs a Capability descriptor with the handler that runs it. Returned by Plugin.Capabilities and consumed by the runtime registrar.

type ResourceBudget ¶

type ResourceBudget struct {
	CPUTimeout     time.Duration
	MaxMemoryBytes uint64
	AllowedHosts   []string
}

ResourceBudget caps what a plugin handler may consume during a single Execute or Simulate call. Plugins opt in by implementing BudgetedPlugin; unknown plugins run unsandboxed.

Phase 3 M3.1 enforces:

• CPUTimeout: real, via context.WithTimeout. Zero disables the cap.
• AllowedHosts: real, via a runtime-supplied http.Client whose transport rejects unlisted destinations. Plugins that bypass the supplied client (e.g. instantiate their own net.Dialer) defeat this layer; the contract is "use plugin.HTTPClient(ctx) for any outbound call."
• MaxMemoryBytes: NOT enforced in-process. Go's runtime does not expose per-handler accounting and the global allocator is shared with the rest of Praxis. The field is reserved so plugin authors can declare their intended ceiling today; the out-of-process loader (future task) will hold it to that limit.

type Watchable ¶

type Watchable interface {
	Watch() <-chan error
}

Watchable is implemented by Plugin variants whose underlying transport can fail asynchronously — the out-of-process loader is the canonical example. The Manager type-asserts every loaded plugin against Watchable; matching plugins get a goroutine that listens for crash events and triggers capability deregistration. Phase 4 out-of-process loader (M3.1).

type Watcher ¶

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

Watcher monitors PRAXIS_PLUGIN_DIR and triggers OnReload when a plugin's manifest.json or .sig changes. Sub-second event bursts are coalesced via Debounce so a single edit doesn't cause five reloads.

The watcher is opt-in: callers control startup (no goroutine starts implicitly) and pass the cancel context that ends the loop.

func NewWatcher(cfg WatcherConfig) (*Watcher, error)

func (w *Watcher) Run(ctx context.Context)

type WatcherConfig ¶

type WatcherConfig struct {
	Root     string
	OnReload func(pluginDir string)
	Debounce time.Duration
}

WatcherConfig parameters the plugin-directory watcher. Root is the directory to watch (PRAXIS_PLUGIN_DIR); OnReload is invoked with the affected plugin directory after a debounce window. Debounce coalesces bursts of FS events (a manifest rewrite often produces several writes per second) into a single reload.