plugin

type AuthGRPCPlugin ¶

type AuthGRPCPlugin = abi.AuthGRPCPlugin

type Caller ¶

type Caller interface {
	Call(ctx context.Context, method string, fn func(ctx context.Context, client any) error) error
}

Caller invokes a method on ONE plugin with the loader's readiness gate and in-flight budget applied — the handle a registered provider (a scoring engine, auth provider, challenge-type checker) uses to reach the plugin process. A call to a non-ready plugin returns ErrNotReady without touching the process, which is the fail-closed layer INSIDE every registered provider.

type ChallengeTypeGRPCPlugin ¶

type ChallengeTypeGRPCPlugin = abi.ChallengeTypeGRPCPlugin

type Config ¶

type Config struct {
	Enabled      bool          // false skips discovery entirely (pure-core mode, == v0.2 behaviour)
	PluginsDir   string        // OSCTF_PLUGINS_DIR — scanned one level deep
	RuntimeDir   string        // OSCTF_RUNTIME_DIR — where pidfiles are written / the boot sweep reads
	PerPluginCap int           // OSCTF_PLUGIN_MAX_INFLIGHT (per plugin)
	GlobalCap    int           // shared fd-accountant grant (across all plugins); 0 = unbounded
	QueueWait    time.Duration // OSCTF_PLUGIN_QUEUE_WAIT
	DrainTimeout time.Duration // OSCTF_PLUGIN_DRAIN_TIMEOUT
	StartTimeout time.Duration // handshake wait before a launch is deemed failed
	HealthStable time.Duration // OSCTF_PLUGIN_HEALTH_STABLE
	MaxAttempts  int           // OSCTF_PLUGIN_RESTART_CAP
	Log          *slog.Logger
	Registrar    Registrar // wires ready plugins into their type registries; nil = no-op (transport only)
}

Config is what the composition root hands the loader at startup. The budget fields come from the shared fd accountant (GlobalCap) + OSCTF_PLUGIN_MAX_INFLIGHT (PerPluginCap); the rest are discovery and supervision knobs.

type ConfigKey ¶

type ConfigKey struct {
	Type     string `yaml:"type"`
	Required bool   `yaml:"required"`
	Secret   bool   `yaml:"secret"`
	Default  string `yaml:"default"`
}

ConfigKey declares one config value's type and resolution rules. Secret keys resolve ONLY from env; a value in the manifest is a validation error (secrets never live in a file the plugin dir might expose).

type Loader ¶

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

Loader discovers, launches, supervises, and routes to plugins. It holds the tracked set under a mutex, dispatches calls only to `ready` plugins, and bounds concurrent host→plugin work with the two-level budget.

func New(cfg Config) *Loader

func (l *Loader) Boot(ctx context.Context)

func (l *Loader) Reload(ctx context.Context, name string) error

func (l *Loader) Snapshot() []PluginStatus

func (l *Loader) Stop(ctx context.Context)

type Manifest ¶

type Manifest struct {
	Name        string               `yaml:"name"`
	Type        string               `yaml:"type"`
	ABI         string               `yaml:"abi"`
	Version     string               `yaml:"version"`
	Executable  string               `yaml:"executable"`
	Description string               `yaml:"description"`
	Override    bool                 `yaml:"override"` // opt-in to replace a protected built-in key
	Config      map[string]ConfigKey `yaml:"config"`
}

Manifest is a plugin's plugin.yaml. Names map to registry keys (auth provider id, scoring mode, challenge-type id), so identity is validated strictly and a collision fails loudly.

type NotificationGRPCPlugin ¶

type NotificationGRPCPlugin = abi.NotificationGRPCPlugin

type PluginStatus ¶

type PluginStatus struct {
	Name   string
	Type   string
	State  string
	Reason string
}

PluginStatus is one plugin's state for the admin view — enough to answer "why isn't my notifier working?" without reading boot logs. Reason is redacted of secret config values.

type Registrar ¶

type Registrar interface {
	Register(name, ptype string, caller Caller) error
	Deregister(name, ptype string)
}

Registrar wires a ready plugin's provider into its type's registry and reverts it before the plugin dies. The composition root implements it per type (auth/scoring/challenge-type/ notification); the loader calls Register once when a plugin FIRST becomes ready and Deregister once when it terminates — before the process is killed (revert-before-death).

type ScoringGRPCPlugin ¶

type ScoringGRPCPlugin = abi.ScoringGRPCPlugin

type ShedError ¶

type ShedError struct {
	Plugin     string
	Level      ShedLevel
	RetryAfter time.Duration
}

ShedError is returned when a call is shed at an in-flight cap after waiting the queue budget. It maps to 503 (errors.Is(err, apperr.ErrUnavailable)) and its message names WHICH cap fired, so the operator log distinguishes the two causes.

func (e *ShedError) Error() string

func (e *ShedError) Is(target error) bool

type ShedLevel ¶

type ShedLevel int

ShedLevel says which in-flight cap shed a call — the distinction an operator needs, since "one plugin at its own cap" and "all plugins exhausting the shared budget" call for different responses (throttle/replace that plugin vs. raise the global budget / add capacity).

const (
	ShedPerPlugin ShedLevel = iota // one plugin hit OSCTF_PLUGIN_MAX_INFLIGHT
	ShedGlobal                     // the shared budget (all plugins) is exhausted
)

type State ¶

type State string

State is the lifecycle state of a tracked plugin. Every plugin is in exactly one; the full state machine is specified in docs/v0.3/03-plugin-loader.md before the loader is built, because process supervision is a new concurrency surface and the last two releases shipped bugs of exactly this shape.

const (
	StateDiscovered State = "discovered" // manifest found + validated; not launched
	StateLaunching  State = "launching"  // process started; handshake+Info+Configure in progress
	StateReady      State = "ready"      // launched, configured, registered, health passing — SERVES
	StateUnhealthy  State = "unhealthy"  // was ready; a health check or call failed; supervisor deciding
	StateRestarting State = "restarting" // being torn down + relaunched; backoff between attempts
	StateFailed     State = "failed"     // restart cap exhausted OR failed to load (e.g. invalid config) → quarantined; not retried automatically
	StateDraining   State = "draining"   // reload/shutdown; no new calls, in-flight allowed to finish
	StateStopped    State = "stopped"    // process exited, resources reclaimed, entry removed — terminal
)