Table of Contents

Interface IFencedOutboxStoreDiagnostics

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

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

cancellationToken CancellationToken

Token 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

newHighWater long

The high-water mark to record.

force bool

When false (the default an operator should reach for), the store MUST refuse a newHighWater strictly below the currently recorded value and throw InvalidOperationException without changing anything. When true, the store MUST apply newHighWater unconditionally, including a lowering.

cancellationToken CancellationToken

Token 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

newHighWater is below the recorded high-water mark and force is false.