Every part is a plugin

Status: Accepted · Audience: Operator · Area: F — Extensibility

---

Purpose

Let a household run what it chooses, in every part of its stack, and have what it chose work as fully as the part it replaced. Plex instead of Jellyfin means members still sign in through the request service, still see their own shelves under their own limits, still play through the guarded door on their phones, and still pick up where they left off. Traefik instead of Caddy means every household name still answers. A guard of the operator’s choosing means the same cases are still refused.

The model since F3 and F4 can settle a plugin as the filler of a capability, but it cannot make the plugin work. Behaviour lives in adapters compiled into the core, and the core names the parts it ships. This feature moves every part’s behaviour behind a published contract, so the core holds no code for any service, and every part, first-party or not, is a plugin (ADR-0041).

Behaviour

A capability is a contract

Each capability the vocabulary names has a published, versioned contract: HTTP and JSON, generated from the core’s port types the way the web API’s documents are. The contract is what the core asks of whatever fills the capability. For the media server, that is the household’s accounts and limits, setup, titles and seasons, what a member was part-way through, the grant, progress, the byte guard and the locations a member is given. A service says which contracts it speaks, and the core holds one client per contract and nothing about any product.

A part is its upstream and its adapter

A plugin that fills a capability brings two containers. One runs the upstream, such as Plex’s server. The other is the plugin’s adapter, which speaks the contract and translates to the upstream. The adapter’s code runs in its own container, never in lemonfiber’s process (F3-R6). The core reaches it with a key minted for that plugin alone, on a network shared only by the core, the adapter and its upstream. Every answer is held to the contract’s schema and bounded in size and time, and anything else is refused.

The bundled parts are plugins too

Jellyfin, the curators, the download clients, the indexers, the request service, the subtitle fetcher, the proxy, the dashboard, the egress guard, the helpers and lemonfiber’s own guards are each a first-party plugin in a repository of their own. They are installed, updated, removed and validated the way any other plugin is. The bundle says which first-party plugin fills each capability until the operator chooses otherwise, and it travels inside the binary, so a first install needs no network.

A part has its repository before it has its adapter. A part without one is assembled by the bundle into the stack lemonfiber ships, as a stack service reached through its in-process adapter and filling its capabilities through its claims; the release whose bundle installs it moves it in place and deletes that adapter (ADR-0045, bundle).

Every part has a capability, and something asks for it

The proxy, the dashboard, quality sync, archive extraction, the stream guard, decline and the request gate join the vocabulary. Every capability is asked by something in the bundle or by the core over its contract, so every part has a slot a substitute can fill: the core asks quality sync, archive extraction, the stream guard and decline, which no service of the bundle queries (ADR-0051), and applies the dashboard’s panel list (ADR-0052). A plugin may ask for capabilities too, which lets a substitute stand in for a part that itself asks. No plugin links to another by name.

A plugin’s service asks in the manifest’s [[ask]], naming a core capability and, where it wants every service that fills it rather than one, each. Nothing in an ask can name the service that answers it. A plugin’s ask is settled as the stack’s own asks of that capability are: against everything installed that claims it, by the operator’s choice, and otherwise by the stack’s own choice. A credential reaches the asker only through the gate in Credentials between plugins. The wiring lists a plugin’s asks after the stack’s, each naming the plugin. An install or update states what each of its asks would reach before it acts.

The guard follows the media server

The media server’s filler declares how its bytes are guarded: which paths carry them, what question decides whether a session may have them, which paths are refused without asking, which query parameters name another item, and in what form a member’s token is presented. The stream guard’s filler enforces exactly that, with the one proxy address it trusts and where it asks the core about a live-stream pass beside it. Every location a member is given, the stream and the pictures alike, is built from templates the filler declares, so a member’s app works the same against any media server.

A substitution replaces

Choosing a filler stops the part it replaces and takes it out of its form. Its data stays where it was, so undoing the choice brings it back as it was. The rehearsal says what does not carry over: accounts the old media server held are not accounts on the new one, and progress stays where it was recorded. Asking the household’s members back is offered as part of the change.

The egress guard’s shape

The egress guard needs to manage the network and open a tunnel, which no other plugin may do. The upstream an egress guard adapter fronts may declare shape = "egress-guard", and the core writes its entry as every plugin’s entry with network administration and the tunnel device added and nothing else. A first-party egress guard the bundle assembles is one service that provides the capability itself and takes the shape, and only the assembly honours that form. The adapter stays unprivileged. The reading names each service taking the shape, and the operator approves each one apart from the offer, on every install and update that takes it. It is one of a closed set of named shapes, beside the media server’s render for hardware transcoding (plugin-manifest).

Each slot is proved by a substitute

Every capability has a substitute beside its first-party filler, built to the same contract and run end to end against its pinned upstream: installed, its first-run flow run, held to the conformance suite, substituted, the features its capability serves exercised, and undone.

Credentials between plugins

Wiring hands credentials from one part to another: a curator’s key to the subtitle finder, the media server’s to the request service. A credential lemonfiber holds reaches a plugin’s service only where it is that plugin’s own, or where the plugin is first-party and the credential is the stack’s or another first-party plugin’s.

A plugin is first-party only where this build embeds it in its first-party set: its id, the digest of its manifest and the digest of its tree, as the signed default bundle names them at the release the build pins. Anything else is third-party however it was installed, a reviewed catalogue entry included. Until the bundle is embedded, the set is empty and nothing is first-party.

A third-party substitute may be granted one named credential for a capability it fills. The grant is part of the install or update offer and needs the operator’s approval; it is journalled, can be revoked, and is shown on the credentials surface. Without a grant, nothing crosses to it.

States

Edge cases

Acceptance criteria

Related

• ADR-0041: the decision this feature carries out
• F3: plugin manifests, and code that never runs in lemonfiber’s process
• F4: the capability vocabulary, fillers and substitution
• F8: first-run flows, which capture what an adapter is given
• F9: the bundled parts’ capabilities, which become first-party plugins
• D11: the guard and the locations a member is given