Interface ISnapshotStore
- Namespace
- Excalibur.EventSourcing
- Assembly
- Excalibur.EventSourcing.Abstractions.dll
Provides storage operations for aggregate snapshots.
public interface ISnapshotStore
Remarks
Snapshots are used to optimize aggregate hydration by storing periodic state checkpoints. This interface is intentionally separate from event storage for clean separation of concerns.
Interface uses ValueTask for synchronous completion optimization. In-memory implementations complete synchronously without allocation overhead.
Tenant confinement. Every operation is confined to the ambient tenant established for this
store instance: GetLatestSnapshotAsync(string, string, CancellationToken) returns the caller's own tenant's latest
snapshot and never another tenant's snapshot for the same aggregate, and every save or delete can
neither affect nor be affected by another tenant's snapshots under the same identifier. Which
mechanism a given provider uses to hold that boundary is declared by its capability marker —
ITenantScopingCapability<TContract> for a store that reads an ambient tenant — and the
package's own ARCHITECTURE.md states the falsifiable guarantee and how it is verified. A store
presenting no marker is not confined by the framework.
Methods
DeleteSnapshotsAsync(string, string, CancellationToken)
Deletes all snapshots for an aggregate.
ValueTask DeleteSnapshotsAsync(string aggregateId, string aggregateType, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier.
aggregateTypestringThe aggregate type name.
cancellationTokenCancellationTokenCancellation token.
Returns
- ValueTask
A task that represents the asynchronous delete operation.
DeleteSnapshotsOlderThanAsync(string, string, long, CancellationToken)
Deletes snapshots older than a specified version.
ValueTask DeleteSnapshotsOlderThanAsync(string aggregateId, string aggregateType, long olderThanVersion, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier.
aggregateTypestringThe aggregate type name.
olderThanVersionlongDelete snapshots with version less than this value.
cancellationTokenCancellationTokenCancellation token.
Returns
- ValueTask
A task that represents the asynchronous delete operation.
GetLatestSnapshotAsync(string, string, CancellationToken)
Gets the latest snapshot for an aggregate.
ValueTask<ISnapshot?> GetLatestSnapshotAsync(string aggregateId, string aggregateType, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier.
aggregateTypestringThe aggregate type name.
cancellationTokenCancellationTokenCancellation token.
Returns
Remarks
Confined to the ambient tenant established for this store instance: a snapshot stored under
another tenant for this aggregateId is reported as not found, the same as one
that was never taken.
SaveSnapshotAsync(ISnapshot, CancellationToken)
Saves a snapshot for an aggregate, keeping the highest version stored for it.
ValueTask SaveSnapshotAsync(ISnapshot snapshot, CancellationToken cancellationToken)
Parameters
snapshotISnapshotThe snapshot to save.
cancellationTokenCancellationTokenCancellation token.
Returns
- ValueTask
A task that represents the asynchronous save operation.
Remarks
Total. Every well-formed snapshot is an acceptable argument. There is no version, payload size, or identifier shape a caller must avoid, and no state of the store in which a save is illegal.
Monotone upsert, scoped to the interval since the last deletion. After
SaveSnapshotAsync returns normally, the version readable for
(aggregateId, aggregateType) within the ambient tenant is at least the version passed. A
save carrying a version lower than or equal to the stored one is a successful no-op. Monotonicity
does NOT hold across a deletion: DeleteSnapshotsAsync,
DeleteSnapshotsOlderThanAsync and provider-level expiry all remove stored versions, after
which a save may legitimately make a LOWER version readable than was readable before. Saves and
deletions on the same key are not ordered with respect to one another, so a save superseded by a
concurrent deletion has not dropped a snapshot. A caller that requires a specific version to be
readable must re-read it; a normal return does not entitle the caller to infer which version is
readable now, only that the store established one at least as high at the moment it completed. A
store that returns normally having neither stored the snapshot nor established that is in
violation; unresolvable contention is reported as ConcurrencyException, never as success.
Modifies only its own key. No other aggregate, aggregate type, or tenant is observably affected.
Faults. Throws only for an invalid argument, for cancellation, or for an infrastructure failure that prevented the store from establishing the outcome above. Implementations MUST NOT report a lost race as a fault, and MUST NOT return normally having neither stored the snapshot nor established that a version at least as high is stored — a silent drop reports success for a snapshot nobody holds.
Exceptions
- ConcurrencyException
May be thrown by an implementation that retries a contended write when it exhausts its attempts without either storing the snapshot or establishing that a version at least as high is already stored. This is the infrastructure-failure case above, reported in the abstraction's own currency: the outcome is UNKNOWN, which is why it is a fault rather than the successful no-op that a proven supersede produces. Implementations that write without retrying cannot reach this state and do not throw it.