Table of Contents

Class DynamoDbEventStore

Namespace
Excalibur.EventSourcing.DynamoDb
Assembly
Excalibur.EventSourcing.DynamoDb.dll

AWS DynamoDB implementation of the cloud-native event store.

[SuppressMessage("Maintainability", "CA1506:Avoid excessive class coupling", Justification = "Event store implementations orchestrate AWS SDK types, serialization, and domain abstractions - high coupling is inherent to the coordinator pattern.")]
public sealed class DynamoDbEventStore : ICloudNativeEventStore, ICloudNativeProviderInfo, ICloudNativeEventStoreChangeFeed, ICloudNativeEventStoreInfo, IEventStore, IServiceProvider, IAsyncDisposable
Inheritance
DynamoDbEventStore
Implements
Inherited Members

Constructors

DynamoDbEventStore(IAmazonDynamoDB, IAmazonDynamoDBStreams, IOptions<DynamoDbEventStoreOptions>, ILogger<DynamoDbEventStore>, ITenantContext)

Initializes a new instance of the DynamoDbEventStore class.

public DynamoDbEventStore(IAmazonDynamoDB client, IAmazonDynamoDBStreams streamsClient, IOptions<DynamoDbEventStoreOptions> options, ILogger<DynamoDbEventStore> logger, ITenantContext tenantContext)

Parameters

client IAmazonDynamoDB

The DynamoDB client.

streamsClient IAmazonDynamoDBStreams

The DynamoDB Streams client.

options IOptions<DynamoDbEventStoreOptions>

The event store options.

logger ILogger<DynamoDbEventStore>

The logger.

tenantContext ITenantContext

The ambient tenant context. Required: this store partitions events by tenant, and it resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

DynamoDbEventStore(IAmazonDynamoDB, IOptions<DynamoDbEventStoreOptions>, ILogger<DynamoDbEventStore>, ITenantContext)

Initializes a new instance of the DynamoDbEventStore class without a Streams client.

public DynamoDbEventStore(IAmazonDynamoDB client, IOptions<DynamoDbEventStoreOptions> options, ILogger<DynamoDbEventStore> logger, ITenantContext tenantContext)

Parameters

client IAmazonDynamoDB

The DynamoDB client.

options IOptions<DynamoDbEventStoreOptions>

The event store options.

logger ILogger<DynamoDbEventStore>

The logger.

tenantContext ITenantContext

The ambient tenant context. Required: this store partitions events by tenant, and it resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

Remarks

The store reads and writes events through the DynamoDB client alone; the Streams client is needed only to serve a change feed. A store built this way is fully functional for appends, loads, and version queries, and reports the change feed as unavailable rather than failing to construct. Use the overload that also takes an Amazon.DynamoDBStreams.IAmazonDynamoDBStreams to consume the change feed.

Properties

CloudProvider

Gets the cloud provider type.

public CloudPersistenceProviderType CloudProvider { get; }

Property Value

CloudPersistenceProviderType

Methods

AppendAsync(string, string, IPartitionKey, IEnumerable<IDomainEvent>, long, CancellationToken)

Appends events to the store with optimistic concurrency control.

public 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.

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

GetCurrentVersionAsync(string, string, IPartitionKey, CancellationToken)

Gets the current aggregate version without loading events.

public Task<long> GetCurrentVersionAsync(string aggregateId, string aggregateType, IPartitionKey partitionKey, 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.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<long>

The current version, or -1 if the aggregate doesn't exist.

Exceptions

ArgumentException

aggregateId or aggregateType is empty or white space.

ArgumentNullException

aggregateId, aggregateType, or partitionKey is null.

GetService(Type)

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

public 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.

public 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.

public 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.

SubscribeToChangesAsync(IChangeFeedOptions?, CancellationToken)

Creates a subscription to the event store change feed.

public Task<IChangeFeedSubscription<CloudStoredEvent>> SubscribeToChangesAsync(IChangeFeedOptions? options, CancellationToken cancellationToken)

Parameters

options IChangeFeedOptions

Change feed options.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IChangeFeedSubscription<CloudStoredEvent>>

A subscription that streams stored events.