Acknowledgement Policies¶
rabbitkit supports four acknowledgement policies, selected per subscriber via ack_policy=.
AUTO (default)¶
rabbitkit manages settlement automatically based on handler outcome.
| Handler result | Action |
|---|---|
| Returns normally | basic.ack |
Raises transient exception, with RetryConfig |
republished to a delay queue (retry) |
| Raises transient exception, no retry, first delivery | basic.nack(requeue=True) |
| Raises transient exception, no retry, message already redelivered | basic.reject → DLQ |
| Raises permanent exception | basic.reject → DLQ |
Transient means TimeoutError, OSError (connection resets and so on),
EOFError and HandlerTimeoutError; everything else, including unknown
exception types, is permanent.
The transient loop is bounded by default. Without retry, a transient
failure is requeued once; if the redelivery fails again it is dead-lettered
(ConsumerConfig.reject_transient_on_redelivery=True, the default). Earlier
releases requeued transient failures immediately and forever: a poison
message that always times out ran thousands of times per second and never
reached the DLQ. The broker's redelivered flag is the only per-message
signal a classic queue carries, so the cap is two attempts, and it also
counts a redelivery caused by a crash or a lost connection. Use
RetryConfig for more attempts with delays, or set
reject_transient_on_redelivery=False to restore unbounded requeueing.
Every handler failure is logged as one structured line: queue, message id,
correlation id, delivery tag, redelivered, the exception class, the reason
for the decision and the action taken. The body, headers and exception text
are never logged (they may contain payload data or secrets); the traceback
is logged at DEBUG. Repeats of the same failure on the same queue are
collapsed to one line per 10 s window, with a count.
@broker.subscriber(queue="orders") # ack_policy=AckPolicy.AUTO is the default
async def handle(body: dict) -> None:
process(body) # ack on success, nack/retry on exception
Use AUTO for most consumers. Combine with RetryConfig for transient failures.
MANUAL¶
The handler receives the raw RabbitMessage and settles it explicitly. rabbitkit never auto-acks.
from rabbitkit import AckPolicy, RabbitMessage
@broker.subscriber(queue="payments", ack_policy=AckPolicy.MANUAL)
async def handle(msg: RabbitMessage) -> None:
try:
result = await charge(msg.body)
await msg.ack_async()
except TransientError:
await msg.nack_async(requeue=True)
except PermanentError:
await msg.reject_async(requeue=False)
Use MANUAL when the handler needs full settlement control — for example, when settlement depends on an external confirmation or a two-phase commit.
If the handler raises without settling, rabbitkit applies the same
failure settlement as AUTO (transient: requeue once, then DLQ; permanent:
DLQ) and logs it. Earlier releases left the delivery unacked until the
channel closed; each such failure held a prefetch slot, so prefetch_count
failures stalled the consumer. A handler that settled before raising is not
settled again.
If your handler settles through something rabbitkit cannot see, a raw
channel or a CoalescingAcker, and then re-raises, set
ConsumerConfig(manual_settle_on_error=False). Otherwise the pipeline
settles the same delivery tag a second time and the broker closes the
channel. Better: do not re-raise after settling.
Warning: If the handler returns without acking or nacking, the message stays unacked until the connection closes (logged as a warning). rabbitkit never auto-acks under MANUAL.
NACK_ON_ERROR¶
Successful handlers are auto-acked. Failed handlers are nacked with requeue=False.
@broker.subscriber(queue="events", ack_policy=AckPolicy.NACK_ON_ERROR)
async def handle(body: bytes) -> None:
process(body) # nack (no requeue) on any exception
Use when you want errors to go straight to the DLQ without retry. Do not combine with RetryConfig.
ACK_FIRST¶
The message is acknowledged before the handler runs.
@broker.subscriber(queue="logs", ack_policy=AckPolicy.ACK_FIRST)
async def handle(body: bytes) -> None:
write_log(body) # message already acked — loss is possible if this fails
Warning: If the handler fails after the ack, the message is lost permanently. Use only when message loss is acceptable — for example, best-effort audit logging.
Never use ACK_FIRST for financial transactions, order processing, or any flow where at-least-once delivery is required.
Handler deadline (processing_timeout)¶
ConsumerConfig(processing_timeout=30.0) gives every handler a deadline
(default None, off). When it expires, HandlerTimeoutError goes through the
failure settlement above: the async broker cancels the handler task; the sync
broker settles the delivery from its I/O thread and lets the handler thread
run to its end, discarding its late result. It is transient, and it carries outcome_unknown=True: the handler
was cut off part-way, so its side effects may or may not have happened. The
failure log says so (outcome_unknown=True), and classify_error reports
it on ClassifiedError.outcome_unknown. Retrying it is only safe for
idempotent handlers.
Only the deadline produces HandlerTimeoutError. A TimeoutError raised by
the handler's own code (an HTTP client timeout, say) stays an ordinary
transient error. The sync broker cannot interrupt a running thread: with a
deadline set it runs handlers off the I/O thread (one dedicated thread when
worker_count=1), and a timed-out handler keeps its worker until it
returns. See
Reliable Messaging.
When the ack itself fails¶
An ack is a frame written to the channel; the broker does not confirm it.
If writing it raises after the handler succeeded (channel closed, socket
reset), rabbitkit does not know whether the broker received it. It logs
"Ack outcome unknown", increments HandlerPipeline.ack_outcome_unknown_total
(and <namespace>_settlement_outcome_unknown_total when the route has a
MetricsMiddleware), and sends nothing else for that delivery. If the ack
was lost, the broker redelivers the message when the channel closes and the
handler runs again, so handlers must be idempotent. Earlier releases sent
the failed ack down the handler-failure path, which tried to reject a
message that had been processed successfully.
Message Safety¶
For AUTO and MANUAL policies, rabbitkit follows this guarantee:
The original message is never acknowledged before the retry or DLQ publish is confirmed by the broker.
If retry publishing fails, the original message is not acked. It remains unacked and will be redelivered after the connection recovers or the channel times out.
See Message Safety for the full guarantee and failure-case analysis.
Choosing a policy¶
| Scenario | Recommended policy |
|---|---|
| Standard consumer with retries | AUTO + RetryConfig |
| Handler needs external confirmation before ack | MANUAL |
| No retries, failed messages go straight to DLQ | NACK_ON_ERROR |
| Best-effort processing, loss acceptable | ACK_FIRST |