Skip to content

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.