Table of Contents

Interface ILeasedInboxStore

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

An optional capability for IInboxStore implementations that support a self-expiring lease idempotency protocol: acquire a lease that expires on its own, hold it across handler execution, then finalize under the term the acquisition returned.

public interface ILeasedInboxStore
Extension Methods

Remarks

This is the self-governing counterpart to IClaimableInboxStore, whose claim never auto-expires and whose TTL the caller governs. The two protocols are separate interfaces because a store supports one, the other, both, or neither — and a caller must be able to tell which it holds before it calls. Admission and expired-lease reclaim collapse into a single atomic compare-and-set, making both the double-admission race and the permanently-stuck claim inexpressible.

A claim is a term. Acquisition returns a LeaseToken, and every later write carries it as a predicate the store enforces inside its own atomic step. A caller whose lease has lapsed therefore cannot alter or finalize the record of the caller that replaced it: it presents the term of the lease it lost, which matches no row. This is why the protocol does not rely on a status predicate — at the instant of the bad write the entry is legitimately Processing, its successor's, so status protects the terminal state and never the term.

Every fenced operation returns a bool, never void. A write rejected for a stale term must be distinguishable from one that took effect; a silent no-op would leave a caller believing it finalized a message it had already lost.

The lease-expiry comparison MUST be evaluated against the store's own server clock inside the atomic operation — never an app-side clock — because the invariant is distributed across competing processors and only the store's single clock is skew-free. The supplied duration governs the app-side lease length only.

Why the term is unique, and the one assumption that carries it. Reclaim admits an entry only when its recorded expiry is strictly earlier than the store clock, and the replacement expiry is that same clock plus a non-negative duration — so a newly written term is always strictly greater than the one it displaced, decided inside one atomic step. That argument holds because each store call resolves the clock independently. A future change that batches an acquisition and its finalization into one shared transaction would, on any store whose clock function is fixed for the transaction's lifetime rather than evaluated per operation, freeze that clock, make two terms compare equal, and silently stop the fence discriminating. Keep each operation on its own transaction, or re-establish uniqueness by another means before batching them.

Only Processed is terminal. A handler failure leaves the entry Failed and clears the lease term — a failed entry has no holder — so a redelivery re-admits it for retry and a failure never silently drops the message.

Methods

CompleteAsync(string, string, LeaseToken, CancellationToken)

Finalizes a leased message as terminal Processed, but only while lease is still the entry's current term.

ValueTask<bool> CompleteAsync(string messageId, string handlerType, LeaseToken lease, CancellationToken cancellationToken)

Parameters

messageId string

The unique identifier of the message.

handlerType string

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

lease LeaseToken

The term returned by TryAcquireLeaseAsync(string, string, TimeSpan, CancellationToken).

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<bool>

true if the caller still held the lease and the entry is now terminal; false if the lease had lapsed and been reclaimed, or the entry no longer exists — in which case the caller has lost its term and MUST NOT treat the message as finalized by it.

Exceptions

ArgumentException

Thrown when messageId or handlerType is null or empty.

FailAsync(string, string, LeaseToken, string, CancellationToken)

Records a handler failure against a leased message, leaving it Failed and re-admittable, but only while lease is still the entry's current term.

ValueTask<bool> FailAsync(string messageId, string handlerType, LeaseToken lease, string errorMessage, CancellationToken cancellationToken)

Parameters

messageId string

The unique identifier of the message.

handlerType string

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

lease LeaseToken

The term returned by TryAcquireLeaseAsync(string, string, TimeSpan, CancellationToken).

errorMessage string

A description of the handler failure.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<bool>

true if the caller still held the lease and the failure was recorded; false if the lease had lapsed and been reclaimed, or the entry no longer exists.

Remarks

Clears the entry's lease term on success: a failed entry has no holder, so it must not continue to carry one that a later comparison could match.

Exceptions

ArgumentException

Thrown when messageId or handlerType is null or empty.

TryAcquireLeaseAsync(string, string, TimeSpan, CancellationToken)

Atomically acquires a self-expiring lease on a message for a specific handler, returning the ownership term to present on finalization.

ValueTask<LeaseToken?> TryAcquireLeaseAsync(string messageId, string handlerType, TimeSpan leaseDuration, CancellationToken cancellationToken)

Parameters

messageId string

The unique identifier of the message.

handlerType string

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

leaseDuration TimeSpan

How long the lease is held before another processor may reclaim it.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<LeaseToken?>

The LeaseToken identifying this holder when the caller acquired the lease, reclaimed an expired one, or re-admitted a previously Failed entry for retry (it is now the sole processor); null if a live lease is held elsewhere, or the entry is terminal Processed.

Remarks

Succeeds when no entry exists, the entry is Received, the entry is Failed (re-admitted for retry), or the entry is Processing with an expired lease (reclaiming a dead processor's stuck claim). A terminal Processed entry is never reclaimed.

Exceptions

ArgumentException

Thrown when messageId or handlerType is null or empty.