diff options
Diffstat (limited to 'docs')
31 files changed, 437 insertions, 374 deletions
diff --git a/docs/access.md b/docs/access.md index 7c6c7e6..019565e 100644 --- a/docs/access.md +++ b/docs/access.md @@ -120,7 +120,7 @@ curl -H "Authorization: Bearer ct1.…" http://other-node:3000/store * **Who signs it**: the node it logged in on, with its node key. Every node takes a token signed by a member of the swarm (the member list gives the keys: a node ID is its key), and none signed by another or since forgotten; in a swarm holding a store - ([`store.md`](store.md), Members), only one it signed itself. + ([`store.md`](store.md), [Members](store.md#members)), only one it signed itself. * **What it says**: who, how it proved it, when it ends, and optionally less than the user may do (`limit`, capabilities as `POST /admin/users/{name}` takes them): never what the user may do. Every node judges a request by the registry it holds then, so @@ -310,12 +310,13 @@ through (they look at the path asked for, the rules at everything the change doe can't cut its node off. With `"signatures": "required"`, a change also needs a signature by the node it names -([`api.md`](api.md), Signed changes): every node then signs what it sends, so every -change leaves vouched for, and one no signature vouches for yet waits, with whatever builds on it, until one does -(they come with the changes, in the same sync messages). A signature vouches for -its change and the node's changes it builds on, no others: a change made under another -node's actor is forged, refused, and logged as its sender's (`A peer brought changes -forged`). A member can then no longer write as another member; the user a change names is still its node's word. +([`api.md`](api.md), [Signed changes](api.md#signed-changes)): every node then signs what +it sends, so every change leaves vouched for, and one no signature vouches for yet waits, +with whatever builds on it, until one does (they come with the changes, in the same sync +messages). A signature vouches for its change and the node's changes it builds on, no +others: a change made under another node's actor is forged, refused, and logged as its +sender's (`A peer brought changes forged`). A member can then no longer write as another +member; the user a change names is still its node's word. Whatever the policy, and without one, a change is refused that Automerge itself wouldn't have written: bytes that aren't Automerge's encoding of the change; a first @@ -468,14 +469,14 @@ Under a strict policy, the same, as part of bob's entry, signed (`continuum-sign _continuum/users/bob '{…}'`). A node takes one only from that user, for that path, replacing what is there, by one of -the user's keys, and if the user may write there ([`api.md`](api.md), Signed values); it -writes nothing else there, nor within or above such a value (`409`), and the users API -changes nothing (`409`). A swarm turns strict only at its start (`--bootstrap-policy`, -[A new swarm](#a-new-swarm), above) or through a remake -([Turning a swarm strict](#turning-a-swarm-strict), below), which keeps only what an -operator looked over: each is its epoch's first change, so no change of a strict epoch is -from before its policy. A change writing a strict policy where the policy isn't strict is -refused; and a policy reads strict only where its `values` is a string, as continuum +the user's keys, and if the user may write there ([`api.md`](api.md), +[Signed values](api.md#signed-values)); it writes nothing else there, nor within or above +such a value (`409`), and the users API changes nothing (`409`). A swarm turns strict only +at its start (`--bootstrap-policy`, [A new swarm](#a-new-swarm), above) or through a +remake ([Turning a swarm strict](#turning-a-swarm-strict), below), which keeps only what +an operator looked over: each is its epoch's first change, so no change of a strict epoch +is from before its policy. A change writing a strict policy where the policy isn't strict +is refused; and a policy reads strict only where its `values` is a string, as continuum writes it: one that would read strict only through an Automerge text is one no node knows, never what its characters spell. A strict swarm stays strict: its policy is written again only as strict, never relaxed nor deleted, nor moved to a policy its nodes don't know (a 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 diff --git a/docs/configuration.md b/docs/configuration.md index 989f268..f48f288 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -116,13 +116,14 @@ listen = ["/ip4/0.0.0.0/tcp/9661", "/ip4/0.0.0.0/udp/9661/quic-v1"] `--transport-order` is their order of preference (`mycelium,libp2p,tor` by default), whether enabled or not; those it leaves out come after, in the default order. How a node -uses several: [`transports.md`](transports.md), Several transports. Options -of a transport the node doesn't use (not enabled), or this build doesn't have, are -ignored, and the node says which at start (`Options of a transport this node doesn't use are ignored`, -with the transport, whether it's built, and the options); a configuration shared -between nodes may carry them on purpose. A transport's options are checked when the -configuration is loaded if the node uses it (Mycelium's always, where it is built), so -`--print-config` catches a wrong one too. +uses several: [`transports.md`](transports.md), +[Several transports](transports.md#several-transports). Options of a transport the node +doesn't use (not enabled), or this build doesn't have, are ignored, and the node says +which at start (`Options of a transport this node doesn't use are ignored`, with the +transport, whether it's built, and the options); a configuration shared between nodes may +carry them on purpose. A transport's options are checked when the configuration is loaded +if the node uses it (Mycelium's always, where it is built), so `--print-config` catches a +wrong one too. What each transport is for and its options: [`transports.md`](transports.md). @@ -258,6 +259,7 @@ continuum-party --config tv.toml write home/tv/motd '"hello"' `key` is an OpenSSH private key file, or a public key an ssh-agent holds: the key itself (`key = "ecdsa-sha2-nistp256 AAAA…"`), or a file of such lines, whose first signs -([`guides/federation/keys.md`](guides/federation/keys.md), Keys in an ssh-agent). +([`guides/federation/keys.md`](guides/federation/keys.md), +[Keys in an ssh-agent](guides/federation/keys.md#keys-in-an-ssh-agent)). `node` and `token` are secrets: never logged, however they are given. diff --git a/docs/dashboard.md b/docs/dashboard.md index d11bf3c..009ac03 100644 --- a/docs/dashboard.md +++ b/docs/dashboard.md @@ -21,36 +21,39 @@ session) goes to at once without one. There, a user logs in with its password (`--htpasswd`, the same file the API's basic authentication takes, which the dashboard never asks for itself, nor takes from the browser: no browser password prompt, the node never challenges a browser), or with a token: from `continuum-signed login` (by key, -[`access.md`](access.md), Tokens), or any other. The page keeps a session for the -browser, a cookie no script reads and no other site's page sends, renewed while the -dashboard is open (half way through the token's life, looked at again when the page -shows, so after the computer slept too) until the login ends (`--session-lifetime`), -then back to the login page; it ends with the token's lifetime once not renewed, or -with "Log out of this browser" on the login page, or "log out" in the user's menu on the dashboard (its -name, top right), which ends this browser's session only: the page stops reading -and goes to the login page, and brought back by the browser's back button it loads -again, so it shows nothing from before. Where the page got in by -what it can't end, the proxy's, "log out" is greyed, and says how instead. The menu's "credentials…" shows the user's keys, each by its name -and as much of the key as fits the dialog, cut in the middle where it doesn't (its end -and comment always shown, the whole in its tooltip), and `edit` at the right: its name -and `.pub` line in fields, to save, or to delete with the red `Delete` (on a second -click from half a second to 3 s after the first, as in the document box; the last key -only where the user has a password on this node, which it logs in by then); or one -added below; what fails says why where it was asked, to be set right and tried again. Under a -strict policy, it says how to sign them anew (`continuum-signed key-add`); and where -the password is: in each node's `--htpasswd`. The page and the login page run their -own script only (a content security policy naming it by its hash), and no other page -may frame them. The API listens on localhost unless `--bind-addr` says otherwise; -to look at a node on another machine, forward the port (`ssh -L 3000:localhost:3000 -<machine>`) or put a TLS proxy in front ([`operations.md`](operations.md), Behind a reverse proxy). +[`access.md`](access.md), [Tokens](access.md#tokens)), or any other. The page keeps a +session for the browser, a cookie no script reads and no other site's page sends, renewed +while the dashboard is open (half way through the token's life, looked at again when the +page shows, so after the computer slept too) until the login ends (`--session-lifetime`), +then back to the login page; it ends with the token's lifetime once not renewed, or with +"Log out of this browser" on the login page, or "log out" in the user's menu on the +dashboard (its name, top right), which ends this browser's session only: the page stops +reading and goes to the login page, and brought back by the browser's back button it loads +again, so it shows nothing from before. Where the page got in by what it can't end, the +proxy's, "log out" is greyed, and says how instead. The menu's "credentials…" shows the +user's keys, each by its name and as much of the key as fits the dialog, cut in the middle +where it doesn't (its end and comment always shown, the whole in its tooltip), and `edit` +at the right: its name and `.pub` line in fields, to save, or to delete with the red +`Delete` (on a second click from half a second to 3 s after the first, as in the document +box; the last key only where the user has a password on this node, which it logs in by +then); or one added below; what fails says why where it was asked, to be set right and +tried again. Under a strict policy, it says how to sign them anew +(`continuum-signed key-add`); and where the password is: in each node's `--htpasswd`. The +page and the login page run their own script only (a content security policy naming it by +its hash), and no other page may frame them. The API listens on localhost unless +`--bind-addr` says otherwise; to look at a node on another machine, forward the port +(`ssh -L 3000:localhost:3000 <machine>`) or put a TLS proxy in front +([`operations.md`](operations.md), +[Behind a reverse proxy](operations.md#behind-a-reverse-proxy)). Every node has its own dashboard, and shows the swarm as that node sees it: what it knows of the others, what they report to it, and its own figures. ## The page -At the top, the node's alias and node ID; in orange, when this node's clock is off -from its peers' ([`measurements.md`](measurements.md), Clocks), by how much; and the connection's status: +At the top, the node's alias and node ID; in orange, when this node's clock is off from +its peers' ([`measurements.md`](measurements.md), [Clocks](measurements.md#clocks)), by +how much; and the connection's status: | Status | Meaning | |---|---| @@ -247,14 +250,14 @@ measured. * **Double-click a node**: subscribe to its links, or no longer. The page then reads the node's own links from it, live, as it measures them (its `/admin/dashboard/links/own/events`, at the dashboard it publishes, - `--dashboard-url`), with a token from this node that lets it read the member list - only ([`access.md`](access.md), Tokens); its links are drawn as it reports them, over what - this node knows of them. The browser must reach that dashboard: not one behind NAT, on - Tor alone, or plain `http` from an `https` page; the node allows this page's origin - as a member's dashboard (`--cors-origins` for others). Subscriptions are kept in the - browser, and handed over with the rest; going to another node's dashboard, the node - left is subscribed to there (this node itself never is: its links and messages are - the page's own). + `--dashboard-url`), with a token from this node that lets it read the member list only + ([`access.md`](access.md), [Tokens](access.md#tokens)); its links are drawn as it + reports them, over what this node knows of them. The browser must reach that dashboard: + not one behind NAT, on Tor alone, or plain `http` from an `https` page; the node allows + this page's origin as a member's dashboard (`--cors-origins` for others). Subscriptions + are kept in the browser, and handed over with the rest; going to another node's + dashboard, the node left is subscribed to there (this node itself never is: its links + and messages are the page's own). * **Right-click a node**: its menu: subscribing to its links (or not), and `go to its dashboard`, greyed where the node publishes none, and on this node's own. * **Go to a node's dashboard** (its menu): in this page, where the node publishes one @@ -322,7 +325,7 @@ them: no HELLOs, keepalives or syncing of its own; their tooltip says so), with: | via | The address this node sends to it at, and whether `direct` or `relayed`: as much as the box's width leaves, cut short with an ellipsis; all of it in the tooltip. | | rtt | The round trip on that path. | | hop | How long its sync and blob messages take to come, by its clock and this node's, its clock offset taken off (`hopDelay` in [`measurements.md`](measurements.md)): this minute's mean, then the last 15 minutes' means as bars, oldest first (a minute without messages blank). Good to half the round trip, but the trend exactly: bars growing mean the link, or a queue on it, gets slower. All figures in the tooltip. | -| clock | How far its clock is ahead of this node's (behind: `−`), give or take (in the tooltip); in orange beyond `--clock-skew-warn`, for sure ([`measurements.md`](measurements.md), Clocks). | +| clock | How far its clock is ahead of this node's (behind: `−`), give or take (in the tooltip); in orange beyond `--clock-skew-warn`, for sure ([`measurements.md`](measurements.md), [Clocks](measurements.md#clocks)). | | reaches | How many members besides this node it reaches, as it said ([`peers.md`](peers.md)); `(+n)`: of those, how many this node doesn't reach itself, which it is a way to. By name in the tooltip, those marked `+`. Blank until it said so in this session. | | epoch | The epoch it last said it is on, by its generation ([`remakes.md`](remakes.md)); orange where it isn't this node's (they don't sync then); its ID in the tooltip; blank while unknown. | @@ -434,10 +437,11 @@ they come (a tenth of a second after the first of a moment's), and are listed in order they went, as the map runs them: each by when its node logged it, on this node's clock (a subscribed node's taken back by how far its clock is ahead, as the map chains the clocks; its own clock's time in the tooltip of the time), so one a slower stream -brought late goes in among those of its moment, not at the bottom. The PINGs the paths layer sends on its own, and the PONGs it answers -PINGs with, are listed too: under the node at the address they went to, where it is -known, else under the address. Not listed: WHO and ME, which stay in the layers -below the node (they are counted, [`measurements.md`](measurements.md), Traffic). +brought late goes in among those of its moment, not at the bottom. The PINGs the paths +layer sends on its own, and the PONGs it answers PINGs with, are listed too: under the +node at the address they went to, where it is known, else under the address. Not listed: +WHO and ME, which stay in the layers below the node (they are counted, +[`measurements.md`](measurements.md), [Traffic](measurements.md#traffic)). A subscribed node's messages with its peers are listed too, as they come from it: named by both ends, the receiver first (`b ← a`), each once, as on the map (those @@ -530,17 +534,17 @@ it reads from each node itself: `GET /admin/dashboard/links/own/events` there, a transport, relayed, dormant, or a round trip moved by a fifth; it looks every 2 s) or it enters a new epoch, with the epoch it is in. The page asks with a token from this node that reads the member list only (`Authorization: Bearer`, [`access.md`](access.md), -Tokens), refreshed half way through its life; the other node allows the page's origin -by CORS where it is a member's dashboard (`--cors-origins` for others). A stream that -fails is opened again, waiting longer each time (up to a minute). +[Tokens](access.md#tokens)), refreshed half way through its life; the other node allows +the page's origin by CORS where it is a member's dashboard (`--cors-origins` for others). +A stream that fails is opened again, waiting longer each time (up to a minute). The links a member reports: its neighbours and the peers it holds dormant (a neighbour that goes dormant is one no more, but stays listed until it is heard from again), by which transport, whether only through a relay, the round trip (as the paths layer measures it), whether it holds the peer dormant or the path is down, the peer's other transports with a path up (each with its fastest path's round trip, and whether it goes -only through a relay), and the peer's clock against the member's ([`measurements.md`](measurements.md), -Per peer, `clock`). +only through a relay), and the peer's clock against the member's +([`measurements.md`](measurements.md), [Per peer](measurements.md#per-peer), `clock`). **Clocks.** The clocks in the links on the map (this node's and the subscribed nodes') chain every member's clock to this node's, along the narrowest bounds, and the page diff --git a/docs/federation-tests.md b/docs/federation-tests.md index 47b76e8..dfa9ca0 100644 --- a/docs/federation-tests.md +++ b/docs/federation-tests.md @@ -119,8 +119,8 @@ U+FFFF); events at federation 1's sizes and just past them; a signature, a versi its hash, a checkpoint and its ID, the genesis change of a federation's root and of a fork's, a snapshot after a checkpoint, and a version naming an ECDSA key, with a write and a key set `ssh-keygen` signed with it. A vector that changes is a change of the -federation, which takes its next number ([`federation.md`](federation.md), Changing the -federation). +federation, which takes its next number ([`federation.md`](federation.md), +[Changing the federation](federation.md#changing-the-federation)). ## Fuzzing and mutants diff --git a/docs/federation.md b/docs/federation.md index 2b76fdf..190f2b4 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -88,8 +88,9 @@ Not promised: * that a node joining from the root, in a federation that never passed a checkpoint, isn't shown a chain old keys grew: of two versions changing one it takes neither, but where its seeds are all the adversary's it is shown one ([Checkpoints](#checkpoints)); -* that a checkpoint, or a fork's root, that a node takes on its operator's word is the - one the others built ([`store.md`](store.md), Pinned checkpoints). +* that a checkpoint, or a fork's root, that a node takes on its operator's word is the one + the others built ([`store.md`](store.md), + [Pinned checkpoints](store.md#pinned-checkpoints)). ## The design @@ -173,8 +174,8 @@ another event of what a party signed. Of an event, federation 1 allows: It names no swarm, no version and no ID of its own: its history says the first two. An event signed in a federation, or in a fork once it forked, has that store's root in its -history, and no other store takes it ([`store.md`](store.md), Forks). An event is -**written under** the version current at its history +history, and no other store takes it ([`store.md`](store.md), [Forks](store.md#forks)). An +event is **written under** the version current at its history ([Changing the policy](#changing-the-policy)). ### The policy @@ -249,7 +250,7 @@ client backs none that isn't: two thirds backing one that can never be written b federation to its version, as a yes binds ([Changing the policy](#changing-the-policy)). What the swarm's document holds beyond the events, and what a node takes at its API, is -the store's ([`store.md`](store.md), On Automerge). +the store's ([`store.md`](store.md), [On Automerge](store.md#on-automerge)). ### Changing the policy @@ -301,25 +302,25 @@ written: it is current at every history that holds it and no version after it. **A node takes a version only where it changes the version the node reads**, or is one it took, written again. A version event of any other, valid at its history or not, it refuses, with everything built on it, reports, and leaves to its operator -([`store.md`](store.md), A node's own); another node's refusal doesn't make it drop what -it took. One valid at its history breaks no rule: the node reports it apart from events -against the rules, and holds nothing against the node that put it. Of two that change -the one it reads, it takes the first it judges; a node still joining takes neither, and -reports, until its operator names one. A node is still joining, for this, from its start -or a rejoin until it has synced with every seed its operator named: continuum's -lifecycle has it `Joining` only until its first sync, with one peer, which could be the -adversary's alone. Without keys voting twice, every version written changes the one -every node reads, or is one it took, and none is refused. +([`store.md`](store.md), [A node's own](store.md#a-nodes-own)); another node's refusal +doesn't make it drop what it took. One valid at its history breaks no rule: the node +reports it apart from events against the rules, and holds nothing against the node that +put it. Of two that change the one it reads, it takes the first it judges; a node still +joining takes neither, and reports, until its operator names one. A node is still joining, +for this, from its start or a rejoin until it has synced with every seed its operator +named: continuum's lifecycle has it `Joining` only until its first sync, with one peer, +which could be the adversary's alone. Without keys voting twice, every version written +changes the one every node reads, or is one it took, and none is refused. **An operator may have its node drop what it took** after its checkpoint: a version the -others refused, or any event, with everything built on it ([`store.md`](store.md), A -node's own), and then take what the others hold. A version that moved the node to a -checkpoint it undoes only by taking a checkpoint its operator pins, as the node forgot -what the other side's version needs. No peer's word moves a node; its operator's does. -The node refuses what it dropped, from whoever brings it, and any version event naming a -version among it, whoever wrote it anew, and writes none itself, though it holds the -votes that passed it, until its operator says otherwise. So either side of keys that -voted twice may join the other without what parts them, and without a fork. +others refused, or any event, with everything built on it ([`store.md`](store.md), +[A node's own](store.md#a-nodes-own)), and then take what the others hold. A version that +moved the node to a checkpoint it undoes only by taking a checkpoint its operator pins, as +the node forgot what the other side's version needs. No peer's word moves a node; its +operator's does. The node refuses what it dropped, from whoever brings it, and any version +event naming a version among it, whoever wrote it anew, and writes none itself, though it +holds the votes that passed it, until its operator says otherwise. So either side of keys +that voted twice may join the other without what parts them, and without a fork. **The current version** is the written version with the highest number: the end of the chain the node took. @@ -425,9 +426,9 @@ version current, version events aside, as it holds the version itself ([What counts](#what-counts)), as the JCS encoding of `{"at": [<IDs>], "keeps": [<IDs>], "version": <version>}`, its IDs ascending and its version the version itself, the object, named by its SHA-256 ([`store.md`](store.md), -Checkpoints). Every node holding the history up to those heads builds the same one, and -its version counts as written: a version event of it that comes later is one the node -took. +[Checkpoints](store.md#checkpoints)). Every node holding the history up to those heads +builds the same one, and its version counts as written: a version event of it that comes +later is one the node took. A version names a checkpoint by its heads (`checkpoint`): events after the current checkpoint, at which it is current too, none in another's history, their IDs ascending, @@ -445,23 +446,24 @@ among it. A node shows, for a proposed checkpoint, what it holds that its heads for a fork ([Forks](#forks)). This is the voter's rule, by its own clock: nothing more is judged. It is a version only where its proposal is above those heads, and a version event writing it is taken only where it is above them too, and so is every vote it is written on -([`store.md`](store.md), Events): so moving to the checkpoint refuses nothing that decided -it. A party's client, and a node voting by itself, vote on the events proposing what they -vote on, and a node proposes a checkpoint on its heads: so their votes are above those -heads wherever the proposal is. A vote beside them binds its party as any yes does, until -the move refuses it. A node that takes the version moves to the checkpoint: it builds it, -forgets everything before those heads that it doesn't keep, and every event not above -them, and refuses such events from then on. Judging an event after them needs nothing it -forgot: the version, every party's keys and node list, and the proposals on the current -version with their votes all count, and are kept. A node starting from a checkpoint reads -what it keeps as written under its version, as it holds none of their histories: each was -written under that one or an earlier, counting there, a kept proposal is on it, and a -later `since` that leaves one out is past it. A node that can't build a checkpoint, as it -was away across a move and a remake after it, or as it joins, takes it only where its -operator pins it ([`store.md`](store.md), Pinned checkpoints). What it can't check of its -heads it takes on its operator's word: that they are after the checkpoint current at the -version naming them, at which that one is current too; so it judges that version as every -node does. +([`store.md`](store.md), [Events](store.md#events)): so moving to the checkpoint refuses +nothing that decided it. A party's client, and a node voting by itself, vote on the events +proposing what they vote on, and a node proposes a checkpoint on its heads: so their votes +are above those heads wherever the proposal is. A vote beside them binds its party as any +yes does, until the move refuses it. A node that takes the version moves to the +checkpoint: it builds it, forgets everything before those heads that it doesn't keep, and +every event not above them, and refuses such events from then on. Judging an event after +them needs nothing it forgot: the version, every party's keys and node list, and the +proposals on the current version with their votes all count, and are kept. A node starting +from a checkpoint reads what it keeps as written under its version, as it holds none of +their histories: each was written under that one or an earlier, counting there, a kept +proposal is on it, and a later `since` that leaves one out is past it. A node that can't +build a checkpoint, as it was away across a move and a remake after it, or as it joins, +takes it only where its operator pins it ([`store.md`](store.md), +[Pinned checkpoints](store.md#pinned-checkpoints)). What it can't check of its heads it +takes on its operator's word: that they are after the checkpoint current at the version +naming them, at which that one is current too; so it judges that version as every node +does. What a checkpoint loses: what counted no more before it, so that a key added back, or a place given back, brings back nothing signed before it, and a party that voted twice on @@ -472,12 +474,13 @@ while the vote takes its course, a client writing once a checkpoint is proposed only on what is above its heads, and a party's client signs again what a move refused. **Joining.** Once a checkpoint passed, a node joins from a checkpoint its operator pins, -not from the root ([`store.md`](store.md), Pinned checkpoints). Whether one passed is -its operator's to know, not the node's: a chain old keys grew need name none. From the -root, keys a version named before it, revoked since or thrown away, could grow another -chain, at histories before the version that followed, and node lists naming only their -own nodes would seal a node joining in it, never shown the other. So a checkpoint bounds -what old keys can do to the versions after it. +not from the root ([`store.md`](store.md), +[Pinned checkpoints](store.md#pinned-checkpoints)). Whether one passed is its operator's +to know, not the node's: a chain old keys grew need name none. From the root, keys a +version named before it, revoked since or thrown away, could grow another chain, at +histories before the version that followed, and node lists naming only their own nodes +would seal a node joining in it, never shown the other. So a checkpoint bounds what old +keys can do to the versions after it. A version that changes nothing but its number, what it changes and its checkpoint only moves the store on. Like any version, it lapses the proposals on the version before, so @@ -533,20 +536,20 @@ written under names for the party. A party's list is that one ([What counts](#what-counts), 5) where it is written under a version numbered at least the `since` its version gives the party's list, otherwise the list its version gives, if any, as with keys ([Keys](#keys)). The store's members are the nodes each party's list names, -each as its party's ([`store.md`](store.md), Members); another party's list does nothing -for a node. A party's list counts until the party writes another or a version names one -anew, whatever keys its version names since, so that no change of keys leaves a swarm -without members; a list a stolen key wrote stays until the party writes one under the -version that replaced that key, which it can at once, through any member. A node puts -whatever events it is given, its party's and others' alike: what counts is who signed an -event, not which node put it. So a party without nodes of its own writes through any node -that takes its events. +each as its party's ([`store.md`](store.md), [Members](store.md#members)); another party's +list does nothing for a node. A party's list counts until the party writes another or a +version names one anew, whatever keys its version names since, so that no change of keys +leaves a swarm without members; a list a stolen key wrote stays until the party writes one +under the version that replaced that key, which it can at once, through any member. A node +puts whatever events it is given, its party's and others' alike: what counts is who signed +an event, not which node put it. So a party without nodes of its own writes through any +node that takes its events. ### Forks Any group can carry on without the rest: too many parties are away for good, a version the group won't follow passed, or the parties can't agree. It **forks**: it starts a -store of its own from the federation's ([`store.md`](store.md), Forks). +store of its own from the federation's ([`store.md`](store.md), [Forks](store.md#forks)). 1. One of the group makes the fork's root, a checkpoint at the heads it forks at, which no party signs, so that one version and one set of heads make one fork @@ -605,10 +608,10 @@ so one first version makes one federation, named by the root's ID. Among the nod the version gives, one names a node of its founders', so the federation starts with members, and other nodes come in as their parties list them. Its swarm's genesis change holds the root, built byte for byte from it, its policy naming the fold `federation` -(`{"version": 2, "store": "federation"}`, [`store.md`](store.md), On Automerge). So -nothing is from before the federation: it changes by versions, and any group carries on by -a fork. A running swarm doesn't become federated; its parties start one, and sign into it -what they keep. +(`{"version": 2, "store": "federation"}`, [`store.md`](store.md), +[On Automerge](store.md#on-automerge)). So nothing is from before the federation: it +changes by versions, and any group carries on by a fork. A running swarm doesn't become +federated; its parties start one, and sign into it what they keep. ## Why it holds @@ -643,8 +646,8 @@ what they keep. ## Attacks What an attacker does, and what happens; what it does to the store, its document and its -remakes, is the store's ([`store.md`](store.md), Attacks). *Unit*: the fold, with -crafted events. *Sim*: a simulation. *Bench*: measured, not judged. +remakes, is the store's ([`store.md`](store.md), [Attacks](store.md#attacks)). *Unit*: the +fold, with crafted events. *Sim*: a simulation. *Bench*: measured, not judged. | # | Attack | What happens | Test | |---|---|---|---| @@ -848,7 +851,7 @@ continuum builds and behaves as it does, and its tests pass untouched. 1. **The store**, generic and in memory, with a fold made for its tests: events, histories, judging at a history, the state, checkpoints and moving to them, a node's - own refusals and drops, forks ([`store.md`](store.md), Tests). + own refusals and drops, forks ([`store.md`](store.md), [Tests](store.md#tests)). 2. **The federation's fold**, as pure code: events and what makes one, versions and what makes one valid, rules and paths, places, keys, votes, passing and dead, version events, which version a node takes and the current one, what counts, node lists and diff --git a/docs/glossary.md b/docs/glossary.md index 5497b57..bc920e4 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -81,8 +81,9 @@ back from it. After `reset_sync()` the Automerge `sync::State` is new, so `their_heads`, `their_have` and `their_need` are all unset; an opening can only say "these are my heads, here is a Bloom filter of what we share", and carries no changes since we don't know yet what the peer has. The code doesn't track openings -separately: `their_heads.is_none()` means nothing has come from the peer since the -reset. Who may open towards whom: [`peers.md`](peers.md), Handshake and join. +separately: `their_heads.is_none()` means nothing has come from the peer since the reset. +Who may open towards whom: [`peers.md`](peers.md), +[Handshake and join](peers.md#handshake-and-join). **path**: an address of a peer on one of this node's transports (`<scheme>:<target>`). A peer with several (on several transports) is reached on the best: paths are measured diff --git a/docs/guides/federation/building-on-the-api.md b/docs/guides/federation/building-on-the-api.md index 4f37b91..45394ed 100644 --- a/docs/guides/federation/building-on-the-api.md +++ b/docs/guides/federation/building-on-the-api.md @@ -2,14 +2,17 @@ An application on a federated swarm reads what counts at a node and writes as a party. This guide says how, through the client or with code of its own. The formats are the -design's ([`federation.md`](../../federation.md), Events, The policy, What counts). +design's ([`federation.md`](../../federation.md), [Events](../../federation.md#events), +[The policy](../../federation.md#the-policy), +[What counts](../../federation.md#what-counts)). ## Reading `GET /events/counts` is what counts, as the node reads it now: the values at places (`values`), the current version and its rules, each party's keys and nodes, the members -([`writing-and-reading.md`](writing-and-reading.md), Reading). There is no stream of what -counts: read it again when the store's heads change (`heads` in `GET /events`). +([`writing-and-reading.md`](writing-and-reading.md), +[Reading](writing-and-reading.md#reading)). There is no stream of what counts: read it +again when the store's heads change (`heads` in `GET /events`). What a node answers is its word: it may be behind, and an application that must not take it on trust reads the events themselves (`GET /events/{id}`) and checks their signatures, @@ -25,8 +28,9 @@ continuum-party --node http://tv:secret@localhost:3000 --key laptop.key \ ``` It signs on the heads the node shows, records what it signed, and puts it; `again` signs -anew what a move to a checkpoint refused ([`writing-and-reading.md`](writing-and-reading.md), -After a move). +anew what a move to a checkpoint refused +([`writing-and-reading.md`](writing-and-reading.md), +[After a move](writing-and-reading.md#after-a-move)). ## Writing with code of its own diff --git a/docs/guides/federation/checkpoints.md b/docs/guides/federation/checkpoints.md index 23f0e9c..66f79e9 100644 --- a/docs/guides/federation/checkpoints.md +++ b/docs/guides/federation/checkpoints.md @@ -2,8 +2,8 @@ A checkpoint writes down what counts at some heads, so that nodes forget the rest and hold what is relevant. The parties pass it as any version. The rules are the design's -([`federation.md`](../../federation.md), Checkpoints; [`store.md`](../../store.md), -Checkpoints). +([`federation.md`](../../federation.md), [Checkpoints](../../federation.md#checkpoints); +[`store.md`](../../store.md), [Checkpoints](../../store.md#checkpoints)). ## What one does @@ -23,12 +23,13 @@ isn't above the heads, which its party signs again ([After a move](#after-a-move A version that only moves the store on is the current one with the next `number`, the current version's hash as `changes`, and the heads as `checkpoint` -([`proposing-and-voting.md`](proposing-and-voting.md), Writing a version). The heads are -events after the current checkpoint, at which the current version is current too, none in +([`proposing-and-voting.md`](proposing-and-voting.md), +[Writing a version](proposing-and-voting.md#writing-a-version)). The heads are events +after the current checkpoint, at which the current version is current too, none in another's history, their IDs ascending: heads a node showed (`heads` in `GET /events`) -once the version was written, and that it has held for a while since, so that every -node holds them. Propose it afterwards: the client signs the proposal on the heads its -node shows then, above the ones it names, as it must be. +once the version was written, and that it has held for a while since, so that every node +holds them. Propose it afterwards: the client signs the proposal on the heads its node +shows then, above the ones it names, as it must be. Like any version, it lapses the proposals on the version before: propose one where nothing that can still pass is proposed on the current version. @@ -75,4 +76,4 @@ leaves out what a checkpoint forgot, the document holds what came before, and a that was away builds the checkpoint from it as any. After such a remake, a node away across it, or joining, takes the checkpoint only where its operator pins it: ask a node you trust for it (`checkpoint` in `GET /events`) -([`running-a-node.md`](running-a-node.md), Joining). +([`running-a-node.md`](running-a-node.md), [Joining](running-a-node.md#joining)). diff --git a/docs/guides/federation/common-changes.md b/docs/guides/federation/common-changes.md index 1dd30c1..a18d863 100644 --- a/docs/guides/federation/common-changes.md +++ b/docs/guides/federation/common-changes.md @@ -1,9 +1,10 @@ # Common changes Recipes for the changes a federation makes most, each a version to propose and vote on -([`proposing-and-voting.md`](proposing-and-voting.md)), and a few a party makes by -itself. The rules are the design's ([`federation.md`](../../federation.md), The policy, -Keys, Nodes). +([`proposing-and-voting.md`](proposing-and-voting.md)), and a few a party makes by itself. +The rules are the design's ([`federation.md`](../../federation.md), +[The policy](../../federation.md#the-policy), [Keys](../../federation.md#keys), +[Nodes](../../federation.md#nodes)). ## The next version @@ -29,7 +30,8 @@ jq --arg key "$(cut -d' ' -f1,2 makefu.key.pub)" --arg node continuum:e2a8… ' A party let in without nodes has an empty list (`nodes: []`) and writes through any node that takes its events. It begins its record before it votes: from the root, as it never -voted ([`proposing-and-voting.md`](proposing-and-voting.md), Voting). +voted ([`proposing-and-voting.md`](proposing-and-voting.md), +[Voting](proposing-and-voting.md#voting)). ## Taking a party out diff --git a/docs/guides/federation/designing-rules.md b/docs/guides/federation/designing-rules.md index 82cec96..db61f62 100644 --- a/docs/guides/federation/designing-rules.md +++ b/docs/guides/federation/designing-rules.md @@ -2,7 +2,8 @@ The rules of a version say who writes where. Good rules let routine work go without a vote and leave votes for what is nobody's by its spelling. The rules are the design's -([`federation.md`](../../federation.md), The policy, Shared identifiers). +([`federation.md`](../../federation.md), [The policy](../../federation.md#the-policy), +[Shared identifiers](../../federation.md#shared-identifiers)). ## How they match diff --git a/docs/guides/federation/forking-and-following.md b/docs/guides/federation/forking-and-following.md index 51d56ab..ffc4fae 100644 --- a/docs/guides/federation/forking-and-following.md +++ b/docs/guides/federation/forking-and-following.md @@ -2,8 +2,9 @@ Any group can carry on without the rest, by a fork: a store of its own, whose root is a checkpoint at heads of the federation's. It needs nobody's vote and binds only those who -go. The rules are the design's ([`federation.md`](../../federation.md), Forks; -[`store.md`](../../store.md), Forks). +go. The rules are the design's ([`federation.md`](../../federation.md), +[Forks](../../federation.md#forks); [`store.md`](../../store.md), +[Forks](../../store.md#forks)). ## When diff --git a/docs/guides/federation/getting-started.md b/docs/guides/federation/getting-started.md index 5dcff5b..003d56e 100644 --- a/docs/guides/federation/getting-started.md +++ b/docs/guides/federation/getting-started.md @@ -20,7 +20,7 @@ That builds the node, `continuum`, and the party's client, `continuum-party`, in The version names each party's keys, and the party signs with them. A key is `ssh-ed25519` or `ecdsa-sha2-nistp256`. The client reads an OpenSSH private key file without a passphrase, of an Ed25519 key, or signs through an ssh-agent holding the key -([`keys.md`](keys.md), Keys in an ssh-agent): +([`keys.md`](keys.md), [Keys in an ssh-agent](keys.md#keys-in-an-ssh-agent)): ```sh ssh-keygen -t ed25519 -N '' -f tv.key @@ -119,7 +119,8 @@ continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv. ``` The value is JSON. The client's options can go in a configuration file instead, as the -node's do ([`configuration.md`](../../configuration.md), The party's client): +node's do ([`configuration.md`](../../configuration.md), +[The party's client](../../configuration.md#the-partys-client)): `continuum-party --config tv.toml write …`. lass reads it on its node, with everything else that counts: diff --git a/docs/guides/federation/keys.md b/docs/guides/federation/keys.md index 7f5bd7a..add7cb3 100644 --- a/docs/guides/federation/keys.md +++ b/docs/guides/federation/keys.md @@ -1,8 +1,9 @@ # Keys A party has two kinds of keys: those its version names, and those of its key set. The -rules are the design's ([`federation.md`](../../federation.md), Keys); this guide says -how to keep them, change them, and what to do when one is stolen. +rules are the design's ([`federation.md`](../../federation.md), +[Keys](../../federation.md#keys)); this guide says how to keep them, change them, and what +to do when one is stolen. ## The two kinds @@ -115,4 +116,4 @@ set that party wrote count no more. A node's own key (`--node-key-file`) is no party's: it is the node, the node ID its party lists. A stolen node key is a node the party takes off its list -([`running-a-node.md`](running-a-node.md), Who syncs). +([`running-a-node.md`](running-a-node.md), [Who syncs](running-a-node.md#who-syncs)). diff --git a/docs/guides/federation/promises.md b/docs/guides/federation/promises.md index 3c9a257..9a1b92f 100644 --- a/docs/guides/federation/promises.md +++ b/docs/guides/federation/promises.md @@ -3,7 +3,9 @@ A federated swarm is kept by parties that don't trust each other. This guide says, in plain words, what holds whatever any of them does, what doesn't, and what that asks of a party, an operator and an application. The design says it precisely -([`federation.md`](../../federation.md), Parties and the adversary, What is promised). +([`federation.md`](../../federation.md), +[Parties and the adversary](../../federation.md#parties-and-the-adversary), +[What is promised](../../federation.md#what-is-promised)). ## Who is who @@ -58,4 +60,5 @@ to whom. A party whose machine is taken over whole is the adversary from then on trust, and keep its store file ([`running-a-node.md`](running-a-node.md)). * **An application**: read from a node you trust, as what it answers is its word; check the events yourself where that matters - ([`writing-and-reading.md`](writing-and-reading.md), Reading). + ([`writing-and-reading.md`](writing-and-reading.md), + [Reading](writing-and-reading.md#reading)). diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md index 91da019..e656083 100644 --- a/docs/guides/federation/proposing-and-voting.md +++ b/docs/guides/federation/proposing-and-voting.md @@ -3,8 +3,9 @@ Everything a federation decides is a change of its policy: who the parties are, the keys they vote with, who writes where, a checkpoint. A party proposes a version, the parties vote, and once two thirds of them back it, it is written. The rules are the design's -([`federation.md`](../../federation.md), The policy, Changing the policy). A party's -node list and its key set are its own to write, without a vote +([`federation.md`](../../federation.md), [The policy](../../federation.md#the-policy), +[Changing the policy](../../federation.md#changing-the-policy)). A party's node list and +its key set are its own to write, without a vote ([`common-changes.md`](common-changes.md#what-a-party-does-by-itself)). ## Writing a version @@ -31,7 +32,8 @@ for the changes made most): version names for it: a party adds and takes off its nodes by itself ([`common-changes.md`](common-changes.md#what-a-party-does-by-itself)). * **`rules`**: in order, the first matching a path deciding who writes there - ([`writing-and-reading.md`](writing-and-reading.md), Places). + ([`writing-and-reading.md`](writing-and-reading.md), + [Places](writing-and-reading.md#places)). * **`checkpoint`**, only where the version moves the store to a checkpoint: the heads. Otherwise leave it out, though the current version names one: its heads are behind, and a version naming them again is never written. @@ -87,10 +89,10 @@ record before it sends the vote. It casts no vote that would make its party vote party backed is dead. The client fetches the votes that made it so from the node, and keeps them in the record beside the new `true`. -A party votes from one client, with one record: two clients backing two proposals at -once is voting twice, and shows ([`federation.md`](../../federation.md), Changing the -policy). A party whose node votes for it by itself votes by hand only through that -node, which keeps its one record: +A party votes from one client, with one record: two clients backing two proposals at once +is voting twice, and shows ([`federation.md`](../../federation.md), +[Changing the policy](../../federation.md#changing-the-policy)). A party whose node votes +for it by itself votes by hand only through that node, which keeps its one record: ```sh continuum-party --node http://tv:secret@localhost:3000 vote 8d02… yes --through @@ -152,7 +154,8 @@ continuum-party --node http://tv:secret@localhost:3000 proposals ``` A node's dashboard shows them so too, and where the node votes for its party by itself, -votes through it ([`dashboard.md`](../../dashboard.md), Federation). +votes through it ([`dashboard.md`](../../dashboard.md), +[Federation](../../dashboard.md#federation)). `GET /events/{id}` shows a proposing event, the version it proposes in `proposal`, and a vote, signed by its party. A node lacking some votes reads a proposal as neither passed diff --git a/docs/guides/federation/refusals-and-drops.md b/docs/guides/federation/refusals-and-drops.md index 09b0442..c4566e3 100644 --- a/docs/guides/federation/refusals-and-drops.md +++ b/docs/guides/federation/refusals-and-drops.md @@ -1,8 +1,10 @@ # Refusals and drops What a node refuses, what of that is its own, and how its operator has it drop what it -took and take it back. The rules are the store's ([`store.md`](../../store.md), A node's -own) and the federation's ([`federation.md`](../../federation.md), Changing the policy). +took and take it back. The rules are the store's ([`store.md`](../../store.md), +[A node's own](../../store.md#a-nodes-own)) and the federation's +([`federation.md`](../../federation.md), +[Changing the policy](../../federation.md#changing-the-policy)). ## What a node refuses @@ -67,5 +69,6 @@ as it reads its document again. It answers `204`. ## When to Dropping and taking back are how an operator chooses a side where keys voted twice -([`when-things-go-wrong.md`](when-things-go-wrong.md), Choosing a side), or keeps out an -event it won't hold: whatever it drops, it reads no more, while the others may. +([`when-things-go-wrong.md`](when-things-go-wrong.md), +[Choosing a side](when-things-go-wrong.md#choosing-a-side)), or keeps out an event it +won't hold: whatever it drops, it reads no more, while the others may. diff --git a/docs/guides/federation/remakes.md b/docs/guides/federation/remakes.md index ef60266..05c27ab 100644 --- a/docs/guides/federation/remakes.md +++ b/docs/guides/federation/remakes.md @@ -3,7 +3,8 @@ A remake moves a swarm to a new document, for Automerge's sake only: the store needs none, and its events stay what they are. A federated swarm takes compactions only. How a remake runs is as in any swarm ([`remakes.md`](../../remakes.md)); this guide says what is -otherwise. The rules are the store's ([`store.md`](../../store.md), Remakes). +otherwise. The rules are the store's ([`store.md`](../../store.md), +[Remakes](../../store.md#remakes)). ## Proposing one @@ -53,8 +54,8 @@ document, one its operator pins (`--store-checkpoint`), or, to an empty document root; and only one with its swarm's policy. A made-up epoch can withhold events from a node and keep it apart from the others, but make it take nothing it wouldn't. A node that can't follow the others' epoch, as its snapshot holds a checkpoint it can't build, -follows it once its operator pins that checkpoint -([`checkpoints.md`](checkpoints.md), Nodes that weren't there). +follows it once its operator pins that checkpoint ([`checkpoints.md`](checkpoints.md), +[Nodes that weren't there](checkpoints.md#nodes-that-werent-there)). ## Without remakes diff --git a/docs/guides/federation/running-a-node.md b/docs/guides/federation/running-a-node.md index b303fab..5d881d6 100644 --- a/docs/guides/federation/running-a-node.md +++ b/docs/guides/federation/running-a-node.md @@ -36,11 +36,11 @@ node refuses to start with them. ## Its files -Beside those of every node ([`lifecycle.md`](../../lifecycle.md), What the files are -for), the store file. Back up the node key, as every node's: its node ID is what its -party lists, and a new key is a new node, which the party lists anew. The document file -and the store file go together: the store file says what the node refuses of what the -document holds. +Beside those of every node ([`lifecycle.md`](../../lifecycle.md), +[What the files are for](../../lifecycle.md#what-the-files-are-for)), the store file. Back +up the node key, as every node's: its node ID is what its party lists, and a new key is a +new node, which the party lists anew. The document file and the store file go together: +the store file says what the node refuses of what the document holds. ## Who syncs diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md index 95dab12..570de19 100644 --- a/docs/guides/federation/upgrades.md +++ b/docs/guides/federation/upgrades.md @@ -1,17 +1,17 @@ # Upgrades and the federation's number Upgrading the continuum a federated swarm's nodes run, and what the federation's number -in each version says. The rules are the design's -([`federation.md`](../../federation.md), Changing the federation). +in each version says. The rules are the design's ([`federation.md`](../../federation.md), +[Changing the federation](../../federation.md#changing-the-federation)). ## Upgrading continuum A node of a federated swarm upgrades as any node does -([`operations.md`](../../operations.md), Upgrading): one at a time, restarted with its -files. Across a change of the wire format, upgraded nodes and the others don't talk, and -the swarm is split until all are upgraded; a remake needs the same Automerge on every -node, and one with another rejoins instead of switching. Until continuum's first release, -take every upgrade as such a change. +([`operations.md`](../../operations.md), [Upgrading](../../operations.md#upgrading)): one +at a time, restarted with its files. Across a change of the wire format, upgraded nodes +and the others don't talk, and the swarm is split until all are upgraded; a remake needs +the same Automerge on every node, and one with another rejoins instead of switching. Until +continuum's first release, take every upgrade as such a change. Nobody runs every node of a federated swarm: each party's operators upgrade its nodes. Agree on when, among the parties, and upgrade close together. diff --git a/docs/guides/federation/voting-by-itself.md b/docs/guides/federation/voting-by-itself.md index bf7a01e..300f60c 100644 --- a/docs/guides/federation/voting-by-itself.md +++ b/docs/guides/federation/voting-by-itself.md @@ -2,8 +2,8 @@ A party may have one of its nodes vote and propose for it, by rules its operator sets, written nowhere in the swarm: every node judges what such a node signs as any vote or -proposal. The rules are the design's ([`federation.md`](../../federation.md), Votes a -node casts by itself). +proposal. The rules are the design's ([`federation.md`](../../federation.md), +[Votes a node casts by itself](../../federation.md#votes-a-node-casts-by-itself)). ## Setting it up @@ -56,13 +56,13 @@ or `POST /admin/events/vote` with `{"proposal": "8d02…", "yes": true}`. ## What it keeps to What a party's client keeps to: one `true` at a time, never `true` and `false` on one -proposal, nothing on the version its record began on, and no `true` for a proposal that -is no version ([`proposing-and-voting.md`](proposing-and-voting.md), Voting). And, for a -version naming a checkpoint, the voters' rule: it backs one only where it changes nothing -of the current version but its number, what it changes and its checkpoint, and its heads -leave out nothing it held for a while before it was proposed -([`checkpoints.md`](checkpoints.md), Backing one). A vote by hand through it keeps to the -same. +proposal, nothing on the version its record began on, and no `true` for a proposal that is +no version ([`proposing-and-voting.md`](proposing-and-voting.md), +[Voting](proposing-and-voting.md#voting)). And, for a version naming a checkpoint, the +voters' rule: it backs one only where it changes nothing of the current version but its +number, what it changes and its checkpoint, and its heads leave out nothing it held for a +while before it was proposed ([`checkpoints.md`](checkpoints.md), +[Backing one](checkpoints.md#backing-one)). A vote by hand through it keeps to the same. It signs its votes on the events proposing what it votes on, and its checkpoint proposals on its heads, so that a version event may be written on them. diff --git a/docs/guides/federation/watching.md b/docs/guides/federation/watching.md index c04a6a3..f55005a 100644 --- a/docs/guides/federation/watching.md +++ b/docs/guides/federation/watching.md @@ -1,8 +1,9 @@ # What to watch What tells an operator, or a party, that a federated swarm needs them. Watch what every -node needs watching ([`operations.md`](../../operations.md), What to alert on), and -besides it, the node's store, through its API and its log. +node needs watching ([`operations.md`](../../operations.md), +[What to alert on](../../operations.md#what-to-alert-on)), and besides it, the node's +store, through its API and its log. ## Through the API @@ -10,8 +11,8 @@ besides it, the node's store, through its API and its log. twice, and nodes may be apart. Act on it at once ([`when-things-go-wrong.md`](when-things-go-wrong.md)). * **No store** (`404` from `GET /events` for longer than a start takes): the node can't - read its store ([`when-things-go-wrong.md`](when-things-go-wrong.md), A node doing less - than it should). + read its store ([`when-things-go-wrong.md`](when-things-go-wrong.md), + [A node doing less than it should](when-things-go-wrong.md#a-node-doing-less-than-it-should)). * **Proposals on the current version** (`proposals` in `GET /events/counts`): each with who voted what, and whether it passed or is dead; the party's record says what it voted. @@ -28,7 +29,7 @@ besides it, the node's store, through its API and its log. A node's dashboard (`/admin/dashboard`) shows the same in its document box, read every 5 s: the version, the parties and which of their nodes are members, the values, the proposals with who voted what and what each changes, and what the node refused -([`dashboard.md`](../../dashboard.md), Federation). +([`dashboard.md`](../../dashboard.md), [Federation](../../dashboard.md#federation)). ## In the log diff --git a/docs/guides/federation/when-things-go-wrong.md b/docs/guides/federation/when-things-go-wrong.md index de2e34a..c79f24f 100644 --- a/docs/guides/federation/when-things-go-wrong.md +++ b/docs/guides/federation/when-things-go-wrong.md @@ -2,8 +2,9 @@ What to do when a node reports a version it refused, when a party voted twice, and when a node doesn't do what it should. The rules are the design's -([`federation.md`](../../federation.md), Changing the policy; [`store.md`](../../store.md), -A node's own). +([`federation.md`](../../federation.md), +[Changing the policy](../../federation.md#changing-the-policy); +[`store.md`](../../store.md), [A node's own](../../store.md#a-nodes-own)). ## A node refused a version @@ -76,6 +77,7 @@ record. * **An event waits** (`waiting` when put): the node lacks an event it builds on. It takes it once that one arrives. * **It doesn't start**: its store file doesn't read, or an option of a swarm that isn't - federated is set ([`running-a-node.md`](running-a-node.md), Its options). -* **A write is refused**: [`writing-and-reading.md`](writing-and-reading.md), Why a write - is refused. + federated is set ([`running-a-node.md`](running-a-node.md), + [Its options](running-a-node.md#its-options)). +* **A write is refused**: [`writing-and-reading.md`](writing-and-reading.md), + [Why a write is refused](writing-and-reading.md#why-a-write-is-refused). diff --git a/docs/guides/federation/writing-and-reading.md b/docs/guides/federation/writing-and-reading.md index 0a04773..3dd0578 100644 --- a/docs/guides/federation/writing-and-reading.md +++ b/docs/guides/federation/writing-and-reading.md @@ -1,8 +1,9 @@ # Writing and reading A party writes values at places, through its client; anyone a node lets in reads what -counts there. The rules are the design's ([`federation.md`](../../federation.md), The -policy, What counts). +counts there. The rules are the design's ([`federation.md`](../../federation.md), +[The policy](../../federation.md#the-policy), +[What counts](../../federation.md#what-counts)). ## Places @@ -36,7 +37,7 @@ or `waiting` for an event it builds on that the node doesn't hold yet. A write counts while the key that signed it is among its party's keys: those of its key set, or, while it has written none, those its version names -([`federation.md`](../../federation.md), Keys). +([`federation.md`](../../federation.md), [Keys](../../federation.md#keys)). ## What counts diff --git a/docs/lifecycle.md b/docs/lifecycle.md index 3140fa8..47cf051 100644 --- a/docs/lifecycle.md +++ b/docs/lifecycle.md @@ -164,12 +164,13 @@ The normal phase. The node: Entered when enough active, ready members (two if this node was ready, one if it never was) advertise the same newer epoch, at most 1000 generations ahead: the node -missed a switch (it was away, or its own build didn't match). With several epochs of -the newest generation advertised (two remakes committed for one epoch; [`remakes.md`](remakes.md), -Limits), it follows the one most of them are on (of those, the lowest ID). A ready node -also rejoins **sideways**, to another epoch of its own generation, when more ready -members are on it than on its own (counting itself; two at least; on a tie, the lower -ID): its own writes on the epoch it leaves all go to quarantine (step 5). What happens: +missed a switch (it was away, or its own build didn't match). With several epochs of the +newest generation advertised (two remakes committed for one epoch; +[`remakes.md`](remakes.md), [Limits](remakes.md#limits)), it follows the one most of them +are on (of those, the lowest ID). A ready node also rejoins **sideways**, to another epoch +of its own generation, when more ready members are on it than on its own (counting itself; +two at least; on a tie, the lower ID): its own writes on the epoch it leaves all go to +quarantine (step 5). What happens: 1. at once (under the document's lock), the node swaps in an empty document labelled with the target epoch, which takes no writes; sync with every peer resets; and a diff --git a/docs/operations.md b/docs/operations.md index 6aa06c2..e1b8e79 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -14,10 +14,11 @@ Settle on these, as they are hard to change later: The node key is the node: a new one is a new member. * **A state file and a document file per node** (`--state-file`, `--document-file`). With them a node restarts on its swarm, with its data, ready at once; without them it - starts empty and has to join again ([`lifecycle.md`](lifecycle.md), What the files are for). + starts empty and has to join again ([`lifecycle.md`](lifecycle.md), + [What the files are for](lifecycle.md#what-the-files-are-for)). * **The transports' keys** (`--mycelium-key-file`, `--libp2p-key-file`, `--tor-state-dir`), so a node's addresses stay the same across restarts - ([`transports.md`](transports.md), Keys). + ([`transports.md`](transports.md), [Keys](transports.md#keys)). * **A supervisor** that restarts the node: it stops when a transport stops (`A transport stopped`). @@ -39,9 +40,9 @@ again, so stop it first. A node stopped but not forgotten stays a member: it is probed now and then, and it counts in the electorate of remakes until its alive stamp is older than -`--electorate-window` (7 days by default; [`remakes.md`](remakes.md), Electorate and majority). -Several of them can keep a remake from reaching a majority: forget those that won't -come back. +`--electorate-window` (7 days by default; [`remakes.md`](remakes.md), +[Electorate and majority](remakes.md#electorate-and-majority)). Several of them can keep a +remake from reaching a majority: forget those that won't come back. ## Keys @@ -70,8 +71,10 @@ but it is being written: export instead. To restore: -* **into a running swarm**: an `import` remake with the backup ([`remakes.md`](remakes.md), Import - and restoring a backup), which replaces the content for everyone; +* **into a running swarm**: an `import` remake with the backup + ([`remakes.md`](remakes.md), + [Import and restoring a backup](remakes.md#import-and-restoring-a-backup)), which + replaces the content for everyone; * **a swarm that is gone**: one node with `--recover-from FILE` (ready at once, on the backup's swarm and epoch), the others joining it; * **its content as a new swarm**: `--genesis --remake import:FILE`. @@ -84,8 +87,9 @@ memory only, and aren't in any backup. Nodes with document files are ready at once on restart and merge with each other. If none has its data any more, they all join and wait for each other, and none becomes ready: start one with `--recover-from` and a backup, or with `--genesis` (with its state -file: the same swarm again, empty), and the others join it ([`lifecycle.md`](lifecycle.md), A whole -swarm restarting). +file: the same swarm again, empty), and the others join it +([`lifecycle.md`](lifecycle.md), +[A whole swarm restarting](lifecycle.md#a-whole-swarm-restarting)). ## Upgrading @@ -100,15 +104,16 @@ One node at a time, restarting each with its files. What to know: every upgrade is such a change, and upgrade all nodes close together. * **Automerge.** A remake needs every node to build the same snapshot, byte for byte, so the same Automerge version everywhere; a node with another one rejoins instead of - switching ([`remakes.md`](remakes.md), Limits). Don't remake while the swarm runs two versions. + switching ([`remakes.md`](remakes.md), [Limits](remakes.md#limits)). Don't remake while + the swarm runs two versions. * **The dashboard** reloads by itself once its node serves another version of it. ## Behind a reverse proxy The HTTP API speaks plain HTTP on `127.0.0.1:3000`; a reverse proxy in front adds TLS. -Let the node check who users are, as it does: its `--htpasswd`, and the tokens of -logging in on any node of the swarm ([`access.md`](access.md), Tokens). The proxy then only -passes requests on, their `Authorization` header with them: +Let the node check who users are, as it does: its `--htpasswd`, and the tokens of logging +in on any node of the swarm ([`access.md`](access.md), [Tokens](access.md#tokens)). The +proxy then only passes requests on, their `Authorization` header with them: ```sh continuum --bind-addr unix:/run/continuum/api.sock --htpasswd htpasswd ... @@ -219,7 +224,7 @@ From the metrics (`GET /admin/stats` as Prometheus, [`measurements.md`](measurem | Metric | Alert when | Means | |---|---|---| | `continuum_ready` | 0 for longer than a join takes | the node can't join or rejoin (its log says why) | -| `continuum_clock_off` | 1 | its clock is off from its peers' ([`trust.md`](trust.md), What depends on clocks) | +| `continuum_clock_off` | 1 | its clock is off from its peers' ([`trust.md`](trust.md), [What depends on clocks](trust.md#what-depends-on-clocks)) | | `continuum_remakes_committed` | above 1 | a double commit; no node switches on its own | | `continuum_quarantined` | above 0 | writes set aside by a rejoin, lost at the next restart | | `continuum_catch_up_attempts` | growing | the node can't get the epoch its peers advertise | @@ -230,11 +235,12 @@ And from the log, at warn or error: * `A transport stopped`: the node stops; * `Still joining the swarm; trying on`: with why (seeds unresolved, peers' states); -* `Several remakes committed for this epoch; not switching on my own`, `Decisions on - this remake disagree; not switching on my own`, `Peers disagree about the newest - epoch; following the one most of them are on`, `More peers are on another epoch of - this generation than on ours`: two remakes committed for one epoch; look at the - quarantines that follow ([`remakes.md`](remakes.md), Troubleshooting); +* `Several remakes committed for this epoch; not switching on my own`, + `Decisions on this remake disagree; not switching on my own`, + `Peers disagree about the newest epoch; following the one most of them are on`, + `More peers are on another epoch of this generation than on ours`: two remakes committed + for one epoch; look at the quarantines that follow ([`remakes.md`](remakes.md), + [Troubleshooting](remakes.md#troubleshooting)); * `Quarantined writes the remake has no place for`; * `Couldn't write the state file`, `Couldn't rewrite the document file`: a full or read-only disk; @@ -251,7 +257,8 @@ And from the log, at warn or error: * **Disk**: the document file, between the full save and that plus what was appended since its last rewrite (`--document-rewrite`); the state file (small); Tor's state directory. -* **Network**: per neighbour, about two keepalives per `--keepalive` interval when - quiet ([`measurements.md`](measurements.md), Traffic), plus sync for every write; a joining node downloads the document once (`savedBytes`, about). +* **Network**: per neighbour, about two keepalives per `--keepalive` interval when quiet + ([`measurements.md`](measurements.md), [Traffic](measurements.md#traffic)), plus sync + for every write; a joining node downloads the document once (`savedBytes`, about). * **Processes and ports**: the HTTP API (`--bind-addr`); a supervised Mycelium daemon and its overlay port; libp2p's listen addresses. diff --git a/docs/peers.md b/docs/peers.md index f5b6ab6..e71d726 100644 --- a/docs/peers.md +++ b/docs/peers.md @@ -13,18 +13,19 @@ says where it is (`mycelium:<public key>`). The identity layer (`transport::iden between the node and its transports keeps the two apart, so everything below speaks of node IDs. A node may have several transports, and reaches a peer on one both have (module `transport::paths`). With several, it measures them: every 30 s (or every -keepalive interval, if that is longer) each gets a PING (the keepalive's, or one of its own), answered by a PONG over the same path, which -gives its round-trip time. A peer's only path is measured the same way once messages -go over it (a busy pair sends no keepalives). The -configured order decides until both are measured; then the node changes to another -path when it is a quarter faster (and at least 5 ms), so it doesn't flap. A send that -fails goes to the next path at once, and a path whose sends fail, or whose PINGs go -unanswered three times in a row, is down: used only when no other works. A path that +keepalive interval, if that is longer) each gets a PING (the keepalive's, or one of its +own), answered by a PONG over the same path, which gives its round-trip time. A peer's +only path is measured the same way once messages go over it (a busy pair sends no +keepalives). The configured order decides until both are measured; then the node changes +to another path when it is a quarter faster (and at least 5 ms), so it doesn't flap. A +send that fails goes to the next path at once, and a path whose sends fail, or whose PINGs +go unanswered three times in a row, is down: used only when no other works. A path that takes messages and drops them shows sooner: when what went to the peer goes unanswered -(the PING that asks again, below, or an overdue sync answer), its other paths come -first until that one answers a PING again, and all of them are pinged at once. A node on -several transports bridges nodes that share none ([`transports.md`](transports.md), Several transports): -the topology links it on each of its transports (below). +(the PING that asks again, below, or an overdue sync answer), its other paths come first +until that one answers a PING again, and all of them are pinged at once. A node on several +transports bridges nodes that share none ([`transports.md`](transports.md), +[Several transports](transports.md#several-transports)): the topology links it on each of +its transports (below). ```mermaid sequenceDiagram diff --git a/docs/remakes.md b/docs/remakes.md index 94d50dc..5156905 100644 --- a/docs/remakes.md +++ b/docs/remakes.md @@ -9,9 +9,9 @@ A remake moves the whole swarm to a new document, the next *epoch*. Use one to: * **import** (`import`): new content from an Automerge document, e.g. a backup made with `GET /admin/document`. Unlike `replace`, Automerge types survive (text, counters, bytes, timestamps, floats). -* **strict** (`strict`): the same as `compact`, turning the swarm strict, keeping only - the signed values an operator's manifest names ([`access.md`](access.md), Turning a - swarm strict). +* **strict** (`strict`): the same as `compact`, turning the swarm strict, keeping only the + signed values an operator's manifest names ([`access.md`](access.md), + [Turning a swarm strict](access.md#turning-a-swarm-strict)). Everything else is the same for all the kinds. All endpoints need the node's basic auth; examples leave it out. @@ -115,11 +115,11 @@ Answers: * `409` if another remake of this epoch is still open on this node's view, if an expired one still holds votes (unless `?force=supersede`), or if this node can't vote for a new one (it voted for another remake of this epoch, or may have before it - restarted), or if this node's clock is off from most of its peers' ([`measurements.md`](measurements.md), - Clocks): the coordinator stamps and judges the deadlines by it (unless - `?force=clock`); or, as for every write a user asks for, if this node doesn't know - the swarm's policy ([`access.md`](access.md)): the proposal is written as the user who - asks. + restarted), or if this node's clock is off from most of its peers' + ([`measurements.md`](measurements.md), [Clocks](measurements.md#clocks)): the + coordinator stamps and judges the deadlines by it (unless `?force=clock`); or, as for + every write a user asks for, if this node doesn't know the swarm's policy + ([`access.md`](access.md)): the proposal is written as the user who asks. * `400` for an invalid request; `503` if the node isn't ready. Dropping the HTTP connection doesn't abort the remake. @@ -254,9 +254,10 @@ aborts it itself, under three conditions that keep it from crossing a late commi * if the node you ask sees the coordinator as an active peer, the coordinator is stuck rather than gone (a different version, a bug: look at its log). Aborting then needs `?force=coordinatorActive`; -* the node you ask must have its clock in line with its peers' ([`measurements.md`](measurements.md), - Clocks): whether the remake expired is judged by it, and a node ahead would abort a - remake its coordinator may still commit. Otherwise `409`, unless `?force=clock`. +* the node you ask must have its clock in line with its peers' + ([`measurements.md`](measurements.md), [Clocks](measurements.md#clocks)): whether the + remake expired is judged by it, and a node ahead would abort a remake its coordinator + may still commit. Otherwise `409`, unless `?force=clock`. The abort is written as the user who asks, who may write remakes: with a policy ([`access.md`](access.md)), the other nodes take a decision from the coordinator or @@ -350,8 +351,8 @@ The swarm stays writable throughout. A rejoining node answers reads from its old document, marked with the `x-continuum-stale` header, and writes go into it; they are carried over into the new -epoch when the rejoin ends, like the node's writes from before ([`lifecycle.md`](lifecycle.md), -Rejoining). +epoch when the rejoin ends, like the node's writes from before +([`lifecycle.md`](lifecycle.md), [Rejoining](lifecycle.md#rejoining)). ## Quarantine @@ -396,7 +397,8 @@ remake report's `local.quarantine` on that node names the entry. the other epoch of that generation rejoin it sideways once they see themselves outnumbered (`More peers are on another epoch of this generation than on ours`, warn), and what was written there goes to quarantine ([`lifecycle.md`](lifecycle.md), - Rejoining). Look at those quarantines; report how it came about ([Limits](#limits)). + [Rejoining](lifecycle.md#rejoining)). Look at those quarantines; report how it came + about ([Limits](#limits)). * **Repairing records by hand.** Remake records live in the document under `_continuum/remakes/<id>`. Old ones need no cleaning up: an epoch's document holds the remakes proposed in it and the record of the remake that made it, and earlier @@ -409,10 +411,12 @@ remake report's `local.quarantine` on that node names the entry. ## Limits -* **Clocks.** Voting periods, expiry and the replay window are judged by each node's - own clock ([`trust.md`](trust.md), What depends on clocks). With clocks further apart than the - grace period (four of the coordinator's keepalives), a remake aborted from another node after expiry - could also have been committed by its coordinator: a contested remake. +* **Clocks.** Voting periods, expiry and the replay window are judged by each node's own + clock ([`trust.md`](trust.md), + [What depends on clocks](trust.md#what-depends-on-clocks)). With clocks further apart + than the grace period (four of the coordinator's keepalives), a remake aborted from + another node after expiry could also have been committed by its coordinator: a contested + remake. * **Document size.** Large transfers go in chunks (`--blob-chunk`, default 64KiB) from up to four peers at once: the new document of a `replace`/`import` remake (it diff --git a/docs/store.md b/docs/store.md index f7f053b..02dc896 100644 --- a/docs/store.md +++ b/docs/store.md @@ -1,25 +1,25 @@ # The store: a design -A design, built stage by stage ([`federation.md`](federation.md), Stages): so far, the -store held in memory (`federation::store`), with a fold made for its tests and the -federation's (`federation::fold`); and on Automerge, a swarm holding a store, started -from its root or joined by its ID (`document::events`), each change judged by what it -writes (`access::holding`), and the store a node reads from its document, by what is its -own, putting again what the document lacks, from a checkpoint its operator pins if it -pins one (`federation::held`); and members by the fold, each node of the party its -operator names, syncing with members only, its neighbours among them, some among its own -party's and those its operator names, and taking no token another node issued; and the -store at a node's API (`api::events`), putting events and showing what counts, what it -refused, and its operator's drops. Not yet: remakes, of which a swarm holding a store -takes no records or acks. The store holds events. Each event is named by the hash of its -bytes and names the events it builds on; it is judged where it was written, at that -history, so every node judges it alike; and the events a node holds read as one state. -The store starts from a checkpoint, the state at some heads written down, and holds what -came after it; moving to a later checkpoint, a node forgets what matters no more, so -that it holds what is relevant and nothing else. What the events are, how one is judged, -what they read as and when the store moves to a checkpoint is a **fold**'s, and the -store is generic over it. The federation ([`federation.md`](federation.md)) is its first -fold. +A design, built stage by stage ([`federation.md`](federation.md), +[Stages](federation.md#stages)): so far, the store held in memory (`federation::store`), +with a fold made for its tests and the federation's (`federation::fold`); and on +Automerge, a swarm holding a store, started from its root or joined by its ID +(`document::events`), each change judged by what it writes (`access::holding`), and the +store a node reads from its document, by what is its own, putting again what the document +lacks, from a checkpoint its operator pins if it pins one (`federation::held`); and +members by the fold, each node of the party its operator names, syncing with members only, +its neighbours among them, some among its own party's and those its operator names, and +taking no token another node issued; and the store at a node's API (`api::events`), +putting events and showing what counts, what it refused, and its operator's drops. Not +yet: remakes, of which a swarm holding a store takes no records or acks. The store holds +events. Each event is named by the hash of its bytes and names the events it builds on; it +is judged where it was written, at that history, so every node judges it alike; and the +events a node holds read as one state. The store starts from a checkpoint, the state at +some heads written down, and holds what came after it; moving to a later checkpoint, a +node forgets what matters no more, so that it holds what is relevant and nothing else. +What the events are, how one is judged, what they read as and when the store moves to a +checkpoint is a **fold**'s, and the store is generic over it. The federation +([`federation.md`](federation.md)) is its first fold. The store asks nothing of what carries its events. It is built first inside a swarm's Automerge document ([On Automerge](#on-automerge)): continuum's sync, transports, saving @@ -89,8 +89,9 @@ joining starts from a checkpoint its operator pins; only for a store that never the root its operator names, the swarm's ID, suffice. Once a store moved, what came before its checkpoint can be grown anew from the root by what the fold refuses since (the federation: keys of versions long replaced, [`federation.md`](federation.md), -Checkpoints), and a node joining from the root would take it. So a node takes nothing on a -peer's word: what it didn't build or judge itself, its operator vouched for. +[Checkpoints](federation.md#checkpoints)), and a node joining from the root would take it. +So a node takes nothing on a peer's word: what it didn't build or judge itself, its +operator vouched for. ## The fold @@ -184,16 +185,16 @@ store stays fast. A fold may have a node refuse an event its history takes, by what the node took before: the federation's node takes a version only where it changes the one the node reads, and -moves to a checkpoint as it takes a version naming one -([`federation.md`](federation.md), Changing the policy, Checkpoints). And an operator -may have its node **drop** events it took after its checkpoint; not what the checkpoint -keeps or holds by ID, as every event after it builds on that. A node undoes a move only -by taking a checkpoint its operator pins. Either way the node refuses the event and -everything built on it, from whoever brings it, until its operator says otherwise, and -reports it; it keeps what it refuses so, and its operator's drops, in a file of its own, -across restarts. No peer's word moves a node; its operator's does. A node that refuses -what another took holds other events, and reads its own state from them; two that hold -the same read the same. +moves to a checkpoint as it takes a version naming one ([`federation.md`](federation.md), +[Changing the policy](federation.md#changing-the-policy), +[Checkpoints](federation.md#checkpoints)). And an operator may have its node **drop** +events it took after its checkpoint; not what the checkpoint keeps or holds by ID, as +every event after it builds on that. A node undoes a move only by taking a checkpoint its +operator pins. Either way the node refuses the event and everything built on it, from +whoever brings it, until its operator says otherwise, and reports it; it keeps what it +refuses so, and its operator's drops, in a file of its own, across restarts. No peer's +word moves a node; its operator's does. A node that refuses what another took holds other +events, and reads its own state from them; two that hold the same read the same. ## Forks @@ -206,7 +207,7 @@ those heads, the fork never takes; nor do they take what the fork takes, as no s takes another's root, nor anything built on it. A node's own refusals are its store's. What a fork's root holds, and who makes one, is its fold's: the federation builds one byte for byte from its version and its heads, so that one version and one set of heads -make one fork ([`federation.md`](federation.md), Forks). +make one fork ([`federation.md`](federation.md), [Forks](federation.md#forks)). ## On Automerge @@ -261,9 +262,10 @@ of all one Automerge itself writes ([Where Automerge sets limits](#where-automerge-sets-limits)). Every node judges a change by these alone, each a question of the change and its history, and refuses it with everything built on it, as continuum refuses a change its rules refuse -([`access.md`](access.md), Changes judged on every node). It judges no event there: which -events it takes is its store's (below). The same event put by two changes at once is one -event: its key holds the same bytes twice. +([`access.md`](access.md), +[Changes judged on every node](access.md#changes-judged-on-every-node)). It judges no +event there: which events it takes is its store's (below). The same event put by two +changes at once is one event: its key holds the same bytes twice. ### What the store takes from the document @@ -395,8 +397,9 @@ documents stay together. ## Attacks What an attacker does to the store on Automerge, and what happens; a fold's own attacks -are in its design ([`federation.md`](federation.md), Attacks). *Unit*: the judging, with -crafted changes. *Sim*: a simulation. *Bench*: measured, not judged. +are in its design ([`federation.md`](federation.md), [Attacks](federation.md#attacks)). +*Unit*: the judging, with crafted changes. *Sim*: a simulation. *Bench*: measured, not +judged. | # | Attack | What happens | Test | |---|---|---|---| diff --git a/docs/transports.md b/docs/transports.md index 8fb81d3..a8f914e 100644 --- a/docs/transports.md +++ b/docs/transports.md @@ -1,11 +1,11 @@ # Transports -How nodes reach each other. A node is its node ID, from its node key; a transport -only says where it is ([`peers.md`](peers.md), node IDs and addresses). Continuum has three -transports, each a cargo feature (`--features mycelium,libp2p,tor`), any of them at -once. Which a node uses is `--<transport>-enable`, and in which order -`--transport-order` ([`configuration.md`](configuration.md), Transports); the options below are each -transport's. +How nodes reach each other. A node is its node ID, from its node key; a transport only +says where it is ([`peers.md`](peers.md), node IDs and addresses). Continuum has three +transports, each a cargo feature (`--features mycelium,libp2p,tor`), any of them at once. +Which a node uses is `--<transport>-enable`, and in which order `--transport-order` +([`configuration.md`](configuration.md), [Transports](configuration.md#transports)); the +options below are each transport's. | | Mycelium | libp2p | Tor | |---|---|---|---| @@ -163,14 +163,14 @@ that fails, the relay carries the traffic. Hole punching needs both to listen, t the firewall may stay closed (`/ip6/::/udp/0/quic-v1`: QUIC sends from where it listens). Each offers where the relay saw it and where it listens, so nodes on one LAN meet there, rather than at their router's public address. A punch that fails is tried -again after a minute, then after 5, then every 30 minutes, while the peers stay -connected through the relay: what failed may have been passing. A relay takes at most 1024 circuits (64 per -peer), each for up to an hour and 1 GiB, and doesn't limit how often they're asked for; a circuit that ends is made again on the next -message. Only relays of the swarm are used, unless the node is told to use public -infrastructure (below). How it goes (AutoNAT's verdict, connections direct or relayed, -relay slots, hole punches, failed dials) is in `/admin/stats` under -`transports.libp2p`, and each peer's connection in `/peers` ([`measurements.md`](measurements.md), -Transports). +again after a minute, then after 5, then every 30 minutes, while the peers stay connected +through the relay: what failed may have been passing. A relay takes at most 1024 circuits +(64 per peer), each for up to an hour and 1 GiB, and doesn't limit how often they're asked +for; a circuit that ends is made again on the next message. Only relays of the swarm are +used, unless the node is told to use public infrastructure (below). How it goes (AutoNAT's +verdict, connections direct or relayed, relay slots, hole punches, failed dials) is in +`/admin/stats` under `transports.libp2p`, and each peer's connection in `/peers` +([`measurements.md`](measurements.md), [Transports](measurements.md#transports)). ### Address ranges @@ -293,4 +293,5 @@ Tor's onion service key is in `--tor-state-dir`, made by arti. ## Figures -How the transports find and reach peers: [`measurements.md`](measurements.md), Transports. +How the transports find and reach peers: [`measurements.md`](measurements.md), +[Transports](measurements.md#transports). diff --git a/docs/trust.md b/docs/trust.md index 72a238d..fda0703 100644 --- a/docs/trust.md +++ b/docs/trust.md @@ -36,19 +36,21 @@ it creates is). **The HTTP API.** Every endpoint but the API description, the login page (`/login`) and logging in by key needs a user from `--htpasswd`, one a reverse proxy names (`--user-header`), or a token a node of the swarm issued to one of those or to a user -signing a challenge with one of its keys ([`access.md`](access.md), Tokens), sent as a -header or as the browser session's cookie: the node believes the proxy's -header from `--trusted-proxies` alone, but from those blindly, so whoever can send -requests from there can be any user. With the default loopback addresses, that is every -user of the host; with only the API's Unix socket (`--trusted-proxies unix`), those its -file's permissions let in: the node's user and group ([`operations.md`](operations.md), Behind a -reverse proxy). It listens on `127.0.0.1:3000` by default (`--bind-addr`) and speaks -plain HTTP: to expose it, put a TLS proxy in front. What each user may do is the -swarm's: its user registry, in the document, gives each capabilities by path, to read -and to write, protocol data apart ([`access.md`](access.md)); a user the registry doesn't have -may do nothing. In a swarm without a registry (started without one), all users may read -and write user data and use the admin endpoints, and only those in `--protocol-writers` -write protocol data. Epoch metadata and the swarm ID are never writable. The `/debug` endpoints exist only with +signing a challenge with one of its keys ([`access.md`](access.md), +[Tokens](access.md#tokens)), sent as a header or as the browser session's cookie: the node +believes the proxy's header from `--trusted-proxies` alone, but from those blindly, so +whoever can send requests from there can be any user. With the default loopback addresses, +that is every user of the host; with only the API's Unix socket +(`--trusted-proxies unix`), those its file's permissions let in: the node's user and group +([`operations.md`](operations.md), +[Behind a reverse proxy](operations.md#behind-a-reverse-proxy)). It listens on +`127.0.0.1:3000` by default (`--bind-addr`) and speaks plain HTTP: to expose it, put a TLS +proxy in front. What each user may do is the swarm's: its user registry, in the document, +gives each capabilities by path, to read and to write, protocol data apart +([`access.md`](access.md)); a user the registry doesn't have may do nothing. In a swarm +without a registry (started without one), all users may read and write user data and use +the admin endpoints, and only those in `--protocol-writers` write protocol data. Epoch +metadata and the swarm ID are never writable. The `/debug` endpoints exist only with `--debug-api`. **The configuration.** Whoever can write a node's configuration file or its options can @@ -65,13 +67,13 @@ three steps, each adding to the one before ([`access.md`](access.md)). on what the document says: * **User data**: any member can write or delete any path. -* **Who wrote what** (`GET /admin/changes`): each change names its node and API user - as the writing node says. Nodes sign their changes ([`api.md`](api.md), Signed - changes), so a change a signature vouches for shows `verified`: its node made it. One - that shows unverified may yet be vouched for by its node's next signature, or may be - another member's claiming that node. The user a change names is its node's claim, - signed or not. The names of the users who write are in the document, and so on every - node. +* **Who wrote what** (`GET /admin/changes`): each change names its node and API user as + the writing node says. Nodes sign their changes ([`api.md`](api.md), + [Signed changes](api.md#signed-changes)), so a change a signature vouches for shows + `verified`: its node made it. One that shows unverified may yet be vouched for by its + node's next signature, or may be another member's claiming that node. The user a change + names is its node's claim, signed or not. The names of the users who write are in the + document, and so on every node. * **The member registry, the user registry, forget records, remakes and votes**: the API lets only users given protocol data write them, but a member can write anything into its own document, and every node acts on it: the topology, the electorate, who @@ -131,9 +133,10 @@ where it matters, for the rest. Nodes don't agree on time; each judges by its own clock: voting periods, when a remake expires and may be aborted by others, the replay window, alive stamps (and so the electorate). Keep the clocks within a grace period (four keepalives) of each other, -e.g. with NTP. A node whose clock is further off can, together with an operator's -abort, make a remake contested ([`remakes.md`](remakes.md), Limits). A node compares its clock with its -peers' and warns when its own is off (`--clock-skew-warn`; [`measurements.md`](measurements.md), Clocks). +e.g. with NTP. A node whose clock is further off can, together with an operator's abort, +make a remake contested ([`remakes.md`](remakes.md), [Limits](remakes.md#limits)). A node +compares its clock with its peers' and warns when its own is off (`--clock-skew-warn`; +[`measurements.md`](measurements.md), [Clocks](measurements.md#clocks)). ## What a stranger can do |
