diff options
| author | tv <tv@krebsco.de> | 2026-11-18 12:48:29 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-18 13:59:42 +0100 |
| commit | d130c0612b4c63f2d30da65ebcc231018c1f2606 (patch) | |
| tree | 8700f2d53351cbbecbe772ea7701bf6240d5210c /docs/api.md | |
| parent | 0bfe07af92a775b0e896e0fc5a989a1d9b65f7b3 (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.md | 73 |
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 |
