Skip to content

Live Updates

A client with only baked defaults changes configuration on restart. Give it a source and it changes configuration while running. A client consumes exactly one source: a local file, or a poll function you supply.


A source feeds candidate updates to the client's background thread, which validates them, merges them over baked defaults and atomically publishes a new snapshot that readers loadA source feeds candidate updates to the client's background thread, which validates them, merges them over baked defaults and atomically publishes a new snapshot that readers load

Whatever the source, the client:

  1. Validates the whole candidate against the schema, off the read path.
  2. Rejects it unless its version is higher than the last accepted one.
  3. Merges it over the baked defaults: a knob in the live snapshot replaces the baked definition as a whole.
  4. Publishes the merged result with one atomic swap.

A rejected or failed update changes nothing; readers keep the last known good snapshot. A transport failure is retried with full-jitter backoff.


The simplest live source is a JSON snapshot file that some other process replaces:

detent::InitOptions opts;
opts.defaults_path = "defaults.json";
opts.source_path = "/var/lib/myapp/live_knobs.json";
opts.poll_interval = std::chrono::milliseconds{200};
detent::Client client(std::move(opts));

The client polls the file every poll_interval and rereads it when its modification time or size changes. A live snapshot looks like a defaults file plus a version:

live_knobs.json
{
"schema_version": 1,
"version": 7,
"knobs": {
"search:max_results": { "default": 50 }
}
}

health() reports the accepted version and how long ago the last update succeeded:

auto h = client.health();
std::printf("version %llu, %.1fs since last update, source %s\n",
static_cast<unsigned long long>(h.accepted_version),
h.staleness_seconds,
h.source_connected ? "connected" : "disconnected");

The poll interval is the upper bound on how stale a client can be while its source is healthy. Shorter intervals propagate faster and cost more polls. An unchanged file poll is one metadata check.

UseTypical interval
Kill switches on latency-sensitive services200 ms – 1 s
General feature flags and settings1 – 5 s

For many processes on one host, prefer one agent per host over one poller per process.


  1. source_path and source_poll are mutually exclusive; setting both is a startup error.
  2. With neither, the client serves baked defaults only and starts no thread.
  3. poll_interval must be positive.
  4. If the source is unreachable at startup, the client serves baked defaults (version 0) and keeps retrying in the background.