Table of Contents

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):

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

aggregateId string

The aggregate identifier. Must not be null, empty, or white space.

aggregateType string

The aggregate type name. Must not be null, empty, or white space.

partitionKey IPartitionKey

The partition key for the aggregate.

events IEnumerable<IDomainEvent>

The events to append.

expectedVersion long

The expected current version (-1 for new aggregate).

cancellationToken CancellationToken

Cancellation 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

aggregateId or aggregateType is empty or white space.

ArgumentNullException

aggregateId, aggregateType, partitionKey, or events is null.

GetService(Type)

Gets an implementation-specific service. Use to access optional capabilities such as ICloudNativeProviderInfo, ICloudNativeEventStoreChangeFeed, or ICloudNativeEventStoreInfo.

object? GetService(Type serviceType)

Parameters

serviceType Type

The type of the requested service.

Returns

object

The service instance, or null if not supported.

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 serviceType is 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

aggregateId string

The aggregate identifier. Must not be null, empty, or white space.

aggregateType string

The aggregate type name. Must not be null, empty, or white space.

partitionKey IPartitionKey

The partition key containing the aggregate.

consistencyOptions IConsistencyOptions

Consistency options for the read.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<CloudEventLoadResult>

The events for the aggregate in version order, with cost information.

Exceptions

ArgumentException

aggregateId or aggregateType is empty or white space.

ArgumentNullException

aggregateId, aggregateType, or partitionKey is 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

aggregateId string

The aggregate identifier. Must not be null, empty, or white space.

aggregateType string

The aggregate type name. Must not be null, empty, or white space.

partitionKey IPartitionKey

The partition key containing the aggregate.

fromVersion long

The version to start loading from (exclusive).

consistencyOptions IConsistencyOptions

Consistency options for the read.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<CloudEventLoadResult>

The events from the specified version, with cost information.

Exceptions

ArgumentException

aggregateId or aggregateType is empty or white space.

ArgumentNullException

aggregateId, aggregateType, or partitionKey is null.