1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
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.
|