Notification router

The swarm's swarm-notify-router service turns forge events into todos on the agents they concern. No hive is in the path, and the agent can be on any hive: swarm-controller keeps the events, the router decides, and each agent's harness takes its own todos off the queue.

Where it runs and how it's enabled: services.md.

It runs beside hive-forge-notify, which still delivers forge notifications the way it did. An agent can get the same news from both.

What an agent gets

The todos are subsystem router in the agent's todo list. A todo under the same key replaces the one before, so an issue gives an agent one assignment todo however often it changes hands. A new event reopens a todo the agent marked done.

The closed todo has its own key, apart from the assignment todo. A reopened issue leaves it in place until the next close replaces it; a new assignment writes the assignment key and leaves it alone.

Only agents get todos. An assignee with no agent of that name gets nothing. An agent assigned before it first reports its status gets its todo on the issue's next assign event.

Forgejo's assign events carry the assignees after the change, not which one changed. The router keeps the assignees it saw on the last assign event per issue and takes the difference. With no earlier assign event for an issue, every current assignee counts as newly assigned and nobody as removed: an router notices an unassign only on an issue it has seen an assign event for.

The path

1. swarm-controller registers two instance-wide hooks, one for the issues and issue_assign events at /webhook/forge/issues and one for pull_request and pull_request_assign at /webhook/forge/pull-request. At each start it adds any of these events a registered hook lacks.
2. On each delivery the controller checks the HMAC and publishes the body, unchanged, to the SWARM_EVENTS stream on $SWARM.events.forge.<X-Forgejo-Event-Type>, such as $SWARM.events.forge.issue_assign. The stream keeps a delivery 7 days and drops a redelivery by its X-Forgejo-Delivery id. A delivery the stream did not keep answers 503, so the forge's delivery log shows it.
3. The router drains its durable consumer, notify-router, in order. For each event it runs every flow, queues the todo ops the flows emit, writes the issue's snapshot to its notify-router-state bucket, then acks the event. A failed step stops the batch: that event and the rest come back in stream order after 30 seconds, and the stream drops the ops queued twice by their message id.
4. Each op goes to the ROUTER_TODOS stream on the agent's own subject, $SWARM.router.todo.<agent>. Work-queue retention: an op stays until its agent acks it, up to 30 days and 1000 per agent.
5. The agent's harness creates its own durable consumer, todo-<agent>, applies each op to its todo list and acks it. An agent that's down, or whose harness predates this, leaves its ops waiting.

The router holds no forge token and no webhook secret, and registers no hook.

Flows

A flow is a graph of nodes joined by edges: one source node naming the forge event types it starts from, match nodes that pass when every condition holds, and todo nodes that emit one todo op per recipient. A match node can have more than one child, and each one runs, so one event can reach several todos. A flow must be a tree: one source, one parent for every other node, every node reachable, no children under a todo. The most is 64 nodes, 16 levels deep, and 100 custom flows. A todo node sends to the agents an event field holds (assignees_added, todo_holders, …) or to one named agent.

The router ships the three flows above, each a source → match on action → todo. The code defines them (swarm_wire::notify_flows::builtins), so a build that changes one reaches every swarm. A custom flow has the same type and the same evaluator, so it can do anything a built-in does.

The stored document. swarm-controller keeps the rest in one document, the all key of the notify-flows bucket: the ids of the built-in flows you switched off, and the custom flows. Only the controller writes it, through GET and PUT /api/notify/flows. A PUT replaces the whole document in one compare-and-set. The controller answers 400 unless every flow passes the tree check above and reads only what exists: a source event from issues, issue_assign, pull_request or pull_request_assign, and condition and recipient fields from the event's field list. The same goes for the {field} placeholders in a todo's key and text. A PUT must carry the revision it read, 0 for no document, and gets 409 when the stored revision is another. Swarm UI's /notifications page shows the document and switches built-ins.

The schema. GET /api/notify/flows also returns a schema object, built from the constants the check reads, so an editor offers only what a PUT accepts:

• source_events: [{name, description}], the source events.
• fields: [{name, description}], the condition and recipient fields, and the {field} placeholders.
• node_kinds: [{kind, description, fields}] for source, match and todo; each field is {name, description, required, values}, and values lists the accepted {name, description} pairs (the upsert and clear of a todo's op), empty for other fields.
• limits: {max_nodes, max_depth, max_flows}.

A controller that predates schema leaves it out of the answer; a client reads it as optional.

What the router runs. It reads the key at most every 10 seconds, when an event arrives, and runs the built-ins you left on, then the custom flows that are on and pass the tree check. It logs a custom flow that fails the check, leaves it out, and runs the rest.

"Can't read" means not JSON, not a flows document, or a version other than 1. Before the router has read any document, "before" means the built-ins, so a bad document never leaves it with no flows. The controller refuses to overwrite a document of a version it doesn't know.

Deploying in any order. The controller, the router and the UI can be on different hosts. A controller that predates this leaves the key absent, and the router runs the built-ins as before. A router that predates this ignores the document, so the page and the API show a state the router isn't yet running.

Credentials and grants

No other client may publish on $SWARM.router.todo.* or $SWARM.events.forge.*, so each has one writer. The agent's create subject carries the consumer's filter, and the queue server checks it against the request, so an agent can't create a consumer that delivers another agent's todos.