Skip to content

Configuring the Client

KurrentClient is one object with five modules hanging off it and one connection behind all of them. You do not build a client per feature, you do not authenticate five times, and a call into any module travels the channel the others already opened.

Almost all of an application’s traffic goes through streams, where records are written and read. The other four are operational, and most projects touch them rarely. The registry holds schemas and their versions, indexes builds secondary indexes over the log, connectors manages the server-side pipelines that move data out of KurrentDB, and admin runs scavenges and node operations.

await client.Streams.AppendStream("order-001", records, ExpectedStreamState.NoStream);
var schema = await client.Registry.GetSchema("order-placed");

A connection string covers most configuration. KurrentClientOptions covers the rest, and everything a connection string sets is reachable there too.

await using var client = KurrentClient.Create("kurrentdb://localhost:2113");
await using var client = KurrentClient.Create("kurrentdb://localhost:2113", opts => {
opts.Resilience = KurrentClientResilienceOptions.Subscription;
opts.LoggerFactory = loggerFactory;
});
var options = KurrentClientOptions.Parse("kurrentdb://localhost:2113");
await using var client = KurrentClient.Create(options);

The client is IAsyncDisposable, so dispose it with await using.

Build one client per process and keep it. It holds a channel per node and multiplexes every call over them. Constructing one per request pays a TCP handshake, a TLS handshake and, on a cluster, a gossip round trip that it did not need to.

Member Purpose
ConnectionName Label that appears in server-side connection metrics
ConnectionScheme Direct or Discover
Endpoints The nodes to reach
Gossip Discovery and node preference
Security TLS and credentials
Resilience Retries, keepalive, call deadline
Schema Registration, validation, schema naming, and the append-format opt-out
Messages Message catalogs and codecs
Compression Wire compression
Initialization Work that runs before the first operation
LoggerFactory Where the client logs
MetadataDecoder How record metadata is decoded

Parsing a connection string overrides only the parameters that string carries. Everything else keeps the value from the profile it started on.

Seven profiles. Each sets a call deadline and a retry policy; keepalive stays at the default of 10 seconds unless you change it.

Profile Deadline Retries For
Default infinite 3, 250 ms initial, 10 s max, 1.5x General use. The default
NoResilience infinite disabled Relying on server behaviour or an external retry layer
FailFast 5 s disabled An immediate answer, typically UI-facing
RetryForever infinite unlimited, 100 ms initial, 30 s max, 2.0x Critical idempotent work that must eventually land
Subscription infinite 8, 100 ms initial, 15 s max, 2.0x Long-lived subscriptions
HighAvailability 30 s 5, fixed 200 ms interval Predictable recovery inside a fixed window
CautiousWrite 60 s 3, 500 ms initial, 15 s max, 1.5x Writes where idempotency is not guaranteed
opts.Resilience = KurrentClientResilienceOptions.Subscription;
opts.Resilience = KurrentClientResilienceOptions.Default;
opts.Resilience.KeepAliveInterval = TimeSpan.FromSeconds(20);
Profile Effect
Tls TLS on, certificate verified. The default
Insecure TLS off. Local development only
Password(username, password) TLS with basic credentials
MutualTls(certPath, keyPath, rootCaPath?, password?) Client certificate authentication from files
MutualTls(certificate, rootCaCertificate?) Client certificate authentication from loaded certificates
opts.Security = KurrentClientSecurityOptions.Password("admin", "changeit");
opts.Security = KurrentClientSecurityOptions.MutualTls(
clientCertPath: "/certs/client.crt",
clientKeyPath: "/certs/client.key",
rootCaPath: "/certs/ca.crt");

AddKurrentSurge is the single entry point, and it registers a KurrentClient for injection.

builder.Services.AddKurrentSurge(surge => surge
.Connection("kurrentdb://admin:changeit@localhost:2113?tls=false"));

A client resolved when nothing configured a connection throws KurrentClientNotConfiguredException rather than connecting to a default.

Wiring Up Surge covers the three entry points, the connection precedence and configuration binding.

Node preference is bound to the client. An application that writes to the leader and reads from followers builds two clients rather than sharing one.

var writes = KurrentClient.Create("kurrentdb+discover://cluster:2113?nodePreference=leader");
var reads = KurrentClient.Create("kurrentdb+discover://cluster:2113?nodePreference=follower");

They share nothing internally, so there is no cost beyond the second set of channels. The registration scope registers at most one client, so hand the second one over explicitly.