NATS broker¶
The nats module is the central broker every other module connects to.
Module id: nats.
Configuration¶
| Config type | Component ref | Description |
|---|---|---|
modulekeyinfo |
nats.modulekeyinfo.<key> |
ModuleKeyInfoConfiguration is one module's key the bus admits, nats.modulekeyinfo.<key> (adr/rfc-035-device-authorization.md D14). |
userkeyinfo |
nats.userkeyinfo.<key> |
UserKeyInfoConfiguration is one person's key the bus admits, nats.userkeyinfo.<key> (adr/rfc-035-device-authorization.md D4): who the key is and which role it holds. |
Both are published under --auth, see below.
JetStream streams are provisioned for data, measurement, config, and config status. Events stay on core NATS (event2) - there is no durable event stream. See Messaging and Events.
NATS endpoints¶
None declared.
The readiness probe and the three auth verbs are declared under the configurable module id (*.app.*.status, *.auth.*.<verb> in the commands reference) rather than under nats, so they are addressed here by subject:
| Subject | Purpose |
|---|---|
local.nats.cmd.app.main.status |
Readiness probe. Other modules wait for JSON "OK" before proceeding |
local.nats.cmd.auth.main.ls |
Lists the identity registry: module bindings and enrolled user keys (--auth only) |
local.nats.cmd.auth.main.enrol |
Enrols a user key with a label and role, or binds a module id to a key |
local.nats.cmd.auth.main.revoke |
Revokes a user key or a module binding, dropping the key's live connections |
The status probe is request-reply, not a telemetry message. See Telemetry.
The three auth verbs are the registry's write surface under --auth (RFC-034 D6). Each request is signed by the caller's NKey - the envelope carries the key, the body and the signature - and only role keymaster may publish them; the boot's root key (/run/algol/nats/root.nkey) is the first keymaster. The registry itself is --registry-file (default /var/algol/nats/registry.json), and the expected module ids are the --module list. A revoked module name stays closed until it is enrolled again - first connect never reopens it; deleting the registry file and restarting nats is the reset that reopens every name. See Messaging for the request and reply shapes. The operational walk-through - first boot, enrolling user keys, using natscli directly - is Device Setup.
Under --auth the module also publishes the identity table the configurer decides writes from (RFC-035 D4, D14): nats.userkeyinfo.<key>, one read-only config per user key it admits, and nats.modulekeyinfo.<key> for the module keys. Both are module-sourced, so they appear as config statuses and never as config updates - algol config ls 'nats.*' lists them. They are published at start, on every enrolment or revocation, and on the status tick; a device where they are missing refuses every user-key request with identity <key> has no role.
Bus authentication is not module isolation: every admitted identity keeps local.> publish and subscribe - the v1 templates confine reply inboxes and the secret verbs, nothing more (RFC-034 D8). A compromised module can still read config bodies and publish another module's status; narrowing what each module may touch is RFC-034's v2 template track.