Interface IFencedOutboxStoreDiagnostics
Optional diagnostic and recovery surface for a store's leadership-fencing high-water mark.
public interface IFencedOutboxStoreDiagnostics
- Extension Methods
Remarks
IFencedOutboxStore's claim is specified never to throw on a stale token — it returns an empty set instead, so a superseded leader's drain does not crash-loop. That makes an empty claim ambiguous from the outside: it means either "no work is due" or "your fencing token is stale", and nothing about the claim itself distinguishes the two. This interface exists to remove that ambiguity and to give an operator a way to recover from a poisoned fence — most commonly a fencing-token generator whose backing store was re-created (a namespace teardown, a deleted coordination lease), which restarts token issuance below the outbox's already-recorded high-water and leaves the outbox silently undrainable, with no error anywhere, forever.
Discovered the same way every other optional outbox capability is: store.GetService(typeof(IFencedOutboxStoreDiagnostics)),
never a cast — a decorated store answers through its own capability seam.
Methods
GetFencingHighWaterAsync(CancellationToken)
Reads the store's currently recorded fencing high-water mark.
Task<long?> GetFencingHighWaterAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- Task<long?>
The recorded high-water mark, or null when no fencing token has ever been presented to this store.
ResetFencingHighWaterAsync(long, bool, CancellationToken)
Administratively sets the store's fencing high-water mark.
Task ResetFencingHighWaterAsync(long newHighWater, bool force, CancellationToken cancellationToken)
Parameters
newHighWaterlongThe high-water mark to record.
forceboolWhen false (the default an operator should reach for), the store MUST refuse a
newHighWaterstrictly below the currently recorded value and throw InvalidOperationException without changing anything. When true, the store MUST applynewHighWaterunconditionally, including a lowering.cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- Task
A task representing the asynchronous reset operation.
Remarks
Lowering the high-water is unsafe by design. The high-water exists to refuse a superseded
leader; lowering it re-admits one — a leader whose token is now below the (lowered) high-water reads
as current again and can claim and complete messages a fresher leader already owns. This is the same
split-brain the fence exists to prevent, self-inflicted through the recovery surface meant to fix a
stuck fence. force exists for the one case where that risk is understood and
accepted (recovering a genuinely poisoned fence, with independent confirmation no live claim
conflicts with the new value) — never as a routine unstick button.
Exceptions
- InvalidOperationException
newHighWateris below the recorded high-water mark andforceis false.