Table of Contents

Interface IScopedTransactionalInboxStore

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

An optional capability for IInboxStore implementations backed by a document store whose native transaction cannot be expressed as a BCL IDbTransaction, enabling exactly-once processing: the handler runs and the message is marked processed inside a single provider-native transaction that commits or rolls back atomically.

public interface IScopedTransactionalInboxStore
Extension Methods

Remarks

This is the document-store analogue of ITransactionalInboxStore. Where the relational seam hands the handler a BCL IDbTransaction, this seam hands it an opaque IInboxTransactionScope; a handler that needs to enlist its own writes casts the scope to the provider-native handle through a provider-specific extension (for example scope.AsMongoSession()).

Presence is reported through SupportsTransactional so a ValidateOnStart guard can fail fast rather than throw at runtime. A store that cannot honour the atomic contract (for example a Cosmos DB store configured without a shared partition key, whose TransactionalBatch is single-partition) MUST report false and fall back to the at-least-once idempotent claim protocol (IClaimableInboxStore) — a documented, structurally-guarded degradation, never a false atomic advertisement.

The exactly-once guarantee holds only on the success path: if the handler throws, the whole native transaction rolls back — nothing is marked processed and the message is redelivered for retry.

Methods

TryProcessTransactionallyAsync(string, string, Func<IInboxTransactionScope, CancellationToken, ValueTask>, CancellationToken)

Atomically, within a single provider-native transaction, checks the message has not already been processed, runs handler, and marks the message processed — committing the handler's enlisted writes and the processed-mark together, or rolling both back on failure.

ValueTask<bool> TryProcessTransactionallyAsync(string messageId, string handlerType, Func<IInboxTransactionScope, CancellationToken, ValueTask> handler, CancellationToken cancellationToken)

Parameters

messageId string

The unique identifier of the message.

handlerType string

The fully qualified type name of the handler processing the message.

handler Func<IInboxTransactionScope, CancellationToken, ValueTask>

The processing delegate, invoked exactly once inside the native transaction if and only if the message was not already processed. It receives an opaque IInboxTransactionScope; writes it performs through the provider-native handle obtained from that scope commit atomically with the processed-mark. Writes made outside the scope are not enlisted and are therefore not atomic with the mark.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<bool>

true if the caller processed the message (handler ran and the processed-mark committed); false if the message was already processed (a duplicate — handler is not invoked).

Exceptions

ArgumentException

Thrown when messageId or handlerType is null or empty.