Table of Contents

Interface ICdcStateStore

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.Abstractions.dll

Defines the contract for storing and retrieving CDC checkpoint positions.

public interface ICdcStateStore
Extension Methods

Examples

// Using state store with CDC processor
public class CdcConsumer
{
    private readonly IChangeDataCapture<Order> _cdc;
    private readonly ICdcStateStore _stateStore;
    private const string ConsumerId = "order-sync-service";

    public async Task ProcessAsync(CancellationToken ct)
    {
        // Load last checkpoint
        var checkpoint = await _stateStore.GetPositionAsync(ConsumerId, ct);

        await foreach (var change in _cdc.GetChangesAsync(checkpoint, ct))
        {
            await ProcessChangeAsync(change);

            // Save checkpoint after processing
            await _stateStore.SavePositionAsync(ConsumerId, change.Position, ct);
        }
    }
}

Remarks

The state store provides durable storage for CDC positions, enabling:

  • Crash recovery - Resume processing from the last acknowledged position
  • Consumer tracking - Multiple consumers can maintain independent positions
  • Progress monitoring - Track how far behind each consumer is

Implementation Guidelines:

  • Implementations should be durable (survive restarts)
  • Consider using the same database as the CDC source for transactional consistency
  • Provide atomic updates to prevent lost checkpoints

Methods

DeletePositionAsync(string, CancellationToken)

Deletes the checkpoint for the specified consumer.

Task<bool> DeletePositionAsync(string consumerId, CancellationToken cancellationToken)

Parameters

consumerId string

A unique identifier for the CDC consumer.

cancellationToken CancellationToken

A token to observe for cancellation requests.

Returns

Task<bool>

true if a checkpoint was deleted; false if no checkpoint existed for the consumer.

Remarks

Use this to reset a consumer to start processing from the beginning, or to clean up checkpoints for decommissioned consumers.

GetAllPositionsAsync(CancellationToken)

Gets all consumer positions tracked by this state store.

IAsyncEnumerable<(string ConsumerId, ChangePosition Position)> GetAllPositionsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A token to observe for cancellation requests.

Returns

IAsyncEnumerable<(string ConsumerId, ChangePosition Position)>

An async enumerable of consumer ID and position pairs.

Remarks

Use this for monitoring and operational visibility into consumer progress.

GetPositionAsync(string, CancellationToken)

Gets the last saved position for the specified consumer.

Task<ChangePosition?> GetPositionAsync(string consumerId, CancellationToken cancellationToken)

Parameters

consumerId string

A unique identifier for the CDC consumer. This allows multiple consumers to independently track their positions in the same CDC stream.

cancellationToken CancellationToken

A token to observe for cancellation requests.

Returns

Task<ChangePosition>

The last saved position for the consumer, or null if no checkpoint exists (indicating the consumer should start from the beginning).

SavePositionAsync(string, ChangePosition, CancellationToken)

Saves a position checkpoint for the specified consumer.

Task<CdcPositionSaveOutcome> SavePositionAsync(string consumerId, ChangePosition position, CancellationToken cancellationToken)

Parameters

consumerId string

A unique identifier for the CDC consumer.

position ChangePosition

The position to save. This represents the last successfully processed change.

cancellationToken CancellationToken

A token to observe for cancellation requests.

Returns

Task<CdcPositionSaveOutcome>

What the store did: Advanced when the checkpoint now holds position, or one of the refusals when it does not. Callers MUST test for Advanced BY NAME — deciding success by excluding the known refusals makes every member added later a success, which is how this contract would fail open.

Remarks

Atomicity: Implementations MUST apply the checkpoint atomically. If the save does not apply, the previous checkpoint remains intact and the return value says so.

Monotonicity is permitted, and it is observable. An implementation MAY refuse to move its checkpoint backwards, reporting RefusedAsStale; an implementation with no such guard performs an unconditional write and reports Advanced. Both are conforming. What is NOT conforming is declining the write and leaving the caller unable to tell: the outcome is the whole point of the return value.

Transactional Processing: For exactly-once semantics, consider saving the checkpoint in the same transaction as the business operation that processes the change.

Exceptions

ArgumentException

consumerId is empty or whitespace.

ArgumentNullException

position is null.

ObjectDisposedException

The store has been disposed.

OperationCanceledException

cancellationToken was signalled.