Wiring Up Surge
AddKurrentSurge is the only door. It opens a registration scope that carries the connection and
every component that runs against it.
using Kurrent.Surge;
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddKurrentSurge(surge => { surge.Connection("kurrentdb://localhost:2113"); surge.AddProcessor<OrderProcessor>(opts => opts.Subscription.Filter = RecordFilter.ByCategory("orders"));});
await builder.Build().RunAsync();The scope registers a KurrentClient for injection, and the processor runs as a hosted service that
the host starts and stops.
Running a Processor shows how to host a processor, read its health check, and handle its failure.
One using covers the lambda. The builder’s methods are declared on IKurrentSurgeBuilder rather
than as extension methods, so a call site needs no using for the options namespaces.
Entry points
Section titled “Entry points”| Call | On | Connection comes from |
|---|---|---|
services.AddKurrentSurge(configure) |
IServiceCollection |
the Connection call inside, or configuration |
builder.AddKurrentSurge(configure) |
IHostApplicationBuilder |
the same |
builder.AddKurrentSurge(connectionName, configure?) |
IHostApplicationBuilder |
ConnectionStrings:{connectionName} |
The named overload is the Aspire shape: the argument is the name of the KurrentDB resource, not a connection string.
builder.AddKurrentSurge("kurrentdb");It throws KurrentClientNotConfiguredException at registration when that key is absent, rather
than starting a host that fails later.
The connection
Section titled “The connection”Four overloads, all on the builder.
surge.Connection("kurrentdb://localhost:2113");
surge.Connection("kurrentdb://localhost:2113", opts => opts.Resilience = KurrentClientResilienceOptions.Subscription);
surge.Connection(KurrentClientOptions.Parse("kurrentdb://localhost:2113"));
surge.Connection(opts => opts.Resilience = KurrentClientResilienceOptions.Subscription);Connection is authoritative. It replaces any KurrentClientOptions or KurrentClient already in
the service collection, and the last call wins.
The two string overloads start from a blank options object, so a configured connection cannot leak into one you stated explicitly. The lambda-only overload is different: with no string it seeds from the configuration chain, so you are tuning the configured connection rather than declaring a new one.
Passing pre-built options validates them immediately, so a bad connection surfaces at registration instead of on first use.
Processors
Section titled “Processors”AddProcessor<T> has four overloads. Two take the processor id first. Each takes the
per-processor settings as Action<ProcessorOptions>, or as Action<ProcessorOptions, IServiceProvider>
when those settings need something resolved.
IKurrentSurgeBuilder AddProcessor<T>(Action<ProcessorOptions>? configure = null);IKurrentSurgeBuilder AddProcessor<T>(string processorId, Action<ProcessorOptions>? configure = null);IKurrentSurgeBuilder AddProcessor<T>(Action<ProcessorOptions, IServiceProvider> configure);IKurrentSurgeBuilder AddProcessor<T>(string processorId, Action<ProcessorOptions, IServiceProvider> configure);AddBatchProcessor<T> has the same four overloads for IRecordBatchProcessor. See
writing a processor for the two handler contracts.
surge.AddProcessor<OrderProcessor>("orders-eu", (opts, sp) => opts.Subscription.Filter = sp.GetRequiredService<IFilterPolicy>().Current);The first argument, orders-eu, is the processor id.
The scope registers T in the container as a singleton, keyed by the processor id. It uses
TryAdd, so a keyed registration of your own for that id wins. The scope registers T and nothing
else. The dependencies of T are yours to register, the way you register any service.
Each processor id gets one hosted service, so the same type runs several times under different ids:
one per tenant, or one per feed. A duplicate id throws InvalidOperationException, and the message
names the id.
The health check comes with the registration. Each processor gets one check, named by its id.
IDrone is registered keyed by the id too.
Resolve a processor elsewhere by its id: GetRequiredKeyedService<OrderProcessor>("orders-eu"), or
[FromKeyedServices("orders-eu")] on a minimal API parameter. While a type runs under one id only,
GetRequiredService<OrderProcessor>() resolves it as well. A second id for the same type removes
that unkeyed registration. A services.AddSingleton<OrderProcessor>() of your own is a separate
instance that the processor runtime never uses.
surge.FailProcessOnFatalError() makes RunAsync throw the exception of a failed processor, so the
process exits with a failure code on .NET 10. See
Failure and exit code.
Configuration
Section titled “Configuration”A processor reads one section, Kurrent:Surge:Processors:{id}, before the configure delegate runs,
so code overrides the file.
{ "Kurrent": { "Surge": { "Processors": { "order-processor": { "Subscription": { "InitialPosition": "Earliest" }, "Checkpoint": { "Interval": 5000 } } } } }}The id is the one you pass at registration. Without one, it is the type name in kebab-case, so
OrderProcessor reads order-processor with no configuration on your part. The processor
orders-eu above reads Kurrent:Surge:Processors:orders-eu. Case, -, and _ do not matter in
the section name.
The scope reads no other section. Configuration cannot set the id: the scope logs a ProcessorId
key as an unrecognised setting. Setting ProcessorId in the delegate does not change the section
that the scope read.
The scope logs configuration problems as warnings, and invalid values fail host startup.
Connection precedence
Section titled “Connection precedence”Most specific first. The first one that resolves is used.
| # | Source |
|---|---|
| 1 | opts.Connection(...) on the processor’s own options |
| 2 | ConnectionString or Connection in Kurrent:Surge:Processors:{ProcessorId} |
| 3 | The scope’s Connection(...) |
| 4 | ConnectionStrings:Kurrent:Surge |
| 5 | ConnectionStrings:KurrentDB |
Sources 2 to 5 resolve before the configure delegate runs, so the delegate receives the connection the processor will use. A connection the delegate sets replaces it.
A processor’s own section outranks the scope so one processor can be pointed at another cluster from configuration alone.
ConnectionStrings keys are matched with separators stripped and case ignored, so
OrderProcessor, order-processor and order_processor all reach the same entry.
What the scope does not register
Section titled “What the scope does not register”Multiple connections. The scope registers at most one. An application that needs a write connection and a read connection builds its own options and clients and hands them where they are needed.
var writes = KurrentClient.Create("kurrentdb+discover://cluster:2113?nodePreference=leader");var reads = KurrentClient.Create("kurrentdb+discover://cluster:2113?nodePreference=follower");
builder.Services.AddSingleton(new OrderWriter(writes));builder.Services.AddSingleton(new OrderReader(reads));Node preference is bound to the client, so two preferences means two clients. They share nothing internally, and the cost is one extra set of channels.
Module clients. StreamsClient, RegistryClient, IndexesClient, ConnectorsClient and
AdminClient have no registration surface. Reach them through the injected client:
client.Streams, client.Registry, client.Indexes, client.Connectors, client.Admin.
Catalogs and codecs. Catalogs come from the assembly attribute or from
opts.Messages.UseCatalog(...), and the codecs are built in. See
catalogs.
Resolving a client when nothing configured a connection throws
KurrentClientNotConfiguredException on first resolve rather than connecting to a default.