Configuration

Client configuration (ConvergenceOptions)

Pass ConvergenceOptions to ConvergenceClient.ConnectAsync():

await using var client = await ConvergenceClient.ConnectAsync(new ConvergenceOptions
{
    Host = "127.0.0.1",
    Port = 3727,
    SourceId = 1,
    LivenessDeadlineMs = 30_000,
    ReconnectMaxDelayMs = 10_000,
    HeartbeatIntervalMs = 15_000,
    SubscriberBufferSize = 4_096,
});

Property	Type	Default	Description
Host	string	required	Server hostname or IP address.
Port	int	required	Server port.
SourceId	byte	required	Writer identity (0 to 63). Must be unique per logical service. See Limits.
AuthToken	string?	null	Optional authentication token.
LivenessDeadlineMs	uint	30000	If the server receives no frames from this client within this duration (milliseconds), the connection is considered dead. Entities with only this source’s bit are tombstoned.
ReconnectMaxDelayMs	int	10000	Maximum exponential backoff between reconnection attempts (milliseconds). The first retry is 100ms, doubling on each failure up to this cap.
HeartbeatIntervalMs	int	15000	How often the client sends keep-alive frames (milliseconds). Must be less than LivenessDeadlineMs to avoid spurious disconnections.
SubscriberBufferSize	int	4096	Per-subscription bounded buffer capacity (number of notifications). If the subscriber falls behind and the buffer fills, the subscriber is disconnected.

Tuning guidelines

Liveness deadline vs. heartbeat interval

The heartbeat interval should be well under half the liveness deadline. With the defaults (15s heartbeat, 30s deadline), the client sends a heartbeat every 15 seconds, giving two chances to reach the server before the deadline expires.

If your network has higher latency or jitter, increase both values proportionally.

Subscriber buffer size

The default of 4,096 handles most workloads. Increase it if:

• Your entity kinds have very high update rates (thousands per second).
• Your notification processing loop performs slow operations (database writes, HTTP calls).

Alternatively, offload expensive work to a background queue and keep the notification loop fast.

Reconnect max delay

The default of 10 seconds means the SDK retries at 100ms, 200ms, 400ms, 800ms, 1.6s, 3.2s, 6.4s, 10s, 10s, 10s… until the connection succeeds.

For latency-sensitive applications, decrease this value. For applications where the server may be down for extended periods, the default is usually fine.

Server configuration

Server configuration is provided via a TOML configuration file or command-line arguments. See the server documentation for details.

Key server-side parameters that affect client behaviour:

Parameter	Default	Description
Coalescing window	20ms	Duration over which writes to the same entity are merged. Affects notification latency.
Tombstone retention	5 minutes	How long tombstoned entities remain visible. Subscribers offline longer must re-bootstrap.
Partition count	auto (one per core)	Number of convergence engine partitions. Each partition is single-threaded.
Data directory	required	Base directory for WAL segments, checkpoints, and disk-backed entity state files. Each partition stores its data in partition-N/ subdirectories.

Disk-backed storage

Disk-backed entity kinds store their state files in the stores/ subdirectory of each partition’s data directory (e.g., data/partition-0/stores/kind-1.dat). These files are append-only and grow over time as entities are updated. Compaction is planned but not yet implemented.

The storage mode is set per kind at registration time via the SDK’s [ConvergenceEntity] attribute (see Defining Entity Kinds). It cannot be changed after registration.

The LRU cache starts at the configured CacheCapacity and grows adaptively if the hit rate drops below 80%. Cache statistics (hit rate, size, capacity) are available via the engine’s stats output. The cache grows but does not shrink; restart the server to reset cache sizes.