summaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/refusals-and-drops.md
blob: 1d29df19168083b2cb47d4790035dc2de9c0d193 (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
72
73
74
75
76
77
78
79
# 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](../../store.md#a-nodes-own)) and the federation's
([`federation.md`](../../federation.md),
[Changing the policy](../../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, and version events naming a version among them.
* `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, or the version
event it stopped at ([`when-things-go-wrong.md`](when-things-go-wrong.md),
[A node stopped](when-things-go-wrong.md#a-node-stopped)), 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: those named, version events naming the
version one of them names, and what is built on them; then the event it stopped at, if
named, after which it takes again. From then on the node refuses those
events from whoever brings them, and any version event naming a version among them,
whoever wrote it anew; it writes none itself, 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, the
version events dropped for naming the version one of them names, 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](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.