Rust SDK - Caching behaviour

The SDK keeps a single in-memory snapshot of all configs, secrets and flags. Every read returns from that snapshot, and reads never block on the network.

Network hits

Event	Network call?
`NexusClient::create().await`	Yes - one `GET /v1/sync`, awaited
Read within the TTL	No
Read after the TTL elapsed	No - the stale snapshot is returned and one background refresh starts
Concurrent reads after the TTL elapsed	One request in total, shared by all of them
SSE event received	Yes - one `GET /v1/sync` on the stream task
`client.sync().await`	Yes
Read while quarantined or in billing back-off	No - the back-off applies to the read path too

One snapshot, shared by every clone

let a = client.clone();
let b = client.clone();
// a, b and client all read the same snapshot and share one refresh.
assert_eq!(a.synced_at(), b.synced_at());

Reads take a short lock, clone the value and release it. A sync replaces the whole snapshot in one assignment, so a reader sees either the old or the new state, never a mixture. The lock is never held across an .await, and a panic elsewhere in the process cannot poison it into a permanently unusable client.

Coalesced refreshes

Syncs are serialised. A burst of triggers - fifty concurrent reads on a stale snapshot, an SSE event storm, a TTL tick landing on top of both - produces one request at a time, so:

the SDK never opens a request per read,
an older response can never overwrite a newer snapshot.

ETag / 304 Not Modified

The ETag from each 200 response is stored and sent back as If-None-Match. On 304:

the snapshot is not replaced,
synced_at is updated, so the TTL clock resets,
the billing and quarantine states are cleared.

Bounded bodies

Every response the SDK parses has a size cap - 8 MiB for sync and AB evaluation, 1 MiB for the token exchange, 64 KiB for metadata. Exceeding it raises ResponseTooLarge; a truncated document is never handed to the parser.

Failure behaviour

On any non-2xx / non-304 response the SDK never clears the cache - reads keep serving the last known-good snapshot. In addition:

Status	Behaviour
402	`billing_overdue()` becomes true and the background refresh backs off for five minutes. The next successful sync clears both. An explicit `sync().await` ignores the back-off
429 with a quarantine body	Sync pauses until `expires_at`, clamped to 24 hours. The stream waits it out without counting it as a transport error
429 without one	`RateLimited`; the stream counts it towards its error budget
401 with WIF enabled	One forced session refresh, then the request is retried once

With SSE active

Every event triggers a sync, so the cache is usually fresher than the TTL requires. The TTL timer keeps running as a fallback at exactly the interval you configured.

Cleanup

{
    let client = NexusClient::create(config).await?;
    client.run_stream();
    // ...
} // the last clone is dropped here: background tasks stop and materialised
  // file-type secrets are removed

close() does the same at a point you choose, and is idempotent. Dropping an individual clone does nothing - the shared state stays alive for the others. std::process::exit skips destructors, so call close() if you exit that way and want the file secrets gone immediately. The SDK deliberately installs no signal handlers: a library that did would silently change how your application responds to Ctrl-C.

Diagnostics

let ts = client.synced_at();        // last successful sync
let overdue = client.billing_overdue();
let kt = client.key_type();         // "sk" | "pk" | ""

Install a tracing subscriber to see each sync, its outcome and the counts it applied:

tracing_subscriber::fmt().with_max_level(tracing::Level::DEBUG).init();

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Rust SDK - Caching behaviour

Network hits

One snapshot, shared by every clone

Coalesced refreshes

ETag / 304 Not Modified

Bounded bodies

Failure behaviour

With SSE active

Cleanup

Diagnostics

​Network hits

​One snapshot, shared by every clone

​Coalesced refreshes

​ETag / 304 Not Modified

​Bounded bodies

​Failure behaviour

​With SSE active

​Cleanup

​Diagnostics

Network hits

One snapshot, shared by every clone

Coalesced refreshes

ETag / 304 Not Modified

Bounded bodies

Failure behaviour

With SSE active

Cleanup

Diagnostics