Durable Authority
The durable authority is what detent-authority runs. Publishers open
authenticated sessions and submit atomic, per-namespace transactions with
compare-and-set preconditions; the authority assigns revisions and commits them
through durable Raft consensus to local storage. The preconditions keep
concurrent publishers from overwriting each other, and only a configured
credential can publish.
Build It
Section titled “Build It”The authority builds by default; DETENT_BUILD_AUTHORITY controls it:
cmake -B build -DDETENT_BUILD_AUTHORITY=ONcmake --build build -jIt requires OpenSSL 3.0 or newer.
Configure a Single Voter
Section titled “Configure a Single Voter”A single-voter authority has local-disk durability without replicated
availability. Create a configuration file owned by the service account or root,
with mode 0600 (or a controlled group-readable 0640):
{ "cluster": "63000000000000000000000000000000", "group": "67000000000000000000000000000000", "epoch": "65000000000000000000000000000000", "directory": "authority-data", "credentials": [{ "token": "replace-with-a-random-token-at-least-32-characters", "producer": "publisher", "namespaces": ["payments"] }]}cluster,groupandepochare independent, nonzero 128-bit identities written as 32 lowercase hex digits. Generate fresh random ones; the values above are for illustration only.directoryis resolved relative to the configuration file. Its parent must already exist.- Each credential binds a bearer
token(at least 32 characters) to aproducername and thenamespacesit may write. Producer identity always comes from the credential, never from a request body.
chmod 600 authority.jsondetent-authority --authority authority.jsonIt listens on 127.0.0.1:8317 by default; --port changes the port.
--daemonize runs it in the background and --status queries it; see
detent-authority.
Publish a Transaction
Section titled “Publish a Transaction”Every request carries Authorization: Bearer TOKEN and the exact authority
identity. First, open a producer session:
POST /v2/openAuthorization: Bearer replace-with-a-random-token-at-least-32-characters
{ "cluster": "63000000000000000000000000000000", "group": "67000000000000000000000000000000", "epoch": "65000000000000000000000000000000", "expected_generation": 0, "nonce": "0123456789abcdef0123456789abcdef"}The response carries your session generation. Then submit transactions with
consecutive sequence numbers:
POST /v2/transactionsAuthorization: Bearer replace-with-a-random-token-at-least-32-characters
{ "cluster": "63000000000000000000000000000000", "group": "67000000000000000000000000000000", "epoch": "65000000000000000000000000000000", "generation": 1, "sequence": 1, "namespace": "payments", "operations": [ { "key": "payments:new_processor", "value": { "default": 0, "rollout_pct": 10, "rollout_value": 1 } }, { "key": "payments:max_retries", "value": { "default": 3 } } ]}A transaction is atomic within its namespace: every operation applies, or none
does. An operation’s value uses the ordinary knob definition
schema, or null to delete.
Compare-and-Set
Section titled “Compare-and-Set”To make sure you’re not overwriting someone else’s change, add a precondition:
"expected_revision": Non an operation succeeds only if that key’s current modification revision isN."expected_revision": 0with"absent_namespace_revision": Rsucceeds only if the key is absent and the namespace is still at revisionR."expected_namespace": Ron the transaction checks the whole namespace’s revision.
Without a precondition, an operation replaces unconditionally.
Outcomes and Retries
Section titled “Outcomes and Retries”| Outcome | Meaning | Next sequence? |
|---|---|---|
applied | Committed, with a new revision | Yes |
no_change | Identical upsert or absent delete; nothing to commit | Yes |
conflict, capacity, exhausted | Deterministic failure | Yes |
503 outcome_unknown | The outcome isn’t known yet | No: retry the same generation, sequence and body |
A retried transaction with the same sequence and the same contents returns its
original outcome; with different contents, it’s a conflict. Never advance the
sequence just because a connection dropped. Use POST /v2/result to look up
the outcome of a sequence, and POST /v2/read for strong reads of up to 128
keys.
The Authority API documents every endpoint and field.
Go Multi-Node
Section titled “Go Multi-Node”A replicated authority uses a fixed list of three or five voters, mutual TLS between peers, and TLS for publishers:
{ "cluster": "…", "group": "…", "epoch": "…", "directory": "authority-data", "node": 1, "voters": [ { "id": 1, "host": "10.0.0.1", "port": 9317, "certificate_sha256": "<64 hex digits>" }, { "id": 2, "host": "10.0.0.2", "port": 9317, "certificate_sha256": "<64 hex digits>" }, { "id": 3, "host": "10.0.0.3", "port": 9317, "certificate_sha256": "<64 hex digits>" } ], "peer_tls": { "certificate": "peer.pem", "key": "peer.key", "ca": "ca.pem" }, "publisher_tls": { "certificate": "pub.pem", "key": "pub.key", "ca": "ca.pem" }, "publisher_bind": "10.0.0.1", "publisher_name": "authority-1.internal", "credentials": [ … ]}Every voter shares the cluster, group, epoch and voter list; each sets its own
node. See Operations: Durable Authority for
certificates, pins, timing and the full field list.