Plugin management: config section, loading with hash checks, recording and the control API

[fylorn]

Management plane for script plugins (track 2a, step 2), on top of the scaffolding in #250.

Configuration (tw-config)

plugins: is a list, and its order is the run order.

Field	Type	Default
id	[a-z0-9-]{1,40}, unique; order and inspect are reserved	required
file	must be plugins/<id>.js, relative to the config dir	required
sha256	64 lowercase hex	required
enabled	bool	true
on_error	reject | skip	reject
scope	{ clients, models, upstreams }, * globs, no blank entries	{}
settings	string | number | bool	{}

• order and inspect are reserved because /plugins/order and /plugins/inspect are fixed paths. A test keeps this list in sync with the endpoint table.
• tw-config holds plain data only. Manifest checks (settings keys and types) happen in the gateway when a plugin loads.
• Documented in docs/config*.md (generated tables, both languages).

Loading (tw-gateway plugin::load)

• Plugins (on AppState, survives reloads) holds the engine, the config dir, per-plugin Stats and LogRing, and a compile cache keyed by SHA-256.
• I9. Every build reads each file once, capped at 1 MiB + 1. It hashes those bytes and compiles those same bytes, and only when the hash matches the approved sha256.
  • A hash mismatch or a missing file gives status changed. The approved copy's manifest is still shown, but it is never run.
  • A load error, or a setting that is undeclared or has the wrong type, gives status error.
  • Neither ever fails a reload.
• AppState::reload_plugins() re-reads the plugin files without a config change.
• Runtime swaps are serialized, so a plugin reload cannot put back an older configuration.
• When an enabled plugin newly stops running, a plugin_failed event is emitted without a request_id.
• ConfigManager::new tells the gateway where the config dir is. Remote cores work the same way, because the files are next to their config.
• File-change detection works two ways:
  • A watcher on plugins/ (tw-watch, 200 ms debounce; the directory is created 0700 at startup) reloads the plugins under the same lock that plugin writes hold.
  • Every config reload re-hashes all plugin files.
• The engine is still the "engine unavailable" stand-in. plugin::fake::FakeEngine serves the tests.

Recording (tw-store)

• SCHEMA 24 adds the plugin_runs table: request_id, seq, at_ms, plugin_id, plugin_name, hook, outcome, error, error_code, error_args, cpu_us, detail. Its rows are pruned along with the requests.
• AppState::plugin_ran hands each run to the store through its own channel.
• The post-plugin request body is stored as {id}.after-plugins (BodyKind::AfterPlugins / Which::AfterPlugins).
• That body goes through the same BodyRecord::for_disk redaction as every other body (Store bodies with secrets replaced; keep 4 MiB of each answer; 5 GiB of bodies by default #252), and a test covers it.

Control API

Endpoints: GET /plugins, POST /plugins/inspect (no side effects), POST /plugins, PUT /plugins/order, PUT /plugins/{id}, DELETE /plugins/{id}, PUT /plugins/{id}/source, GET /plugins/{id}/source, POST /plugins/{id}/approve, POST /plugins/{id}/trial, GET /plugins/{id}/logs.

• Create, replace and approve:
  • They compile the source first.
  • They write the plugin file and its approved copy (0600, atomic) before the configuration. If the config write fails, the files are restored.
  • Approve reads the file once and accepts it only if its hash equals the hash the caller reviewed.
  • Settings are checked against the manifest and written out in full. On replace and approve, settings that still fit are kept.
• I12. CreatePlugin, ReplacePluginSource and ApprovePluginFile are documented in the endpoint table as not for the desktop webview.
• RequestDetail gains plugins and request_after_plugins, and history rows gain plugin_changed.
• TrialPlugin answers control.plugin.trial_unavailable until the data-plane trial lands. It refuses a changed plugin.
• The CONTROL_API_VERSION note now covers all of this, under 33 (no number change).

Checks

• cargo fmt --all --check
• cargo clippy --workspace --all-targets -- -D warnings, and --lib
• cargo test --workspace
• the ts feature: clippy, tests, export, tsc --strict
• smoke: /plugins and the plugins/ mode are now covered

🤖 Generated with Claude Code