plugin

package
v1.17.1 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Package plugin is the host side of tool plugins: a kind=tool binary under plugins/tools/<key>/ registers as an ordinary tool (grid, palette, access rules, config page) whose routes reverse-proxy to the plugin's HTTP server on a unix socket. The process is spawned on first use, held for at most DefaultHold, and idle-killed by the pool sweeper unless keep_warm.

Index

Constants

View Source
const (
	StateActive  = "active"  // loaded and routable
	StateError   = "error"   // the last load failed; reason says why
	StateIdle    = "idle"    // seen and deliberately not loaded (disabled, state unreadable)
	StatePending = "pending" // installed but no pass has looked at it yet
)

Load states reported by State.

View Source
const DefaultDrainGrace = 30 * time.Second

DefaultDrainGrace is Pool.DrainGrace unless set.

View Source
const DefaultHold = 10 * time.Second

DefaultHold bounds how long a request waits for a cold plugin to finish its handshake before the host answers 503.

View Source
const DefaultIdle = 10 * time.Minute

DefaultIdle is how long an unused tool plugin stays running; WICK_TOOL_PLUGIN_IDLE (a Go duration) overrides it.

Variables

View Source
var ErrNotReady = errors.New("tool plugin not ready")

ErrNotReady is returned by Acquire when the plugin did not come up within the hold window (or failed to start).

Functions

func ErrKeyTaken added in v1.16.0

func ErrKeyTaken(key string) error

ErrKeyTaken is what a Sink returns when a plugin's key belongs to a tool the plugin does not own (a built-in).

Types

type Pool

type Pool struct {

	// PublicBase returns wick's public base URL (app_url); set once at
	// startup, read per request so an app_url edit applies without reload.
	PublicBase func() string

	// DrainGrace bounds how long an unloaded version may finish in-flight
	// requests before its process is killed.
	DrainGrace time.Duration
	// contains filtered or unexported fields
}

Pool holds every loaded tool plugin's Runner and sweeps idle ones, using the same rule as the connector plugin sweeper: not warm, nothing in flight, unused for longer than the idle TTL.

func NewPool

func NewPool() *Pool

NewPool returns an empty pool; call Start once tools are loaded.

func (*Pool) Attach added in v1.16.0

func (p *Pool) Attach(s Sink)

Attach hands the pool the live Sink and makes every later Reconcile (watcher tick, install, enable, disable) act on the running process. Plugins loaded at boot are already registered, so Attach only remembers the sink — mount those through Modules.

func (*Pool) BuildModule

func (p *Pool) BuildModule(f connplugin.Found) tool.Module

BuildModule turns one discovered kind=tool plugin into a tool.Module whose routes proxy to the plugin, and registers its runner with the pool.

func (*Pool) Inflight

func (p *Pool) Inflight() int

Inflight sums in-flight proxied requests (graceful reload waits on it).

func (*Pool) KillAll

func (p *Pool) KillAll()

KillAll stops the sweeper and every process (app shutdown).

func (*Pool) Load

func (p *Pool) Load(dir string, enabled func(string) (bool, error), record func(key, kind, version string) error,
	register func(tool.Module), validate func(tool.Module) error) int

Load registers every enabled, verified, valid kind=tool plugin under dir with register (tools.Register) and returns how many were registered. Call it before tools.All() so the plugin's config rows are seeded like a built-in tool's. record (optional) is told the kind + version of each plugin.

dir, enabled and record are kept for the live passes that follow (see Reconcile); until Attach hands the pool a Sink those passes do nothing.

enabled reports the stored enable flag; a read error keeps the plugin's current state (an unloaded plugin stays unloaded). validate (optional) is the same check the live Sink runs: a module it rejects is not registered and shows Error with the reason — boot never fails on a plugin.

func (*Pool) Modules added in v1.16.0

func (p *Pool) Modules() []tool.Module

Modules returns the loaded tool plugin modules, sorted by key.

func (*Pool) Owns added in v1.16.0

