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.
Build a client
Section titled “Build a client”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.
What the options carry
Section titled “What the options carry”| 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.
Resilience profiles
Section titled “Resilience profiles”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);Security profiles
Section titled “Security profiles”| 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");Dependency injection
Section titled “Dependency injection”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.
Two clients for two node preferences
Section titled “Two clients for two node preferences”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.