Reliability
What if Quonfig goes down?
Uptime matters a great deal to us, but configuration is critical infrastructure, so every SDK has two independent delivery legs and keeps a local copy of its config.
Backend SDK Clients run on local copies of data
First, it's important to understand that Quonfig backend SDKs store all config locally, so they are robust to network blips or outages.
If a connection is lost for any reason, your services keep working as-is because they keep config locally — they simply won't receive new configuration until the connection recovers.
Starting New Clients
Your services don't run indefinitely, though. New pods or servers spin up and they need to pull down configuration as they boot.
A new client boots by fetching configuration from the delivery service. If the primary delivery service is down — or merely slow — the SDK also asks the secondary (details below), so a booting client still gets its configuration within a few seconds during a full primary outage. On the startup fetch the secondary is asked after a 2-second hedge delay, and in server SDKs each leg is abandoned after 6 seconds (3 seconds in the browser SDK), so a hung primary can't consume the whole initialization budget and starve the secondary attempt. The fallback poller's fetches use the same hedged cycle.
If neither leg can be reached at startup, what happens next is your choice. See If Quonfig Is Unreachable at Startup.
Automatic failover to the secondary
Every backend SDK ships with a primary and a secondary delivery leg and fails over between them automatically. You don't configure anything — it is on by default.
- Primary — the delivery service running on Fly.io.
- Secondary — an identical delivery surface running on completely separate infrastructure, so an outage of the primary's platform does not take the secondary with it.
Two mechanisms use these legs:
- Hedging. On a config fetch the SDK asks the primary first. If the primary hasn't answered within a short hedge delay (2s by default), the SDK also asks the secondary in parallel and takes whichever responds first with a valid, not-older envelope. A slow or hung primary therefore doesn't stall your reads.
- Failover. If the primary is unreachable or errors, the SDK falls over to the secondary. An ordering guard ensures the client never regresses to older configuration during a failover, and the client heals forward to the primary once it recovers.
Live updates over SSE stay pinned to the primary's stream (stream.primary.…)
with retry-forever reconnect; the secondary is the fetch/failover leg, not a
second stream herd. If the stream can't be established or has been down for two
minutes, backend SDKs fall back to HTTP polling (every 60 seconds, with the same
hedged primary/secondary fetch) and stop polling once the stream recovers.
Browsers and the Swift SDK keep a last-known-good copy
The browser SDK (@quonfig/javascript, and the React bindings built on it)
additionally persists the last successfully fetched configuration in
localStorage, keyed to your SDK key and evaluation context. If every delivery
URL is unreachable — including the secondary — the SDK serves that cached
configuration instead of failing, and marks it STALE so your code can tell
the difference.
Returning visitors therefore keep evaluating flags even if both delivery legs
are unreachable at once. First-time visitors have no cache; if they can reach
neither leg, the SDK's onInitFailure setting decides what happens (see
Startup failure), and the
client keeps retrying in the background either way. Where localStorage is
unavailable (server-side rendering, some private browsing modes, and React
Native, which has no localStorage), the cache is simply skipped.
The Swift SDK keeps the same kind of copy on disk, per SDK key and context. It loads that copy at startup and also serves it when a fetch fails, so an app that has fetched config once keeps its last values through an outage.
What still degrades during a full primary outage
The secondary keeps reads working, but it is a read-only standby. While the primary platform is down:
- No configuration changes. The dashboard, API, and CLI run on the same infrastructure as the primary, so you can't create or edit flags and configs until it recovers. Served configuration is frozen at its last value — consistent, just not updatable.
- Very recently created or rotated SDK keys may not be recognized. The secondary learns about key changes on a short delay (under a minute in normal operation), so a key minted moments before the outage may not work until the primary returns. All previously issued keys keep working.
- Telemetry ingestion pauses. SDKs keep failed telemetry batches for up to 5 minutes and resend them when the endpoint recovers, dropping the oldest rather than growing or blocking your application; flag evaluation is unaffected. See Telemetry.
- Live updates pause. SSE streams reconnect automatically when the primary returns — and since no writes can happen during the outage, there are no updates to miss.
- A brand-new backend instance that can reach neither leg fails
initialization by default. Its init call throws, rejects or returns an
error after
initTimeout, and your orchestrator's restart is the retry. You can choose to wait or to start on code defaults instead; see If Quonfig Is Unreachable at Startup.
Invalid or revoked SDK key
If Quonfig rejects your SDK key while a client is running (the key was revoked, rotated away, or its workspace was archived), every SDK follows the same rule. It keeps serving the configuration it already has, slows its requests right down, logs one error, and recovers by itself when the key works again. You don't need to restart or rebuild the client.
When it applies. A client treats the key as rejected only when a whole config fetch cycle fails this way:
- no delivery leg (primary or secondary) returned
200or304, and - the primary leg returned
401,403,404or410.
A primary 401 with a secondary 503 or timeout counts. A primary 503 with
a secondary 401 does not: that is handled as an ordinary transient outage,
because a brand-new key can take a moment to reach the secondary. An SSE stream
that is rejected on its own never counts either. The stream keeps its normal
reconnect schedule until a fetch cycle confirms the rejection. In backend SDKs
that cycle is the fallback poller's, so a key revoked mid-life is usually
detected about two minutes after the stream drops. In polling mode (and in the
browser and mobile SDKs) it is the first rejected poll. The initial fetch at
startup never counts; a bad key at boot is handled by your SDK's
onInitFailure setting (see Startup failure).
While the key is rejected:
- The SDK stops the SSE stream and the fallback poller.
- It sends one probe (a normal fetch across every leg) every 150 to 300 seconds, picked at random each time. In polling mode the wait is the larger of that and your poll interval. There is no doubling, and the SDK never gives up.
- Connection-state accessors report disconnected, never "falling back". There is no new state value.
- Evaluation keeps working against the last configuration the client installed. A browser client also keeps serving its last-known-good copy.
Logging. The fetch cycle that detects the rejection logs one ERROR naming the HTTP status and the host. It never includes the key. Each later probe logs at DEBUG, and recovery logs one INFO. A revoked key also stops telemetry for the process, with its own one-time error (see Telemetry), so a production log shows at most two errors for a revoked key, not one per retry.
Recovery. The first probe that gets a valid 200, or a 304, on any leg
installs that configuration, leaves the rejected state and restarts streaming
(or normal polling) from the start. If the key is rejected again later, the
same rule applies again.
SDK support
Every current major version of every SDK behaves this way, and the OpenFeature
providers inherit it from the SDK they wrap. React Native gets the browser
behavior through @quonfig/javascript. Early releases kept retrying a
rejected key at their normal cadence, so upgrade if you are pinned to an old
version.
How we verify this
The failover path is exercised continuously, not just designed:
- Chaos tests in every backend SDK's CI. Each backend SDK runs a shared suite of network-fault scenarios — hung connections, dropped streams, dead legs, out-of-order responses — against a real delivery server, on every change and on a nightly schedule. The suite asserts that failover happens within seconds, and also asserts what must not happen: SSE repointing to the secondary, or a client regressing to older configuration.
- Scheduled game-days. We periodically run live failover exercises against the real deployed secondary — in staging and in production — pointing a real SDK at a deliberately dead or hung primary and verifying cold-start, hedge, no-regression, and heal-forward behavior end to end.
- Production telemetry for every failover event. SDKs report hedge fires, ordering-guard rejections, and which leg actually served each client, so failover in the wild is measured, not inferred. Independent monitors probe the secondary from outside both clouds and alert if it is missing any workspace the primary serves.
We take reliability seriously and invite you to check status.quonfig.com for our track record.
How URLs derive from QUONFIG_DOMAIN
Rather than configure each hostname by hand, backend SDKs derive them all from
a single QUONFIG_DOMAIN (default quonfig.com):
QUONFIG_DOMAIN=quonfig.com
-> https://primary.quonfig.com (config fetch — primary)
-> https://stream.primary.quonfig.com (SSE stream — primary)
-> https://secondary.quonfig.com (config fetch — secondary / failover)
-> https://telemetry.quonfig.com (telemetry ingestion)
Set QUONFIG_DOMAIN (env var) to point an SDK at a different environment — for
example quonfig-staging.com — and both legs plus telemetry move together. This
is the recommended way to switch environments in local development and testing.
Custom API URLs and the failover caveat
Every SDK exposes an explicit URL override (apiUrls / WithAPIURLs /
api_urls, depending on language) for advanced setups such as an on-prem proxy.
This override replaces the derived list wholesale.
If you pass a single URL, you lose automatic failover — the SDK has no secondary to fall over to. To keep failover with custom URLs, pass both a primary and a secondary URL:
apiUrls = [ "https://primary.your-proxy.example", "https://secondary.your-proxy.example" ]
Every backend SDK and the browser SDK log a one-line warning at client init when an explicit URL override collapses the list to a single leg.