Class FirestoreCdcProcessor
Processes Firestore CDC events using Realtime Listeners.
[SuppressMessage("Maintainability", "CA1506:Avoid excessive class coupling", Justification = "CDC processors inherently couple with many SDK and abstraction types.")]
public sealed class FirestoreCdcProcessor : IFirestoreCdcProcessor, ICdcStreamProcessor<FirestoreDataChangeEvent, FirestoreCdcPosition>, ICdcProcessor<FirestoreDataChangeEvent>, IAsyncDisposable, IDisposable
- Inheritance
-
FirestoreCdcProcessor
- Implements
- Inherited Members
Remarks
This processor uses Firestore's push-based Realtime Listeners to capture document changes. Position is tracked synthetically using document UpdateTime and DocumentId for deterministic ordering.
For continuous processing, use StartAsync(Func<FirestoreDataChangeEvent, CancellationToken, Task>, CancellationToken). For serverless batch processing, use ProcessBatchAsync(Func<FirestoreDataChangeEvent, CancellationToken, Task>, CancellationToken).
Constructors
FirestoreCdcProcessor(FirestoreDb, IOptions<FirestoreCdcOptions>, IFirestoreCdcStateStore, ILogger<FirestoreCdcProcessor>, IOptions<CdcFatalErrorOptions<FirestoreDataChangeEvent>>?, IMessageFailureClassifier?)
Initializes a new instance of the FirestoreCdcProcessor class.
public FirestoreCdcProcessor(FirestoreDb db, IOptions<FirestoreCdcOptions> options, IFirestoreCdcStateStore stateStore, ILogger<FirestoreCdcProcessor> logger, IOptions<CdcFatalErrorOptions<FirestoreDataChangeEvent>>? fatalErrorOptions = null, IMessageFailureClassifier? failureClassifier = null)
Parameters
dbFirestoreDbThe Firestore database.
optionsIOptions<FirestoreCdcOptions>The CDC options.
stateStoreIFirestoreCdcStateStoreThe state store for position persistence.
loggerILogger<FirestoreCdcProcessor>The logger.
fatalErrorOptionsIOptions<CdcFatalErrorOptions<FirestoreDataChangeEvent>>Optional fatal-error handling. When omitted (or its handler is null), a fatal error rethrows and stops the processor (fail-loud — never a silent infinite retry).
failureClassifierIMessageFailureClassifierOptional shared classifier deciding whether a processing error is fatal (non-retryable) or transient. When omitted, a conservative built-in fallback is used.
Methods
ConfirmPositionAsync(FirestoreCdcPosition, CancellationToken)
Confirms that all events up to the specified position have been processed.
public Task ConfirmPositionAsync(FirestoreCdcPosition position, CancellationToken cancellationToken)
Parameters
positionFirestoreCdcPositionThe position to confirm.
cancellationTokenCancellationTokenA 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.
Dispose()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public void Dispose()
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.
GetCurrentPositionAsync(CancellationToken)
Gets the current processing position.
public Task<FirestoreCdcPosition> GetCurrentPositionAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenA token to observe for cancellation requests.
Returns
- Task<FirestoreCdcPosition>
The current position, or a beginning position if none exists.
ProcessBatchAsync(Func<FirestoreDataChangeEvent, CancellationToken, Task>, CancellationToken)
Processes a single batch of CDC changes and returns.
public Task<int> ProcessBatchAsync(Func<FirestoreDataChangeEvent, CancellationToken, Task> eventHandler, CancellationToken cancellationToken)
Parameters
eventHandlerFunc<FirestoreDataChangeEvent, CancellationToken, Task>A delegate that handles each change event.
cancellationTokenCancellationTokenA token to observe for cancellation requests.
Returns
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".
StartAsync(Func<FirestoreDataChangeEvent, CancellationToken, Task>, CancellationToken)
Starts continuous CDC processing until cancellation.
public Task StartAsync(Func<FirestoreDataChangeEvent, CancellationToken, Task> eventHandler, CancellationToken cancellationToken)
Parameters
eventHandlerFunc<FirestoreDataChangeEvent, CancellationToken, Task>A delegate that handles each change event.
cancellationTokenCancellationTokenA 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.