Interface IColdEventStore
- Namespace
- Excalibur.EventSourcing
- Assembly
- Excalibur.EventSourcing.Abstractions.dll
Defines the contract for cold (archive) event storage operations.
public interface IColdEventStore
Remarks
Cold storage is optimized for cost and capacity, not read speed. Events are stored in compressed, immutable batches (e.g., in blob storage).
Used by the TieredEventStoreDecorator for transparent read-through when
events are missing from the hot tier, and by EventArchiveService for
writing archived events.
Every operation identifies a stream by its case-sensitive tenant, aggregate type and aggregate ID. Reads validate the entire stored batch before version filtering and return ascending versions. Mismatched identities, duplicate events, missing payloads and malformed stored data must fail rather than appear absent or authorize hot deletion. Legacy archives may derive missing tenant provenance from their exact tenant-qualified key. A legacy key occupied by another aggregate type must fail; it must never be treated as the requested stream.
Methods
HasArchivedEventsAsync(KeyedTenantPartition, string, string, CancellationToken)
Checks whether any archived events exist for an aggregate.
Task<bool> HasArchivedEventsAsync(KeyedTenantPartition tenant, string aggregateId, string aggregateType, CancellationToken cancellationToken)
Parameters
tenantKeyedTenantPartitionThe tenant partition that owns the events.
aggregateIdstringThe aggregate identifier.
aggregateTypestringThe case-sensitive aggregate type belonging to this stream.
cancellationTokenCancellationTokenCancellation token.
Returns
ReadAsync(KeyedTenantPartition, string, string, long, CancellationToken)
Reads archived events for an aggregate from a specific version.
Task<IReadOnlyList<StoredEvent>> ReadAsync(KeyedTenantPartition tenant, string aggregateId, string aggregateType, long fromVersion, CancellationToken cancellationToken)
Parameters
tenantKeyedTenantPartitionThe tenant partition that owns the events.
aggregateIdstringThe aggregate identifier.
aggregateTypestringThe case-sensitive aggregate type belonging to this stream.
fromVersionlongThe version to start reading from (exclusive).
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<IReadOnlyList<StoredEvent>>
The archived events from the specified version in order.
ReadAsync(KeyedTenantPartition, string, string, CancellationToken)
Reads all archived events for an aggregate from cold storage.
Task<IReadOnlyList<StoredEvent>> ReadAsync(KeyedTenantPartition tenant, string aggregateId, string aggregateType, CancellationToken cancellationToken)
Parameters
tenantKeyedTenantPartitionThe tenant partition that owns the events.
aggregateIdstringThe aggregate identifier.
aggregateTypestringThe case-sensitive aggregate type belonging to this stream.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<IReadOnlyList<StoredEvent>>
The archived events in version order.
WriteAsync(KeyedTenantPartition, string, string, IReadOnlyList<StoredEvent>, CancellationToken)
Writes events to cold storage for a specific aggregate and returns the durable low-water mark:
the highest version V such that every version <= V for this
aggregate is durably committed in cold storage (post-upload/flush/quorum), and therefore safe for
the caller to delete from the hot tier.
Task<long> WriteAsync(KeyedTenantPartition tenant, string aggregateId, string aggregateType, IReadOnlyList<StoredEvent> events, CancellationToken cancellationToken)
Parameters
tenantKeyedTenantPartitionThe tenant partition that owns the events. Cold storage keys are composed with this term, so events archived under one tenant are unreachable from another tenant's read or watermark check.
aggregateIdstringThe aggregate identifier.
aggregateTypestringThe case-sensitive aggregate type belonging to this stream.
eventsIReadOnlyList<StoredEvent>The events to archive.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<long>
The durable low-water-mark version safe to delete from the hot tier, or
-1when no contiguous prefix from version zero is proven by this call.
Remarks
The returned value is a contiguous durable prefix, never the merely-submitted
maximum. An implementation that persists only part of the batch (or defers a buffered write) MUST
return the highest contiguously-durable version, not the highest submitted one — returning the
submitted max while the write is not yet durable authorizes the caller to destroy the only other
copy of not-yet-archived events. Even an acknowledged atomic upload may return -1 when
the durable set does not contain version zero. The prefix must contain every version from zero.
Defined early-return acks: an empty events input returns -1 ("nothing
proven by this call; delete nothing"); a batch already fully present returns the confirmed
existing contiguous prefix. The caller deletes hot events only up to the returned
watermark, so a partial or deferred cold write bounds hot deletion rather than losing data.