aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-18 18:49:50 +0000
committertv <tv@krebsco.de>2026-11-18 20:29:41 +0100
commitc64fcc05d8c53bee99ab039bd709039afb730cdd (patch)
tree45baad78d7b92de42283be2954fc3f9b4dd6129d /docs/guides/federation
parent598366b03679eac9d04f32d9194f3ba4ba9c3da8 (diff)
federation: a node stops at a version it doesn't read
A version event writing a proposal passed on the version a node reads, which doesn't read as a version there (of a later federation, using what a later continuum takes, or none at all), the node can't judge: `Fold::stops`. The store stops at it: it takes nothing and refuses nothing from then on, holding back whatever comes, that event first (`Offered::Stopped`), and keeps none of it across a restart, where it stops there again. One beside the version the node reads is refused of its own, as any other. Its operator has it drop that event (`POST /admin/events/drop`), or one it builds on: it is refused as dropped, or as built on what was, any version event writing that version with it, kept in the store file; the node judges what it held back and goes on under the version before. Allowed again, it stops there once more. The node logs the stop and its end; `GET /events` names the event, why, and how many it holds back (`stopped`); a put answers `stopped`, written into the document all the same; a node voting by itself casts nothing while stopped. The test fold's eras tagged `new` stop a store. Row 39 is tested (`federation_attack_39`); of rows 9, 10 and 48, a node stops at the version event.
Diffstat (limited to 'docs/guides/federation')
-rw-r--r--docs/guides/federation/proposing-and-voting.md5
-rw-r--r--docs/guides/federation/refusals-and-drops.md8
-rw-r--r--docs/guides/federation/upgrades.md11
-rw-r--r--docs/guides/federation/watching.md8
-rw-r--r--docs/guides/federation/when-things-go-wrong.md34
-rw-r--r--docs/guides/federation/writing-and-reading.md5
6 files changed, 59 insertions, 12 deletions
diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md
index e656083..12f8dfd 100644
--- a/docs/guides/federation/proposing-and-voting.md
+++ b/docs/guides/federation/proposing-and-voting.md
@@ -42,7 +42,10 @@ Party names are 1 to 64 of `A-Z a-z 0-9 . _ @ -`; a party has up to 16 keys and
nodes; a rule's path is a path as a write's is, its first segment literal and not
`_continuum`, `**` last only, `{party}` once at most, and its writer a party of the
version, `"{party}"` where the path holds it, or `false`. A version breaking any of that
-is none: it can't pass, and a party's client backs none.
+is none, and a party's client backs none; where two thirds pass it all the same, nodes
+stop at the version event writing it, until their operators have them drop it
+([`when-things-go-wrong.md`](when-things-go-wrong.md),
+[A node stopped](when-things-go-wrong.md#a-node-stopped)).
## Proposing
diff --git a/docs/guides/federation/refusals-and-drops.md b/docs/guides/federation/refusals-and-drops.md
index b32a819..1d29df1 100644
--- a/docs/guides/federation/refusals-and-drops.md
+++ b/docs/guides/federation/refusals-and-drops.md
@@ -40,8 +40,9 @@ file`).
## Dropping
-An operator may have the node drop events it took after its checkpoint, with everything
-built on them:
+An operator may have the node drop events it took after its checkpoint, or the version
+event it stopped at ([`when-things-go-wrong.md`](when-things-go-wrong.md),
+[A node stopped](when-things-go-wrong.md#a-node-stopped)), with everything built on them:
```sh
curl -u tv:secret -X POST -H 'Content-Type: application/json' \
@@ -50,7 +51,8 @@ curl -u tv:secret -X POST -H 'Content-Type: application/json' \
```
It answers what it dropped, in the order taken: those named, version events naming the
-version one of them names, and what is built on them. From then on the node refuses those
+version one of them names, and what is built on them; then the event it stopped at, if
+named, after which it takes again. From then on the node refuses those
events from whoever brings them, and any version event naming a version among them,
whoever wrote it anew; it writes none itself, though it holds the votes passing it, and
keeps so across restarts. Not what its checkpoint keeps
diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md
index 570de19..f91143f 100644
--- a/docs/guides/federation/upgrades.md
+++ b/docs/guides/federation/upgrades.md
@@ -26,8 +26,11 @@ the snapshot, and the Automerge version, whose encoding fixes a change's hash. T
bytes are fixed by vectors that the tests check (`federation::vectors`).
There is one federation, 1. A node knows it alone: a version naming another is none to
-it, refused where a version event names it, with everything built on it. A proposal
-naming another is taken as a proposal, and a party's client backs none.
+it. Where one passes, the node stops at the version event writing it, taking nothing and
+refusing nothing, until it runs a continuum that knows it, or its operator has it drop
+that event ([`when-things-go-wrong.md`](when-things-go-wrong.md),
+[A node stopped](when-things-go-wrong.md#a-node-stopped)). A proposal naming another is
+taken as a proposal, and a party's client backs none.
A change to any of that is a federation of its own, with the next number, and its own
design. A swarm moves to it by a version naming it, which the parties pass once their
@@ -37,5 +40,5 @@ A change that only has the federation take what it refused, and reads nothing it
otherwise, keeps the number: `ecdsa-sha2-nistp256` keys beside Ed25519 ones. Roll it out
first, then use it: every party's operators upgrade their nodes, and only then does a
party name such a key in a version or a key set, or sign with one. A node not upgraded
-refuses what uses it and reads otherwise than the others: a version naming such a key is
-none to it, and it stays on the version before.
+refuses what uses it and reads otherwise than the others; at a version naming such a key,
+none to it, it stops, until it is upgraded.
diff --git a/docs/guides/federation/watching.md b/docs/guides/federation/watching.md
index f55005a..ec7ce6a 100644
--- a/docs/guides/federation/watching.md
+++ b/docs/guides/federation/watching.md
@@ -10,6 +10,11 @@ store, through its API and its log.
* **A version the node refused** (`own` in `GET /events/refused` not empty): keys voted
twice, and nodes may be apart. Act on it at once
([`when-things-go-wrong.md`](when-things-go-wrong.md)).
+* **A stop** (`stopped` in `GET /events` not `null`): a version passed that the node's
+ continuum doesn't read, and it takes nothing until upgraded, or until its operator has
+ it drop that version event
+ ([`when-things-go-wrong.md`](when-things-go-wrong.md),
+ [A node stopped](when-things-go-wrong.md#a-node-stopped)).
* **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](when-things-go-wrong.md#a-node-doing-less-than-it-should)).
@@ -37,6 +42,9 @@ At warn or error:
* `Refused an event its history takes, by what this node took before: kept so`: a version
the node refused, as above;
+* `The store stopped at an event this continuum can't judge: it takes none until it runs
+ one that does, or its operator has it drop that one`: a stop, as above; `The store
+ takes events again` once its operator had it drop that event;
* `This node isn't a member of its store, as it reads now: its party doesn't list it, and
members don't sync with it`;
* `The pinned checkpoint isn't in the document (yet): holding no store until it is`;
diff --git a/docs/guides/federation/when-things-go-wrong.md b/docs/guides/federation/when-things-go-wrong.md
index c79f24f..8c46e1d 100644
--- a/docs/guides/federation/when-things-go-wrong.md
+++ b/docs/guides/federation/when-things-go-wrong.md
@@ -1,8 +1,8 @@
# When things go wrong
-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),
+What to do when a node reports a version it refused, when a party voted twice, when a
+node stopped at a version it doesn't read, and when a node doesn't do what it should. The
+rules are the design's ([`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)).
@@ -65,6 +65,34 @@ or with its keys named anew ([`forking-and-following.md`](forking-and-following.
Tell the other parties what your node took and what it refused, and send them your
record.
+## A node stopped
+
+A node stops at a version event writing a version that passed on the version it reads,
+which its continuum doesn't read: of a later federation, using what a later continuum
+takes, or none at all. It takes nothing and refuses nothing from then on, and votes
+nothing by itself or by hand; what is put through it, it still writes into the document
+(`stopped` when put). Its log says so (`The store stopped at an event this continuum
+can't judge`), and `GET /events` names the event, why, and how many it holds back:
+
+```sh
+curl -s -u tv:secret localhost:3000/events | jq .stopped
+# {"heldBack":12,"id":"9a1e…","why":"version 3c0f… passed, and doesn't read as one…"}
+```
+
+Upgrade the node to a continuum that reads it: restarted, it reads its store anew and
+takes it. Where none does (two thirds passed a proposal that is no version), have the node
+drop that event: it goes on under the version before, refuses the event and any writing
+that version, and keeps so (`--store-file`):
+
+```sh
+curl -u tv:secret -X POST -H 'Content-Type: application/json' \
+ --data '{"ids": ["<the event it stopped at>"]}' localhost:3000/admin/events/drop
+# {"dropped":["9a1e…"]}
+```
+
+Allowed again (`/admin/events/allow`), it stops there once more. A node that stopped
+keeps none of it in its store file: restarted, it stops there again.
+
## A node doing less than it should
* **It holds no store** (`404` from `GET /events`): it hasn't read its document yet, its
diff --git a/docs/guides/federation/writing-and-reading.md b/docs/guides/federation/writing-and-reading.md
index 3dd0578..057aad7 100644
--- a/docs/guides/federation/writing-and-reading.md
+++ b/docs/guides/federation/writing-and-reading.md
@@ -33,7 +33,10 @@ object, the whole event up to 256 KiB. `null` empties the place.
The client signs the write with its key (`--key`), on the heads its node shows, which
are what the party read; records it (`--record`), to sign it again after a move; and puts
it through the node. The node answers what became of it: `taken`, `held` (taken before),
-or `waiting` for an event it builds on that the node doesn't hold yet.
+`waiting` for an event it builds on that the node doesn't hold yet, or `stopped`: the
+node stopped at a version it doesn't read, and holds it back
+([`when-things-go-wrong.md`](when-things-go-wrong.md),
+[A node stopped](when-things-go-wrong.md#a-node-stopped)).
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