diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/guides/federation/refusals-and-drops.md | 15 | ||||
| -rw-r--r-- | docs/openapi.yaml | 17 | ||||
| -rw-r--r-- | docs/store.md | 13 |
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. |
