Skip to content

Client

#include "detent/client.hh"

detent::Client owns one process’s view of its knobs: the baked defaults, the CLI overrides, the current published snapshot, and (optionally) the background updater thread that keeps it fresh. It’s neither copyable nor movable; construct one and share it by reference.


explicit Client(InitOptions options);
explicit Client(Snapshot in_memory_snapshot);

The first form loads defaults_path, parses cli_overrides, publishes the defaults as version 0, and starts the updater thread if a source is configured. It throws std::runtime_error for missing or invalid defaults and invalid CLI overrides, and std::invalid_argument for invalid options such as a non-positive poll_interval.

The second form builds a test client from an in-memory snapshot, with no files, overrides or background thread.

The destructor stops and joins the updater thread.

FieldTypeDefaultMeaning
defaults_pathstd::filesystem::pathemptyBaked defaults file; empty starts with no knobs
cli_overridesstd::vector<std::string>empty"name=value" pairs; see Testing
source_pathstd::optional<path>nonePoll this snapshot file
source_pollstd::optional<SourcePoll>noneA generic polling function
read_sourcestd::optional<ReadSourceFactory>noneA scoped read source, e.g. managed generations
source_idstd::string"file"Label for the source in diagnostics
poll_intervalstd::chrono::milliseconds200msBase poll cadence; must be positive
refresh_alert_afterstd::chrono::milliseconds5 minutesStaleness threshold for alerting
max_knobsstd::size_t100'000Largest accepted snapshot
on_updatestd::optional<OnUpdate>noneCalled on the updater thread after each accepted update

source_path, source_poll and read_source are mutually exclusive. on_update can’t be combined with read_source. It must be fast and must not throw; it isn’t called for the initial defaults snapshot.


Result<std::int64_t, KnobError> get(std::string_view name,
std::optional<std::string_view> hash_val = std::nullopt,
std::optional<std::string_view> switch_val = std::nullopt) const;
template <typename T>
Result<T, KnobError> get_as(std::string_view name,
std::optional<std::string_view> hash_val = std::nullopt,
std::optional<std::string_view> switch_val = std::nullopt) const;
std::int64_t get_or_panic(std::string_view name,
std::optional<std::string_view> hash_val = std::nullopt,
std::optional<std::string_view> switch_val = std::nullopt) const;
  1. get evaluates the knob with the precedence rules and returns its int64.
  2. get_as<T> converts with std::in_range<T>, returning ConversionFailed instead of truncating. It works for any integer T, signed or unsigned. get_as<bool> takes only 0 and 1.
  3. get_or_panic aborts on any KnobError.

All of them are safe to call concurrently from any number of threads.


ClientReadView read_view() const noexcept;

A ClientReadView pins one immutable snapshot (or one managed generation) and evaluates against it:

auto view = client.read_view();
auto a = view.get_as<bool>("checkout:new_path", user_id, group);
auto b = view.get("search:max_results");
auto c = view.get_as<std::uint16_t>("search:page_size");

A view is cheap to copy, remains valid across later updates and after the Client is destroyed, and applies the client’s CLI overrides. Reads through a view don’t increment the client’s metrics.


std::shared_ptr<const Snapshot> current_snapshot() const;

Returns the whole current merged snapshot. It’s meant for tools that republish snapshots, like the agent, not for ordinary reads. A client built with a read_source throws std::logic_error here; use read_view().


HealthSnapshot health() const noexcept;
const Metrics& metrics() const noexcept;
HealthSnapshot fieldMeaning
initializedThe client finished construction
source_connectedThe last source interaction succeeded
accepted_versionVersion of the current live snapshot (0 for defaults only)
staleness_secondsMonotonic time since the last successful update
knobsKnob count in the current snapshot
cli_overridesNumber of CLI overrides

Metrics holds process-wide atomic counters: reads_ok, reads_missing, reads_conversion_failed, snapshot_swaps, refresh_failures, stale_updates, and the source_connected flag. See Observability.


struct GroupRollout { std::uint8_t rollout_pct = 0; };
using GroupOverride = std::variant<std::int64_t, GroupRollout>; // forced value or percentage
struct KnobDef {
std::int64_t default_value = 0;
flat_map<std::string, GroupOverride, std::less<>> overrides;
std::optional<std::uint8_t> rollout_pct;
std::optional<std::int64_t> rollout_value; // present exactly when a percentage is
};
struct Snapshot {
std::uint64_t version = 0;
std::optional<std::string> published_at;
std::string source_id;
flat_map<KnobName, KnobDef, std::less<>> knobs;
};

Snapshot instances are immutable once published; every update builds a new one.