aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/guides/federation/refusals-and-drops.md15
-rw-r--r--docs/openapi.yaml17
-rw-r--r--docs/store.md13
3 files changed, 29 insertions, 16 deletions
diff --git a/docs/guides/federation/refusals-and-drops.md b/docs/guides/federation/refusals-and-drops.md
index c4566e3..b32a819 100644
--- a/docs/guides/federation/refusals-and-drops.md
+++ b/docs/guides/federation/refusals-and-drops.md
@@ -21,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).
@@ -49,9 +49,11 @@ 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. 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`).
@@ -62,8 +64,9 @@ 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
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 2017f15..3dbcd62 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -1576,7 +1576,8 @@ paths:
description: |
The events the store refused: `own`, those its history takes but this node
doesn't, by what it took before (a version changing another than the one it
- reads), apart from the rest; `dropped`, those its operator had it drop; and
+ reads), apart from the rest; `dropped`, those its operator had it drop, and
+ version events naming a version among them; and
`refused`, every other, with its kind (`none`: none of the federation's events;
`judged`: refused at its history; `builtOn`: built on `on`, refused;
`notAbove`: not above the checkpoint's heads, as a move refuses it) and why.
@@ -1679,11 +1680,12 @@ paths:
tags: [Events]
summary: Drop events this node took
description: |
- Drops events the store took after its checkpoint, with everything built on
- them: this node refuses them from then on, from whoever brings them, and keeps
- so across restarts (`--store-file`), until it is told otherwise
- (`/admin/events/allow`). Not what the checkpoint keeps or holds by ID. Answers
- what it dropped, in the order taken. Needs `write` on `_continuum`.
+ Drops events the store took after its checkpoint, version events naming the
+ version one of them names, and everything built on them: this node refuses them
+ from then on, from whoever brings them, and any version event naming a version
+ among them, and keeps so across restarts (`--store-file`), until it is told
+ otherwise (`/admin/events/allow`). Not what the checkpoint keeps or holds by
+ ID. Answers what it dropped, in the order taken. Needs `write` on `_continuum`.
requestBody:
required: true
content:
@@ -1715,7 +1717,8 @@ paths:
summary: Take back what this node refused of its own, or dropped
description: |
Takes back what this 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
+ 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. Needs `write` on
`_continuum`.
requestBody:
diff --git a/docs/store.md b/docs/store.md
index 02dc896..3192389 100644
--- a/docs/store.md
+++ b/docs/store.md
@@ -113,7 +113,9 @@ A fold says, of its events:
* **the store's members**, the nodes that carry it, at a state, each with the name of
its group ([Members](#members));
* where it needs to, **what a node refuses that its history takes**, by what the node
- took before ([A node's own](#a-nodes-own)).
+ took before ([A node's own](#a-nodes-own));
+* where it needs to, **what an event writes that others may write alike**, so that a node
+ dropping it refuses them all (the federation: a version event's version).
In Rust, roughly:
@@ -132,6 +134,10 @@ pub trait Fold {
fn keeps(_now: &Self::State, _id: &Id, _event: &[u8]) -> bool {
true
}
+ /// What the event writes that other events may write alike, where it writes such.
+ fn writes(_event: &[u8]) -> Option<Id> {
+ None
+ }
/// The checkpoint at `heads`, read as `at`: its bytes, and the events it keeps.
fn checkpoint(at: &Self::State, heads: &[Id]) -> (Vec<u8>, Vec<Id>);
/// The heads a checkpoint was built at, and the events it keeps.
@@ -191,8 +197,9 @@ moves to a checkpoint as it takes a version naming one ([`federation.md`](federa
events it took after its checkpoint; not what the checkpoint keeps or holds by ID, as
every event after it builds on that. A node undoes a move only by taking a checkpoint its
operator pins. Either way the node refuses the event and everything built on it, from
-whoever brings it, until its operator says otherwise, and reports it; it keeps what it
-refuses so, and its operator's drops, in a file of its own, across restarts. No peer's
+whoever brings it, until its operator says otherwise, and reports it; a drop takes with it
+whatever writes what a dropped event writes, as its fold says. It keeps what it refuses
+so, and its operator's drops, in a file of its own, across restarts. No peer's
word moves a node; its operator's does. A node that refuses what another took holds other
events, and reads its own state from them; two that hold the same read the same.