jochen
ec80dcfc22
A handler takes an event by returning and asks for it again by throwing; any mesh/event answer but an error is taken. Written down in the README where event handling is, with what follows for a handler: throw only when the work was not done, and be safe to run twice. Both SDKs added the handler before asking the runtime and kept it when the runtime refused, so a module that asks again until it is taken (every Go consumer does) ran its handler once per attempt for every event. A refused subscribe now removes its handler; one the Go runtime did not answer in time is kept, since the runtime may have bound it.
140 lines
8.1 KiB
Markdown
140 lines
8.1 KiB
Markdown
# mesh-sdk
|
|
|
|
The stable spine a Novox Mesh **module's own code builds against** — the tool it uses to plug
|
|
into the mesh, and nothing that belongs to a specific module or to another tier.
|
|
|
|
It earns its place by **rarely changing** (novox/hq [ADR 0039](https://git.novox.be/novox/hq)).
|
|
The test for anything here: *if editing it recompiles unrelated modules and it changes often, it
|
|
does not belong.* Per-module code (a service's API client, its tool implementations, its
|
|
create-a-resource adapter) lives **in the module**, never here — that coupling is exactly what
|
|
turned the old SDK into constant maintenance and made every edit rebuild every module.
|
|
|
|
## What is in it
|
|
|
|
Five small areas, each a thing a module's `tools/` or `provisioner/` imports:
|
|
|
|
### `contracts` — the runtime shapes module code touches
|
|
Not the manifest schema (the control plane owns and parses that, in Go). The shapes a module's
|
|
*running code* receives and returns: a provisioning **grant** and its credentials, the
|
|
**mesh interface** definitions (what an `analytics` grant contains, what an `oidc-client` grant
|
|
contains — the contract both a provider and a consumer conform to), and the tool and event types.
|
|
These change rarely and deliberately; when one does, a rebuild of everything is *correct*.
|
|
|
|
### `provisioner` — the reconcile harness every provider shares
|
|
The loop is identical for postgres, redis, minio and umami: watch the grants directory, for each
|
|
requested grant call the provider's adapter, write the sealed credential, handle withdrawal, and
|
|
keep converging (`watch`). That loop lives here. A **module provides only the adapter** — "create
|
|
a database", "create a umami site" — which is the volatile, per-service half and belongs in the
|
|
module. This is the ADR 0039 line drawn through provisioning: stable loop here, per-service create
|
|
in the module.
|
|
|
|
**A consumer the mesh stops asking for is retired, not withdrawn whole** (novox/hq ADR 0230). ACTIVE
|
|
becomes RETIRED only once the same set of consumers has gone unasked in five consecutive passes that
|
|
read the file AND for ten minutes (`stableForMs`, `STABLE_FOR_MS`; a pass that cannot read the file
|
|
starts both again). An adapter with `retire` disables the consumer's access, reversibly, and marks it;
|
|
`reenable` (optional) undoes that before `create` when it is asked for again. **An adapter without
|
|
`retire` is mark-only**: nothing in the backend changes — the consumer keeps its access — and the
|
|
harness marks it "retired, access kept, needs deletion", says so loudly and announces it. **`remove` is
|
|
never called to retire**; it is the delete of an adapter without `delete`, reached only through a
|
|
person's `provisioner_delete`. A stable set of more than 3, or more than half of those held where more
|
|
than one is held, is not retired without a person: the provider waits for
|
|
`provisioner_retire_approve` or `provisioner_retire_reject`, and says `provisioner.retirement`
|
|
(`waiting`) through the `announce` option. Asked for again, a retired consumer is created — re-enabled
|
|
— at once. Given `module`, the four tools (`provisioner_retirement`, `provisioner_retire_approve`,
|
|
`provisioner_retire_reject`, `provisioner_delete`) are registered for it; `provisionerTools(handle)`
|
|
builds them otherwise. Additions and changes are never delayed.
|
|
|
|
### `tools` — the tool-serving harness
|
|
`registerModuleTools`, the `ToolDefinition` type, and the registry/worker that loads a module's
|
|
tools and exposes them through the mesh's command surface. *How* a tool is declared and served is
|
|
settled; it does not change when an individual tool does. The tools themselves, and the API client
|
|
they call, live in the module.
|
|
|
|
### `messaging` — the broker and event framework
|
|
The broker client (connect, request/reply, publish/subscribe), the event-consumer a module uses to
|
|
react to mesh events, and the envelope/routing-key conventions. Transport primitives.
|
|
|
|
#### Taking an event — the one rule
|
|
|
|
A module's handler (`on(pattern, handler)` here, `stdio.Subscribe` in Go, the same in every language)
|
|
**takes an event by returning, and asks for it again by throwing** (Go: returning an error). Nothing
|
|
else counts: what a handler returns is not read.
|
|
|
|
On the wire, the runtime hands the bundle `mesh/event` with the envelope and acknowledges the event on
|
|
the bus when the answer is **anything but a JSON-RPC error** — `{}` (what the SDKs send), `null`, or no
|
|
`result` at all. An `error` answer, no answer within the runtime's event timeout (two minutes), or the
|
|
bundle exiting leaves it unacknowledged: it is offered again after five seconds, up to the module
|
|
consumer's maximum deliveries, after which the bus gives it up and the controller raises a condition
|
|
(`max-deliveries`). The runtime's line for an event not taken quotes a handler's error as the
|
|
handler's own words, so it is never mistaken for the runtime's.
|
|
|
|
So, for a handler:
|
|
|
|
- **Throw only when the work was not done** — the service refused, was unreachable, the store failed.
|
|
Never for something that went right but answered oddly: an API that answers an empty body is a
|
|
success, and reading it as JSON is a throw that has every event offered five times, its work done
|
|
five times, and a false alarm raised (novox/hq issue 276).
|
|
- **Delivery is at-least-once**, so the work must be safe to do twice, or the handler skips an event
|
|
whose `x-event-id` (`event.id`) it already did — remembering it only once the work succeeded, so one
|
|
that failed is done when it is offered again.
|
|
- An event no handler matches is answered at once and taken.
|
|
- A subscribe the runtime refused leaves no handler behind, so asking again until it is taken hands
|
|
each event to the handler once.
|
|
|
|
Checked by the SDKs' stdio tests (TypeScript `test/stdio.test.ts`, Go `go/stdio_test.go`) and the
|
|
runtime's (`node-tools/internal/launch`, mesh-tools).
|
|
|
|
### `state` — a module's current state on the bus
|
|
`state(name)` reaches a state the module declared it keeps (`state` in its manifest) or reads
|
|
(`reads`, as `<module>.<name>`): `get`, `put`, `delete`, `keys`, and `watch`, which hands the current
|
|
values and then every change. Through the runtime that launched the bundle, which refuses what the
|
|
module did not declare. Current values, never history and never a secret (novox/hq ADR 0201).
|
|
|
|
### `primitives` — sealing, semver, resolved-env
|
|
Seal/unseal for secrets, semantic version comparison, and the accessor a module uses to read its
|
|
own resolved environment.
|
|
|
|
## What is NOT in it, and where it goes
|
|
|
|
- **A module's API client and its tool implementations** → in the module. (The Plex client, the
|
|
Umami client, `tools/plex.ts` — all module-local. ADR 0039.)
|
|
- **Delivery machinery** — build executor, bundler, dependency resolver, artifact manager, feature
|
|
handlers → **mesh-controller**. It co-evolves with the pipeline.
|
|
- **Host synchronisers** — config-sync, ufw config, vhost generation, systemd, health checks →
|
|
**mesh-host**'s apply engine. The host applies these; they are not module code.
|
|
- **Domain logic** — tasks, workflows, agents, provider integrations → **tier-2 contexts**.
|
|
|
|
That is why this stays small: everything volatile has somewhere else to be.
|
|
|
|
## Using it
|
|
|
|
A module's tools:
|
|
|
|
```ts
|
|
import { registerModuleTools, ToolDefinition } from "@novox/mesh-sdk/tools";
|
|
import { UmamiClient } from "../client.js"; // the client lives in the module, not here
|
|
|
|
registerModuleTools("umami", (env) => getUmamiTools(new UmamiClient(env.UMAMI_URL)));
|
|
```
|
|
|
|
A provider's provisioner:
|
|
|
|
```ts
|
|
import { runProvisioner, Grant, Credential } from "@novox/mesh-sdk/provisioner";
|
|
|
|
runProvisioner("analytics", {
|
|
async create(grant: Grant): Promise<Credential> { /* create a umami site, return the grant */ },
|
|
async remove(grant: Grant): Promise<void> { /* delete the site */ },
|
|
});
|
|
```
|
|
|
|
The adapter is the only thing the module writes; the watching, sealing and grant-file handling are
|
|
the harness's.
|
|
|
|
## Where the reasoning lives
|
|
|
|
Design and decisions are in [`novox/hq`](https://git.novox.be/novox/hq):
|
|
|
|
- `02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md` — the stability rule this repository is
|
|
- `02-DECISIONS/0040-what-a-module-is.md` — a module, and why its per-module code lives in the module
|