jochen
a7b2db9efc
The seats half of to-be 27's review is settled, so the two records it rests on are accepted and the vocabulary catches up: the glossary's *seat* becomes a named role from a closed set, held by an assignment and possibly delivering a provision, and 23 — Choosing a provider gains the seat step in resolution, with ambiguity still refused rather than guessed. Both were held back when 0110 was proposed, because a document may not rest on a record that is not accepted. 26 — The seats moves to in-progress rather than designed: it names the files that implement it, and naming a file claims implementation, which is only defensible once those files are on the owning repositories' main branches. It becomes implemented when mesh-controller #63 and mesh-catalog #69 land. 0112, 0113 and 0114 stay proposed; to-be 27 stays proposed with them.
69 lines
4.8 KiB
Markdown
69 lines
4.8 KiB
Markdown
# Glossary — the words this repository uses, and the ones it stopped using
|
|
|
|
One name per thing. This page is the authority; where an older record says something else, that
|
|
record is being superseded, not this page. It exists because the terms kept drifting in
|
|
conversation — control plane / controller / master / hub for one thing, substrate / foundation for
|
|
another — and a mesh you cannot name precisely is a mesh two people describe differently.
|
|
|
|
## The mesh and its machines
|
|
|
|
- **node** — a machine in the mesh. There are 0..n of them, and each runs the host agent. A node is
|
|
just a machine that has joined; being one implies nothing about what it runs.
|
|
- **control-node** — the one node that also holds the `mesh-controller` seat. There is exactly one
|
|
per mesh. "control-node" is not a separate kind of machine — it is a node that additionally runs
|
|
the controller (and, today, the foundation). Lose it and the other nodes keep running what they
|
|
were last told; they simply cannot be told anything new.
|
|
- ~~master / slave~~, ~~hub / peer~~ — not used. The relationship is *controller and nodes*, and no
|
|
node is subordinate: a node applies declarations on its own and survives the control-node dying.
|
|
|
|
## What runs the mesh
|
|
|
|
- **controller** — the component that decides what each node should be, holds the mesh's records,
|
|
and tells nodes over the broker. Replaces **"control plane"** (borrowed from networking's
|
|
control-plane/data-plane, and opaque here).
|
|
- **mesh-controller** — the module that runs the controller. It **claims** the `mesh-controller`
|
|
seat at mesh scope, which is what makes it singular. Replaces the module name **`mesh-control`**.
|
|
(The git repository has been renamed `mesh-control` -> `mesh-controller` on the forge; the module,
|
|
container and image it produces are `mesh-controller`.)
|
|
- **foundation** — the store and the broker, raised at genesis before any module system exists.
|
|
Replaces **"substrate"** (a biology metaphor that landed for no one). The foundation is not a
|
|
third thing beside the store and broker — it *is* those two, named together.
|
|
- **store** — the one postgres server. It holds the controller's own context databases
|
|
(`inventory`, `identity`, `licences` — a context owns its store, [ADR 0008](../02-DECISIONS/0008-a-context-owns-its-store.md))
|
|
and every module's own database. One server, many databases — never one shared "mesh database".
|
|
- **broker** — the one lavinmq message bus. It carries the mesh bus on the `/` vhost and a vhost per
|
|
consumer that requires `amqp`.
|
|
|
|
## What the mesh stores and serves
|
|
|
|
- **package** — what code resolves when it is **compiled**: an npm/cargo/pypi dependency, by
|
|
**version**. Served by the **package-registry** (gitea). Only a builder talks to it.
|
|
- **artifact** — what the mesh delivers to a machine to **install and run**: an OCI image, by
|
|
**digest**. Served by the **artifact-store** (distribution). Every node pulls from it.
|
|
- These are two protocols, not one store being weak — see [ADR 0075](../02-DECISIONS/0075-two-stores-and-which-provides-what.md).
|
|
|
|
## How modules relate to the mesh
|
|
|
|
- **seat** — a named role at a scope (node / site / mesh), held by a module assignment, from a
|
|
**closed set** the mesh defines: a claim naming a seat outside the set is refused. A seat may
|
|
**deliver a provision**, and its holder is then the mesh's answer for it when several modules
|
|
provide it ([ADR 0110](../02-DECISIONS/0110-a-seat-is-a-module-assignment-from-a-closed-set.md)).
|
|
The set, with who holds each seat, is the overview of what a mesh has
|
|
([26 — The seats](../03-DESIGN/01-to-be/26-the-seats.md)). A seat has a **capacity**: a
|
|
capacity-1 seat is exclusive (one holder); a higher-capacity seat is a **bench** (several holders
|
|
coexist).
|
|
- **claim** — a module taking a spot on a seat. `claims: [{name, scope}]` in a manifest. A
|
|
mesh-scoped exclusive claim is how the mesh says "there is one of me". A foundation seat is
|
|
named after the server it guards: the `mesh-controller`, `postgres` and `lavinmq` modules claim
|
|
the `mesh-controller`, `mesh-store` and `mesh-broker` seats ([ADR 0079](../02-DECISIONS/0079-the-foundation-seats-are-named-after-their-servers.md)).
|
|
- **provision** — a service one module `provides` and others `require`; the mesh resolves a provider
|
|
and wires the two with an endpoint and a credential. A provision is a service you offer, a seat
|
|
is a role you occupy, and the two meet where a seat delivers a provision: occupying the seat is
|
|
what makes a module *the* provider of it.
|
|
|
|
## How this page is kept
|
|
|
|
A new name for an existing thing lands here first, in the same change that introduces it in code. A
|
|
record under `02-DECISIONS/` keeps whatever word it was written with — those are immutable — so a
|
|
term retired here may still appear there, and the mapping above is how to read it.
|