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.
How Updates Flow
Section titled “How Updates Flow”Whatever the source, the client:
- Validates the whole candidate against the schema, off the read path.
- Rejects it unless its version is higher than the last accepted one.
- Merges it over the baked defaults: a knob in the live snapshot replaces the baked definition as a whole.
- 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.
A File Source
Section titled “A File Source”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:
{ "schema_version": 1, "version": 7, "knobs": { "search:max_results": { "default": 50 } }}Watch It Converge
Section titled “Watch It Converge”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");Choosing a Poll Interval
Section titled “Choosing a Poll Interval”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.
| Use | Typical interval |
|---|---|
| Kill switches on latency-sensitive services | 200 ms – 1 s |
| General feature flags and settings | 1 – 5 s |
For many processes on one host, prefer one agent per host over one poller per process.
Source Selection Rules
Section titled “Source Selection Rules”source_pathandsource_pollare mutually exclusive; setting both is a startup error.- With neither, the client serves baked defaults only and starts no thread.
poll_intervalmust be positive.- If the source is unreachable at startup, the client serves baked defaults
(version
0) and keeps retrying in the background.