jochen
a4b92c1306
A consumer made on 2026-10-06 was handed three hours of raised-and-cleared conditions at once and the holder said each as new: 20 desktop notifications in a second. What is said is now decided by the controller's open set and by an event's own time, never by its arrival; bursts are one message, the desktop gets warnings at most every 15 min, the cap is said once, and the first minute after start says only the urgent conditions still open. Replays of that morning's 96 events are tests. Also drops two committed binaries. (novox/hq issue 271)
105 lines
6.7 KiB
Markdown
105 lines
6.7 KiB
Markdown
# messenger
|
|
|
|
The holder of the `operator-channel` seat: how the mesh tells its operator what it noticed (novox/hq
|
|
to-be 45 §5, ADR 0227, research 028 — the minimal form, Q1a, Q5a, Q8).
|
|
|
|
- **Declares and holds `operator-channel`**, held once for the mesh, serving `open`, `history` and
|
|
`notify`.
|
|
- **Reads the controller's open conditions** (`seat:mesh-controller.conditions`) — the state it
|
|
believes, before and beside the events.
|
|
- **Consumes the controller's condition events** — `mesh-controller.condition-raised`, `-changed`,
|
|
`-cleared` — and decides what is sent. The controller calls nobody. The events are read in one
|
|
place, `cmd/messenger/condition.go`, which states every assumption it makes about their shape.
|
|
- **Two channels:** Telegram (a bot to the operator's chat) and the desktop notifier — the
|
|
`node-notifier` seat's `send` verb on the machine the operator sits at (ADR 0208), asked through the
|
|
mesh. Nothing new runs on that machine.
|
|
- **Keeps its open messages in its own state** (`open`; the recent sends in `sent`), so a restart
|
|
forgets nothing (ADR 0201).
|
|
|
|
## What is sent, and when
|
|
|
|
**History is never news** (novox/hq issue 271). The events stream hands everything it holds to a
|
|
consumer that is new, was made again, or whose holder was away — on 2026-10-06 a newly made consumer
|
|
handed over three hours of raised-and-cleared conditions at once, and each was said as if new. So
|
|
what is said is decided by the state now and by when a thing happened, never by when it arrived:
|
|
|
|
- **The state first.** On start, every 10 min, and at once when an old event arrives, the holder reads
|
|
what is open now from the controller (`mesh-controller.conditions`). An event older than that
|
|
reading is already in it and is not acted on. What is open here and not there ended meanwhile: it is
|
|
forgotten quietly (Telegram's message is edited, which notifies nobody; the desktop is not woken). An
|
|
urgent condition open and never said is said — all of them in **one** message. A warning raised in
|
|
the last 10 min and not heard is said like any other; an older one is state.
|
|
- **Old is state.** An event whose own time (`at`) is more than **10 min** old is recorded, never said.
|
|
- **A clearing of something never said says nothing**, and a message still held when its condition
|
|
clears is dropped.
|
|
- **Start grace.** Nothing is sent in the **first minute** after start but that one urgent message;
|
|
what arrives meanwhile goes out, coalesced, when the minute ends.
|
|
|
|
| When | What |
|
|
|---|---|
|
|
| `condition-raised` | one message, deduplicated by the condition's key |
|
|
| still open after 1 h (urgent) or 12 h (warning) | once more — never sooner than that after it was first said |
|
|
| `condition-changed` from warning to urgent | once more, to both channels |
|
|
| `condition-cleared` | the first message edited to say so; said inside a digest, a line in the next one |
|
|
| cleared and raised again within 10 min | the same message, edited back to open — not a new one |
|
|
| silenced | nothing, its clearing included |
|
|
|
|
- **Routing:** urgent to Telegram and the desktop; warning to the desktop when a session there
|
|
answers, otherwise to Telegram. The notifier answering is how "the operator's session is there" is
|
|
read until presence is decided (research 028 Q4).
|
|
- **Bursts are one message.** What is to be said on a channel is held **30 s** from the first and goes
|
|
out together: alone, as itself; several, as one digest (`WARNING: 5 new warnings`, a line each). An
|
|
urgent message goes at once when nothing went out on its channel in the last 30 s.
|
|
- **The desktop is gentle:** warnings reach it as at most **one message every 15 min**; urgent ones
|
|
are not held to that.
|
|
- **Cap:** at most 20 messages an hour per channel — a last line of defence the above keeps far away.
|
|
Reached, it is said **once**, in a message of its own, and the rest is held to go out as one digest
|
|
when the hour allows.
|
|
- **What may leave the mesh:** roles and words. A message carrying an address (IP, host name, URL,
|
|
mail address), a path, or anything shaped like a secret (a token, a key block, a long random or
|
|
hexadecimal string, `password=…`) is refused, logged, stated as the `refused` event, and sent in its
|
|
place as `channel-refused` with the words that carried it withheld. The rule is `cmd/messenger/content.go`.
|
|
- **Nothing silent:** a channel that cannot send says so in `messenger_status` and in the log, and
|
|
what it holds is tried again every minute while the condition is open. `messenger_status` also says
|
|
when the open conditions were last read, why they could not be, and how many events were taken as
|
|
history. An event that cannot be read
|
|
is refused by name, counted, and told to the operator once an hour.
|
|
- **No answering back.** Acknowledging is `conditions silence`, through the mesh.
|
|
|
|
## What the operator gives
|
|
|
|
Nothing is sent until these are given; `messenger_status` says which is missing.
|
|
|
|
1. **The bot token**, as this module's own secret: `secret accept <machine> messenger telegram-token`,
|
|
then push that machine. A value the mesh minted because none was accepted is recognised as not a
|
|
bot token and said so.
|
|
2. **The chat id**, as a setting: `settings` for `messenger` with `{"telegram-chat-id": "<id>"}`.
|
|
3. **The desktop machines**, as a setting: `{"desktop-machines": ["<the machine the operator sits at>", …]}`.
|
|
Without it, warnings go to Telegram.
|
|
|
|
## Tools
|
|
|
|
| tool | does |
|
|
|---|---|
|
|
| `operator-channel.open` | what is open now, urgent first, with where it went, silenced, reminded, held, refused, unsent |
|
|
| `operator-channel.history` | what was said lately, and the refusals |
|
|
| `operator-channel.notify` | a message from a module using the seat: key, severity, summary; `clear` to end it |
|
|
| `messenger_status` | whether the operator can be reached and why not; `check` asks Telegram whether the token works |
|
|
| `messenger_recent` | the recent sends, edits, digests and failures |
|
|
| `messenger_test` | a test message now, to telegram, desktop or both |
|
|
| `messenger_check` | whether some words may leave the mesh |
|
|
|
|
## Where it runs
|
|
|
|
Held once for the mesh: assign it to one machine whose tool runtime runs as root, since its secret
|
|
and settings are root's files at 0600 (as every runtime-carried module's are).
|
|
|
|
## Not yet
|
|
|
|
- **`notify` is a served verb, not a work queue.** The design has the seat *accept* `notify` so a
|
|
message waits for a holder; the node's tool runtime does not yet hand a bundle its seat's queue,
|
|
and an accepted queue nobody takes would hold messages silently. It is answered request-and-reply
|
|
until the runtime takes a seat's queue for a bundle (mesh-tools).
|
|
- **Channels are inside the holder**, not modules contributing to the seat: a seat a module declares
|
|
cannot receive contributions yet (ADR 0212 kinds are compiled for the mesh's own seats).
|