Skip to main content

Queues & subscriptions

Vhost → topic → subscription​

  • A vhost is an xcon-db database — an isolation boundary with its own topics and access.
  • A topic (the AMQP "queue") is a durable log: a q_<name> table.
  • A subscription is a durable cursor over a topic. Its workers share the cursor round-robin — competing consumers, each message to exactly one worker. A second subscription is an independent reader (fan-out) with its own cursor.

Acknowledgement advances the subscription's cursor. The message is not deleted — retention is the only eraser — so a new subscription can replay history from earliest, and a lagging one catches up.

Credits​

A worker is delivered messages up to its credit window; each ack returns a credit. Credit is broker-authoritative and self-replenishing, so a slow or hung worker simply stops receiving instead of stalling the subscription. In AMQP terms, credit is basic.qos prefetch.

Filters​

A subscription may carry a subject filter ("" = all, x.* = prefix, else exact). Non-matching messages are skipped durably — the cursor tracks the head, so a 0%-match subscription never wedges and the filtered-out past is never replayed. AMQP topic exchanges express the richer */# grammar; see AMQP mapping.

Dead-letter queues​

A message that fails delivery maxAttempts times (with an exponential backoff ladder between tries) is moved to a per-subscription dead-letter queue, <topic>__<sub>__dlq, with an envelope recording the source sequence, subscription, and attempt count. Per-subscription DLQs mean one consumer's poison never disturbs another's.