Table of Contents

Interface ICdcStreamProcessor<TEvent, TPosition>

Namespace
Excalibur.Cdc
Assembly
Excalibur.Cdc.dll

Extended contract for CDC processors that support continuous streaming with position tracking.

public interface ICdcStreamProcessor<TEvent, TPosition> : ICdcProcessor<TEvent>, IAsyncDisposable, IDisposable

Type Parameters

TEvent

The provider-specific change event type.

TPosition

The provider-specific position type used for checkpointing.

Inherited Members

Examples

// Only works with streaming CDC providers
public class StreamProcessor
{
    private readonly ICdcStreamProcessor<MongoDbDataChangeEvent, MongoDbCdcPosition> _processor;

    public async Task RunAsync(CancellationToken ct)
    {
        await _processor.StartAsync(
            async (evt, token) => await HandleAsync(evt, token),
            ct);
    }
}

Remarks

Streaming providers (MongoDB, CosmosDB, Postgres, DynamoDB, Firestore) implement this interface. Poll-only providers (SQL Server, InMemory) implement only ICdcProcessor<TEvent>.

This interface follows the Interface Segregation Principle: consumers that only need batch processing depend on the base ICdcProcessor<TEvent> and work with all providers. Consumers that need streaming with position management depend on this extended interface, which provides compile-time safety — attempting to inject a poll-only provider produces a compile error rather than a runtime NotSupportedException.

Position tracking: Each provider has a structurally unique position type (LSN pair, resume token, WAL offset, shard iterators, continuation token). The TPosition generic parameter captures this without requiring a common marker interface that would add no value.

Methods

ConfirmPositionAsync(TPosition, CancellationToken)

Confirms that all events up to the specified position have been processed.

Task ConfirmPositionAsync(TPosition position, CancellationToken cancellationToken)

Parameters

position TPosition

The position to confirm.

cancellationToken CancellationToken

A token to observe for cancellation requests.

Returns

Task

A task representing the asynchronous operation.

Remarks

This persists the position to the state store. On restart, processing will resume from this confirmed position. When using StartAsync(Func<TEvent, CancellationToken, Task>, CancellationToken), position confirmation is typically automatic. Use this method for manual control in batch scenarios.

GetCurrentPositionAsync(CancellationToken)

Gets the current processing position.

Task<TPosition> GetCurrentPositionAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A token to observe for cancellation requests.

Returns

Task<TPosition>

The current position, or a beginning position if none exists.

StartAsync(Func<TEvent, CancellationToken, Task>, CancellationToken)

Starts continuous CDC processing until cancellation.

Task StartAsync(Func<TEvent, CancellationToken, Task> eventHandler, CancellationToken cancellationToken)

Parameters

eventHandler Func<TEvent, CancellationToken, Task>

A delegate that handles each change event.

cancellationToken CancellationToken

A token to observe for cancellation requests.

Returns

Task

A task that completes when processing stops due to cancellation.

Remarks

This method runs continuously until cancelled. It automatically handles connection management, reconnection, and position tracking. Position is confirmed after each successfully processed event. Use ProcessBatchAsync(Func<TEvent, CancellationToken, Task>, CancellationToken) for manual batch control.