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 onon, 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.
