Table of Contents

Interface ICloudNativeOutboxStore

Namespace
Excalibur.Data.CloudNative
Assembly
Excalibur.Data.Abstractions.dll

Defines outbox operations optimized for cloud-native databases that use change-feed triggers rather than background polling.

public interface ICloudNativeOutboxStore
Extension Methods

Remarks

Relationship to IOutboxStore: This interface is intentionally separate from Excalibur.Dispatch.IOutboxStore. The two serve fundamentally different outbox patterns:

  • IOutboxStore -- traditional polling-based outbox for SQL Server, Postgres, MongoDB. Uses OutboxBackgroundService and SQL transactions.
  • ICloudNativeOutboxStore -- serverless outbox for Cosmos DB, DynamoDB, Firestore. Uses change-feed triggers, partition keys, and cloud-native batching.

Serverless Pattern:

1. Write event + outbox entry in transactional batch
2. Change feed triggers serverless function (Azure Function / Lambda / Cloud Function)
3. Function publishes to message broker
4. Mark outbox entry as processed

Provider-Specific Triggers:

  • Cosmos DB: Change feed → Azure Function
  • DynamoDB: DynamoDB Streams → Lambda
  • Firestore: Cloud Functions trigger

Tenancy: Rows written through this contract belong to a tenant, so it declares TenantOwnedAttribute. A store registered under this contract in a deployment using row-discriminator multi-tenancy must present a tenant capability or be refused at registration. The applicable one is the partitioned capability, not the ambient-scoping one: this is a change-feed contract whose reads are addressed by partition key and are deliberately estate-wide - GetPendingAsync(IPartitionKey, int, CancellationToken) takes no tenant - so the owning tenant is carried on the row in TenantId and re-established from it when the message is read back. A store confining these reads to an ambient tenant would read that tenant as absent on the trigger path, return the empty set, and stall publication for every tenant.

Properties

ProviderType

Gets the underlying cloud provider type.

CloudPersistenceProviderType ProviderType { get; }

Property Value

CloudPersistenceProviderType

Methods

AddAsync(CloudOutboxMessage, IPartitionKey, CancellationToken)

Adds a message to the outbox within a transactional batch.

Task<CloudOperationResult<CloudOutboxMessage>> AddAsync(CloudOutboxMessage message, IPartitionKey partitionKey, CancellationToken cancellationToken)

Parameters

message CloudOutboxMessage

The outbox message to add.

partitionKey IPartitionKey

The partition key for the message.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<CloudOperationResult<CloudOutboxMessage>>

The operation result with cost information.

GetPendingAsync(IPartitionKey, int, CancellationToken)

Gets pending (unpublished) messages from a partition in FIFO order.

Task<CloudQueryResult<CloudOutboxMessage>> GetPendingAsync(IPartitionKey partitionKey, int batchSize, CancellationToken cancellationToken)

Parameters

partitionKey IPartitionKey

The partition key to query.

batchSize int

Maximum number of messages to retrieve.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<CloudQueryResult<CloudOutboxMessage>>

Pending messages with cost information.

Remarks

This is a query, not a claim. It modifies nothing: no lease is taken, no message is marked, no row is written. Two callers running it concurrently against the same partition therefore receive the same messages and both will publish them. It does not divide work between processes, and no amount of care at the call site makes it do so.

Do not build a multi-process poller on it. Two models support concurrent publishing and this member is part of neither: the provider's change-feed trigger, which holds one lease per partition, and — where a self-managed poller is genuinely wanted — ClaimPendingAsync(IPartitionKey, int, string, CancellationToken), which takes a real per-message lease. Choose one and do not combine them: the trigger path does not observe the claim's lease, so running both reproduces the duplicate delivery the claim exists to prevent.

What this read is for: recovery. A change feed surfaces a document when it is written or updated, and not again on its own. A message whose publish failed, and whose failure was never recorded back onto the document, is consequently never surfaced a second time — the feed has already moved past it, and nothing else will mention it. This read is how such a message is found. The ordinary retry path does not need it: recording the failure through IncrementRetryCountAsync(string, IPartitionKey, string?, CancellationToken) rewrites the document, which puts it back on the feed. This read is the backstop for when that did not happen — a publisher that swallowed the error, or one that stopped between the failed publish and the record of it.

Run it from a single process — a scheduled sweep or an operator tool — and treat overlapping runs as producing duplicates, which handlers must tolerate in any case.

FIFO, and what "eventually" can mean for a provider that orders via a secondary index. A provider whose native query engine can order a strongly-consistent read (Cosmos DB's ORDER BY, Firestore's OrderBy) returns messages in exact creation order with no further caveat. A provider that must order via a separately-maintained, eventually-consistent index (for example DynamoDB, whose base-table query is physically ordered by a per-message key and therefore orders pending reads through a Global Secondary Index instead) can, for a brief interval after AddAsync(CloudOutboxMessage, IPartitionKey, CancellationToken) returns, omit a just-staged message from this read — a LATENCY property, not a loss one: the message is durably present on the provider's strongly-consistent primary store throughout, and a subsequent call (the next poll, or this recovery sweep) will see it. AWS documents GSI propagation as typically completing within a fraction of a second under normal conditions, with no formal upper bound (a failure scenario can extend it) — design a recovery sweep interval, never a single immediate read, around this guarantee. Messages this call DOES return are always in creation order.

MarkAsPublishedAsync(string, IPartitionKey, CancellationToken)

Marks a message as published.

Task<CloudOperationResult> MarkAsPublishedAsync(string messageId, IPartitionKey partitionKey, CancellationToken cancellationToken)

Parameters

messageId string

The message identifier.

partitionKey IPartitionKey

The partition key for the message.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<CloudOperationResult>

The operation result with cost information.

SubscribeToNewMessagesAsync(IChangeFeedOptions?, CancellationToken)

Creates a change feed subscription for outbox processing.

Task<IChangeFeedSubscription<CloudOutboxMessage>> SubscribeToNewMessagesAsync(IChangeFeedOptions? options, CancellationToken cancellationToken)

Parameters

options IChangeFeedOptions

Change feed options.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IChangeFeedSubscription<CloudOutboxMessage>>

A subscription that streams new outbox messages.