Skip to main content

How Backend SDKs Work

Backend SDKs (Node, Go, Ruby, Python, Java, .NET, and other server runtimes) authenticate with a backend SDK key (qf_sk_…), generated on the Environments & Keys page in the dashboard. For how it differs from the other credentials — and why it must stay server-side — see Keys & Credentials.

SDK Architecture​

The Quonfig server-side SDKs are all built with the following 3 goals in mind:

  1. Very fast lookups that do not require any remote calls.
  2. Being highly resilient in the case of outages (once a process has loaded its configuration; for what happens if it can't load it at startup, see Startup failure)
  3. Near instant updates when changes are made

The architecture to do this looks like this:

Your code will instantiate a singleton of a Quonfig Client. This client fetches the latest configuration, falling back to the secondary delivery service if the primary is slow or down (Reliability). Once it gets a connection it will unlock and be available for your code.

The client will also start a streaming connection to the APIs to pull down new changes.

The delivery service is split across two hosts: short-lived HTTP fetches go to primary.quonfig.com and the long-lived SSE stream goes to stream.primary.quonfig.com. You don't configure any of these URLs: the SDK derives the primary and secondary fetch URLs, and the stream. host, on its own. If you do override apiUrls, list both the primary and the secondary URL; a single URL turns off failover to the secondary, and the SDK logs a warning when that happens.

If the stream can't be established, or has been down for about two minutes, the SDK falls back to polling over HTTP every 60 seconds, and stops polling once the stream recovers (Reliability).

Note that the evaluation is always happening in-process in your application. Feature flags and config are stored in process so are lightning fast (no API calls when you access them).

See Frontend SDKs to compare

Implementation​

When your client boots, it creates a local thread safe hashmap which will hold the config. When you change a flag or config, the delivery service pushes the update to every connected SDK over the SSE stream, and the fallback poller picks it up if the stream is down. Changes typically reach connected SDKs within a few seconds.

Feature flags are built on top of the Quonfig config store so all reliability notes are applicable for Feature Flags as well.