Skip to main content
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 timer does.

​
When does the SDK hit the network

evaluateFlags and evaluateAB are always live network calls - they bypass the cache by design. Use them only when you need the most up-to-date result for a specific user/context.

​
The atomic snapshot guarantee

The snapshot is replaced as one immutable record. Two reads either see the same old state or the same new state - never a mix. This means you can iterate getAllConfigs() or getAllFlags() 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:
…the SDK keeps the existing snapshot and resets the next-poll timer. No payload transferred. When the etag changes, the new payload replaces the cache atomically.

​
Background sync errors

Background syncs never throw to the application. If the network call fails:
  1. The error is swallowed silently
  2. The existing cache continues to be served
  3. The next read after the TTL elapses retries automatically
This is intentional - a transient backend hiccup must not surface as a customer-facing error in your handler.

​
File-type secrets

When the sync response contains file-type secrets, the SDK writes them to disk:
Behaviour:
  • The path is stable across syncs as long as the value is unchanged (the hash component is content-derived).
  • When a value changes, a new file is written and the previous one is deleted.
  • All temp files are removed when client.close() is called.
If you cache getSecretFilePath() somewhere, that path may go stale after a sync - re-read it before each use.

​
Cache lifetime

The cache lives as long as the NexusClient instance. Disposing the client (via close()) releases the memory and tears down the polling timer + SSE socket. Typical use is one singleton client per process, kept around for the entire lifetime.

​
Diagnostics