Plugins

Process plugins

The process-tier runtime contract in full, entry point, exports, config, logging, crashes and the deadlines core enforces.

The entry point#

A process plugin is one Rust crate built as a cdylib for wasm32-wasip2 against the fliks-plugin-sdk crate. You implement the Plugin trait, which has one method per guest export, and call fliks_plugin_sdk::export!(YourType) once. Every method has a default, so a plugin implements only what it uses. The component carries everything it needs: there is nothing to install next to it, and the archive holds just plugin.wasm, the manifest and a logo. See Your first plugin for a complete crate and SDK reference for every type.

hello is not on the trait. export! answers it for you with the id and pluginApi from the crate's plugin.template.json and the version from CARGO_PKG_VERSION, and core compares the three with the signed manifest.

The 9 exports#

Export Plugin method Called Deadline Behaviour
hello generated by export! Once per new instance 10 s Receives the core version and the plugin's settings (keys without the plugin.<id>. prefix) and answers { id, version, plugin-api }. A mismatch with the signed manifest fails the plugin with manifest-mismatch and nothing retries.
start start() -> Result<(), String> Once after hello, whenever the plugin has no other live instance 15 min Run migrations here and re-arm background work. The plugin is ready once it returns. An Err is a crash, unless a db call in it failed unavailable: then the plugin is degraded and start is retried.
health health() -> HealthReport Every 15 s on the core instance 10 s { ok: bool, detail: Option<String> }. ok: false counts like a timeout. The default answers ok.
http http(HttpRequest) -> Result<HttpResponse, String> Once per proxied request to a declared route 180 s See below. An Err answers 503.
event event(name, payload) A domain event, no reply 60 s payload is the event as JSON text. Every ready process plugin gets every domain event; ignore what you don't care about.
config-changed config_changed(keys: Vec<String>) After an admin saves one of your settings none of its own Names the unprefixed keys that changed, never the new values; call config_get. It reaches every live instance before that instance's next call.
job job(name, job_id, args) -> Result<(), String> A cron tick, or an admin's manual trigger, for a job this manifest declared 60 min job_id is a fresh UUID. A returned Err is only logged, never retried automatically.
scheduled scheduled(key, payload, attempt) -> Result<(), String> A durable delayed call you made with scheduled::schedule 5 min At-least-once, so the handler must be idempotent. See below.
shutdown shutdown() Before the instances are dropped 3 s Flush what you must; the instance is dropped right after.

Proxied routes: http#

Core serves a plugin's declared routes under /api/plugins/<id>/.... A request goes through, in order: authentication (401), the declared route (403 when none matches), the caller's ability against the route's policy (403), the objectGuard (403), then the live check: a plugin that is not ready, degraded included, answers 503 PLUGIN_UNAVAILABLE.

HttpRequest carries:

  • method, as sent.
  • path, the raw sub-path after /plugins/<id>, percent-encoded, query excluded. The SDK's Router matches it with the same rules the host used to pick the route and decodes captures.
  • query, the decoded key=value pairs in order, repeats kept.
  • body, the request's JSON text as bytes. No body is {}. Malformed JSON, or more than 100 kB, is answered by core before the plugin is reached.
  • principal, always Delegated(user id) for a proxied route and for pre-roll: the authenticated user, never the system. The type also has a System case.

HttpResponse is { status, headers, body }. Core sets Cache-Control: no-store first (a plugin may then set its own cache-control) and X-Content-Type-Options: nosniff plus Content-Security-Policy: sandbox on every answer, which a plugin cannot override. Only these headers pass: content-type, content-disposition, cache-control, etag, last-modified (Set-Cookie, Location and Authorization can never be set). Content-Type defaults to application/octet-stream; the SDK's Response::json sets application/json. A status outside 100 to 599 is answered 502.

Failures: a guest Err, a trap or any other failed call answers 503 PLUGIN_UNAVAILABLE; a timeout answers 504 PLUGIN_TIMEOUT and drops the instance that ran the call. Requests wait in a queue of 32 for at most 30 seconds for a free instance (the deadline of 180 s starts when the call starts), and a full queue answers 503 at once.

Config and settings#

A plugin reads its own plugin.<id>.* admin settings two ways, both with the prefix stripped:

  1. hello's config, a snapshot given to each new instance.
  2. host::config_get(keys), a live host call that always returns the current value. This is the pattern to prefer: both real plugins call it at the point of use, so a setting an admin just changed is honoured on the very next thing that reads it. fliks.notify reads target_url on every delivery.

A setting is owned by the installed plugin whose id is the longest plugin.<id>. prefix of its key (ids contain dots, so fliks is a prefix of fliks.download). config_get returns only keys the caller owns, and config_set of a key it doesn't own is ERR_DENIED. config_set writes through the settings service; the writer gets no config-changed echo for its own write. A setting marked secret: true on a form page is stripped from the settings read API, but config_get returns it in clear.

Events, jobs and scheduled calls#

Events. Delivery is fire-and-forget and at-most-once, through a ring of 64 per plugin drained in order by the event lane. When it is full the oldest event is dropped and eventDropCount rises. The events[] manifest key is ignored for a process plugin.

Jobs. jobs[] are cron entries core runs as job calls on that job's own instance, with no overlap per job: a tick or trigger of a job that is still running is skipped with a warning, or answers 409 already running to an admin. A plugin that is not ready skips its ticks. Different jobs run concurrently. A triggerable job can be run from the scheduler page or POST /api/commands.

Scheduled calls. A guest holds no timer between calls and may be dropped at any time, so durable delayed work is a host service. scheduled::schedule(key, delay_ms, &payload) stores one pending call per key (a second call with the same key replaces the first, which is the dedupe); scheduled::cancel(key) removes it. Core runs it as scheduled(key, payload, attempt) after the delay, and the call survives restarts, disable and upgrade (an uninstall deletes it). Limits: key 1 to 128 characters, delay at most 30 days, payload at most 64 KiB, at most 10 000 pending calls and 16 MiB of payload per plugin, else ERR_VALIDATION. Delivery is at-least-once: an Err, a trap or a timeout leaves the call to fire again, with an increasing attempt, and after 20 attempts it is dropped with an error log. Because pending calls outlive an upgrade, a handler must accept payloads written by an earlier version of the plugin. The plugin's own backoff policy lives in the handler, which re-schedules itself with a new delay; fk-plugin-notify is built this way (see Examples).

Logging#

Use the SDK's debug!, info!, warn! and error! macros. They send one line per call to core, tagged plugin:<id> in its log viewer, and scrub every scheme://user:pass@ into scheme://***:***@. Anything written to stdout is logged at info; stderr at error, or warn when the line starts, after optional [tag] prefixes, with WARN. Output is capped at 64 KiB per minute across the three; past that, lines are dropped for the rest of the minute with one warning. Pass any URL you log through fliks_plugin_sdk::log::redact_url, which also drops the query and fragment.

Budgets inside an export#

A guest budgets its own work so it can stop cleanly before core abandons the call. host::deadline_remaining_ms() returns the milliseconds left in the export it is called from, and rt::Budget::host() wraps it. The SDK gives a margin under each host deadline in rt::budgets: HTTP 150 s, EVENT 50 s, SCHEDULED 4 min and JOB 50 min. fk-plugin-download sets one on entry to each export and ends every outbound request by its own timeout or the budget, whichever comes first.

Crashes, backoff and the circuit breaker#

The full state machine and its thresholds are in Architecture. One thing worth restating here because it changes how you read a stuck plugin: six crashes inside a rolling 10-minute window trip a permanent circuit breaker. Core stops recreating instances, the plugin's row shows Failed, and it stays that way until an admin disables and re-enables it, installs an upgrade, or calls POST /api/plugins/<id>/restart. If your plugin is crash-looping during development, fix the crash rather than waiting it out.

A crash is a trap, an out-of-memory trap, a missed deadline, a trapped health, a failed hello, a start that returns Err, or four consecutive failed health checks. A guest Err from http, job or scheduled is not a crash.

Environment and filesystem#

The guest sees no environment variables and no arguments. Configuration arrives through hello and config_get.

One directory is visible, /data, preopened read-write. It is keyed by your plugin id alone, survives restarts, upgrades and disable/enable cycles, and is deleted only when an admin uninstalls with Also delete this plugin's data. Nothing else on the host filesystem is visible.

Deadlines and limits#

What Value On breach
hello 10 s Crash, instance recreated with backoff.
start 15 min Crash, instance recreated with backoff.
health 10 s, asked every 15 s A timeout is a miss. 2 consecutive misses degrade the plugin; 4 drop the instance.
config-changed none of its own Runs inside the deadline of the call it precedes.
shutdown 3 s Instance dropped.
proxied http 180 s 504, instance dropped.
pre-roll 3 s, queue wait included The item list is omitted.
event 60 s Instance dropped.
scheduled 5 min Instance dropped, the call fires again.
job 60 min Instance dropped.
One host call 8 s, except library_ingest at 30 min ERR_TIMEOUT; the plugin keeps running.
db query / execute 60 s The query is cancelled, SQLSTATE 57014.
db migrate 10 min The call fails.
Outbound requests in flight 32 per plugin The 33rd waits for a slot, inside the call's deadline.
Outbound request, host side connect 10 s, first byte 60 s, between bytes 60 s The request fails; the SDK reports Error::Timeout.
Proxied requests waiting for an instance queue of 32, 30 s 503 PLUGIN_UNAVAILABLE.
Events waiting for the event lane ring of 64 Oldest dropped.
stdout, stderr and log 64 KiB per minute Output dropped for the rest of that minute, once with a warning.
One SQL result 32 MiB ERR_RESULT_TOO_LARGE, query cancelled.
Memory (memoryMb) at most 1024, per instance; twice that per plugin memory.grow past it traps that instance.

Guest CPU is bounded by the wall-clock deadline, enforced by epoch interruption: a guest that spins is interrupted once its deadline passes, and a guest waiting on a host call, a query or a request is reached by the timeout.

Metrics#

GET /api/plugins/metrics (needs the read:Settings permission) reports, per installed plugin, { pluginId, kind, metrics }, with metrics: null for a data plugin (it has no instances) and for a process plugin that isn't currently running, never a row of zeros that reads like a healthy plugin. For a running process plugin, summed over its instances:

Field Meaning
hostCallCount / hostCallFailureCount Every call the guest makes to the host interface. db and log calls are not counted.
hostCallP95Ms p95 duration over the most recent 256 host calls. null before the first call.
restartCount Crashes since this plugin was registered.
eventDropCount Events core couldn't deliver because the plugin's ring of 64 was full.
residentSetSizeBytes The linear memory in use across the instances, read on demand. null when no instance is up.

Edit this page on GitHub

Esc