Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The bus

NATS with JetStream is the only infrastructure (ADR-0002). Not “the message broker among other services” — the entire platform substrate:

  • Transport & persistence. Every event between units crosses a JetStream stream (VEJAS, subjects vx.>). A hop is acknowledged only after the next stage’s write is confirmed — publish-before-ack, so a crash anywhere redelivers instead of losing (at-least-once, end to end).
  • State. Offsets, versions, leases, proposals: JetStream KV buckets. There is no database.
  • Scaling. Flows and sinks are competing consumers on durables — add an instance, throughput distributes; kill -9 one, nothing is lost (measured: 20 000/20 000 through an instance kill under load). Sources that must be singletons take a KV lease (clustering).
  • Audit. Mutations append to an audit stream; the DLQ is a subject hierarchy (vxdlq.>) with death envelopes.

Subjects

Everything speaks vx.<domain>.<name> (root configurable via VEJAS_SUBJECT_ROOT). A connector publishes into the taxonomy or consumes from it; a flow declares source "vx…" and emits to other subjects. An external connector in any language is a first-class citizen by following the same rules on the same bus — publish JSON on vx.<domain>.<name>, consume with a durable, ack after your side effect. The full contract: Subjects reference.

Delivery contract

At-least-once, per-subject FIFO, redelivery after VEJAS_ACK_WAIT_SECS (default 30s; floor 1s), 5 attempts then the dead-letter queue with an explicit envelope — never a silent drop (DLQ & replay). Consumers must be idempotent or carry a dedup key; the transport invariants are CI-tested on a live bus (FIFO, redelivery→cap→DLQ, kill -9 no-loss, reconnection).