Table of Contents

Interface IInbox

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.Abstractions.dll

Defines the contract for inbox pattern implementations that deduplicate redelivered messages so each is processed effectively once. Delivery itself remains at-least-once — the transport may deliver the same message more than once — and the inbox removes the duplicate effect by tracking processed messages, not the duplicate delivery. Handlers must be idempotent.

public interface IInbox : IAsyncDisposable
Inherited Members
Extension Methods

Remarks

The inbox pattern is essential for building resilient distributed systems that can handle message delivery guarantees across service boundaries. It provides deduplication capabilities and ensures that messages are processed exactly once, even in the presence of network failures, retries, or system restarts. This pattern is particularly important for financial systems, order processing, and other scenarios where duplicate processing could have serious business consequences.

Methods

RunInboxDispatchAsync(string, CancellationToken)

Asynchronously processes all pending messages in the inbox for the specified dispatcher, ensuring each is processed effectively once (a redelivered message is skipped, not reprocessed) and proper message ordering where required.

Task<int> RunInboxDispatchAsync(string dispatcherId, CancellationToken cancellationToken)

Parameters

dispatcherId string

The unique identifier of the dispatcher instance processing messages, used for coordination and preventing concurrent processing conflicts in multi-instance deployments.

cancellationToken CancellationToken

Token to monitor for cancellation requests during inbox processing.

Returns

Task<int>

A task that represents the asynchronous inbox processing operation, containing the number of messages successfully processed during this execution.

Remarks

This method implements the core inbox processing logic, handling message deduplication, ordering constraints, and error recovery. It processes messages in a transactionally safe manner, ensuring that message processing and inbox state updates are atomic. Failed message processing may result in messages being retried according to configured retry policies.

Exceptions

ArgumentException

Thrown when dispatcherId is null, empty, or whitespace.

SaveMessageAsync<TMessage>(TMessage, string, IMessageMetadata, CancellationToken)

Asynchronously saves a message to the inbox with deduplication tracking, ensuring that duplicate messages (identified by external ID) are not processed multiple times.

Task SaveMessageAsync<TMessage>(TMessage message, string externalId, IMessageMetadata metadata, CancellationToken cancellationToken) where TMessage : IDispatchMessage

Parameters

message TMessage

The message instance to save for future processing.

externalId string

A unique external identifier for the message, typically from the originating system, used for deduplication and idempotency checking.

metadata IMessageMetadata

Message metadata containing correlation information, timestamps, and other contextual data needed for proper message processing and tracing.

cancellationToken CancellationToken

Token to monitor for cancellation requests during save operations.

Returns

Task

A task that represents the asynchronous message save operation.

Type Parameters

TMessage

The type of message to save, must implement IDispatchMessage.

Remarks

This method implements the message storage aspect of the inbox pattern, ensuring that incoming messages are durably persisted with proper deduplication tracking. If a message with the same external ID has already been processed, the implementation may choose to ignore the duplicate or handle it according to configured duplicate message policies. The method should be transactionally safe and handle concurrent message arrival scenarios appropriately.

Exceptions

ArgumentNullException

Thrown when message, externalId, or metadata is null.