Table of Contents

Interface ICdcProcessor<TEvent>

Namespace
Excalibur.Cdc
Assembly
Excalibur.Cdc.dll

Base contract for CDC processors that support batch (poll-based) processing. All CDC providers implement this interface.

public interface ICdcProcessor<TEvent> : IAsyncDisposable, IDisposable

Type Parameters

TEvent

The provider-specific change event type.

Inherited Members

Examples

// Works with ANY CDC provider (SQL Server, MongoDB, etc.)
public class BatchProcessor
{
    private readonly ICdcProcessor<MyChangeEvent> _processor;

    public async Task ProcessAsync(CancellationToken ct)
    {
        var count = await _processor.ProcessBatchAsync(
            async (evt, token) => await HandleAsync(evt, token),
            ct);
    }
}

Remarks

This interface defines the minimal CDC processing contract: a single batch processing method. All CDC providers — both poll-based (SQL Server, InMemory) and streaming (MongoDB, CosmosDB, Postgres, DynamoDB, Firestore) — implement this interface.

Streaming providers that support continuous processing with position tracking additionally implement ICdcStreamProcessor<TEvent, TPosition>, which extends this interface.

Usage pattern:

  • Depend on ICdcProcessor<TEvent> when your code only needs batch processing and should work with all providers.
  • Depend on ICdcStreamProcessor<TEvent, TPosition> when you need continuous streaming with position management.

Methods

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

Processes a single batch of CDC changes and returns.

Task<int> ProcessBatchAsync(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<int>

The number of events processed in this batch.

Remarks

Use this method for serverless scenarios or when you need explicit control over batch processing cadence.

Delivery semantics are provider-specific and this contract does not strengthen them. Providers differ in whether a batch that ends abnormally — a handler that throws, a cancelled token, a process that stops — redelivers the changes it had already read, and in whether a durable position is advanced on this path at all. Consult the documentation of the provider you register before relying on redelivery, and prefer ICdcStreamProcessor<TEvent, TPosition> where the provider offers it: its position management is explicit, whereas this method's is not part of the shared contract.

Consumer obligation: handlers MUST be idempotent. A provider that does redeliver does so without coordinating with the handler, so a handler that succeeded before a batch failed can be called again with the same change.

A return of zero does not necessarily mean "no changes were available". A provider that holds per-stream state MAY serve overlapping calls single-flight: while one call is processing, a second returns 0 immediately without touching the stream, and the work is picked up by a later invocation. This is specified behaviour rather than a failure — overlapping invocations are ordinary for the documented timer-trigger usage, and refusing them with an exception would surface as an unobserved task exception in most hosts. A provider that does this MUST log each skip so it is distinguishable from a stalled processor. Treat the return value as "changes processed by THIS call", never as "changes outstanding".