How a message is settled¶
The core defines what a handler may say and what each outcome means (Settle a delivery). This page is what the adapter does on the broker for each, under each delivery mode.
At-most-once: the broker settles it¶
An AtMostOnce source consumes with automatic acknowledgement. The broker considers the message
delivered the moment it sends it, so a handler's Ack, Nack or silence is recorded by the bus and
acts on nothing here. There is no lease and no redelivery. A message already received when the source retires or the connection
drops is not redelivered.
At-least-once: the adapter settles it¶
An AtLeastOnce source consumes with manual acknowledgement, with prefetch set to the subscription's
Bound. After the handler returns, the bus calls the adapter with the outcome:
| Outcome | Broker call | Result |
|---|---|---|
Acked |
basic.ack |
the message is gone |
anything else, while attempt < MaxDeliver |
basic.reject with requeue |
the message returns to its queue, and the broker counts a failed delivery |
anything else, once attempt >= MaxDeliver |
basic.reject without requeue |
the broker dead-letters it to the queue's dead-letter exchange; the source counts it Exhausted |
"Anything else" is Nacked, silence, and an outcome the adapter does not know. It does not tell them
apart, which is the core's rule that an unrecognised outcome is a decline.
The decline is immediate. The adapter registers only the plain settlement callback, not the one that
carries a delay, and it does not declare DelaysRedelivery. A subscription that asks for a delayed
redelivery is therefore refused when the bus is built. Capabilities
has the list of what is absent.
Attempts and MaxDeliver¶
The attempt a handler sees is the message's x-delivery-count header plus one, or 1 when the header
is absent. x-delivery-count is the broker's count of failed deliveries, which is why a queue's
delivery limit must be at least MaxDeliver - 1. With a limit of 4 and MaxDeliver of 5, the
fifth delivery has a count of 4, and the adapter dead-letters it itself instead of requeueing. A
limit below that would have the broker dead-letter the message after attempt four, and Subscribe
refuses it.
The count lives on the message in the quorum queue, so it survives a restart of the consumer or the broker.
The lease¶
RabbitMQ has no per-message ack deadline the consumer can extend. It has a consumer timeout on the whole queue that cancels the consumer. The adapter does not rely on it. It keeps its own timer, from the moment the delivery is taken off the library's channel:
| Policy | The timer runs to | When it fires |
|---|---|---|
ExtendLease (the core's default) |
MaxProcessingTime |
a counted reject, LeaseExpired incremented |
Redeliver |
AckWait, or Settings.DefaultAckWait (30s) when AckWait is zero |
a counted reject, LeaseExpired unchanged |
"A counted reject" is the same call as a decline: requeue while attempts remain, dead-letter on the
last, where it also counts Exhausted. The handler may still be running, so it can be handed the
message again while it works on the first copy. That is the duplicate LeaseExpired warns of and
the reason handlers must be idempotent.
Afterwards the handler's own Ack or Nack is accepted and not sent to the broker. A word that
arrives after the source has been retired is refused with ErrSettlementRefused, which the bus
counts as Settlement.Refused.
The timer starts when the adapter takes the delivery, before it is handed to the core. Time spent
waiting for a free handler counts against it. Prefetch is Bound; the adapter's buffer holds
Bound - 1 deliveries and one more is with the goroutine that hands them to the core.
Retirement¶
Retiring a source cancels its consumer, drains what the client library had already received, and gives
back everything it holds: buffered messages with basic.nack and requeue, and messages in a handler's
hand with basic.reject and requeue. The returns during retirement are counted in the final
Pending, not as a failure of the message. Under AtMostOnce nothing needs returning, because the
broker acknowledged on delivery.
When the broker ends the consumer¶
RabbitMQ cancels a consumer with basic.cancel for a delivery timeout, a deleted queue, a failover
or an operator's own cancel, and the client advertises that it understands the cancel. The source
logs a warning, ends, and records why as the cause on its final. A channel error ends it the same way.