Plugins
Architecture
The plugin lifecycle from install to running, the wasm sandbox, the core-to-plugin interface, and how UI contributions reach the client.
The lifecycle, end to end#
| # | Step | What happens |
|---|---|---|
| 1 | Upload or catalog fetch | An admin uploads a .fkplugin archive, or picks a version from a configured catalog. Either way the bytes reach core as one ZIP buffer. |
| 2 | Inspect | Core runs the archive through a fixed set of guards (legal entry names, size caps, Ed25519 signature, manifest shape) and, if it passes, stages the bytes on disk. At most 5 staged archives exist at once and an hourly sweep removes any older than an hour. Nothing is written to the database yet. |
| 3 | Consent | The admin sees the plugin's identity, its trust level (official, unverified, unsigned) and everything it's asking to be able to do, and must explicitly acknowledge anything short of official trust. |
| 4 | Confirm | The staged archive is re-inspected byte for byte, and for a process plugin that asks for a schema a Postgres role and schema are provisioned. The archive and its manifest are stored in the database. |
| 5 | Register | Core validates every semantic rule a manifest must satisfy (pluginApi, the fliks range, routes, permissions, jobs, UI targets, i18n namespace) and, for a process plugin, compiles the component, runs the hello handshake and starts it. |
| 6 | Running | A data plugin is simply registered: its declarations are live. A process plugin is ready once its start call returns, and is monitored from then on. |
| 7 | Disable | The plugin's instances are stopped and every live registration (routes, UI contributions, jobs, webhooks) is dropped. The stored archive, its database role and schema, its data directory, its settings and its pending scheduled calls stay. |
| 8 | Enable | Registers again from the stored archive; for a process plugin, starts it again. |
| 9 | Upgrade | A newer version is inspected and confirmed like a fresh install, over the existing row. A plugin that was disabled stays disabled after an upgrade. A version lower than the installed one is allowed and logged. |
| 10 | Uninstall | The registration is torn down and the plugin's plugin.<id>.* settings, pending scheduled calls and granted scopes are deleted. Its Postgres schema and data directory are kept unless the admin also ticks Also delete this plugin's data; a reinstall finds them again. |
Uninstalling deletes the plugin's settings. Export first if you want them back (see Storage and database).
Every operation that changes one plugin (install, upgrade, enable, disable, restart, uninstall,
import, auto-update) takes that plugin's lock, so two racing operations on the same id are
serialised. A restore of a server backup refuses them with PLUGIN_BUSY until it ends.
The sandbox#
A process plugin is a WebAssembly component. Core compiles it with wasmtime and runs it in the
server's own process; there is no child process, no socket and no uid involved. The component only
has what the host links in:
- Compilation. The archive stored in the database is hashed at every load and the component is
compiled from those bytes. Compiling is slow for a large component, so it runs in a short-lived
child of the server and the result is cached under the runtime directory
(
FLIKS_RUNTIME_DIR, by defaultplugins/under the data directory), authenticated against a hash recorded in the database. A boot normally loads the cache and never compiles. - Network. No sockets. Outbound HTTP goes through
wasi:http, and core vets every request:httpandhttpsonly, the name resolved once and every returned address checked, no redirect followed on the plugin's behalf, at most 32 requests per plugin in flight. Private ranges are refused unless the manifest declaresnetwork: { "internal": true }and an admin consented at install; reserved, multicast and link-local (cloud metadata) ranges stay refused either way. - Filesystem. One directory,
/data, private to the plugin and kept across restarts and upgrades. Nothing else is visible. - Environment. Empty: no variables, no arguments.
- Database. Its own role and schema, through the
dbinterface only. - Memory and time.
memoryMbcaps each instance's linear memory, all live instances of one plugin together may hold at most twice that, and every call has a wall-clock deadline. A trapped, out-of-memory or overdue instance is dropped; core and the other plugins are unaffected. - Host functions. A fixed set of calls, each bound to the calling plugin's id and checked
against the
scopesit declared.
The full deadline and limit table is in Process plugins.
Instances and supervision#
A WebAssembly instance runs one call at a time, so core keeps several per plugin, grouped in lanes so that a slow job never delays a health check:
| Lane | Instances | Calls |
|---|---|---|
core |
exactly 1 | hello, start, health, config-changed, shutdown |
event |
1, created at the first event | event, in arrival order |
http |
0 to 4 | proxied routes and pre-roll |
| one per declared job | 1 each, created at its first run | job |
scheduled |
0 to 2 | scheduled |
Idle http, job and scheduled instances are dropped after 10 minutes and recreated on demand.
No state that matters lives in an instance: it lives in the plugin's schema, its /data, or a
scheduled call.
- Handshake.
hello(core-version, config)must answer within 10 seconds with the plugin'sid,versionandpluginApi. Core compares all three for exact equality with the signed manifest. A mismatch is deterministic, so nothing retries: the plugin isfailedwith reasonmanifest-mismatch. - Start.
startruns once afterhello, whenever the plugin has no other live instance. It runs the plugin's migrations and re-arms its own background work. The plugin isreadyoncestartreturns; core waits up to 15 seconds for that when installing, enabling or booting, and reportsspawn-failed(still starting) if it isn't, while the plugin keeps starting. Astartmay take up to 15 minutes. If core's own database was unreachable duringstart, the plugin isdegradedandstartis retried until it succeeds, with no crash counted. - Health. The
coreinstance getshealthevery 15 seconds with a 10 second deadline. A reply ofok: falseor a timeout is a miss. Two consecutive misses mark the plugindegraded(its routes answer 503 and it leaves the UI); four drop the instance and count a crash. A good reply recovers it. A health call that traps is a crash at once. - Crash and backoff. A crash drops only that instance. Its lane creates a new one after a delay
that climbs 1s, 2s, 4s, 8s, 16s, then holds at 30s; 120 seconds of continuous
readyresets the ladder. Six crashes inside a rolling 10-minute window trip a circuit breaker: every instance is dropped, the plugin isfailed, and it stays that way until an admin restarts or re-enables it. - Stop.
shutdownis called on thecoreinstance with a 3 second deadline, then every instance is dropped. WebAssembly has no signal to send, and pending events are discarded.
A guest Err result from http, job or scheduled is not a crash. A trap, an out-of-memory
trap and a missed deadline are.
The interface between core and a plugin#
The contract is a WebAssembly interface (WIT) package, fliks:plugin@3.0.0, shipped in the
fliks-plugin-sdk crate. The SDK generates the bindings, so a plugin never writes wire code.
| Direction | Interface | Contents |
|---|---|---|
| Core calls the plugin | guest |
9 exports: hello, health, start, http, event, config-changed, job, scheduled, shutdown. |
| The plugin calls core | host |
The scope-checked functions: media and acquisition reads, release scoring, library ingest, event publication, counts, progress, settings, scheduled calls, deadline-remaining-ms. |
| The plugin calls core | db |
query, execute, migrate on the plugin's own schema. |
| The plugin calls core | log |
One line at a level, tagged plugin:<id> in core's log. |
| The plugin calls core | wasi:http |
Outbound requests, vetted as described above. |
Core links one package version per pluginApi value, so any change to a record or a function is a
new pluginApi; today that is 3.
Every signature is in SDK reference.
How a UI contribution reaches the client#
- A plugin's manifest declares
ui.contributions(nav entries, menu rows) andui.configPages(settings pages), described fully in UI extensions. No Angular ships with a plugin; it only ships data. - At registration, core validates every UI-facing rule the manifest must satisfy: a route opening
one of the plugin's own pages must point at a page the same manifest actually declares, the
i18nroot namespace can't collide with another plugin's, and so on. - The Fliks client calls
GET /api/plugins/uiat app boot, and again after an install or an enable/disable toggle, and caches the result in a registry service. The response is one entry per currently active plugin: its contributions, its config pages, its translated strings, and (if it won the tie-break) its release-picker declaration. Aprocessplugin only appears in that response while it isready; a plugin that has become unavailable simply isn't in the list, so a client never has to reason about a half-working plugin. - Per-viewer filtering happens on that same call: a
tableorproviderspage is only included if the requesting user's permissions would actually let them call the route it lists from, and any nav entry or menu row that only opens a withheld page is withheld with it. - The client renders each slot with its own existing component (there's no generic "plugin slot" widget): nav entries go into the sidebar/nav bar, settings pages get their own section in the admin sidebar named after the plugin, and menu rows join the card and detail-page action menus next to core's own entries, sorted by weight. See UI extensions for the full mapping.
whenpredicates (isAdmin,hasPermission:...,mediaType:movie, and so on) are evaluated entirely client-side from state the client already has; an unrecognised predicate always evaluates to false, so an older client hides a row it doesn't understand rather than guessing. None of this is a trust boundary: every route a plugin's UI opens is still checked server-side.
Updates#
| Trigger | Cadence |
|---|---|
| Catalog refresh | Once a day at 03:00 server time, plus on demand from Manage sources. A source that has never been fetched, or whose cache is older than 6 hours, is also refreshed once at boot, without delaying startup. |
| Auto-update | Runs right after the daily catalog refresh, if the admin setting Update plugins automatically is on (it is, by default). For each installed plugin it takes the newest version any enabled source offers and installs it only if that version is signed by the official release key (official trust). It skips a version that asks for network.internal the plugin was not granted, and holds one that asks for new scopes (shown as a held update on the plugin list until an admin installs it by hand). If the new version does not come up active, the previous archive is installed again and the version is held as failed. |
| Manual update | Identical to a fresh install: inspect, then confirm, of a version newer (or, with Allow installing older versions on, older) than what's installed. |
An upgrade over an installed plugin that was signed by a key must carry the same key
(PLUGIN_SIGNER_CHANGED, 409); uninstall with the data deleted first to switch signer.
Revocation (a catalog's denyList) reaches an already-running plugin the moment its catalog
refreshes, stopping it immediately rather than waiting for a restart; see
Publishing for the full mechanics.
Trust, at a glance#
| Trust | What it means | What triggers it |
|---|---|---|
| Official | The archive's plugin.json is signed by a key core has compiled in (release-2026). |
The plugin was packaged and signed by the Fliks catalog. |
| Unverified | Signed, but not by a key core recognises. | Any other syntactically valid signature: a plugin signed with its author's own key, for instance. |
| Unsigned | No signature at all. | Packaged locally with cargo xtask package and no --key, or a source that ships archives unsigned. |
A process plugin that is not official is refused with PLUGIN_UNSIGNED unless the admin turned
on Allow unsigned plugins (plugins.allow_unsigned), which exists for local development. That
covers unverified as well as unsigned: core has no registry of third-party signing keys. A
data plugin installs with any trust level, behind the explicit acknowledgement in the consent
step. Pinning a key on a source verifies that source's catalog document only; it never makes the
archives it lists official. See Packaging and signing for what
is signed and how, and Publishing for how a catalog earns official trust
for what it lists.