When does the SDK hit the network
The atomic snapshot guarantee
The snapshot is replaced as one immutable record reference, behind anAtomicReference. Two threads reading concurrently 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’sETag. The next sync sends If-None-Match: <etag>. If nothing has changed:
syncedAt timestamp and serves the existing snapshot. No payload transferred.
Background sync errors
Background syncs never throw to the application. If the network call fails:- The error is logged at
ERROR(a switched-off environment is logged once, atWARN) - The existing cache continues to be served
- The next read after the TTL elapses retries, subject to the throttles above
Cache lifetime
The cache lives as long as theNexusClient bean - typically the entire application lifetime. The auto-configuration registers the bean with destroyMethod = "close", so the stream is stopped and file-type secrets are removed on context shutdown.
Diagnostics
If you set the SDK logger to
DEBUG level via SLF4J:
Spring Actuator integration
Exposing a custom health indicator that reports the SDK’s freshness:Concurrency model
- All reads are thread-safe and lock-free - the snapshot is read from an
AtomicReference. - Syncs are serialised - a background sync, a stream-triggered sync and your own
sync()take one lock in turn, aReentrantLock, so a virtual thread waiting for it is not pinned to its carrier. - Background sync runs in a daemon thread - at most one is started at a time.
- The stream runs in its own daemon thread - started by
connectStream().
@Async method, @RestController, or @Scheduled task - on platform or virtual threads - are equally safe.