From ce9fa3a0f33e2e74e018a4d57d7dc393d1c9b680 Mon Sep 17 00:00:00 2001 From: Guilherme Appel Date: Thu, 5 Nov 2026 20:09:12 -0300 Subject: [PATCH] docs: say how each transport defers a message and what that does to ordering HandlerFailure.md said a defer goes through a scheduler and de-orders the message, which isn't true on every transport. Ian suggested a table in PR #209, so the page now has one, and the two sentences that said so point to it. Part of issue #208. --- contents/HandlerFailure.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/contents/HandlerFailure.md b/contents/HandlerFailure.md index 7099c55..ae4db32 100644 --- a/contents/HandlerFailure.md +++ b/contents/HandlerFailure.md @@ -73,7 +73,7 @@ You control requeue behavior through two `Subscription` properties: How the delay is implemented depends on the transport. Some transports support native delay; others rely on a configured `IAmARequestScheduler`. See [Error Handling Options](/contents/ErrorHandlingOptions.md) for configuration details. -The delay mechanism depends on a configured scheduler (`IAmARequestScheduler`). By default, Brighter supplies an `InMemoryScheduler` that holds deferred messages in memory. If the host shuts down before a deferred message fires, it is lost. For production systems that require durability, configure an external scheduler such as Quartz, Hangfire, TickerQ, or AWS Scheduler. +On the [transports that use a scheduler](#blocking-retry-and-non-blocking-retry), the delay depends on that scheduler (`IAmARequestScheduler`). By default, Brighter supplies an `InMemoryScheduler` that holds deferred messages in memory. If the host shuts down before a deferred message fires, it is lost. For production systems that require durability, configure an external scheduler such as Quartz, Hangfire, TickerQ, or AWS Scheduler. ### When to Use Requeue with Delay @@ -85,7 +85,26 @@ Because a Performer in Brighter, is a single-threaded message pump, using Polly However, if you don't want to block the thread throwing `DeferMessageAction` will create a **Non-Blocking Retry** by moving the message into Brighter's scheduler (or use native delay support on the transport), which will deliver it after a delay, freeing up the Performer to process the next message in the channel. -`DeferMessageAction` will de-order the message. This means you cannot rely on the order of messages in the channel. Either, your message must be able to processed independently of the others, or you must use a strategy to process out-of-order. For example you may add a version stamp to the message and only applying it if you have not already processed a later message. +What a defer does to the message, and so to its order, depends on the transport: + +| Broker | Defer Message Uses | Ordering | +|--------|--------------------|----------| +| AWS SQS | `ChangeMessageVisibility` on the same message, no scheduler | FIFO queue: preserved within the message group when `BufferSize` is 1, the default. Standard queue: no order to preserve | +| RabbitMQ | A new message, through the delayed message exchange if the exchange has `SupportDelay` set, otherwise through the scheduler | De-orders | +| Azure Service Bus, topic subscription | Abandons the message. The delay is ignored and a warning is logged | Not guaranteed | +| Azure Service Bus, `UseServiceBusQueue` or `ForwardTo` | A new message scheduled on the broker, or through the scheduler with `RequeueSchedulerMode.Global` | De-orders | +| PostgreSQL | Updates `visible_timeout` on the same row, no scheduler | De-orders: later rows are read while this one waits | +| RocketMQ | `ChangeInvisibleDuration` on the same message, no scheduler. A delay above 12 hours is cut to 12 hours | Not guaranteed | +| GCP Pub/Sub | Returns the message to Pub/Sub at once, no scheduler. The subscription's retry policy decides when it comes back | Not guaranteed | +| All others (Kafka, Redis, MQTT, MSSQL) | The scheduler | De-orders | + +On an SQS FIFO queue with a `BufferSize` above 1, messages of the group that were already fetched still run while the deferred one waits. + +On GCP Pub/Sub, Brighter sets the retry policy from `RequeueDelay` and `MaxRequeueDelay` when it creates or updates the subscription. A delay on the defer itself is ignored. + +With a delay of zero, RabbitMQ and the transports in the last row skip the scheduler and put the message straight back on the channel, which still de-orders it. + +Unless the table says the order is preserved, you cannot rely on the order of messages in the channel after a `DeferMessageAction`. Either, your message must be able to processed independently of the others, or you must use a strategy to process out-of-order. For example you may add a version stamp to the message and only applying it if you have not already processed a later message. A useful rule of thumb is: