aboutsummaryrefslogtreecommitdiffstats

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, A node's own) and the federation's (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:

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:

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

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, Choosing a side), or keeps out an event it won't hold: whatever it drops, it reads no more, while the others may.