Interface IOutboxStore
Provides persistent storage for outbound messages in the Transactional Outbox pattern.
public interface IOutboxStore : IServiceProvider
- Inherited Members
- Extension Methods
Remarks
Traditional (polling) outbox for relational and document databases
(SQL Server, Postgres, MongoDB, etc.). Messages are staged within a database
transaction alongside business data, then published by a background polling service
(OutboxBackgroundService).
For cloud-native databases that use change-feed triggers instead of polling
(Cosmos DB, DynamoDB, Firestore), see
Excalibur.Data.CloudNative.ICloudNativeOutboxStore.
The two interfaces serve fundamentally different outbox patterns and are
intentionally separate:
IOutboxStore-- polling-based, SQL transactions, background serviceICloudNativeOutboxStore-- change-feed triggers, partition keys, serverless
This interface contains 5 core methods following the Microsoft IDistributedCache pattern. For batch operations, implement IOutboxStoreBatch. For admin/query operations, implement IOutboxStoreAdmin.
Optional capabilities are discovered through GetService(Type),
never by casting the store. A store answers for the capability interfaces it implements and
returns null for the rest. A decorator answers for what it adds and defers everything
else to the store it wraps, so decoration cannot silently drop a capability the underlying store has.
Casting (store is IOutboxStoreAdmin) sees only the outermost type and is therefore lossy through
any decorator; it must not be used.
Interface uses ValueTask for synchronous completion optimization. In-memory implementations complete synchronously without allocation overhead.
Methods
EnqueueAsync(IDispatchMessage, IMessageContext, CancellationToken)
Enqueues a message in the outbox for later delivery with context.
[RequiresUnreferencedCode("Outbox stores serialize the message payload reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming and AOT.")]
[RequiresDynamicCode("Outbox stores serialize the message payload reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming and AOT.")]
ValueTask EnqueueAsync(IDispatchMessage message, IMessageContext context, CancellationToken cancellationToken)
Parameters
messageIDispatchMessageThe message to enqueue.
contextIMessageContextThe message context.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- ValueTask
A task representing the asynchronous enqueue operation.
Remarks
Postcondition on what is staged. The staged message's headers contain exactly the
values marked on context with
SetPropagatedItem(IMessageContext, string, string), plus whatever envelope keys
this store supplies as its own framing. No other context state reaches them — in
particular not Items, which is request-local.
This is stated here, on the interface, because it is the specification and not an implementation detail: while it lived only in the implementations, one store staged the whole Items collection, two staged their envelope keys and nothing else, and six staged neither — all three behaviours legal, none a subtyping violation, and a consumer unable to predict which they would get. Staging MORE than this is now as wrong as staging less, and a conformance derivation can check both directions.
Build the staged message with FromContext(string, byte[], string, IMessageContext, IDictionary<string, object>?), which satisfies the postcondition by construction. A store that assembles an OutboundMessage by hand is responsible for satisfying it itself.
Exceptions
- ArgumentNullException
Thrown when message or context is null.
GetUnsentMessagesAsync(int, CancellationToken)
Retrieves unsent messages from the outbox for publishing.
ValueTask<IEnumerable<OutboundMessage>> GetUnsentMessagesAsync(int batchSize, CancellationToken cancellationToken)
Parameters
batchSizeintMaximum number of messages to retrieve.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- ValueTask<IEnumerable<OutboundMessage>>
Collection of unsent messages ready for delivery.
Remarks
This operation returns persisted payload bytes and closed routing/header data; it does not discover or deserialize consumer payload types. Payload decoding belongs to the configured worker codec and its explicit metadata. Provider construction may impose separate runtime requirements. This claim is unfenced. A store that can enforce leadership fencing implements IFencedOutboxStore, whose overloads take the leadership token; a store that cannot is never handed one.
Exceptions
- ArgumentOutOfRangeException
Thrown when batchSize is less than 1.
MarkFailedAsync(string, string, int, CancellationToken)
Marks a message as failed during delivery.
ValueTask MarkFailedAsync(string messageId, string errorMessage, int retryCount, CancellationToken cancellationToken)
Parameters
messageIdstringThe unique identifier of the message that failed.
errorMessagestringThe error description or exception message.
retryCountintThe current retry attempt count.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- ValueTask
A task representing the asynchronous mark-failed operation.
Remarks
A failure is a delay, not an ending. The message stays owed delivery, and three conditions hold together to keep that true without turning it into a retry loop. Each is stated because a store can satisfy the other two and still be wrong.
The message is withheld, then returned. It does not become claimable again immediately -- an immediate re-claim is a zero-backoff loop that saturates the transport against a destination that is failing anyway -- and it does become claimable once the store's failure-backoff floor has elapsed. The floor is measured from the recorded failure, not from a claim lease: a message that failed without ever being claimed has no lease, and a floor derived from one would yield nothing for it. Withholding it permanently satisfies the first half and silently drops the message, so both halves are required.
A report from a dispatcher that no longer holds the claim is a no-op rather than an error -- it is stale, not invalid. Honouring it would release a claim its successor is still delivering under, and both would then send the same message. A message that was never claimed has no owner and is reported freely. The guard must not be satisfied by refusing everybody -- the owner's own report still has to land, or the store cannot record failures at all.
HOW FINELY "no longer holds the claim" IS JUDGED VARIES BY STORE, AND THIS MEMBER DOES NOT PROMISE PER-CLAIM PRECISION. An earlier wording here said only the claim's owner may report against it, which reads as a per-claim guarantee that no shipped store keeps through this member. What the shipped stores actually compare is a per-PROCESS identity, so two successive claims by the same process are indistinguishable to it: a report from an expired claim of a still-running dispatcher is accepted, and it releases a reservation a live successor of that same process still holds.
THE FLOOR A CALLER MAY RELY ON, stated because "varies by store" is not a contract. Every shipped store that offers this member refuses a report against a message currently held by a DIFFERENT dispatcher process, and admits one against a message nobody holds. That is the floor, and it is uniform: what varies above it is only whether a store can also distinguish two claim cycles of the SAME process, and none of them can through this member. An implementor of this interface is required to meet the floor; a store that matches on the message identifier alone does not implement this member's contract, however well it records the identity elsewhere.
The floor is expressed differently by different data models -- a prefix of a stored claim token, an equality against a configured processor identity, a conditional script, an in-process comparison -- and the obligation is the property, not the mechanism. Note what the floor deliberately does NOT require: an "ownership term" a caller can satisfy by omitting the value it guards is not a guard, so a store whose only option would be such a predicate must instead offer the claim-scoped member below and refuse here, rather than carry a predicate with a hole in it.
For a completion judged against the specific claim the caller holds, use IClaimScopedOutboxStore. It takes the claim identity as an argument and returns an outcome saying whether the store applied the completion or refused it, so a caller whose claim has lapsed is told rather than silently succeeding. Discover it with GetService(Type) rather than a cast: a cast sees only the outermost type and is lossy through any decorator. Not every store implements it; a caller that needs the guarantee should check, because the fallback to this member is the weaker comparison described above.
The recorded attempt count never decreases. Implementations record the greater of the stored
count and retryCount. The ceiling that eventually gives up on a message is driven
by that count, so a late report carrying a lower number would push the ceiling further away each time
one arrived, and the message would be retried without end.
Marking a message that does not exist is a silent no-op. A message in a terminal state is never reopened by a late failure report, and terminal means delivered or dead-lettered -- in both, the decision to stop delivering has already been taken and recorded. Guarding only the delivered state is the error this wording exists to prevent: a reopened dead-lettered message re-enters the retry population it was deliberately removed from. A message merely in flight is not terminal, and a failure report against one must land -- that is the ordinary path this method exists to serve.
The ownership condition above cannot carry this guarantee, and a store that relies on it will be wrong. Dead-lettering releases the delivery lease, so a dead-lettered message presents as never-claimed and is therefore reported freely by that rule. The terminal-state check is required in its own right and applies unconditionally.
The obligation is the property, not the mechanism. A store satisfies it however its data model allows: a status term in the mutation's own predicate, a terminal transition that removes the row so no later report can match it, a claim record stamped with an identity no caller can present, or a claimable predicate keyed on a field the failure path never writes. What is required is that a late report cannot reopen a terminal message -- not that any particular column be tested.
Exceptions
- ArgumentException
Thrown when messageId is null or empty.
- ArgumentNullException
Thrown when errorMessage is null.
MarkSentAsync(string, CancellationToken)
Marks a message as successfully sent.
ValueTask MarkSentAsync(string messageId, CancellationToken cancellationToken)
Parameters
messageIdstringThe unique identifier of the message to mark as sent.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- ValueTask
A task representing the asynchronous mark-sent operation.
Remarks
This mutation is unfenced. A store that can enforce leadership fencing implements IFencedOutboxStore.
Exceptions
- ArgumentException
Thrown when messageId is null or empty.
- InvalidOperationException
Thrown when the message does not exist or is already marked as sent.
StageMessageAsync(OutboundMessage, CancellationToken)
Stages a message in the outbox for later delivery.
ValueTask StageMessageAsync(OutboundMessage message, CancellationToken cancellationToken)
Parameters
messageOutboundMessageThe outbound message to stage.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- ValueTask
A task representing the asynchronous stage operation.
Exceptions
- ArgumentNullException
Thrown when message is null.
- InvalidOperationException
Thrown when a message with the same ID already exists.