diff options
| author | tv <tv@krebsco.de> | 2026-11-17 13:50:58 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-17 15:04:35 +0100 |
| commit | 6ceaa7d464650ddef79870a94ad6e121f2955763 (patch) | |
| tree | 4ced5372a72754d3e15fa08fda97d384f3d86798 | |
| parent | a9d8da21897817206abd1e750395c88a7d103deb (diff) | |
guides: remakes under a federation
Compactions only, the electorate among the store's members, the snapshot holding the
store read at the base, what a node puts again after a switch, the lower of two epochs,
which epochs a node rejoins, and a swarm that never remakes.
| -rw-r--r-- | docs/guides/federation/README.md | 2 | ||||
| -rw-r--r-- | docs/guides/federation/remakes.md | 62 |
2 files changed, 64 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index 80d2a22..eb142e0 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -28,3 +28,5 @@ by them, in its words. by its operator's rules: its key, its record, following, proposing checkpoints. * [`refusals-and-drops.md`](refusals-and-drops.md): what a node refuses and what of it is its own, the store file, dropping events and taking them back. +* [`remakes.md`](remakes.md): compactions only, the electorate, the snapshot, putting + again after a switch, two epochs for one, and rejoining. diff --git a/docs/guides/federation/remakes.md b/docs/guides/federation/remakes.md new file mode 100644 index 0000000..ef60266 --- /dev/null +++ b/docs/guides/federation/remakes.md @@ -0,0 +1,62 @@ +# Remakes under a federation + +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). + +## Proposing one + +```sh +curl -u tv:secret -X POST -H 'Content-Type: application/json' \ + --data '{"kind": "compact"}' localhost:3000/admin/remakes +``` + +Any other kind is refused (`400`: `a swarm holding a store takes compactions only`). +Every user a node lets in may propose one there. The electorate is the members whose +alive stamp is recent, as in any swarm, but only those the store names as members, with +the party their entries name: another node's entry counts for nothing. The acks tell an +honest coordinator when to commit, and bind nobody. + +## The snapshot + +Every node builds the snapshot itself, from the base it holds: the store as it reads the +document up to the base, from the document's checkpoint, by its own refusals and drops. +It holds the checkpoint the store reached there (where it isn't the root) at +`_continuum/checkpoint`, the events that checkpoint keeps and those after it, and of +continuum's protocol data what a compaction carries, but the entries of nodes that +aren't members. What that checkpoint forgot, and events nobody takes, leave the +document here. A node reading its store anew starts at the document's checkpoint. + +Nodes that read the store differently at the base, the sides of keys that voted twice, +build different snapshots, and part here. + +## After the switch + +A node puts again what the new document lacks: what it holds beyond the base, and, where +it moved to a later checkpoint since the base, what the old document holds that the new +one's store needs to reach that checkpoint (`Of the document left, events to put again`, +`Put again events the document lacked`). It replays no events: they are put again as they +were. + +## Two epochs for one + +Of two epochs decided for one, by a coordinator that wrote two decisions or by remakes +decided at once, a node follows the one with the lower ID, and a node on the other +rejoins it. + +## Rejoining + +A node that was away, lacks the base, or is on the higher of two epochs rejoins, but only +an epoch whose snapshot holds its document's checkpoint, one it builds from that +document, one its operator pins (`--store-checkpoint`), or, to an empty document, the +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). + +## Without remakes + +A swarm that never remakes holds what one that remakes all the time holds; its document +only grows. Nothing in the federation waits on a remake. |
