aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/refusals-and-drops.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/guides/federation/refusals-and-drops.md')
-rw-r--r--docs/guides/federation/refusals-and-drops.md32
1 files changed, 20 insertions, 12 deletions
diff --git a/docs/guides/federation/refusals-and-drops.md b/docs/guides/federation/refusals-and-drops.md
index 09b0442..1d29df1 100644
--- a/docs/guides/federation/refusals-and-drops.md
+++ b/docs/guides/federation/refusals-and-drops.md
@@ -1,8 +1,10 @@
# 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).
+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
@@ -19,7 +21,7 @@ curl -s -u tv:secret localhost:3000/events/refused
```
* `own`: refused by what the node took before.
-* `dropped`: dropped by its operator.
+* `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).
@@ -38,8 +40,9 @@ file`).
## Dropping
-An operator may have the node drop events it took after its checkpoint, with everything
-built on them:
+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' \
@@ -47,9 +50,12 @@ curl -u tv:secret -X POST -H 'Content-Type: application/json' \
# {"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
+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`).
@@ -60,12 +66,14 @@ 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,
+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), or keeps out an
-event it won't hold: whatever it drops, it reads no more, while the others may.
+([`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.