86 lines
4.8 KiB
Markdown
86 lines
4.8 KiB
Markdown
---
|
|
topic: what runs on it
|
|
status: accepted
|
|
date: 2026-10-03
|
|
deciders: jochen
|
|
reconstructed: false
|
|
extends: 02-DECISIONS/0195-the-meshs-tools-are-found-by-address-not-announced-whole.md
|
|
---
|
|
|
|
# 197. Every tool announces itself on the bus, in the NATS services protocol
|
|
|
|
## Context
|
|
|
|
[ADR 0195](0195-the-meshs-tools-are-found-by-address-not-announced-whole.md) gave every tool an
|
|
address and the console five tools to find them. Where the console learns what exists, it inherited
|
|
from [to-be 34](../03-DESIGN/01-to-be/34-the-console.md) §3: ask the catalogue for its roster, ask
|
|
each module on the roster for its `tools`, and read the machines and assignments from the
|
|
controller's printed `node list` and `module list`. Built that way on 2026-10-03, it worked and showed
|
|
what is wrong with it:
|
|
|
|
- **It asks what should exist and infers what does.** The roster holds every module the catalogue
|
|
ever registered; 47 of them were reported "not answering" on 2026-10-03, most with no tools at all
|
|
and several retired.
|
|
- **It parses prose.** Two of the controller's answers are text for a person, and a reworded column
|
|
breaks discovery.
|
|
|
|
The bus already knows what answers. NATS has a services protocol for exactly this: a service answers
|
|
`$SRV.PING` and `$SRV.INFO` — every instance, on one request — with its name, its instance, and every
|
|
endpoint's subject and metadata, in a published format the NATS tools read. The operator's direction:
|
|
*every tool announces itself; the mesh has the full picture, so nothing should be inferred or parsed.*
|
|
|
|
## Considered Options
|
|
|
|
1. **Keep asking the roster, and give the controller JSON answers.** Fixes the parsing, keeps the
|
|
inference.
|
|
2. **Re-serve every tool through a NATS services library.** The announcement for free, but every
|
|
runtime's serving path rewritten around a library, in two languages, for no change in behaviour.
|
|
3. **Every runtime answers the services protocol's discovery subjects with what it serves; serving
|
|
is unchanged.** Chosen.
|
|
|
|
## Decision
|
|
|
|
**1. What answers announces itself.** Every runtime that serves tools — each machine's tool runtime,
|
|
the per-module runtimes still in containers, and the controller for the seat it holds — answers
|
|
`$SRV.PING` and `$SRV.INFO` in the NATS services format: one service per module or seat it serves,
|
|
named for it, its instance the machine; one endpoint per tool, its subject and queue exactly as
|
|
served, its metadata the tool's description, argument schema, the machine, the seat and scope where
|
|
it is a seat's verb, and whether the module's instances are interchangeable.
|
|
|
|
**2. The console finds what exists by asking the bus,** one `$SRV.INFO` request, every answer
|
|
gathered for a short window. What it announces through ADR 0195's five tools is what answered.
|
|
|
|
**3. What should exist is the mesh's records, read as data.** The controller answers its machines and
|
|
modules as JSON, and says which modules declare tools; the console names as *not answering* only an
|
|
assignment that declares tools and did not announce them. A module with no tools is never listed.
|
|
|
|
**4. The grants say so.** Every principal that serves tools may subscribe the services discovery
|
|
subjects for what it serves; the console's and every runtime's account may publish the discovery
|
|
request. Replies travel to the asker's own inbox as every reply does.
|
|
|
|
## Consequences
|
|
|
|
- The standard `nats micro list` and `nats micro info` show the mesh's tools, live, to anybody holding
|
|
a credential — the bus's own view, not the mesh's description of it.
|
|
- Discovery costs one request and a gathering window, not one request per roster entry.
|
|
- What got harder: three runtimes must answer the same format the same way — the Go tool runtime, the
|
|
TypeScript runtime the containers still run, and the controller. The format is NATS's, so a test
|
|
reads all three with the NATS services client and nothing of the mesh's.
|
|
|
|
## How it is checked
|
|
|
|
| Rule | Checked by |
|
|
|---|---|
|
|
| A runtime announces exactly what it serves | each runtime's test: `$SRV.INFO` answered with one service per served module or seat, its endpoints' subjects the subjects served |
|
|
| The format is NATS's | the same tests read the answer with the NATS services client's own types |
|
|
| A module with no tools is never listed; an assignment with tools that did not answer is | the console's test, against controller records with both |
|
|
| Nothing is parsed from prose | the console reads only JSON answers (code review; the text parsers are deleted) |
|
|
| Live | `nats micro list` against the mesh's bus lists every machine's tool runtime and the controller |
|
|
|
|
## References
|
|
|
|
- [ADR 0195](0195-the-meshs-tools-are-found-by-address-not-announced-whole.md),
|
|
[ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md),
|
|
[ADR 0175](0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md)
|
|
- [to-be 34](../03-DESIGN/01-to-be/34-the-console.md)
|