Evaluation Semantics
These are the exact rules every Detent reader follows: the C++ client, the
Python and Rust bindings, scoped read views, and detent get.
Result<std::int64_t, KnobError> get(name, hash_val = nullopt, switch_val = nullopt);Result<T, KnobError> get_as<T>(name, hash_val = nullopt, switch_val = nullopt);- CLI override. If the process has a CLI override for
name, return it. - Lookup. Find
namein the current snapshot. Absent isMissingKnob. - Group override. If
switch_valis present and exactly matches a key inoverrides:- A forced integer returns that value.
- A
{"rollout_pct": N}returnsrollout_valuewhenhash_valis present andbucket < N, anddefaultotherwise.
- Knob-wide rollout. If
rollout_pctis set andhash_valis present, returnrollout_valuewhenbucket < rollout_pct, anddefaultotherwise. - Default. Return
default.
An unmatched switch_val simply falls through to step 4. A caller outside a
percentage, or without a hash, gets default: a rollout ramps callers from
default to rollout_value and never serves a third value.
get_as<T> calls get, then converts with a range check: a value that doesn’t
fit T is ConversionFailed, never truncated or wrapped. get_as<bool> takes
0 as false and 1 as true; any other value is ConversionFailed.
The Stable Bucket
Section titled “The Stable Bucket”input = UTF8(knob_name) || 0x00 || UTF8(hash_val)digest = SHA256(input)u64 = big_endian_uint64(digest[0..8])bucket = u64 % 100- Domain separation. The zero byte keeps
("ab", "c")and("a", "bc")from colliding. - Stickiness. The same
(knob_name, hash_val)gives the same bucket on every host, in every process and language, across restarts and versions. - Independence. Including the knob name gives the same entity unrelated buckets for different knobs.
- Monotonic ramps.
bucket < pctmeans raisingpctonly adds buckets. - Boundaries.
0servesrollout_valueto nobody;100serves it to every caller that supplies a hash value. - No implicit hash. Without
hash_val, the rollout is skipped. An empty string is a hash value like any other only if you pass one explicitly.
The bucket depends only on the knob name and hash value, never on the group, so a group rollout and the knob-wide rollout compare the same bucket against different thresholds.
Golden Vectors
Section titled “Golden Vectors”The test suite pins the hash with golden vectors in
tests/detent/test_hash_golden.cc; any reimplementation in another language
should reproduce them. A quick cross-check in Python:
import hashlib
def bucket(name: str, hash_val: str) -> int: digest = hashlib.sha256(name.encode() + b"\0" + hash_val.encode()).digest() return int.from_bytes(digest[:8], "big") % 100
bucket("payments:new_processor", "user-1") # 10: outside 10%, inside 50%bucket("payments:new_processor", "user-42") # 2: inside 10%Snapshot Consistency
Section titled “Snapshot Consistency”- A single read observes exactly one snapshot.
- Two consecutive reads may observe two different snapshots if an update lands
between them. Use
read_view()to pin one snapshot for several reads. - Readers never observe a partially applied update.
- A failed lookup is never cached: a knob that’s missing now is found as soon as a snapshot that contains it is published.