aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/designing-rules.md
blob: 82cec96bb8e9523d09eb25d56ba0d8c52d2a4143 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
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.