Snapshots and configuration freshness
Understand ETags, polling, invalidation, stale snapshots, and consistency.
Snapshot evaluation trades immediate hosted freshness for low-latency in-process decisions and resilience. One snapshot contains active typed flags and ordered rules for one project environment.
Use snapshots only in trusted server processes. They include server-only values and targeting configuration and must never be exposed to browsers.
GET /v1/snapshot requires a server runtime key with runtime:snapshot. The key fixes the project
and environment; no URL parameter can redirect the request to another boundary.
Validate the complete response before replacing application state. A partial or malformed snapshot must not displace a last-known-good configuration.
The Node.js SDK performs this validation during initialize(). Initialization rejects when the key,
request, or snapshot is invalid unless the application operates from bootstrap data only.
The snapshot response includes an ETag. Send it in If-None-Match on the next poll. An unchanged
snapshot returns 304 without another response body.
The Node.js SDK polls every 30 seconds by default. It replaces in-memory state only after a successful, validated response.
Call refresh() when an immediate check is justified, such as after an operator-controlled change in
a deployment or incident workflow. Do not refresh before every evaluation.
Snapshot clients are eventually consistent with hosted configuration. Different processes can briefly hold different versions because they poll at different times or experience different network failures.
Do not assume a console save is visible to every process immediately. For urgent changes, verify refresh health in application telemetry and understand the maximum tolerated staleness.
Direct HTTP evaluation uses current hosted configuration and avoids polling delay, but introduces a network dependency for every request.
GET /v1/snapshot/stream is a Server-Sent Events invalidation channel. It tells a consumer that a new
snapshot may exist. It does not carry authoritative flag configuration.
Streams can disconnect, duplicate notifications, or arrive after a poll. A consumer must fetch the snapshot and continue ETag polling as its source of truth.
The released Node.js SDK uses polling and does not consume the stream. Do not document or depend on stream behaviour through that package.
After one successful load, a background refresh failure leaves the last snapshot available. This prevents a temporary control-plane outage from becoming an application outage.
The tradeoff is stale configuration. Report background failures through onError, monitor their
duration, and alert when staleness exceeds the application's operational tolerance.
Before the first successful load, only bootstrap flags or caller defaults are available. Decide explicitly whether startup should fail, continue in a degraded state, or wait and retry.
Bootstrap flags can make a client ready immediately and support offline tests. When a runtime key is also present, a later successful refresh replaces the bootstrap state.
Treat production bootstrap data as code-owned configuration. Review its age, safe defaults, and deployment lifecycle. Do not let an old embedded snapshot become an unnoticed permanent source.
refresh() once.304: the hosted snapshot has not changed for that key-bound environment.Related pages: Node.js SDK, Errors and fallbacks, and the generated snapshot reference.