Class InboxMiddleware
- Namespace
- Excalibur.Dispatch.Middleware.Inbox
- Assembly
- Excalibur.Dispatch.dll
Middleware responsible for implementing inbox semantics to ensure at-most-once message processing.
[AppliesTo(MessageKinds.All)]
public sealed class InboxMiddleware : IDispatchMiddleware
- Inheritance
-
InboxMiddleware
- Implements
- Inherited Members
- Extension Methods
Remarks
This middleware provides two modes of operation:
- Full Inbox Mode : Uses persistent storage via IInboxStore for durability across restarts
- Light Mode : Uses in-memory deduplication via IInMemoryDeduplicator for performance
The inbox middleware implements the Idempotent Consumer pattern by:
- Admitting a message atomically (duplicate detection)
- Persisting message receipt before handler execution (inbox persistence)
- Marking message as processed after successful handler completion
- Handling failures with appropriate retry mechanisms
Concurrency guarantee. Both modes admit through a single atomic compare-and-set, so concurrent
redeliveries of the same message can never both execute the handler: light mode claims through an
IClaimableDeduplicator; full mode claims through the store's lease-based
TryAcquireLeaseAsync(string, string, TimeSpan, CancellationToken)
(a self-expiring lease that also reclaims a dead processor's stuck claim). A full-mode store that does
not implement lease claiming falls back to a durable-status check whose at-most-once guarantee holds
across process restarts but is not race-free across concurrent processors — the registration guard
surfaces that weaker configuration.
Constructors
InboxMiddleware(IOptions<InboxConfigurationOptions>, IInboxStore?, IInMemoryDeduplicator?, DispatchJsonSerializer, ILogger<InboxMiddleware>)
Initializes a new instance of the InboxMiddleware class. Creates a new inbox middleware instance.
public InboxMiddleware(IOptions<InboxConfigurationOptions> options, IInboxStore? inboxStore, IInMemoryDeduplicator? deduplicator, DispatchJsonSerializer serializer, ILogger<InboxMiddleware> logger)
Parameters
optionsIOptions<InboxConfigurationOptions>Configuration options for inbox behavior.
inboxStoreIInboxStoreOptional persistent inbox store for full inbox mode.
deduplicatorIInMemoryDeduplicatorOptional in-memory deduplicator for light mode.
serializerDispatchJsonSerializerThe configured serializer used to write payloads symmetrically with the read path.
loggerILogger<InboxMiddleware>Logger for diagnostic information.
Properties
ApplicableMessageKinds
Gets the message kinds that this middleware applies.
public MessageKinds ApplicableMessageKinds { get; }
Property Value
- MessageKinds
The set of message kinds this middleware applies to.
Remarks
Specifies which types of messages this middleware should process. The pipeline filters middleware based on these flags, ensuring only relevant middleware processes each message. This improves performance and allows middleware to specialize in handling specific message types. If not implemented, defaults to All for backward compatibility.
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.
[UnconditionalSuppressMessage("Trimming", "IL2026:Members annotated with 'RequiresUnreferencedCodeAttribute' require dynamic access otherwise can break functionality when trimming application code", Justification = "Inbox payload serialization is only used for known message types registered at startup.")]
[UnconditionalSuppressMessage("AotAnalysis", "IL3050:Calling members annotated with 'RequiresDynamicCodeAttribute' may break functionality when AOT compiling.", Justification = "Inbox payload serialization relies on JSON serialization and is not supported in AOT scenarios.")]
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.