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
- Variables
- func ErrKeyTaken(key string) error
- type Pool
- func (p *Pool) Attach(s Sink)
- func (p *Pool) BuildModule(f connplugin.Found) tool.Module
- func (p *Pool) Inflight() int
- func (p *Pool) KillAll()
- func (p *Pool) Load(dir string, enabled func(string) (bool, error), ...) int
- func (p *Pool) Modules() []tool.Module
- func (p *Pool) Owns(key string) bool
- func (p *Pool) Reconcile()
- func (p *Pool) Reject(key string, err error)
- func (p *Pool) Remove(key string)
- func (p *Pool) Start()
- func (p *Pool) State(key string) (state, reason string)
- func (p *Pool) Sweep() int
- func (p *Pool) Version(key string) (string, bool)
- type Proxy
- type Runner
- type Sink
Constants ¶
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.
const DefaultDrainGrace = 30 * time.Second
DefaultDrainGrace is Pool.DrainGrace unless set.
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.
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 ¶
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
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
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) 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
Modules returns the loaded tool plugin modules, sorted by key.
func (*Pool) Owns ¶ added in v1.16.0
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
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 ¶
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
State reports what the running process does with tool plugin key, and for StateError why the last load failed.
type Proxy ¶
type Proxy struct {
// contains filtered or unexported fields
}
Proxy forwards /tools/{key}/* to one tool plugin's unix socket.
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
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.
type Sink ¶ added in v1.16.0
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.