Interface IFencedClaimScopedOutboxStore
An outbox store that can evaluate BOTH the leadership fence and the claim in the one atomic action that records a completion.
public interface IFencedClaimScopedOutboxStore
- Extension Methods
Remarks
This is the intersection of two capabilities, not a member added to either of them. A fenced completion needs a fencing token AND a claim identity, so it can only be honoured by a store that has both. Declaring it on the fencing contract would oblige every fenced store to implement a member most of them cannot honour — a precondition strengthened on an existing contract, imposed on implementors that never asked for it. Keeping the obligation on its own contract lets a store that has only one of the two remain honest rather than throwing from a member its interface claims it has.
It inherits NOTHING, and that is a confidentiality requirement rather than a style choice. The obvious spelling — deriving from the fencing and claim-scoped contracts to make the product explicit to the type system — pulls in the payload-bearing store surface transitively. A decorator that enforces a confidentiality boundary can forward a capability unmediated only when no member of it, inherited members included, carries a message payload; a capability that fails that test is denied instead, and a denied capability is silently absent for exactly the consumers who enabled encryption. So the product is carried by the MEMBER — which cannot be called without both a tenure token and a claim identity — and not by the base list. Nothing here moves a payload: identifiers, an error string, a retry count, an optional instant, and two opaque tokens.
Discovered through GetService(Type), never by casting the store. A cast sees only the outermost type and is lossy through any decorator, so a decorated store that has this capability would answer "absent" while the startup guard, which probes correctly, answers "present".
Why this closes what the fence alone does not. The fence covers the claim and the mark-sent; a failure report carrying no token is a write a superseded tenure can still perform, and a report carrying no claim is one an earlier cycle of the SAME tenure can still perform. Only a member holding both terms, compared inside one statement, refuses both.
Methods
MarkFailedAsync(string, string, int, DateTimeOffset?, OutboxWriteAuthority, CancellationToken)
Records a delivery failure, applying it only if the caller still holds BOTH the tenure and the claim.
ValueTask<OutboxCompletionOutcome> MarkFailedAsync(string messageId, string errorMessage, int retryCount, DateTimeOffset? nextAttemptAt, OutboxWriteAuthority authority, CancellationToken cancellationToken)
Parameters
messageIdstringThe unique identifier of the message that failed.
errorMessagestringThe error describing the failure.
retryCountintThe absolute attempt count for this message.
nextAttemptAtDateTimeOffset?The time before which the message must NOT be re-claimed, or null to record the failure without a computed backoff schedule.
authorityOutboxWriteAuthorityThe tenure and claim the caller is acting under.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- ValueTask<OutboxCompletionOutcome>
What the store did, decided by the same atomic action that performed the mutation.
Remarks
ONE member rather than two, because the backoff schedule is a VALUE the caller already has or does not. The unfenced surface splits the plain and scheduled completions across two members; here the caller has already decided which it wants and holds the computed instant, so a second member would differ only in whether one argument was supplied. The nullable schedule is not the omitted-guard shape that the authority deliberately avoids: "there is no backoff schedule" is a real state with a real meaning to the statement, whereas "there is no tenure" cannot arise on a fenced member at all.
Implementations MUST evaluate the fence, the claim and the mutation in ONE atomic action, and MUST decide the returned outcome from that same action. A store that re-reads the row afterwards to classify what happened compares a value captured outside the window it must describe, which is wrong exactly when the refusal is real.
Implementations MUST persist the high-water mark such that it never decreases across process restart, failover or replica promotion. A store whose high-water is only as durable as an asynchronously-replicated value does not satisfy this and MUST NOT implement this interface.
Atomicity is necessary and not sufficient, and the second half is why this clause exists. A fence is two properties: the comparison and the mutation are one indivisible action, AND the mark is monotone non-decreasing under every fault in the deployment's model. A store can satisfy the first perfectly and still be unsafe — if a failover, an eviction or a restore can roll the mark backwards, a superseded tenure presents a token that is no longer below it and is admitted. A monotonic counter that can decrease is not a fence, and a store providing only the atomicity half satisfies the letter of this interface while breaking the guarantee it exists to give.
The refusals are REPORTED, never thrown. The drains report a delivery failure from inside their own exception handlers, where a sibling handler on the same block cannot run, so an exception raised here escapes the whole cycle and abandons every message the caller still legitimately holds. The two refusals also differ in how much work they cost: FenceRefused means a NEWER TENURE exists and the caller must stop draining entirely, while ClaimLost concerns this one message and the caller continues with the rest.
Exceptions
- ArgumentException
Thrown when
messageIdis null or empty.
MarkSentAsync(string, OutboxWriteAuthority, CancellationToken)
Marks a message sent only while the caller holds the current tenure and claim.
ValueTask<OutboxCompletionOutcome> MarkSentAsync(string messageId, OutboxWriteAuthority authority, CancellationToken cancellationToken)
Parameters
messageIdstringThe persisted message identifier captured at acquisition.
authorityOutboxWriteAuthorityThe immutable acquisition evidence captured before delivery.
cancellationTokenCancellationTokenToken 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.