aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/federation.md56
1 files changed, 54 insertions, 2 deletions
diff --git a/docs/federation.md b/docs/federation.md
index 8905818..39b9bbe 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -1699,8 +1699,8 @@ takes along those of the nodes that carry for a user it holds.
* `POST /admin/refused/drop`, naming the peer whose word it takes (Partitions).
* `POST /admin/check/accept`: write again after a check of itself that differed
(Continuum changing under a swarm).
- * `POST /admin/put-off/take`, naming a user: take what was put off for the writers
- past its limit (Users).
+ * `GET /admin/put-off`: what the node put off, by user; `POST /admin/put-off/take`,
+ naming a user: take what was put off for the writers past its limit (Users).
* **Who may connect** is outside this design. Today it is the swarm key, a secret all
nodes share: it keeps those who aren't parties from connecting and reading, as far
as every party keeps it, and is no boundary between the parties. Nothing here
@@ -1757,6 +1757,58 @@ For the registry: a hundred nodes and a few thousand hosts make statements and v
of some MB, and a snapshot of as much; their stamps alone fill `remakeChanges` in about
a hundred days, and a remake follows.
+### What to watch, and when to act
+
+Each signal shows at the endpoint named and as a metric beside it, with the threshold
+the design recommends; who acts, and how. A node shows each where it waits on it
+(`GET /admin/epochs`, the dashboard).
+
+**A node's operator:**
+
+| Signal | Act when | What to do |
+|---|---|---|
+| the epoch's changes × writers × 4 B, beside the node's memory | over a quarter of it | ask the voters for lower `remakeChanges` or `remakeWriters`, or give the node memory |
+| the writers of a user the node carries for (`GET /registry/users`) | half of `limits.writers` | find the node that restarts in a loop |
+| what the node put off, by user (`GET /admin/put-off`) | anything | take it (`POST /admin/put-off/take`), or leave it to the next remake |
+| what waits by a party's budget, by party | waiting an hour | a party that writes without end, or a budget too small |
+| a claim of a user the node carries for, not settled (`GET /registry/claims`) | ten times `witness` | its neighbours and seeds; the roots' nodes' last change |
+| the age of the last change of the roots' nodes the node holds | twice `stamp` | its seeds; tell the roots |
+| peers in another epoch (`GET /peers`) | longer than a switch delay and `catchUp` | a peer that keeps the epoch, or the ID (`POST /admin/epochs/rejoin`) |
+| a committed remake whose ID the node doesn't get | at once | versions differ: upgrade, or report it |
+| a refused peer, a forked actor proven (`GET /peers`, `sync.refusedPeers`) | at once | drop (`POST /admin/refused/drop`), or not |
+| two digests for the same changes; a check of itself that differed | at once | upgrade, or write on (`POST /admin/check/accept`) |
+| a policy the node doesn't know | at once | upgrade, or refuse the decision |
+| a proposal its bounds would refuse, or a policy that breaks them (`GET /registry/decisions`) | while the votes run | tell the voters; refuse it when decided, or change the bounds |
+
+**A user**, through a node it trusts:
+
+| Signal | Act when | What to do |
+|---|---|---|
+| out, and how long its names still wait (`GET /registry/users`) | at once | find another to vouch for it, within `gone` |
+| a name of its own contested (`GET /registry/claims`) | at once | release it, or ask the voters whose it is |
+| a claim held "while an unvouch or a cut stands" | until it is final | a second vouch, so that one voucher's keys don't decide |
+| what was signed with its keys and not by it | at once | cut the key off from before (a key above; above the first keys, the voters), within `final` |
+| what stopped counting after a cut, what is in the quarantine | at once | sign it again |
+| what a policy no longer covers (`GET /registry/uncovered`) | before `uncovered` runs out | take it away, or move it |
+
+**A voter:**
+
+| Signal | Act when | What to do |
+|---|---|---|
+| when each voter last voted and a node of its last stamped (`GET /registry/decisions`) | a fifth not taking part | decide on a list of those who do, before a third stop |
+| how many voters each node carries for | a tenth | those voters name another node, before one is a third |
+| what hangs, how many records it is short of, who would refuse | at once | decide a later proposal of the matter |
+| a moved-in user's first keys contested; a name contested; a root marked for both orders | at once | give first keys, say whose the name is, or leave the root out |
+| a root's or a voter's key stolen | at once | first keys anew with a cut: one decision |
+
+**A root:**
+
+| Signal | Act when | What to do |
+|---|---|---|
+| a node of its own up: its last stamp | older than twice `stamp` | start one: while none is up, nothing settles |
+| a moved-in user without keys that came to it | at once | give it its first keys |
+| its own keys | stolen | ask the voters for first keys with a cut |
+
## Why it holds
**Promise 1**, by how a change is judged: every node judges a change before applying