aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation
diff options
context:
space:
mode:
Diffstat (limited to 'docs/guides/federation')
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/remakes.md62
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.