A plugin after it lands

Status: Accepted · Audience: Operator · Area: N — Companion

---

Purpose

N5 makes installing a plugin a companion act: the catalogue, what vouches for a plugin, an install in progress, a refused one. N20 keeps what a plugin would send off the machine apart from the install that wants it. Neither says what happens next.

F6 does: an install is rehearsed before it is written, verified after, and reversed if either fails; an update is one account and one reversal; a removal is a rollback with a name on it. F5 adds that where a plugin came from, and whether anybody read it, stays with it for as long as it is installed. This page is those acts, and that record, from here.

Behaviour

A rehearsal says everything the install would do, and asks nothing

Before anything is written, the stack says every change the install makes, in order and in full paths; every proof it would ask; every bundled setting it declares it will change; and every capability it would leave contested. The app shows all four. A rehearsal that showed less than the real run would be a preview of a different install.

A rehearsal asked no proof, and a proof nobody asked is not a proof that passed. The app never shows the first as the second.

A privileged shape is approved on its own

A plugin that fronts an egress guard takes a privileged shape: a service of it is granted network administration and given the tunnel device, which no other plugin’s service may have (F14-R12). A media server takes another, the host’s render device for hardware transcoding (ARCH-R237). Where an install or update would give a service either, the rehearsal names each service that takes a shape, with the capabilities it is granted and the devices it is given. The operator approves each one apart from the offer, and agreeing to the offer approves none of them (F14-R21). A service left unapproved leaves the install refused, and the app says which service it was and why it needs the shape.

A plugin’s settings are the operator’s to change

A plugin’s services can read values the operator sets: the countries an egress guard may exit from, the domain the proxy answers on. The app lists them on the plugin, each with the services that read it, its default, and the operator’s value where there is one, read from the stack’s settings (ARCH-R254). Changing one is rehearsed first and says which services restart for it; agreeing sends the offer that rehearsal answered (ARCH-R255). Putting a setting back to its default is the same act.

Secrets are listed beside the settings and never shown: each says whether a value is held and where it came from, and nothing more. The app offers no way to change one, and says that a secret is changed at the stack’s terminal (ARCH-R256). These screens are the operator’s alone; a member never sees them.

Installed means proven and verified, and a failure says what went back

An install is finished when its proofs held and the stack’s own checks found nothing it made worse. Where either failed, the stack puts it back and says what went back and what did not, with the reason each is still standing. The app shows that account as it came. Could not tell is not broke, and a check the stack could conclude nothing about is shown as that rather than as a failure.

An update is one thing, with one answer

Moving a plugin from one version to another is rehearsed as one account and put back as one unit. The app shows both versions, every service that stops for it — named before any of them does — and, where the new version did not hold, what putting the old one back came to. The stack is never shown between the two.

A removal says what it stops and what it leaves unfilled, before it happens

Taking a plugin out stops its services and can leave something asking for a capability nothing then fills. Both are said before the removal is agreed to. Afterwards, what was put back and what was not are shown, because a removal that got as far as the files and no further is a different machine from one that finished.

A recipe the plugin offers on demand is run from the plugin

A plugin can declare recipes that run only when asked for by name. Each installed plugin lists its demand recipes with the title and the reason the manifest gives, and offers running each one. Running is rehearsed first and labelled a rehearsal: every step in the order the recipe gives, each adapter named as lemonfiber’s, and each pair it would carry, with the value’s name, where it comes from and the destination by the name the manifest gave (N20). A pair that leaves the machine, or releases a value a service answered with, is agreed to as itself, apart from the run and with none agreed for the operator; an approval given at install covers no run, and each run asks again.

Agreed, the app sends the run with the offer its rehearsal named and the pairs approved, follows the job, and shows what ran step by step, a step the stack held with its reason. An offer that moved since the rehearsal is rehearsed and shown again, and nothing runs until the operator agrees to the new one.

A recipe that asks the operator for a value is not run from the app. It is listed with what it asks for, and the app says it is run at the web console or the terminal: a value a recipe asks for may be a secret, and the app takes no such value for an install, an update or a run.

Where it came from, and whether anybody read it, stays on it

Every installed plugin carries the source the operator named, its version, and whether anybody reviewed it. Unreviewed is not a banner at install time; it is part of the plugin for as long as the plugin is here, and the app shows it on every appearance.

States

Edge cases

• A plugin installed from a source that has since gone. It keeps working (F5-R11), and is shown with the source it was installed from.
• An install that would contest a capability the bundled stack fills. The contest is shown in the rehearsal, and answering it is N5’s.
• A plugin whose shape the operator does not approve. The install is refused, not run without the shape, and the service is named.
• A setting changed on another surface while the app shows it. The settings event brings the new value, and a change agreed to against the old one is refused as an offer that moved.
• A demand recipe that asks for a value. Listed with what it asks for and where it is run; not offered here.
• A run whose offer moved. Rehearsed and shown again; nothing runs on the old one.
• A reversal that could not finish. What is still standing is named with its reason; the install is not shown as undone.
• A plugin whose configuration directory still holds what its service wrote after an update went back. Named as still standing.

Requirements

Notes

None of this can be answered while nothing serves it. The plugins envelope is published and generated into the SDK, and no HTTP route produces it: the action route accepts no plugin verb, and the read table serves no plugin read (the register records this). N5-R10 and N5-R11 wait on the same read. The rows stand as written, because the envelope already describes what they need.

The core’s side is required and scheduled. F6-R14 requires what is installed to be a read of the web API, F6-R15 requires installing, updating and removing to be actions of it, and F6-R16 requires each to be rehearsable there; 0.18.0 locks all three. F6-R14 also requires a record that cannot be read to be refused rather than answered with an empty list, which is the distinction N25-R10 asks for and the envelope alone does not carry.

Related

• N1 — parity, and what the app may claim
• N5 — the catalogue, and installing
• N20 — what a plugin may send, and may never run
• N6 — what a reversal owes, and a rehearsal’s label
• N11 — the record every change is journalled in
• F5 — the catalogue and what vouches for a plugin
• F6 — the plugin lifecycle
• F14 — the one privileged shape, and approving it