Recipes and named adapters

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

---

Purpose

Let a plugin configure the thing it installed, and the services around it, without letting it become a way to move an operator’s secrets somewhere they did not agree to.

F3 says what a plugin is: data describing a service. That is enough to add a service and not enough to substitute one. The case the whole design exists for — run Plex instead of Jellyfin — needs an account created, a server claimed and a token read back, because the media server is what the request service signs in through. Those are first-run flows, and a manifest that could not express them would describe a container nobody had configured.

So a plugin carries recipes: ordered calls that capture values, feed them into later calls, branch on what came back, and wait when something is not ready yet. Where even that cannot reach, it names an adapter lemonfiber implements, and never supplies one.

This is separated from F3 because it is the part with the risk in it. F3’s manifest describes a container whose reach is fixed by lemonfiber (ADR-0021). A recipe is different in kind: it runs with lemonfiber’s own authority — the credential store, every service in the stack on its loopback port, and the open internet — and it does so on behalf of a manifest a stranger wrote. Shipping it in the same version as the first plugin anything would mean the riskiest mechanism arriving before anybody has operated the simplest one.

Behaviour

A recipe is a sequence, not a program

A recipe is an ordered list of calls. Each may capture values out of a response and name them, substitute values captured earlier into a later call, branch on a status code or a captured value, and wait and retry a bounded number of times when a service is not ready.

There is no arbitrary computation, no loop that does not terminate, no destination worked out while running, and no call assembled out of something that came back. A recipe is powerful enough to create an account, claim a server and read back a token — which is what a first-run flow is — and no more powerful than that.

That bound is not tidiness. It is what makes the next section possible: a sequence this shape has a finite, computable set of things it could do, so the question what would this plugin send, and where can be answered by reading the manifest rather than by running it and watching. Relaxing the bound later would not cost elegance; it would cost the only mechanism that makes recipes safe to offer.

A recipe runs on install, or when it is asked for

Most recipes are first-run flows: the account created, the server claimed, the library pointed at. Those run as part of installing the plugin, after its proofs and the stack’s own checks hold and before it is recorded as installed, and again when it is updated. If one fails, the install goes back like any install that does not hold, and the account says which calls had already landed somewhere it cannot reach back into.

Some are not first-run flows: a re-claim after a token was revoked, a library added after the fact. A recipe says which it is. One that runs on demand runs only when the operator asks for that recipe by name, with a rehearsal, an offer and approvals of its own: what was agreed to at install covers the install, and a demand recipe that carries a value out of the machine is agreed to again, each time it is run. One that fails changes nothing about what is installed, and says what landed. A recipe that says neither runs on install, which is what a recipe is for.

An input is asked for before the yes

A recipe may ask the operator for a value it cannot find for itself: an account name, a token a service printed once. A surface asking for it only once the recipe is running asks at the moment the operator has already agreed, which is too late to decline on the strength of the question. So the plugin reading lists, for each recipe, every input it asks the operator for, with its name, the sentence it asks and whether the value may be a secret, and a surface collects them before the yes (F8-R19). A value given for a secret input is held and used and never shown back, by any reading or any answer.

A credential goes back where it came from

A recipe can bring in a credential lemonfiber already holds, because a first-run flow against a bundled service needs one: signing in to Sonarr to point it at a new download client is done with Sonarr’s own key. It can carry that credential to the service it belongs to and nowhere else — not to another service of the stack, not to a service the plugin itself runs, not out of the machine. A plugin may use a key on the door it opens; it may not take the key away.

What a service answers stays with it

A value a recipe reads out of the answer of a service in the stack belongs to that service, whatever it holds. A token, an id, a path and a sentence all look like text, and nothing reading the text can tell which of them matters somewhere else. A rule holding only what looks like a credential, or what a credential was traded for, leaves every other value free, and a service’s own storage is then a way to carry what it keeps anywhere a pair names. So every capture from a service in the stack is held to that service because of where it came from, not what it holds, and it may go back to that service freely. What a call carrying a credential gets back is held tighter still, as the credential itself is: a session handed over for a key opens what the key opens, so nothing releases it.

Carrying one anywhere else is a release. The pair that carries it says so and says why, in a sentence the operator reads:

