From 1126567cfdd2ff51933edae7b94ff8b8aca400ef Mon Sep 17 00:00:00 2001 From: tv Date: Sat, 14 Nov 2026 05:52:45 +0000 Subject: federation: what to watch, and when to act The design showed much and said nowhere who looks at what, nor when to act. A section says it for each who acts, a node's operator, a user, a voter and a root: each signal, where it shows (an endpoint, and a metric beside it), the threshold the design recommends, and what to do. What a node put off shows (`GET /admin/put-off`), beside taking it. --- docs/federation.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) (limited to 'docs/federation.md') 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 -- cgit v1.3.1