aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 13:50:35 +0000
committertv <tv@krebsco.de>2026-11-17 15:04:34 +0100
commita9d8da21897817206abd1e750395c88a7d103deb (patch)
tree562a58f9f856e4e8ee64de1d74801ea14a3387ce /docs
parent4cdf14260f5d9fc0db99d9e3c89155bf38062f35 (diff)
guides: refusals and drops
What `GET /events/refused` shows and of which kinds, the events a refused change carried, what the store file keeps across restarts, having a node drop events and take them back, and when an operator does.
Diffstat (limited to 'docs')
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/refusals-and-drops.md71
2 files changed, 73 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md
index cc415cd..80d2a22 100644
--- a/docs/guides/federation/README.md
+++ b/docs/guides/federation/README.md
@@ -26,3 +26,5 @@ by them, in its words.
party in, taking one out, giving places, zones and blocks, and keys named anew.
* [`voting-by-itself.md`](voting-by-itself.md): a node voting and proposing for its party
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.
diff --git a/docs/guides/federation/refusals-and-drops.md b/docs/guides/federation/refusals-and-drops.md
new file mode 100644
index 0000000..09b0442
--- /dev/null
+++ b/docs/guides/federation/refusals-and-drops.md
@@ -0,0 +1,71 @@
+# 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).
+
+## What a node refuses
+
+A node refuses an event with everything built on it, from whoever brings it. Most
+refusals are every node's: what the event's history doesn't let be written. Two kinds
+are the node's own: a version its history takes but that changes another than the one
+the node reads (of two versions changing one, the second it judged), and what its
+operator had it drop. `GET /events/refused` shows them apart:
+
+```sh
+curl -s -u tv:secret localhost:3000/events/refused
+# {"dropped":[],"own":["5f19…"],"refused":[{"id":"a03c…","kind":"builtOn",
+# "on":"5f19…","why":"it builds on 5f19…, refused"}]}
+```
+
+* `own`: refused by what the node took before.
+* `dropped`: dropped by its operator.
+* `refused`: every other, with its kind and why: `none` (none of the federation's events,
+ or larger than it allows), `judged` (refused at its history), `builtOn` (built on
+ `on`, refused), `notAbove` (not above the checkpoint's heads, as a move refuses it).
+
+A change of another node that a node refuses doesn't take its events with it: the store
+takes them as from anywhere (`Took events a refused change carried`), and the node puts
+them again.
+
+## Kept across restarts
+
+A node reads its store anew from its document at every start; what it refused of its
+own, and what it dropped, it keeps in its store file (`--store-file`), written whenever
+it changes. Without the file, a restart may take what it refused; a file that doesn't
+read stops the node from starting; one it can't write it logs (`Couldn't write the store
+file`).
+
+## Dropping
+
+An operator may have the node drop events it took after its checkpoint, with everything
+built on them:
+
+```sh
+curl -u tv:secret -X POST -H 'Content-Type: application/json' \
+ --data '{"ids": ["5f19…"]}' localhost:3000/admin/events/drop
+# {"dropped":["5f19…","a03c…"]}
+```
+
+It answers what it dropped, in the order taken. From then on the node refuses those
+events from whoever brings them, writes no version naming a version among them, though it
+holds the votes passing it, and keeps so across restarts. Not what its checkpoint keeps
+or holds by ID: every event after it builds on that. A move to a checkpoint is undone
+only by a checkpoint its operator pins (`--store-checkpoint`).
+
+## Taking back
+
+```sh
+curl -u tv:secret -X POST -H 'Content-Type: application/json' \
+ --data '{"ids": ["5f19…"]}' localhost:3000/admin/events/allow
+```
+
+takes back what the node refused of its own, or dropped, among the events named, and
+what was refused for building on them: they are taken again where the store takes them,
+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.