Table of Contents

Interface IClaimScopedOutboxStore

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

An optional capability for outbox stores that can scope a completion report to the CLAIM the caller holds, rather than to the process it runs in.

public interface IClaimScopedOutboxStore
Extension Methods

Remarks

A fencing token identifies a TENURE. It cannot discriminate two claim cycles of the same tenure, so a report from an earlier cycle of the same process is indistinguishable from one by the current holder. The claim identity is per-claim, and it travels on the message as DispatcherId because a map from message id to claim is overwritten by the re-claim it exists to detect.

This is a SEGREGATED capability interface — composition, NOT inheritance of IOutboxStore — so that a decorator enforcing a confidentiality boundary can forward it whole: no member here accepts or returns a message payload.

Discovered through GetService(Type), never by casting the store. A cast sees only the outermost type and is lossy through any decorator.

Methods

MarkFailedAsync(string, string, int, string, CancellationToken)

Records a delivery failure reported by the claim identified by claimIdentity.

ValueTask<OutboxCompletionOutcome> MarkFailedAsync(string messageId, string errorMessage, int retryCount, string claimIdentity, CancellationToken cancellationToken)

Parameters

messageId string

The unique identifier of the message that failed.

errorMessage string

The error describing the failure.

retryCount int

The absolute attempt count for this message.

claimIdentity string

The claim under which the caller received this message, from DispatcherId.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<OutboxCompletionOutcome>

What the store did, decided by the same atomic action that performed the mutation.

Remarks

Implementations MUST evaluate the claim and the mutation in ONE atomic action, and MUST decide whether to refuse from that same action. A store that reconstructs the decision from a separate read compares a value captured before the window it must describe, which is false exactly when the refusal is real.

A refusal is REPORTED, not thrown, and the reason is the caller's control flow rather than style. The drain reports a delivery failure from inside its own exception handler; an exception raised there is not caught by a sibling catch on the same try, so it escapes the whole cycle and abandons every message the caller still holds. The refusal must cost one message, so it travels in the return value where the caller reads it without unwinding.

A refusal here is ROW-LEVEL, and the distinction decides how much work is abandoned. A fence refusal means a NEWER TENURE exists and the whole drain cycle must stop, whereas ClaimLost means only that this message was re-claimed — the caller stops writing for THIS message and continues with the others it still holds. A caller that aborts its cycle on a lost claim abandons messages a live tenure owns.

Exceptions

ArgumentException

Thrown when messageId is null or empty.

MarkFailedWithBackoffAsync(string, string, int, DateTimeOffset, string, CancellationToken)

Records a delivery failure reported by the claim identified by claimIdentity, applying the per-message backoff schedule.

ValueTask<OutboxCompletionOutcome> MarkFailedWithBackoffAsync(string messageId, string errorMessage, int retryCount, DateTimeOffset nextAttemptAt, string claimIdentity, CancellationToken cancellationToken)

Parameters

messageId string

The unique identifier of the message that failed.

errorMessage string

The error describing the failure.

retryCount int

The absolute attempt count for this message.

nextAttemptAt DateTimeOffset

The time before which the message must NOT be re-claimed.

claimIdentity string

The claim under which the caller received this message, from DispatcherId.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<OutboxCompletionOutcome>

What the store did, decided by the same atomic action that performed the mutation.

Remarks

This member exists because the backoff route is the one a genuine delivery failure takes when automatic retry is enabled. Scoping only the plain completion would leave the dominant failure path unscoped while the capability appeared to close it. The same atomicity and reported-refusal requirements as MarkFailedAsync(string, string, int, string, CancellationToken) apply here in full.

Exceptions

ArgumentException

Thrown when messageId is null or empty.

MarkSentAsync(string, string, CancellationToken)

Marks a message sent only while the caller holds the current claim.

ValueTask<OutboxCompletionOutcome> MarkSentAsync(string messageId, string claimIdentity, CancellationToken cancellationToken)

Parameters

messageId string

The persisted message identifier captured at acquisition.

claimIdentity string

The immutable acquisition evidence captured before delivery.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<OutboxCompletionOutcome>

The outcome decided atomically with the guarded terminal transition.

Remarks

Missing or released leases return ClaimLost. Validate nonblank identifiers before mutation. A fenced authority additionally requires a positive tenure; evaluate its fence before row-level outcomes. Retained terminal rows return AlreadyTerminal. Never infer the outcome from a later read.