Quick-start
This guide builds Detent, starts a durable authority and a managed agent on your own machine, publishes a knob and reads it from the shell. The authority listens only on 127.0.0.1. DON’T PANIC, it takes just a few minutes.
Run the commands in order, in one terminal. The next pages continue in the same shell, with the same helpers and variables.
Building
Section titled “Building”git clone https://github.com/Kronuz/Detent.gitcd Detentcmake -B build -DDETENT_BUILD_TESTS=OFF -DDETENT_BUILD_EXAMPLES=OFF -DDETENT_BUILD_BENCHMARKS=OFFcmake --build build -j 4export PATH="$PWD/build/src:$PATH"This builds the three programs the guide uses, in build/src: detent-authority, the
authority; detent-agent, the managed agent; and detent, the shell reader.
The Installation section covers compiler requirements,
build options and platform notes.
Certificates and Credentials
Section titled “Certificates and Credentials”The agent verifies the authority’s TLS certificate, so the authority needs one.
The repository’s test fixture makes a throwaway CA and localhost leaf
certificates with OpenSSL, valid for one day. Work in build/quickstart:
mkdir -p build/quickstart && cd build/quickstartOPENSSL_CONF=../../tests/detent_authority/tls_ambient.cnf \ cmake -DOUTPUT="$PWD/certs" -DOPENSSL=openssl \ -P ../../tests/detent_authority/tls_certificates.cmakeThen pick an authority identity and two tokens: one for the publisher, one for the agent. Identities are 32 hexadecimal characters; tokens are at least 32 characters:
CLUSTER=$(openssl rand -hex 16)IDENTITY="\"cluster\":\"$CLUSTER\",\"group\":\"$(openssl rand -hex 16)\",\"epoch\":\"$(openssl rand -hex 16)\""WRITER_TOKEN=$(openssl rand -hex 24)READER_TOKEN=$(openssl rand -hex 24)Starting the Authority
Section titled “Starting the Authority”cat > authority.json <<EOF{ $IDENTITY, "directory": "authority-data", "publisher_tls": { "certificate": "certs/one.pem", "key": "certs/one.key", "ca": "certs/ca.pem" }, "credentials": [ { "token": "$WRITER_TOKEN", "producer": "writer", "namespaces": ["search", "checkout", "payments"] }, { "token": "$READER_TOKEN", "producer": "agent", "principal": "agent-reader", "publish": false, "namespaces": ["search", "checkout", "payments"] } ]}EOFchmod 600 authority.jsondetent-authority --authority authority.json --runtime-dir run --daemonizeWith no voters, the authority is a single voter. It listens on 127.0.0.1
port 8317 and keeps its durable store in authority-data. The writer
credential may publish to the three namespaces; the agent credential may only
read them, as principal agent-reader.
Publishing
Section titled “Publishing”Every request carries the writer’s token and the authority identity. Define a helper and open a publishing session:
api() { curl --fail-with-body -sS -w '\n' --cacert certs/ca.pem \ -H "Authorization: Bearer $WRITER_TOKEN" -H 'Content-Type: application/json' \ --data "{$IDENTITY,$2}" "https://localhost:8317/v2/$1"}api open '"expected_generation":0,"nonce":"00000000000000000000000000000001"'--daemonize returns once the authority has a leader, so the open succeeds on
its first attempt. The reply looks like this, with the identity elided:
{"authority":{...},"status":"applied","revision":0,"namespace_revision":0,"generation":1,"sequence":0}The reply’s "generation":1 is this producer’s session. Each transaction in it
carries the next sequence number. A second helper publishes one knob
definition per transaction, in the namespace before the colon:
sequence=0publish() { sequence=$((sequence + 1)) api transactions "\"generation\":1,\"sequence\":$sequence,\"namespace\":\"${1%%:*}\",\"operations\":[{\"key\":\"$1\",\"value\":$2}]"}Starting the Agent
Section titled “Starting the Agent”cat > managed.json <<EOF{ "cluster": "$CLUSTER", "namespaces": ["search", "checkout", "payments"], "token": "$READER_TOKEN", "ca": "certs/ca.pem"}EOFchmod 600 managed.jsondetent-agent --managed managed.json --generation-dir agent-state --runtime-dir run \ --initialize-managed --daemonizeexport DETENT_GENERATION_DIR="$PWD/agent-state"The agent connects to localhost:8317 over TLS, checks the certificate against
certs/ca.pem, and publishes immutable generations in agent-state.
--initialize-managed creates that store on the first start; later starts
leave it out. detent get reads the newest generation from
DETENT_GENERATION_DIR and never opens managed.json.
Reading
Section titled “Reading”Publish an integer knob and read it:
publish search:max_results '{"default":25}'sleep 1detent get search:max_results# 25Each transaction replies with its outcome and the authority’s new revision:
{"authority":{...},"status":"applied","revision":1,"namespace_revision":1,"generation":1,"sequence":1}Now change the value without restarting anything:
publish search:max_results '{"default":100}'sleep 1detent get search:max_results# 100sleep 1 gives the agent time to deliver the update. Your applications see it
the same way: the next read after the update lands returns the new value, with
no restart and no redeploy.
The next pages walk through each idea in turn, in the same shell and directory:
- Basic Concepts: knobs, snapshots, versions and defaults.
- Settings and Flags: numeric settings and on/off switches.
- Gradual Rollouts: percentage ramps with stable buckets.
- Group Overrides: forcing or ramping specific groups.
- Next Steps: stopping the daemons, and where to go from here.