Interface ICloudNativeEventStore
- Namespace
- Excalibur.Data.CloudNative
- Assembly
- Excalibur.Data.Abstractions.dll
Defines core event store operations optimized for cloud-native document databases.
public interface ICloudNativeEventStore
Remarks
This interface provides partition-aware event storage and retrieval with optimistic concurrency via document versioning/ETags and cost tracking.
Advanced features are available as ISP sub-interfaces via GetService(Type):
- ICloudNativeProviderInfo -- cloud provider type metadata
- ICloudNativeEventStoreChangeFeed -- change feed subscriptions
- ICloudNativeEventStoreInfo -- version queries without event loading
Document Model:
Document ID: {tenantId}:{aggregateId}:{version}
Partition Key: {tenantId} or {aggregateId}
Concurrency: Uses conditional writes on version field to ensure optimistic concurrency without cross-partition transactions.
Tenancy: Events written through this contract belong to a tenant -- the document model above composes the owning tenant into the document id -- so it declares TenantOwnedAttribute. A store registered under this contract in a multi-tenant deployment must present a tenant capability or be refused at registration. The applicable one is the ambient-scoping capability: every read here is addressed by aggregate and partition key with no tenant argument, so confinement can only come from the store applying the ambient tenant. A store that composes its keys without the tenant returns another tenant's events for the same aggregate id, so the refusal is the correct outcome for it rather than a limitation to work around.
Methods
AppendAsync(string, string, IPartitionKey, IEnumerable<IDomainEvent>, long, CancellationToken)
Appends events to the store with optimistic concurrency control.
Task<CloudAppendResult> AppendAsync(string aggregateId, string aggregateType, IPartitionKey partitionKey, IEnumerable<IDomainEvent> events, long expectedVersion, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier. Must not be null, empty, or white space.
aggregateTypestringThe aggregate type name. Must not be null, empty, or white space.
partitionKeyIPartitionKeyThe partition key for the aggregate.
eventsIEnumerable<IDomainEvent>The events to append.
expectedVersionlongThe expected current version (-1 for new aggregate).
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<CloudAppendResult>
The result of the append operation with cost information.
Remarks
An identifier that is null, empty, or white space is a usage error, never a legitimate stream: accepting one would fabricate a stream or partition key and write events where no reader will ever look. Every implementation rejects such an argument by throwing, before any request reaches the service. A returned CloudAppendResult models a domain or infrastructure outcome — a concurrency conflict, a throttled request — never a caller defect.
Exceptions
- ArgumentException
aggregateIdoraggregateTypeis empty or white space.- ArgumentNullException
aggregateId,aggregateType,partitionKey, oreventsis null.
GetService(Type)
Gets an implementation-specific service. Use to access optional capabilities such as ICloudNativeProviderInfo, ICloudNativeEventStoreChangeFeed, or ICloudNativeEventStoreInfo.
object? GetService(Type serviceType)
Parameters
serviceTypeTypeThe type of the requested service.
Returns
Remarks
The default implementation answers for any capability this instance itself implements. A leaf store need not override it. A store whose capability is conditional on its configuration -- a change feed that needs a stream client, for example -- overrides it to answer null while that condition is unmet, and a decorator overrides it to defer unknown capabilities to the store it wraps.
Exceptions
- ArgumentNullException
Thrown when
serviceTypeis null.
LoadAsync(string, string, IPartitionKey, IConsistencyOptions?, CancellationToken)
Loads all events for an aggregate within a partition.
Task<CloudEventLoadResult> LoadAsync(string aggregateId, string aggregateType, IPartitionKey partitionKey, IConsistencyOptions? consistencyOptions, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier. Must not be null, empty, or white space.
aggregateTypestringThe aggregate type name. Must not be null, empty, or white space.
partitionKeyIPartitionKeyThe partition key containing the aggregate.
consistencyOptionsIConsistencyOptionsConsistency options for the read.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<CloudEventLoadResult>
The events for the aggregate in version order, with cost information.
Exceptions
- ArgumentException
aggregateIdoraggregateTypeis empty or white space.- ArgumentNullException
aggregateId,aggregateType, orpartitionKeyis null.
LoadFromVersionAsync(string, string, IPartitionKey, long, IConsistencyOptions?, CancellationToken)
Loads events for an aggregate from a specific version.
Task<CloudEventLoadResult> LoadFromVersionAsync(string aggregateId, string aggregateType, IPartitionKey partitionKey, long fromVersion, IConsistencyOptions? consistencyOptions, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier. Must not be null, empty, or white space.
aggregateTypestringThe aggregate type name. Must not be null, empty, or white space.
partitionKeyIPartitionKeyThe partition key containing the aggregate.
fromVersionlongThe version to start loading from (exclusive).
consistencyOptionsIConsistencyOptionsConsistency options for the read.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<CloudEventLoadResult>
The events from the specified version, with cost information.
Exceptions
- ArgumentException
aggregateIdoraggregateTypeis empty or white space.- ArgumentNullException
aggregateId,aggregateType, orpartitionKeyis null.