Table of Contents

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:

  1. Admitting a message atomically (duplicate detection)
  2. Persisting message receipt before handler execution (inbox persistence)
  3. Marking message as processed after successful handler completion
  4. 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

options IOptions<InboxConfigurationOptions>

Configuration options for inbox behavior.

inboxStore IInboxStore

Optional persistent inbox store for full inbox mode.

deduplicator IInMemoryDeduplicator

Optional in-memory deduplicator for light mode.

serializer DispatchJsonSerializer

The configured serializer used to write payloads symmetrically with the read path.

logger ILogger<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

message IDispatchMessage

The message being processed.

context IMessageContext

The message context containing metadata and processing state.

nextDelegate DispatchRequestDelegate

The delegate to invoke the next middleware in the pipeline.

cancellationToken CancellationToken

The 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.