aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/designing-rules.md89
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.