summaryrefslogtreecommitdiffstats
path: root/docs/api.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-18 12:48:29 +0000
committertv <tv@krebsco.de>2026-11-18 13:59:42 +0100
commitd130c0612b4c63f2d30da65ebcc231018c1f2606 (patch)
tree8700f2d53351cbbecbe772ea7701bf6240d5210c /docs/api.md
parent0bfe07af92a775b0e896e0fc5a989a1d9b65f7b3 (diff)
docs: references to another document's section linked to it
Where a document names a section of another after linking to it ("([`store.md`](store.md), Pinned checkpoints)"), the name links to that section too, by the id both GitHub and cgit's about filter give its heading; paragraphs that grew past the width are wrapped anew, links and code kept on one line each.
Diffstat (limited to 'docs/api.md')
-rw-r--r--docs/api.md73
1 files changed, 40 insertions, 33 deletions
diff --git a/docs/api.md b/docs/api.md
index 418d7b9..957030f 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -39,12 +39,14 @@ curl -u alice:secret -X POST 'localhost:3000/store/stats/visits?increment=1' #
`401`'s `WWW-Authenticate` only of what isn't a browser, by its `Sec-Fetch-*`
headers or a `Mozilla/…` user agent, so a browser never prompts),
named by a reverse proxy in front that authenticated it (`--user-header`;
- [`operations.md`](operations.md), Behind a reverse proxy), or a token from logging in on any node
- of the swarm (`Authorization: Bearer`, [`access.md`](access.md), Tokens). What each may do, the swarm's user
- registry says, by path ([`access.md`](access.md)): `403` where it doesn't let the user, and
- of a part it may only partly read, a read shows the keys on the way to what it may.
- In a swarm without a registry, users are all alike: each can read and write
- everything but protocol data (below).
+ [`operations.md`](operations.md),
+ [Behind a reverse proxy](operations.md#behind-a-reverse-proxy)), or a token from logging
+ in on any node of the swarm (`Authorization: Bearer`, [`access.md`](access.md),
+ [Tokens](access.md#tokens)). What each may do, the swarm's user registry says, by path
+ ([`access.md`](access.md)): `403` where it doesn't let the user, and of a part it may
+ only partly read, a read shows the keys on the way to what it may. In a swarm without a
+ registry, users are all alike: each can read and write everything but protocol data
+ (below).
* A key with `/` in it, or an empty key, can be written inside a value at its parent,
but not named in a path: read it through the parent.
@@ -130,10 +132,10 @@ JSON.
## Consistency
**Reads are local.** A node answers from its copy, which may lack writes other nodes
-made a moment ago: they arrive by sync, as fast as messages get from the writer to
-this node (a hop between neighbours, a few in a large swarm; [`measurements.md`](measurements.md),
-Propagation), and after a partition once it heals. There is
-no read that waits for the rest of the swarm.
+made a moment ago: they arrive by sync, as fast as messages get from the writer to this
+node (a hop between neighbours, a few in a large swarm;
+[`measurements.md`](measurements.md), [Propagation](measurements.md#propagation)), and
+after a partition once it heals. There is no read that waits for the rest of the swarm.
**Writes are local too, and never refused for want of others.** A write is applied to
the node's copy at once (the answer holds the value written) and spreads from there.
@@ -229,10 +231,10 @@ A node serves the store once it holds the swarm's document ([`lifecycle.md`](lif
go into that document (so reads show them), carried over into the new epoch when the
rejoin ends, unless newer writes touched their paths
([Concurrent writes](#concurrent-writes)); streams are `503`.
-* **Remakes** ([`remakes.md`](remakes.md)) don't interrupt anything else: a node switches to the new
- document between two requests, and writes made meanwhile are carried over (at
- their path, or where the remake's rules put them; [`remakes.md`](remakes.md), Writes around a
- remake).
+* **Remakes** ([`remakes.md`](remakes.md)) don't interrupt anything else: a node switches
+ to the new document between two requests, and writes made meanwhile are carried over (at
+ their path, or where the remake's rules put them; [`remakes.md`](remakes.md),
+ [Writes around a remake](remakes.md#writes-around-a-remake)).
Load balancers can send requests to any ready node: `/ready` is the check.
@@ -248,10 +250,11 @@ only where their operators make it so, which nothing checks.
`GET /admin/changes` lists them,
newest first, with the paths each touched and whether a signature by its node vouches
for it (`verified`, [Signed changes](#signed-changes)), and `GET /admin/refused` those
-this node refused under the swarm's policy ([`access.md`](access.md), Changes judged on
-every node); `GET /admin/changes/settings` those that touched what is at `settings`. Every
-node holds every change, so user names are known to the whole swarm, and so is who wrote
-what, until a remake drops the history ([`remakes.md`](remakes.md)).
+this node refused under the swarm's policy ([`access.md`](access.md),
+[Changes judged on every node](access.md#changes-judged-on-every-node));
+`GET /admin/changes/settings` those that touched what is at `settings`. Every node holds
+every change, so user names are known to the whole swarm, and so is who wrote what, until
+a remake drops the history ([`remakes.md`](remakes.md)).
## Signed changes
@@ -289,8 +292,9 @@ changes are read with their signatures one by one later, at a signature per chan
(about 25 µs to make, 30 µs to check on every node, 96 bytes kept). `none` where who
wrote a change matters only for what protocol data and the listed paths hold, to save
the signatures entirely. A swarm whose policy requires signatures
-([`access.md`](access.md), Changes judged on every node) signs what is sent with
-`none` too: every change must arrive vouched for.
+([`access.md`](access.md),
+[Changes judged on every node](access.md#changes-judged-on-every-node)) signs what is sent
+with `none` too: every change must arrive vouched for.
Signatures travel with the changes, in the sync messages that carry them, along the
same paths: a message carries the signatures of the changes it carries, whatever the
@@ -318,10 +322,11 @@ document.
## Signed values
-Where the swarm has its users sign values ([`access.md`](access.md), Values signed by
-their users), a user writes one by signing it with its SSH key: the value, one line of
-JSON; the meta, one line of JSON; then the signature of those two lines (without the
-second's newline), as `application/continuum-signed`.
+Where the swarm has its users sign values ([`access.md`](access.md),
+[Values signed by their users](access.md#values-signed-by-their-users)), a user writes one
+by signing it with its SSH key: the value, one line of JSON; the meta, one line of JSON;
+then the signature of those two lines (without the second's newline), as
+`application/continuum-signed`.
```sh
# The swarm it is for; the envelope there, if any, and what replaces it names: its
@@ -357,19 +362,21 @@ and streams (`/stream`).
## Sealed values
A value may be sealed for its readers, encrypted with age to their SSH keys
-([`access.md`](access.md), Values sealed for their readers): a string,
-`cs1.<age file>`, that the API stores and shows as it is. Where the swarm declares
-values sealed, a write leaving one there plain, or sealed for others than the declared
-readers' keys, is `409`.
+([`access.md`](access.md),
+[Values sealed for their readers](access.md#values-sealed-for-their-readers)): a string,
+`cs1.<age file>`, that the API stores and shows as it is. Where the swarm declares values
+sealed, a write leaving one there plain, or sealed for others than the declared readers'
+keys, is `409`.
## Protocol data
`_continuum` holds what the nodes coordinate through: the swarm ID, the member registry,
-remakes and votes ([`architecture.md`](architecture.md), The document). It is part of the store and shows
-in `GET /store`, but isn't application data: only users given it may write it
-([`access.md`](access.md); in a swarm without a user registry, those in `--protocol-writers`), for
-repairs. Keep application data out of it, and leave it out when reading
-the whole store if it's in the way.
+remakes and votes ([`architecture.md`](architecture.md),
+[The document](architecture.md#the-document)). It is part of the store and shows in
+`GET /store`, but isn't application data: only users given it may write it
+([`access.md`](access.md); in a swarm without a user registry, those in
+`--protocol-writers`), for repairs. Keep application data out of it, and leave it out when
+reading the whole store if it's in the way.
## Large stores