aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/refusals-and-drops.md
blob: 09b04426c67bc5d0f7917eb490fc65dac2130a4c (plain)
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.