Interface ISubscriptionCheckpointStore
- Namespace
- Excalibur.EventSourcing.Subscriptions
- Assembly
- Excalibur.EventSourcing.dll
Persists subscription checkpoint positions for durable subscriptions.
public interface ISubscriptionCheckpointStore
Remarks
Checkpoint stores enable event subscriptions to resume from their last known position after a restart. Each subscription is identified by a unique name.
Follows the pattern from Azure.Messaging.ServiceBus.ServiceBusProcessor
which uses checkpoint-based position tracking for message processing.
Methods
AdvanceCheckpointAsync(string, string, Guid, long?, long, CancellationToken)
Advances the checkpoint for one projection within a subscription, but only while it still holds the position the caller last observed.
Task<CheckpointAdvanceOutcome> AdvanceCheckpointAsync(string subscriptionName, string projectionKey, Guid bindingId, long? expectedPosition, long newPosition, CancellationToken cancellationToken)
Parameters
subscriptionNamestringThe nonblank stable subscription name, at most 255 characters.
projectionKeystringThe nonblank projection key, at most 512 characters, as carried by ProjectionKey. Addressed as a pair with the subscription name for the reason stated on GetCheckpointAsync(string, string, CancellationToken).
bindingIdGuidThe binding returned by the roster read before processing. Stale lifetimes cannot advance.
expectedPositionlong?The position the caller believes is stored now, or null when the caller believes no checkpoint exists yet. "No checkpoint" and "a checkpoint of 0" are different states and must stay distinguishable, which is why this is nullable rather than a sentinel value.
newPositionlongA nonnegative position at least as large as
expectedPositionwhen supplied. Equal positions are accepted only if the atomic comparison still matches.cancellationTokenCancellationTokenCancellation token.
Returns
- Task<CheckpointAdvanceOutcome>
Advanced when the comparison matched and the position was accepted (including an equal position), or Superseded when the expected checkpoint state did not match, in which case NOTHING was written.
Remarks
This is a conditional update of an existing member, never an insert. The binding identifier must match as well as the nullable position. Release and rebind invalidate every previous writer. This is a compare-and-set rather than a blind write, and the difference is not defensive tidiness. A blind write lets a reader that paused and resumed -- or a second reader of the same subscription -- move the checkpoint BACKWARDS to a value it read minutes ago, after which every event between the two positions is delivered a second time.
Implementations MUST perform the comparison and the write as ONE atomic operation against the durable store: a conditional UPDATE, never a read followed by a write. A read-then-write implementation reintroduces precisely the interleaving this signature exists to exclude, and it does so invisibly -- the signature would still look correct.
A comparison mismatch is reported as Superseded. Invalid negative or descending arguments throw before storage access, even when the expectation would not match. These checks and the atomic comparison together prevent rewind within the same checkpoint lifetime. Deletion, restoration, external writes, and legacy writers are outside that guarantee.
Acceptance is not exclusive ownership or fencing of projection effects. Multiple equal-position calls may succeed. A caller receiving Superseded must reconcile its processing state before continuing; the result alone does not prove that another reader remains active.
Exceptions
- ArgumentException
Either key part is null, empty or whitespace.
- ArgumentOutOfRangeException
Either position is negative, or the new position is smaller than the supplied expected position.
BindSubscriptionAsync(string, IReadOnlyList<SubscriptionMember>, CancellationToken)
Atomically binds each supplied projection to the subscription, and returns the subscription's COMPLETE roster as the durable store holds it.
Task<SubscriptionRoster> BindSubscriptionAsync(string subscriptionName, IReadOnlyList<SubscriptionMember> members, CancellationToken cancellationToken)
Parameters
subscriptionNamestringThe nonblank stable subscription name, at most 255 characters.
membersIReadOnlyList<SubscriptionMember>The projections this caller hosts, each with its own fingerprint and destination. Distinct by ProjectionKey under Ordinal.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<SubscriptionRoster>
Every member bound to this subscription, INCLUDING any the caller did not supply.
Remarks
ONE ROW PER PROJECTION, NOT ONE FINGERPRINT PER SET, and the difference is the whole point. A fingerprint covering the registration set refuses every cooperating host whenever a projection is added, removed or renamed, or any destination moves — and the only remedy re-folds every projection from zero, including the ones that did not change. Binding per member makes an additive change additive: a new projection binds alone and folds alone, and a changed destination refuses only the projection whose destination moved.
THE RETURNED ROSTER IS LOAD-BEARING AND MUST NOT BE DISCARDED. A member present in the store and absent from the calling process is work this process cannot perform, and therefore cannot attest. A caller that computes its required set from its own registration list instead will fold what it can see, report freshness, and say nothing about a sibling bound by another deployment that has not folded the same events — an attestation that is false and that nothing downstream can detect, because the caller was told it need not re-check. The roster is a property of the SUBSCRIPTION, not of the process.
Per member, the first writer establishes the binding atomically: an insert-if-absent keyed on (subscription, projection key), performed as ONE action the engine enforces. It is a CLAIM and never an upsert — the loser of a race must not overwrite the winner, and no operation on this contract may update a bound member's fingerprint. Concurrent writers supplying an identical fingerprint join; a different one is refused for that member, naming it, while members that match stay bound. Binding never creates a checkpoint: an absent checkpoint must remain distinguishable from zero. Call this before reading or applying subscription work. A binding is not a lease, an ownership claim, or a fence on external handler effects.
The store compares fingerprints only; it does not discover or verify their contents. Destination is persisted so a refusal can name what moved, and is never compared. The built-in processor incorporates a configured destination identity when the resolved store advertises the optional IProjectionDestinationIdentity capability; where that capability is absent the consumer must identify the destination in the subscription scope instead. Configured names are not physical resource identities or lifecycle fences: alias repointing, or resource replacement under the same name, is not detected. External edits, deletion or restoration of definition or checkpoint storage are outside this contract's lifetime guarantee.
Exceptions
- ArgumentException
The name, a projection key or a fingerprint does not satisfy the stated format, or two members share a projection key.
- InvalidOperationException
A supplied projection is already bound to a different processing definition. The message names that projection and both destinations. Restore that definition, or release the member and rebuild it deliberately — releasing one member re-folds that projection alone.
EnumerateCheckpointsAsync(CancellationToken)
Enumerates every stored subscription checkpoint.
Task<IReadOnlyList<SubscriptionCheckpoint>> EnumerateCheckpointsAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<IReadOnlyList<SubscriptionCheckpoint>>
All persisted checkpoints, one per (subscription, projection key) pair. Returns an empty list when no checkpoints have been stored.
Remarks
Enables projection-lag reporting: pairing each subscription's checkpoint with the global stream head position yields the per-stream lag.
GetCheckpointAsync(string, string, CancellationToken)
Gets the last checkpointed position for one projection within a subscription.
Task<long?> GetCheckpointAsync(string subscriptionName, string projectionKey, CancellationToken cancellationToken)
Parameters
subscriptionNamestringThe nonblank stable subscription name, at most 255 characters.
projectionKeystringThe nonblank projection key, at most 512 characters, as carried by ProjectionKey.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<long?>
The last stored position, or null if no checkpoint exists (indicating the projection should start from the beginning).
Remarks
A CURSOR IS ADDRESSED BY THE PAIR, NOT BY ONE COMPOSED STRING, and the difference is a storable row rather than a style preference. The two parts are bounded independently -- 255 and 512 -- so any single column wide enough for one is too narrow for both concatenated, and a deeply namespaced projection type reaches that. A pair that binds successfully as a member row has to be addressable as a cursor too: otherwise the member is bound and its cursor can never be written, which is a permanent stall rather than a refusal, and under a provider that truncates instead of refusing it is two projections silently sharing one cursor and each skipping what the other consumed.
Both parts are compared ORDINALLY, so two keys differing only in case are two cursors.
Exceptions
- ArgumentException
Either part is null, empty or whitespace.
ReadSubscriptionAsync(string, CancellationToken)
Reads one consistent snapshot of a subscription, including member identities and cursors.
Task<SubscriptionRoster> ReadSubscriptionAsync(string subscriptionName, CancellationToken cancellationToken)
Parameters
subscriptionNamestringThe subscription name.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<SubscriptionRoster>
The current roster, empty when nothing is bound.
ReleaseSubscriptionMemberAsync(string, string, Guid, CancellationToken)
Removes one projection from a subscription's roster together with its checkpoint, so that the projection re-binds and re-folds from the beginning on its next start.
Task<bool> ReleaseSubscriptionMemberAsync(string subscriptionName, string projectionKey, Guid bindingId, CancellationToken cancellationToken)
Parameters
subscriptionNamestringThe nonblank stable subscription name.
projectionKeystringThe member's projection key.
bindingIdGuidThe lifetime being retired. A replacement binding is never removed.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<bool>
true when a member row was removed; false when the subscription had no such lifetime, a reader still referenced it, or a database concurrency conflict rolled back the mutation. A false result confirms that this operation wrote nothing.
Remarks
THE MEMBER ROW AND ITS CHECKPOINT MUST BE REMOVED IN ONE DURABLE TRANSACTION, and the atomicity is load-bearing rather than tidy. Removing the member alone leaves a cursor that nothing validates and that no operation on this contract can clear, so lag reporting shows it forever. Removing the checkpoint alone leaves a bound member that re-folds from zero on a destination still holding the previous generation's rows. The checkpoint is addressed by the SAME pair as the member row, so the two deletes share one key and neither can be aimed at a row the other did not write.
This is what makes a deliberate per-projection rebuild expressible, and what makes a semantic revision bump remediable: without it a changed fingerprint can only refuse startup forever, because no operation can unbind. A re-fold from zero into a live destination is safe because an asynchronous projection is required to perform positioned writes, so the destination refuses a position it has already folded.
Exceptions
- ArgumentException
The name or projection key is null, empty or whitespace.