diff options
| author | tv <tv@krebsco.de> | 2026-11-17 13:52:57 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-17 15:04:43 +0100 |
| commit | 2f78f51a4cd779e0ab989057727995f7bccf75ab (patch) | |
| tree | ace976a4f7ae842566927dd72982534c29100b7b /docs/guides | |
| parent | b4bc2251891677b471e34d72d1cb8ed32350fc48 (diff) | |
guides: designing a federation's rules
How rules match, a namespace each, zones and blocks a party holds by its name, shared
places given by rules of their own and kept apart from party names, what rules cost in
votes and size, and the krebs registry's rules as an example.
Diffstat (limited to 'docs/guides')
| -rw-r--r-- | docs/guides/federation/README.md | 2 | ||||
| -rw-r--r-- | docs/guides/federation/designing-rules.md | 89 |
2 files changed, 91 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index 1c8e049..5a44306 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -36,3 +36,5 @@ by them, in its words. or a party. * [`building-on-the-api.md`](building-on-the-api.md): an application reading what counts and writing as a party, through the client or with code of its own. +* [`designing-rules.md`](designing-rules.md): how rules match, namespaces, zones and + blocks, what is nobody's by its spelling, what rules cost, and the krebs registry's. diff --git a/docs/guides/federation/designing-rules.md b/docs/guides/federation/designing-rules.md new file mode 100644 index 0000000..82cec96 --- /dev/null +++ b/docs/guides/federation/designing-rules.md @@ -0,0 +1,89 @@ +# Designing rules + +The rules of a version say who writes where. Good rules let routine work go without a +vote and leave votes for what is nobody's by its spelling. The rules are the design's +([`federation.md`](../../federation.md), The policy, Shared identifiers). + +## How they match + +Rules go in order; the first whose path matches a path says who writes there. A rule's +path is segments separated by `/`: + +* the first literal, and not `_continuum`; +* any other literal, `{party}` (the name of a party of the version, once in a rule at + most: a segment naming no party doesn't match, and a later rule decides), `*` (any one + segment) or, last only, `**` (one segment or more). + +Its writer is a party of the version, `"{party}"` (the party the path names, where it +holds `{party}`), or `false`: nobody. A path no rule matches, nobody writes. A place is a +path, not a key in a tree: a version may give a place and the places below it alike, to +one party or to others. + +## A namespace each + +```json +{ "path": "home/{party}/**", "writer": "{party}" } +``` + +gives every party `home/<its name>/` and everything below it, and needs no change as +parties come and go. `**` takes one segment or more: `home/tv` itself is no place of it. + +## What a party holds by its name + +Names and addresses are spelled as paths by the application. Spelled by their parts, a +party's zone or block takes a rule or two, and a new name or host in it is a write: + +```json +{ "path": "names/r/{party}", "writer": "{party}" }, +{ "path": "names/r/{party}/**", "writer": "{party}" }, +{ "path": "ip4/10/243/7/*", "writer": "tv" } +``` + +Here a name is written by its labels, last first (`names/r/tv/toaster` for +`toaster.tv.r`, `names/r/tv` for `tv.r`), and an address by its parts +(`ip4/10/243/7/3`). + +## What is nobody's by its spelling + +A name like `wiki.r` is shared: no party holds it by its name, and nothing is first come, +first served. A version gives it to one party by a rule of its own, before any rule +that would match it otherwise, and takes it back or gives it to another the same way: + +```json +{ "path": "names/r/wiki", "writer": "lass" } +``` + +What a former writer signed there counts no more once a version gives the place to +another; given back, it shows again, unless something replaced it since or a checkpoint +left it out. A rule with `false` keeps a place from anyone a later rule would give it to. + +Keep party names apart from the shared spellings: a party named `wiki` takes `wiki.r` +where a `{party}` rule comes before the rule giving it to lass. Put the rules naming +shared places first, and let no party be named like one of them. + +## What rules cost + +A version holds all its rules, and every change of one is a version, which takes the +parties' votes. A rule per shared name is a vote per name, and makes every version that +much larger: give zones and blocks by rules where the spelling allows, and leave literal +rules to what is shared. + +## An example: the krebs registry + +The krebs users who will vote are parties, each with its hosts in its namespace +(`home/tv/hosts/laptop`); the others are in a party that is a group, until a version +makes one a party of its own. Every decision takes two thirds of all parties, quiet ones +counted, so the first version names only those that will vote. Its rules: + +```json +[ { "path": "names/r/wiki", "writer": "lass" }, + { "path": "home/{party}/**", "writer": "{party}" }, + { "path": "names/r/{party}", "writer": "{party}" }, + { "path": "names/r/{party}/**", "writer": "{party}" }, + { "path": "names/w/{party}", "writer": "{party}" }, + { "path": "names/w/{party}/**", "writer": "{party}" }, + { "path": "ip4/10/243/7/*", "writer": "tv" } ] +``` + +Each party writes its namespace, its names in `.r` and `.w`, and its block; `wiki.r` is +lass's by a version, and any other name is given the same way. |
