Plugins
The manifest
Every plugin.json field, its type, whether it's required, its constraints, and the exact errors a bad value produces.
Where it comes from#
plugin.json sits at the archive root. For a process plugin you don't write it by hand: you keep
plugin.template.json (the same document without version and files) and
cargo xtask package produces plugin.json from it. The manifest is validated in layers, and each
layer produces a different kind of failure:
- Structural parsing. Not valid JSON, larger than 256 KiB, missing a required field, a wrong
type, an unknown top-level key, a
kindother thandata/process, aruntimeother thanwasm, an unknown or emptyscopeslist, a badingestRootsentry, a malformednetwork,memoryMbover 1024, or ani18nblock that breaks the rules below all fail the same way:PLUGIN_BAD_MANIFEST, "plugin.json failed structural validation." No finer reason is given at this layer. The packaging tool runs the same check, so it catches these before you install. - Id and version. Checked separately, with a specific reason each:
PLUGIN_BAD_IDorPLUGIN_BAD_VERSION. - UI and events shape. The
ui.*andeventsblocks are checked field by field, each with its own reason (PLUGIN_BAD_UI_CONTRIBUTIONS,PLUGIN_BAD_UI_CONFIG_PAGES, and so on). - Registration-time semantics, once the archive has already been installed:
pluginApi, thefliksrange, route methods, paths and policies, jobs, permissions, webhooks, the release picker, contribution targets, the i18n namespace, the component itself. A failure here does not undo the install; the plugin is stored withstatus: 'failed'and astatusReasonnaming exactly which rule it broke, so you can fix the manifest and reinstall.
Layers 1-3 run during inspect, before anything reaches the database (see Architecture). Layer 4 runs during register, right after confirm.
Unknown top-level keys are rejected outright, on both tiers, so a typo in a field name fails the install instead of being silently ignored.
Base fields (both tiers)#
| Field | Type | Required | Constraint |
|---|---|---|---|
id |
string | yes | Pattern ^[a-z][a-z0-9]*(\.[a-z0-9]+)*$, lowercase letters, digits and dots only, no hyphens or underscores, at most 51 characters. Reverse-DNS style, e.g. acme.subtitles. The cap keeps the longest name derived from it (the database role fp_<8 hex>_<id>) inside Postgres's 63-byte identifier limit. ui, metrics, sources and import are reserved. |
pluginApi |
number | yes | The contract revision this plugin is written against. Core accepts every value in SUPPORTED_PLUGIN_API_VERSIONS; today that's just 3; a package built for an older value is installed but failed with incompatible-api and the plugin list says to install a pluginApi 3 build. |
name |
string | yes | Display name, non-empty. |
version |
string | yes | Must be valid semver. cargo xtask package writes it from the crate version. |
fliks |
string | yes | A non-empty semver range, matched against the running core version with its prerelease stripped (so a 6.0.0-rc.1 core satisfies >=6.0.0). See the callout below about upper bounds. |
author |
string | yes | Free text; may be empty. |
description |
string | yes | Free text; may be empty. |
license |
string | yes | Free text; may be empty. |
logo |
string | yes | The archived file name, logo.svg or logo.png. |
homepage |
string | no | The only identity field that's optional. |
kind |
"data" | "process" |
yes | Picks which of the two shapes below applies. |
ui |
object | no | See UI extensions. |
events |
array | no | Webhook subscriptions. Honoured for a data plugin only; see Data plugins. A process plugin receives every domain event and ignores the list. |
i18n |
{ locale: { key: string } } |
no | See the i18n rules below. |
Core does not refuse a fliks range that has no upper bound (">=6.0.0" installs fine on a
manual upload). Give it one anyway, ">=6.0.0 <7.0.0", never a bare lower bound: the official
catalog's own submission check refuses a range without one, and a plugin that has never been
checked against a future major will be the first thing that breaks when it ships.
Process-only fields#
A data manifest may not carry any of these; a process manifest must carry all of them except
where marked optional.
| Field | Type | Required | Constraint |
|---|---|---|---|
runtime |
"wasm" |
yes | The only legal value. |
memoryMb |
number | yes | The cap on each instance's linear memory, in MiB, at most 1024. All live instances of one plugin together may hold at most twice this. A memory.grow past the cap traps that instance. |
files |
{ path: sha256 } |
yes | sha256 of every archived entry except the manifest and its own signature: plugin.wasm and the logo. cargo xtask package computes it. |
database |
{ schema: boolean, coreRefs: string[], secrets?: [...] } |
yes | Whether the plugin wants its own Postgres schema, which core tables it needs REFERENCES grants on, and which stored values are credentials. See below. |
routes |
array of { method, path, policy, objectGuard? } |
yes, may be empty | Every HTTP route core will proxy to this plugin. A route not declared here does not exist, full stop. |
scopes |
array | yes, non-empty | Which host-function groups this plugin may call. Table below. |
ingestRoots |
array of strings | yes, may be empty | Absolute path prefixes library_ingest is allowed to take files from. Each must be absolute, already normalised (no .., . or //), and not a filesystem root (/ or C:\). A drive-letter path is read as a Windows path. |
jobs |
array of { name, cron, triggerable, labelKey } |
no | Named cron entries core schedules and dispatches. At most 16. |
permissions |
array of strings | no | Raw names; core builds the CASL subject as plugin:<id>:<name>. |
network |
{ "internal": true } |
no | Lets the plugin's outbound requests reach private addresses (a download client on the LAN). Any other shape is refused. The install consent sheet is the grant. |
checklist |
array of strings | no | Accepted and silently ignored; core reads nothing from it. |
database#
schema is a boolean. If it is false, coreRefs must be empty, or registration fails with
db-provision-failed. Each coreRefs name must match ^[a-z_][a-z0-9_]*$, be at most 63
characters, and appear once.
secrets (optional) lists the credentials the plugin stores in its own tables, so an export can
leave them out: an array of { table, column, jsonPath? }. Without jsonPath the whole column is
masked. With it, jsonPath is a dotted path of object keys inside a json, jsonb or JSON-text
column (* walks the elements of an array and may not be last). A malformed entry or an unknown
key is PLUGIN_BAD_MANIFEST. See
Storage and database.
routes[]#
| Field | Constraint |
|---|---|
method |
One of GET POST PUT PATCH DELETE HEAD OPTIONS, case-insensitive. |
path |
Starts with / and must parse as a path-to-regexp v8 pattern: :name matches one non-empty segment, *name the rest. Matching is case-insensitive, accepts one trailing /, and percent-decodes captured values. |
policy |
"<action>:<Subject>", split at the first colon. action is one of manage create read update delete approve decline grab track. Subject is one of the closed core set (User, Media, FliksRequest, QualityProfile, LanguageProfile, SubtitleProvider, SubtitleFile, TranslationProvider, Library, Playlist, Settings) or this plugin's own plugin:<id>:<name> subject, where <name> is one of this same manifest's declared permissions. |
objectGuard (optional) |
"<guard>:<paramName>". Exactly two guards exist: libraryAccessible and mediaAccessible, each checking the numeric path param against the requesting user's accessible libraries or media. <paramName> must actually appear in path, and the value must be a canonical positive integer. |
No two routes may share the same method and path (duplicate-route). A route that one of core's own
/api/plugins/:id/... routes would shadow is refused (invalid-route-path): GET /logo,
GET /export, and POST /import, /enable, /disable, /restart, /events/test. A pattern with
a parameter, such as /:page, stays legal.
scopes[]#
| Scope | Host functions it unlocks |
|---|---|
media:read |
media_acquisition_context, media_resolve, media_exists, media_resolve_or_create (it tells which titles exist), and (because both answer with media identity across the whole library) acquisition_candidates and releases_match |
media:create |
media_resolve_or_create (with media:read): adds a title to a library when none holds it, and adopts and approves the pending requests for it. An update that newly declares it waits for an admin. |
acquisition:candidates |
acquisition_candidates, releases_match |
releases:score |
releases_score |
ingest:write |
library_ingest |
events:emit |
events_publish, notifications_dispatch_grab_started, events_emit_own, counts_set, progress_set |
config:rw |
config_get, config_set |
notify:users |
notify_users: send a push notification to users. The admin sees the scope at install. See Sending notifications |
Calling a host function without every scope it needs fails with ERR_DENIED, plugin "<id>" is missing scope "<scope>" required for "<method>". Declare every scope every function you call
needs; there's no partial grant within one function. db, log, schedule_call, cancel_call
and deadline_remaining_ms need no scope. Scopes are consented once at install and written from
the manifest by a confirmed install only: boot, enable and restart never change them.
jobs[]#
| Field | Constraint |
|---|---|
name |
Non-empty, unique within this manifest, and not one of core's own job names or another plugin's. |
cron |
Five fields, or six with a leading seconds field, or an @ nickname. Evaluated in the server's time zone. |
triggerable |
Boolean: whether an admin can run it on demand from the scheduler page. |
labelKey |
Non-empty i18n key shown on the scheduler page. |
permissions[]#
Each entry must match ^[a-z][a-z0-9_-]{0,63}$ and be unique. Every distinct action:subject
policy your routes[] declare under a given permission name becomes its own tick box in the roles
editor (so read:plugin:<id>:queue can be granted separately from
manage:plugin:<id>:queue); a declared name no route mentions is offered whole and grants every
action once ticked. Nothing is granted by default: until an admin ticks a box, only admins pass the
routes declared under it.
The i18n block#
"i18n": {
"en": { "acme.settings.title": "Settings", "acme.settings.hint": "..." },
"fr": { "acme.settings.title": "Paramètres", "acme.settings.hint": "..." }
}- Every key must contain at least one dot; a bare
"title"is refused. - No key may be a dotted ancestor of another declared key (
acme.configalongsideacme.config.titleis refused). - Every key across every locale must share exactly one root segment (here,
acme). It does not have to equal or derive from the plugin's ownid. - Breaking any of the three rules above refuses the archive with
PLUGIN_BAD_MANIFEST. - At registration, that root is claimed: a second plugin declaring the same root fails with
i18n-namespace-conflict; whichever plugin loaded first keeps it.
Full validation error reference#
Archive-level refusals (PLUGIN_BAD_MAGIC, PLUGIN_TOO_LARGE and the rest) are listed in
Packaging and signing.
| Code / reason | Meaning |
|---|---|
PLUGIN_BAD_MANIFEST |
The structural layer above: not valid JSON, a required field missing, an unknown top-level key, a wrong kind or runtime, and so on. |
PLUGIN_BAD_ID |
id fails the pattern, exceeds 51 characters or is reserved. |
PLUGIN_BAD_VERSION |
version isn't valid semver. |
PLUGIN_BAD_UI |
ui is present but isn't an object. |
PLUGIN_BAD_UI_CONTRIBUTIONS |
A ui.contributions[] entry is missing id, slot, labelKey, a numeric weight, or an action object with a string kind. |
PLUGIN_BAD_UI_CONFIG_PAGES |
A ui.configPages[] entry is missing what its kind requires (see UI extensions), or a group page item nests another group inside it. |
PLUGIN_BAD_UI_RELEASE_PICKER |
ui.releasePicker isn't a map of kinds to levels (work, group, item) of {search, grab} routes. |
PLUGIN_BAD_EVENTS |
An events[] entry is missing a string event or webhook. |
PLUGIN_TIER_VIOLATION |
A data archive carries plugin.wasm, or a process archive doesn't. |
PLUGIN_UNSIGNED |
A process plugin isn't signed by the official key and Allow unsigned plugins is off. |
PLUGIN_FILE_SET_MISMATCH |
The manifest's files keys don't match the plugin.wasm plus logo entries in the archive. |
PLUGIN_BAD_WASM |
plugin.wasm doesn't start with the WebAssembly component preamble. |
PLUGIN_HASH_MISMATCH |
An entry's sha256 doesn't match what files declares for it. |
PLUGIN_BAD_LOGO |
The logo's bytes don't match its claimed format, or an SVG logo carries a <script>, an event-handler attribute, or a javascript: URI. |
PLUGIN_SIGNER_CHANGED (409) |
An upgrade over a package that was signed by a key must carry the same key. |
PLUGIN_KEPT_DATA_SIGNER (409) |
The plugin's kept data was left by a different signer than this package. Uninstall with the data deleted first. |
PLUGIN_DENIED (403) |
A catalog denyList entry matches this package. |
(registration, not install) untrusted |
The archive's signature no longer verifies against the specific key that verified it at install. |
revoked |
A denyList entry (see Publishing) matches this exact package. |
incompatible-api |
pluginApi isn't in SUPPORTED_PLUGIN_API_VERSIONS. |
incompatible-fliks |
The fliks range doesn't match the running core version. Bypassable with the admin setting Ignore the required Fliks version; incompatible-api never is. |
invalid-webhook-event / unknown-webhook-setting / invalid-webhook-url / insecure-webhook-scheme / internal-webhook-host |
One of the events[] entries is malformed: an unknown event name, a setting:<key> naming no declared form field, an unparsable or non-https URL, or a URL whose host is an internal/private IP literal. |
invalid-release-picker |
A releasePicker search or grab route isn't declared in routes[] with the right method. |
invalid-player |
ui.player.preRollRoute isn't a declared POST route. |
invalid-ui-contribution |
A contribution's own route opens /plugins/... or /admin/settings/plugins/... for a page id this same manifest doesn't declare. |
i18n-namespace-conflict |
This manifest's i18n root is already claimed by another installed plugin. |
invalid-permission |
A permissions[] entry fails its pattern or is duplicated. |
invalid-job-name / job-name-conflict / invalid-job-cron / invalid-job-triggerable / invalid-job-label |
A jobs[] entry is malformed, one field at a time, or there are more than 16. |
invalid-route-method / invalid-route-path / invalid-route-policy / invalid-route-object-guard / duplicate-route |
A routes[] entry is malformed, one field at a time. |
network-not-granted |
The manifest asks for network.internal and the install consent did not grant it. |
invalid-component |
plugin.wasm doesn't compile, or isn't a component of the plugin world. |
db-provision-failed |
The plugin's Postgres role/schema couldn't be created, or a declared coreRefs table/column doesn't exist. |
manifest-mismatch |
The id, version or pluginApi the component reports in hello differs from the signed manifest. |
spawn-failed |
The first instance didn't come up: hello or start errored or timed out, or start is still running after 15 seconds. |
tampered |
The stored archive no longer matches the signed files hashes. |
Any reason other than disabled, tampered, db-provision-failed, spawn-failed,
incompatible-fliks, incompatible-api, network-not-granted, manifest-mismatch or
invalid-component tears the plugin's routes, contributions, permissions and jobs down entirely;
those instead leave the plugin "installed but not running", so a request to one of its routes gets
a 503 rather than acting as if the plugin never existed.
A worked example#
The manifest in Your first plugin is the minimum that satisfies every
process-tier rule above. For every field in real, production use at once, read
Examples, which walks through fliks.download's full manifest field by field.
Proposing a new extension point#
Everything a plugin can reach, the host functions, the scopes, the UI slots, the routes a manifest may declare, is a closed set on purpose: a closed set is what makes a plugin's blast radius reviewable, and what lets core promise a plugin keeps working across a release. "Can my plugin do X?" has no answer an author can reach alone when X isn't already in one of those sets; that's a core change, proposed as an issue that says:
- What the plugin is trying to do, as a user-visible outcome, not the API you imagined for it.
- What you tried within the existing set, and where it stopped.
- What core would have to trust you with: a new host function is a new scope, or a widening of one, say which, and what a hostile plugin holding it could do.
- Whether it can avoid a break.
pluginApiis a single integer, and core links one WIT package version per value, so any change to a record or a function, an added field included, bumpspluginApi. Core accepts only the values it lists (SUPPORTED_PLUGIN_API_VERSIONS, today[3]), and a plugin declaring any other is installed butfailedwithincompatible-api, which is why a change that needs a new value waits for a scheduled break.