Overview

The surface you write against is small: push a message, pop it, acknowledge it. The fourth call is not a fourth operation but a container. POST /api/v1/transaction takes an operations array of pushes and acks, any number of each, spanning any number of queues, partitions and consumer groups, and commits the whole array in one PostgreSQL transaction. Every application in this section is those three operations and that container in a different arrangement.

The container takes two more arrays, and they are top-level fields of the request body rather than entries in operations: kv writes transactional state and timers schedules or cancels a timer. Both are served by every broker, and a bundle that carries neither is byte for byte the call it was before they existed.

Ephemeral queues are the one thing here that is not built on that commit at all. They are a second storage class, on their own routes, whose contents live in the broker’s memory and survive nothing, for the workloads that have no use for history and should not pay for it.

const res = await client
  .queue('orders')
  .partition('customer-42')
  .push([{ data: { orderId: 9137, amount: 99.5 } }])

The queue and the partition are created by the push that names them, so there is nothing to provision first. The model is one page: queue, partition, offset, consumer group, cursor, lease, ack.

Two rules shape everything built on top. An acknowledgement is a commit of a position, not a receipt for one message, so acking the last message of a batch completes the batch. And a consumer group holds at most one leased batch per partition, so parallelism comes from partitions, not from more consumers on one.

Everything is HTTP over a small JSON API, so curl is a client and the SDKs are convenience over it. Clients hold no coordination state: a worker that restarts does not stall its peers.

What people build with it:

• Producer and consumer. One queue, one group, an ack when the work is done: the loop.
• Fan-out. Two groups over one queue, each reading every message, at one copy of the data: fan-out.
• Deduplicated ingest. A deterministic transactionId, and the repeat refused by the broker: deduplication.
• Transactional pipeline. Ack the input and push the next stage in one commit: the pipeline.
• Replay. Move a group’s cursor back to a timestamp, or point a new group at history: replay.
• Windowed aggregation. Tumbling, sliding, session and cron windows, with the accumulator in the same PostgreSQL: streams.

Pick a client, write the loop, read errors before it meets traffic.