func (p *Pool) Owns(key string) bool

Owns reports whether key is a tool plugin the running process has loaded.

func (*Pool) Reconcile added in v1.16.0

func (p *Pool) Reconcile()

Reconcile rescans the tool plugin folder and brings the running process in line with it: a new or updated plugin is loaded (the old version's process stopped first), a disabled or removed one is unloaded, and a plugin that fails to load records why. A no-op until Load and Attach ran.

func (*Pool) Reject added in v1.16.0

func (p *Pool) Reject(key string, err error)

Reject unloads tool plugin key (no sink: the caller already took it out of the registry) and shows err as its status — for a plugin boot accepted but could not mount.

func (*Pool) Remove

func (p *Pool) Remove(key string)

Remove unloads tool plugin key ahead of an uninstall deleting its files: its process is stopped, its routes and registry entry go (through the attached Sink) and it is dropped from the pool.

func (*Pool) Start

func (p *Pool) Start()

Start warms keep_warm tools and starts the idle sweeper and the plugin folder watcher (live install / update / enable / disable).

func (*Pool) State added in v1.16.0

func (p *Pool) State(key string) (state, reason string)

State reports what the running process does with tool plugin key, and for StateError why the last load failed.

func (*Pool) Sweep

func (p *Pool) Sweep() int

Sweep runs one idle pass and returns how many processes were killed.

func (*Pool) Version

func (p *Pool) Version(key string) (string, bool)

Version returns the installed version of tool plugin key; ok is false for a built-in tool.

type Proxy

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

Proxy forwards /tools/{key}/* to one tool plugin's unix socket.

func (*Proxy) ServeCtx

func (p *Proxy) ServeCtx(c *tool.Ctx, cfgKeys []string)

ServeCtx proxies a session-gated tool route.

func (*Proxy) ServeWebhook

func (p *Proxy) ServeWebhook(c *tool.WebhookCtx, cfgKeys []string)

ServeWebhook proxies a manifest-declared webhook route: no session and never wrapped. A request carrying a valid wick PAT or SSO JWT (see tool.WebhookCtx.TokenCaller) gets its owner as X-Wick-Token-User-* headers, and the plugin's Host API calls for it run as that person — except for wick's own system identity, which is passed on but runs no call as a user.

type Runner

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

Runner owns the lifecycle of one tool plugin: at most one process, spawned on first use (singleflight, so N concurrent cold requests cause one spawn), idle-killed by the pool sweeper unless keep_warm or a request (including a long-lived SSE/websocket one) is still in flight.

func (*Runner) Acquire

func (r *Runner) Acquire(ctx context.Context, cfg map[string]string) (http.RoundTripper, func(), error)

Acquire returns a transport to the running plugin (spawning it if needed) with cfg pushed, and a release func the caller must call when the request — including any streamed body — is finished. It waits at most the hold window for a cold start; the spawn keeps going in the background so the next request finds it ready.

func (*Runner) Close added in v1.16.0

func (r *Runner) Close(grace time.Duration) (done <-chan struct{})

Close stops the runner once the requests it is serving finish, waiting at most grace. It is closed at once (no new spawn, no new request); the kill happens in the background and done is closed after it.

func (*Runner) Inflight

func (r *Runner) Inflight() int64

Inflight is the number of requests currently being proxied.

func (*Runner) Running

func (r *Runner) Running() bool

Running reports whether a live process is attached.

func (*Runner) Stop

func (r *Runner) Stop()

Stop closes the runner and kills the process unconditionally.

func (*Runner) Warm

func (r *Runner) Warm() error

Warm spawns the process now (keep_warm tools at boot). Errors are returned for logging; the next request retries.

type Sink added in v1.16.0

type Sink interface {
	Add(m tool.Module) error
	Remove(key string)
}

Sink is what a running wick does with a tool plugin the pool loads or unloads: mount / drop its routes, add it to / remove it from the tool registry, seed its config rows and default tags. Add returning an error leaves the plugin unloaded, with the error shown as its status.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL