Class DeadLetterOnExhaustionMiddleware
- Namespace
- Excalibur.Dispatch.ErrorHandling
- Assembly
- Excalibur.Dispatch.dll
Optional opt-in middleware that auto-dead-letters an in-process dispatch once RetryMiddleware
has exhausted every retry attempt. It is placed upstream of RetryMiddleware
so the retry middleware runs as its next delegate; it then routes a genuine retry-exhaustion to
the dead-letter queue, whether the exhaustion arrives as a returned IMessageResult or as a
propagating exception.
public sealed class DeadLetterOnExhaustionMiddleware : IDispatchMiddleware
- Inheritance
-
DeadLetterOnExhaustionMiddleware
- Implements
- Inherited Members
- Extension Methods
Remarks
This decorator composes the retry-exhaustion terminal — it does not re-implement attempt counting or exhaustion detection (RetryMiddleware is the single source of truth). It routes only a genuine exhaustion, which the retry middleware records on the message context — never a fault it declined to retry, and never a handler's own failed result from before the retry cap, neither of which is an exhaustion.
It is intentionally distinct from PoisonMessageMiddleware (which owns PoisonMessage/DeserializationFailed): this decorator owns MaxRetriesExceeded only, so the two compose rather than duplicate.
The dead-letter write is a best-effort side effect: the original exhaustion always flows up unchanged — a returned failure stays terminal and visible (never swallowed into a fake success), and a propagating exception is rethrown untouched. A failure of the dead-letter enqueue itself is logged and swallowed (fail-open) so an unavailable dead-letter queue can never mask or crash the original exhaustion.
Constructors
DeadLetterOnExhaustionMiddleware(IDeadLetterQueue, ILogger<DeadLetterOnExhaustionMiddleware>)
Initializes a new instance of the DeadLetterOnExhaustionMiddleware class.
public DeadLetterOnExhaustionMiddleware(IDeadLetterQueue deadLetterQueue, ILogger<DeadLetterOnExhaustionMiddleware> logger)
Parameters
deadLetterQueueIDeadLetterQueueThe dead-letter queue exhausted dispatches are routed to.
loggerILogger<DeadLetterOnExhaustionMiddleware>The logger instance.
Properties
Stage
Gets the pipeline stage where this middleware should execute.
public DispatchMiddlewareStage? Stage { get; }
Property Value
- DispatchMiddlewareStage?
The pipeline stage for this middleware.
Remarks
The stage determines the execution order of middleware in the pipeline. If null, the middleware will be registered at the end of the pipeline. Stages are processed in numeric order, allowing fine-grained control over middleware execution sequence.
Methods
InvokeAsync(IDispatchMessage, IMessageContext, DispatchRequestDelegate, CancellationToken)
Processes the message within the middleware pipeline.
public ValueTask<IMessageResult> InvokeAsync(IDispatchMessage message, IMessageContext context, DispatchRequestDelegate nextDelegate, CancellationToken cancellationToken)
Parameters
messageIDispatchMessageThe message being processed.
contextIMessageContextThe message context containing metadata and processing state.
nextDelegateDispatchRequestDelegateThe delegate to invoke the next middleware in the pipeline.
cancellationTokenCancellationTokenThe cancellation token to observe.
Returns
- ValueTask<IMessageResult>
A ValueTask<TResult> representing the result of message processing, potentially modified by this middleware. ValueTask can avoid allocating a Task for a synchronously completed result; other dispatch work can still allocate.
Remarks
Implementations can execute logic before calling nextDelegate, after calling it, or both. To short-circuit the pipeline, don't call nextDelegate and return an appropriate result. The context can be used to share data between middleware components. Respect the cancellation token to support timeouts and graceful shutdown.
Exceptions
- ArgumentNullException
Thrown when message, context, or nextDelegate is null.
- OperationCanceledException
Thrown when the operation is cancelled.