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'sRoutermatches it with the same rules the host used to pick the route and decodes captures.query, the decodedkey=valuepairs 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, alwaysDelegated(user id)for a proxied route and for pre-roll: the authenticated user, never the system. The type also has aSystemcase.
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:
hello'sconfig, a snapshot given to each new instance.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.notifyreadstarget_urlon 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. |