Appearance

Replication ​

Last updated 

A spool is the storage unit that holds your queues: every queue lives in exactly one spool, and every account starts with one named default. Replication is what happens to a spool's data beyond one node.

Everything on this page is observable with an API key and curl, given two numbers set in the console when a spool is created. Both are immutable afterwards:

  • numReplicas — how many nodes hold the spool's data, primary included. The plan's replicas limit caps it — see limits.
  • numSync — how many of the other copies must confirm a write before the response; at most numReplicas-1. The default spool sets every copy synchronous.

What a response promises ​

Every write response — for example, a send's 201 or an ack's 204 — makes one promise: the primary wrote it to disk and synced, and numSync other copies confirmed it. The remaining copies catch up on their own; the response does not wait for them.

numReplicasnumSyncthe write is on
10one node
nn-1every node holding the spool
n0the primary; the other copies follow, unconfirmed

Losing a node ​

A spool is served by one node at a time, its primary. When that node is lost, requests answer 503 until the spool has a primary again; retry them.

  • One copy. Nothing else holds the data. The spool waits for its node to return; losing that node's storage loses the spool's data.
  • Synchronous copies. A copy that confirmed every acknowledged write becomes the primary. No acknowledged write is lost.
  • Asynchronous copies (numSync of 0). A copy becomes the primary with whatever it had received. Writes acknowledged after that point are lost. This is the price of not waiting.

A primary change never preserves in-flight leases: their messages are redelivered, and a settle presenting an old lease answers 410stale_lease — see delivery.

Losing a copy ​

A write on a spool with numSync above zero does not return until that many copies confirmed it. While fewer are reachable, sends and settles wait; receives keep working — a lease is not durable state, as a primary change dropping every in-flight lease already shows. A client that gives up waiting must treat the write as unconfirmed: it may still take effect. The rule is the one for operation_unconfirmed — retry a send only on a queue with a dedup window, carrying the same key; see deduplication.

Choosing ​

  • numReplicas of 1 for development, tests, and data you can regenerate.
  • Every copy synchronous when a 201 has to mean the write survives the loss of a node. Each write waits for the confirmations; that wait is the cost.
  • numSync of 0 when the writes acknowledged in the moments before a node is lost are worth less than the wait.

Copies add durability, not throughput: the primary serves every request.