Skip to content

Processors

A processor replaces hand-written subscription code. You do not manage a subscription, a checkpoint, a reconnect loop or a partition assignment. You write the handler.

DiagramKurrentDBProcessorStreamsCheckpointsSubscriptionBatchHandlerTrack nextrecordscommitted position

Everything in that loop except Handler is the runtime’s job. This is a complete program:

using Kurrent.Surge;
using Kurrent.Surge.Client.Streams;
using Kurrent.Surge.Processors;
using Microsoft.Extensions.Hosting;
var builder = Host.CreateApplicationBuilder(args);
builder.AddKurrentSurge(surge => surge.AddProcessor<TemperatureMonitorProcessor>(options => {
options.Connection("kurrentdb://localhost:2113");
options.Subscription.Filter =
RecordFilter.ByExpression("schema_name = 'SensorReading'");
}));
await builder.Build().RunAsync();

And this is the processor it runs:

public sealed class TemperatureMonitorProcessor : IRecordProcessor {
public ValueTask ProcessRecord(ProcessRecordContext context) {
if (context.Record.Value is SensorReading reading)
Evaluate(reading, context.Logger);
return ValueTask.CompletedTask;
}
public ValueTask OnCheckpoint(CheckpointContext context) {
context.Logger.LogInformation("Checkpoint {Id}", context.CheckpointId);
return ValueTask.CompletedTask;
}
}

Running a Processor covers the connection, the options, the processor identity, and the health check.

The client can subscribe. Doing it by hand means you also own the position you resume from, the commit of that position, the behaviour on a handler exception, the back-off, the distribution of work across instances, and the shutdown that does not lose the last batch.

A processor owns all of it. That is the trade: you give up control of the loop and get the loop written correctly.

IProcessor supplies three lifecycle hooks, each with a default, so you override only what you need:

Hook When
OnInitialize once, before the subscription opens
OnConnected when the subscription is live
OnCheckpoint when a position is committed

On top of IProcessor, implement one of two shapes:

Interface Method Use it for
IRecordProcessor ProcessRecord(ProcessRecordContext) one record at a time
IRecordBatchProcessor ProcessBatch(BatchContext) a batch at a time

Configured through ProcessorOptions:

Concern Option
What to read Subscription, which holds the filter and the start position
Position tracking Checkpoint
Batch shape Batching
Reconnecting a dropped subscription Resilience
Checkpoint partition count internal, and pinned to 1 in this release
Observability Observers, MeterFactory, TrackSourceLag