[[recipe.pair]]
value   = "library-id"
to      = "sonarr"
release = "Sonarr files new series into the library Komga just made, so it needs that library's id."

The operator agrees to a release at install consent, as itself, the way they agree to a pair leaving the machine. The consent screen names the value, the service it was read from, where it is going and the plugin’s reason. A release frees a capture and never a credential: a value the credential store holds goes to its own service, released or not.

What a recipe may carry is declared as pairs

Declaring the secrets a plugin holds and the hosts it reaches, as two separate lists, describes both halves of a problem and refuses neither. A manifest saying “I capture the media server’s API key” and “I reach plex.tv” has declared everything and still described sending the first to the second.

So the manifest declares pairs: this captured value, to that destination. Every value carries where it came from — a service in this stack, the credential store, the operator, or an external response — and every destination is either a service in this stack or an external host. A flow with no pair behind it is a validation failure, found before anything runs (ADR-0022).

The verbosity is the point. A plugin capturing three values and reaching two hosts has six possible pairs and will want very few of them, and the ones it does not declare are the ones nobody has to wonder about afterwards.

Anything leaving the machine is agreed to, specifically

A pair that carries a value to an external host is stated at the rehearsal in the terms an operator can judge — this plugin will send your media server’s API key to plex.tv — and is approved as itself. Not as a consequence of approving the install: a single yes to an installation is consent to the installation, and the pairs are the one part of a manifest an operator can meaningfully weigh.

Everything else a rehearsal says is about a change to their own machine. This is the only part about something leaving it.

A recipe names, and never addresses

An in-stack destination is named by its service id, and lemonfiber resolves it to the address it already knows. An external destination is named by a DNS name. A manifest carrying an IP literal, a network range or a bare host port is refused.

Without that rule a declared host is a declared host wherever it points, and the machine this runs on sits beside a router’s administration page, a NAS and whatever else the household owns — none of it reachable from outside, all of it reachable from here. Names close the manifest; they do not close DNS, so an external name that answers with a loopback, private or link-local address is refused at the call. The manifest said this destination was outside; an answer from inside contradicts it, and the contradiction is the refusal rather than a thing to be reconciled.

Where data will not reach, a plugin names an adapter

Some flows cannot be honestly expressed as calls and captures. For those a plugin names one of a fixed set of adapters lemonfiber implements and ships — the Servarr-shaped registration flow, and others as they earn their place. The plugin supplies the parameters; lemonfiber supplies the behaviour.

This keeps the awkward cases in code that is reviewed, tested and covered like the rest of the product, while still letting a plugin reach them. The set is published rather than discovered, and naming one that does not exist is a validation failure listing what is available.

On the companion

Anything leaving the machine is agreed to, specifically is the sentence a phone is most likely to break, because a phone is where one large button covering everything is the natural design. The surface that most wants a single Install is the surface that must not have one (N20).

So N20-R2 is written as a prohibition on combining two agreements rather than as a requirement to ask twice. The failure is not a missing prompt — it is a present one that covers more than the operator read it as covering, and a second prompt bolted onto the first would not fix that. N20-R1 carries what the first prompt has to say: which value, and to which host, in terms somebody can weigh.

A recipe names, and never addresses becomes N20-R3 and N20-R4. The app shows the name the manifest gave; a resolved address in its place answers a question nobody asked and hides the one they did, because where is this going is a name rather than a number. And where a name answered from inside the network, the refusal carries its reason — rendered as a network error with a retry, it becomes a button that keeps trying to reach a household’s router.

A recipe is a sequence, not a program becomes N20-R5: the rehearsal lists every step in the order given, and is not summarised into an outcome. Configures Plex has removed the only thing an operator can actually judge. Where a plugin names an adapter, N20-R6 requires the app to say which, and that it is one lemonfiber implements rather than anything the plugin supplied.

States

Edge cases

Acceptance criteria

Related

• ADR-0022 — why pairs rather than lists, and why the check is static
• F3 — what a plugin is, and the manifest these extend
• F4 — the capability a substitution fills once a recipe has configured it
• F6 — the rehearsal the approval happens in
• G8 — the account of what leaves this machine, and the switch a declared reach gets
• plugin-manifest contract — where the blocks these add are declared