43 lines
3.8 KiB
Markdown
43 lines
3.8 KiB
Markdown
# mesh-contracts
|
|
|
|
The mesh's seat contracts (novox/hq ADR 0608 §5, ADR 0613, ADR 0620, ADR 0625, ADR 0627; design 26 *A seat's
|
|
definition*): one language-neutral definition per seat, the Go and TypeScript code generated from it, and the client
|
|
of a seat whose callers share logic over it. This repository holds contracts only and no seat: a seat's holder
|
|
implements its contract, and no holder's code lives here.
|
|
|
|
## Where a seat's code goes
|
|
|
|
- **The definition**, written by hand: `seats/<seat>/seat.json`, its fixtures in `seats/<seat>/fixtures/`, and the
|
|
parts several seats include whole in `parts/` (the four registry seats' verbs and events are `parts/registry.json`).
|
|
mesh-sdk's `seatdef` is the one reader of the format; the indexer and the generators use it.
|
|
- **A state**, in the definition's `states` (ADR 0608 §1, ADR 0634 §6): `{name, template, writer, key-forms, history,
|
|
max-age-days, description}`. `template` is one of ADR 0595's six (`state`, `events`, `work-queue`, `log`, `objects`,
|
|
`ledger`); `writer` is `holder` (the default) or `caller`; each key form is `{key, value, description}`, the key a
|
|
pattern of named parts between angle brackets (`<asker>.<id>`) and the value its JSON Schema. A definition names no
|
|
holder module: a reader takes the holder from its own manifest's `reads`. A fixture of a state is `state:<name>/<key>`.
|
|
- **The seat set**, generated: `go/seats` (module `git.novox.be/novox/mesh-contracts/go`), every seat's name, scope,
|
|
verbs and provision at the seat list's grain (ADR 0625 §2). mesh-sdk's `catalogue` is its only importer in mesh-sdk.
|
|
A change of it rebuilds every importer of the seat set. Its npm package is `ts/` (`@novox/mesh-contracts`, the
|
|
seat list alone).
|
|
- **A seat defined whole**, generated: `go/seats/<seat without hyphens>`, a Go module of its own importing nothing,
|
|
holding the seat's verbs, events and subjects, its message types and a test of its fixtures (ADR 0625 §1). A module
|
|
imports only the seats it uses, so a change of one seat rebuilds only its users. Its npm package is
|
|
`ts/seats/<seat without hyphens>` (`@novox/mesh-contracts-<seat>`), holding the parts it includes whole: the indexer
|
|
counts the npm package a lock resolves, so here too a module is rebuilt only for the seats it uses.
|
|
- **A seat's client**, written by hand: `go/clients/<seat without hyphens>client`, a Go module of its own, only where
|
|
two or more callers share logic over the seat (ADR 0625 §4, ADR 0627 §1): operator-channel's (checking an ask,
|
|
its digest, a warrant's, and an asking module's keeping of its asks), node-engine's (checking compose-candidate's ask
|
|
and answer) and the four registry seats' (publishing a file in parts). A client imports its own seat's contract and mesh-sdk's runtime, never another seat's client, and names
|
|
no module's subject or tool.
|
|
- **Not here**: the value layouts of seats not yet defined whole (they stay in mesh-sdk until their domain moves,
|
|
ADR 0625 §9), and a role only one module could ever play (that module's own tools and events, ADR 0625 §8).
|
|
|
|
## How it is checked
|
|
|
|
Every file under `go/` and `ts/` outside `go/clients/` is written by the generator (seatgen, the source of the Go and
|
|
Node build modules' generate step) and compared on every build: a hand-written file there fails, named (ADR 0625 §5).
|
|
`seatgen -check` (mesh-catalog `modules/mesh-build-go/buildstep/cmd/seatgen`) also runs the client check (each client is for a seat defined whole, a module of its own, importing
|
|
only its seat's contract and mesh-sdk) and checks `module.json`'s Go and npm package artifacts against the tree.
|
|
|
|
Made by the mesh from the gitea module's config value `repositories` (novox/hq ADR 0428). Main takes no push: a change reaches it by a pull request whose `mesh/check` passed: the checker's verdict on its head merged onto main, its tests run by their language's convention (novox/hq ADR 0447, ADR 0445).
|