Interface IClaimableInboxStore
An optional capability for IInboxStore implementations that support an atomic claim-before-execute idempotency protocol: reserve a message for processing, then either finalize it on success or release it on failure.
public interface IClaimableInboxStore
- Extension Methods
Remarks
This is a segregated capability interface (composition, NOT inheritance of IInboxStore) so that IInboxStore stays within the Interface Segregation threshold. Inbox stores that support atomic claiming implement this interface in addition to IInboxStore.
The protocol makes idempotent handling correct under concurrent duplicate delivery without dropping a message whose handler fails:
- TryClaimAsync(string, string, CancellationToken) atomically before the handler runs. false means another caller already holds the claim (duplicate) — skip.
- On handler success, finalize the claim via MarkProcessedAsync(string, string, CancellationToken) (the entry becomes terminal Processed).
- On handler failure, ReleaseAsync(string, string, CancellationToken) the claim so a redelivery can re-admit the message. Leaving a terminal entry on failure would silently drop the message.
The steps above are the whole of this protocol: the claim never auto-expires, and the caller governs its TTL. A store that instead supports a self-expiring lease — where admission and expired-lease reclaim collapse into one atomic compare-and-set, and a handler failure needs no explicit release — declares ILeasedInboxStore. The two are separate interfaces so a caller can tell which protocol it holds before it calls; a store may declare one, the other, both, or neither.
Methods
ReleaseAsync(string, string, CancellationToken)
Releases a previously acquired claim for a specific handler by removing the entry, so that a redelivery of the same message can be re-admitted.
ValueTask ReleaseAsync(string messageId, string handlerType, CancellationToken cancellationToken)
Parameters
messageIdstringThe unique identifier of the message.
handlerTypestringThe fully qualified type name of the handler.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- ValueTask
A task that represents the asynchronous release operation.
Remarks
Call this when the handler fails after a successful TryClaimAsync(string, string, CancellationToken). Releasing an already-removed or never-claimed entry is a no-op, and so is releasing it twice: a failure path that is itself retried must not be turned into a second failure.
The removal is restricted to non-terminal entries. A caller is not expected to release a claim it has already finalized through MarkProcessedAsync(string, string, CancellationToken), but one whose claim lapsed can arrive here after a replacement processor took the message over and finalized it, and an implementation MUST leave that terminal entry in place rather than delete it. Erasing the processed record would re-admit the message on its next delivery and run the handler a second time, repeating every side effect, with no duplicate visible to any caller.
Exceptions
- ArgumentException
Thrown when
messageIdorhandlerTypeis null or empty.
TryClaimAsync(string, string, CancellationToken)
Atomically claims a message for a specific handler by inserting a non-terminal (Processing) entry if and only if none already exists.
ValueTask<bool> TryClaimAsync(string messageId, string handlerType, CancellationToken cancellationToken)
Parameters
messageIdstringThe unique identifier of the message.
handlerTypestringThe fully qualified type name of the handler processing the message.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- ValueTask<bool>
true if the caller created the claim (first writer, proceed to handle); false if an entry already exists for the key — already claimed, already processed, or previously failed (duplicate, skip).
Remarks
This is a single atomic "first writer wins" operation (e.g. INSERT … ON CONFLICT DO NOTHING,
INSERT … WHERE NOT EXISTS, or an atomic add). It replaces the racy check-then-act of a
separate IsProcessedAsync(string, string, CancellationToken) followed by a later mark.
Admission is decided by the presence of an entry, not by its status. The claim is refused whenever any entry already exists for the key — Processing, terminal Processed, and Failed alike. Retry on this protocol is reached by ReleaseAsync(string, string, CancellationToken), which removes the row: the next redelivery finds no entry and the claim admits it again. A caller therefore releases on every handler failure it intends to retry, and records a failure only for an attempt it is handing to the retry drain.
A Failed entry is deliberately not re-claimable. It belongs to the estate-wide retry drain, which reads failed entries and dispatches them itself. This protocol carries no term — the claim never auto-expires and nothing identifies its holder — so there is nothing with which to fence a redelivery against the drain. Admitting a failed entry here would let a redelivery enter the handler while the drain is dispatching the same entry, running it twice.
This diverges from ILeasedInboxStore, and the divergence is deliberate. TryAcquireLeaseAsync(string, string, TimeSpan, CancellationToken) does re-admit a Failed entry for retry, because recording a failure there clears the lease term — a failed entry has no holder — and every subsequent write is fenced by the term the acquisition returned, so the retrying processor and any concurrent one cannot both act. The two protocols reach retry by different means: removal of the row here, re-acquisition under a fresh term there. A consumer holding one must not assume the other's behaviour.
Exceptions
- ArgumentException
Thrown when
messageIdorhandlerTypeis null or empty.