.NET SDK - Caching Behaviour

The SDK keeps every config / secret / flag in an in-memory snapshot that is replaced atomically as a whole on each sync. Reads never block on the network; only the periodic background refresh does.

When does the SDK hit the network

Event	Result
`NexusClient.CreateAsync(...)`	Blocking full sync. The constructor only resolves once the cache is populated.
Read within the TTL window	No network - served from the in-memory cache
Read after TTL has elapsed	Stale cache returned immediately; one background refresh fires in parallel
Server returns `304 Not Modified`	TTL reset, no payload downloaded
Multiple concurrent expirations	Only one background sync runs at a time (`Interlocked` guard)
SSE event received	Immediate full sync, regardless of TTL
SSE stream connected	Effective TTL bumped to 60 s as a safety net (the stream handles fresh updates)

The atomic snapshot guarantee

The snapshot is replaced as one immutable record. Two reads from different threads either see the same old state or the same new state - never a mix.

var a = client.GetConfig("a");   // sees snapshot N
// ... some other thread triggers a sync ...
var b = client.GetConfig("b");   // sees snapshot N+1 (or still N - but always consistent)

This means you can iterate GetAllConfigs() without worrying about an entry being added or removed mid-loop.

ETag / 304

Every successful sync stores the server’s ETag. The next sync sends If-None-Match: <etag>. If nothing has changed:

HTTP/1.1 304 Not Modified

…the SDK resets its SyncedAt timestamp and serves the existing snapshot. No payload transferred.

Background sync errors

Background syncs never throw. If the network call fails:

The error is logged via INexusLogger.Error(...)
The existing cache continues to be served
The next read after the TTL elapses retries automatically

Cache lifetime

The cache lives as long as the NexusClient instance. Disposing the client (or letting it be garbage-collected) releases the memory. Typical use is one singleton client per application, registered with DI; do not create per-request.

Diagnostics

Property	What it tells you
`client.SyncedAt`	When was the last successful sync - useful for “Last refreshed” UI
`client.IsStreamConnected`	Is the SSE stream currently up
`client.KeyType`	`"sk"` or `"pk"` - confirms the SDK saw the right key prefix

Logging INexusLogger.Debug will emit one line per sync:

nexus: sync OK - configs=12 secrets=4 flags=7 key_type=sk
nexus: sync 304 Not Modified - cache retained

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

.NET SDK - Caching Behaviour

When does the SDK hit the network

The atomic snapshot guarantee

ETag / 304

Background sync errors

Cache lifetime

Diagnostics

​When does the SDK hit the network

​The atomic snapshot guarantee

​ETag / 304

​Background sync errors

​Cache lifetime

​Diagnostics

When does the SDK hit the network

The atomic snapshot guarantee

ETag / 304

Background sync errors

Cache lifetime

Diagnostics