When does the SDK hit the network
The TTL applies the same way whether or not the stream is connected; while it is, a refresh usually answers
304 Not Modified.
The atomic snapshot guarantee
The snapshot is replaced as one immutable struct value, behind async.RWMutex. Two goroutines reading concurrently either see the same old state or the same new state - never a mix.
GetAllConfigs() or GetAllFlags() without worrying about an entry being added or removed mid-loop. The returned map is also a defensive copy.
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.
When the etag changes, the new payload replaces the cache atomically.
Background sync errors
Background syncs never return errors to the caller. If the network call fails:- The error is logged at
Errorlevel - The existing cache continues to be served
- A later read retries after a backoff - 1 s, doubling to 60 s - so a failing backend is not asked again on every read
Cache lifetime
The cache lives as long as the*Client. Cancelling the context passed to NewClient does NOT release the cache; it only affects the initial sync. A *Client typically lives for the entire process - share by passing a pointer, don’t construct per-request.
Diagnostics
With a
Logger configured, the SDK emits one debug record per sync:
client.SyncErrors() lists the resources the server left out of the last sync that carried data - a secret with no value, a config whose secret reference did not resolve - and each is logged once as a Warn record when it first appears.
Concurrency model
- All reads are safe to call from any goroutine - internally guarded by
sync.RWMutex. - Background sync goroutine - at most one at a time; spawned on TTL expiry.
- SSE goroutine - exactly one, started by
NewClientand stopped byClose.
0700 directory private to the client, under os.TempDir(), on every sync when the value changes. All temp files are removed when client.Close() is called.