diff options
| author | tv <tv@krebsco.de> | 2026-11-17 13:50:35 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-17 15:04:34 +0100 |
| commit | a9d8da21897817206abd1e750395c88a7d103deb (patch) | |
| tree | 562a58f9f856e4e8ee64de1d74801ea14a3387ce /docs | |
| parent | 4cdf14260f5d9fc0db99d9e3c89155bf38062f35 (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.md | 2 | ||||
| -rw-r--r-- | docs/guides/federation/refusals-and-drops.md | 71 |
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. |
