aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/federation.md61
1 files changed, 35 insertions, 26 deletions
diff --git a/docs/federation.md b/docs/federation.md
index 1854ef6..25acc9e 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -374,10 +374,16 @@ grows. A statement is signed by one user and says one thing:
proposals, until a remake or its operator takes what is put off; how many a user's
nodes started shows (`GET /registry/users`), for a remake to come first.
* **A party's budget.** A node takes changes from a party's nodes no faster than a
- budget, its own setting: what is over waits, and nothing is refused for it. For a
- budget a party is a user with the users below it that no line reaches but through
- it, as the graph stands where the node reads it: creating users makes no second
- budget. A node carrying for several users draws on each.
+ budget, its own setting (`--party-budget`): changes, their bytes and their
+ operations an hour, recommended 600 changes, 4 MiB and 100 000 operations a party.
+ What is over waits, and nothing is refused for it: a change larger than what is left
+ of the hour is taken once nothing of its party waits before it, and the party's next
+ changes wait until the hour it overdrew is paid. For a budget a party is a user with
+ the users below it that no line reaches but through it, as the graph stands where
+ the node reads it: creating users makes no second budget. A node's changes draw on
+ the party of the user its writers count for (above), whatever they carry: a
+ statement another party hands a node draws on the node's party, which takes it at
+ its own pace.
* **Past a limit.** A user's statements of one kind are counted from the first: each
has, and states, the number after the highest of those it was signed in sight of,
and of two with one number the one with the lower digest comes first. A statement is
@@ -693,13 +699,15 @@ a cut from before it (Cuts).
What this gives:
* **Settled.** Every node writes its member entry as often as `stamp` says, and a
- root's node also when a claim reaches it that it hadn't seen, `witness` apart at
- most. Such a change has in its history everything the node had received. The
- roots' nodes are on every side. So once a root's node wrote after receiving a
- claim, while it held no other of that name that stood, every other claim of the
- name is late against it: one surfacing later, however little it says it saw, and
- one that was there and comes to count later. The claim is **settled**, within
- `witness` of reaching a root's node. A node tells (`settled`, below).
+ root's node also once claims reach it that it hadn't seen: within `witness`, one
+ change for all that reached it meanwhile, so no more often than `witness` (with a
+ minute, 1 440 changes a day, within the budget recommended for its party). Such a
+ change has in its history everything the node had received. The roots' nodes are on
+ every side. So once a root's node wrote after receiving a claim, while it held no
+ other of that name that stood, every other claim of the name is late against it: one
+ surfacing later, however little it says it saw, and one that was there and comes to
+ count later. The claim is **settled**, within `witness` of reaching a root's node. A
+ node tells (`settled`, below).
* **Several roots.** Any one of them settles a claim. Two that received two claims in
different orders make each late against the other: contested, as two claims made
at once are, and one releases. So with more roots a claim is settled though one is
@@ -2298,25 +2306,26 @@ Nodes and syncing:
| 129 | Logs in on another party's node with a key of the registry; has a name in the registry that the node's own users have | Keys in the registry give nothing on anyone's node by themselves: whom a node lets in is its operator's, and what a user may write is in its signature | 3 | unit: `registry_keys_open_no_node` |
| 130 | Lies in its member entry (ready, reached, stable); publishes a short window there to make every node stamp hourly; writes an entry of any size | Sync and trees bend; nothing gets in that way. How often nodes stamp is the policy's; an entry has a shape and a size, or the change is refused | 6 | unit: `an_entry_has_a_shape`, `stamps_by_the_policy`; argued (Reaching the others) |
| 131 | Sends envelopes that don't check, without end | Refuse each (a signature costs about 30 µs to check *(docs)*); the node is refused as a whole after the first of its own | 6 | sim: `a_refused_node_costs_little` |
-| 132 | Writes its own member entry without end; signs and gives up without end; fills the waiting changes; sends changes that say they saw little, each to be judged far back | Take them no faster than a budget per party: put off, never refused; a share of the waiting each | 6 | sim: `a_party_past_its_budget_waits` |
+| 132 | Writes its own member entry without end; signs and gives up without end; fills the waiting changes; sends changes that say they saw little, each to be judged far back | Take them no faster than a budget per party (changes, bytes and operations an hour): put off, never refused; a share of the waiting each | 6 | sim: `a_party_past_its_budget_waits` |
| 133 | Starts a writer with every change: each costs every node memory in proportion to the document's history | Past `limits.writers` a user and epoch, every node puts off the changes that start more of the nodes whose writers count for it: a node's, for the user its member entry names. Nothing is refused; what reaches a node within others' histories is held, and a remake leaves it out. A user below a root costs the root nothing, and one beside others on a node costs them nothing, but where the node's entry names it | 6; not bounded | sim: `writers_past_their_limit_wait` |
| 134 | One of the users a node carries for, besides the node's own, starts writers past its limit, from nodes of its own | The node's writers count for the user its member entry names, over a remake too, and nothing of it is put off for the others: the users beside it write on | 6 | sim: `writers_count_for_the_user_an_entry_names_beside_others` |
| 135 | Signs its `node` statement naming another party's node again and again until its digest is the lowest, so that the node's writers count for it after a remake, then starts writers past its limit | A node's writers count for the user its member entry names, the node's own word, carried over a remake; the digest decides only where the entry names none | 6 | unit: `writers_count_for_the_user_an_entry_names` |
| 136 | Sends a node a change of the node's own writer, another value, to make it start a writer | Refused as forged; the node switches only where its own key signed it (a copy of its files) | 6 | unit, exists: `another_writing_as_this_node` |
| 137 | Crafts a first change of another node's writer, authored as a third node, to sort before the writer's own in a batch, so that screening judges the writer's changes as the third node's | Screening names a change's node by its own author, or that of its actor's first change in its own history, never by another change of the batch: the writer's changes are vouched for by their own node's signature, and the crafted one, a second first change of the writer, is refused as forged | 1, 2 | unit, exists: `a_committer_from_its_own_history` |
-| 138 | Sends a change of a few bytes that holds a million operations | Taken, at the cost of applying it: nothing bounds a change's operations | not promised (a bound on what an epoch's document costs) | argued |
-| 139 | Crafts a change Automerge won't take, or that writes in an object nowhere to be found | Refuse *(checked: the rules refuse the second today)*; only the message that brought it fails | 1 | unit: `a_change_writing_nowhere` |
-| 140 | Crafts a change Automerge takes and shouldn't: bytes it wouldn't encode itself, operations numbered against its dependencies', a gap in its actor's changes, an operation named that is elsewhere or outside its history, an operation Automerge's transactions never write (an element written over naming the one inserted after it, an insert that replaces, a deletion or an increment inserted, a deletion named as replaced), a table written into, a value written at a mark's begin | Refuse before Automerge sees it, by the change and its own history alone: applied, such a change makes a node panic, save a document that doesn't load, or part from nodes it reached in another order | 1, 2 | unit, exist: `bytes_automerge_wouldnt_encode_are_refused`, `operations_numbered_against_their_dependencies_are_refused`, `a_gap_in_an_actors_changes_is_refused`, `operations_named_at_the_wrong_place_are_refused`, `operations_outside_a_changes_history_are_refused`, `only_what_transactions_write_passes`, `only_what_holds_a_value_is_replaced`, `no_table`, `no_mark`, `what_passes_leaves_automerge_sound`, `a_batch_is_checked_against_itself`, `a_change_refused_after_its_check_stands_in_for_nothing` |
+| 138 | Sends a change of a few bytes that holds a million operations | Taken, at the cost of applying it, against its party's budget, which counts operations: the party's next changes wait until it is paid | 6; not promised (a bound on what an epoch's document costs) | argued; sim: `a_party_past_its_budget_waits` |
+| 139 | Claims and releases a name a minute, by many users, to have every root's node write for each | A root's node writes once a `witness` at most, for all claims that reached it meanwhile, and takes the party's claims at its budget's pace | 6 | unit: `a_root_witnesses_once_a_witness` |
+| 140 | Crafts a change Automerge won't take, or that writes in an object nowhere to be found | Refuse *(checked: the rules refuse the second today)*; only the message that brought it fails | 1 | unit: `a_change_writing_nowhere` |
+| 141 | Crafts a change Automerge takes and shouldn't: bytes it wouldn't encode itself, operations numbered against its dependencies', a gap in its actor's changes, an operation named that is elsewhere or outside its history, an operation Automerge's transactions never write (an element written over naming the one inserted after it, an insert that replaces, a deletion or an increment inserted, a deletion named as replaced), a table written into, a value written at a mark's begin | Refuse before Automerge sees it, by the change and its own history alone: applied, such a change makes a node panic, save a document that doesn't load, or part from nodes it reached in another order | 1, 2 | unit, exist: `bytes_automerge_wouldnt_encode_are_refused`, `operations_numbered_against_their_dependencies_are_refused`, `a_gap_in_an_actors_changes_is_refused`, `operations_named_at_the_wrong_place_are_refused`, `operations_outside_a_changes_history_are_refused`, `only_what_transactions_write_passes`, `only_what_holds_a_value_is_replaced`, `no_table`, `no_mark`, `what_passes_leaves_automerge_sound`, `a_batch_is_checked_against_itself`, `a_change_refused_after_its_check_stands_in_for_nothing` |
Rules, and the swarm as it is:
| # | The adversary | Honest nodes | Promise | Shown by |
|---|---|---|---|---|
-| 141 | A rule differs between versions (a bug) | Each side refuses what the other takes, or their stamps name two digests for the same changes: each logs and shows it. A node that finds itself apart from the nodes of more than two thirds of the other voters at its first start with a version writes nothing. One side upgrades and drops | not promised | sim: `a_side_drops_and_comes_back`, `two_digests_one_history`; unit: `a_node_checks_itself` |
-| 142 | Stamps a wrong digest, to keep the nodes that upgrade from writing; one of three voters does | A node stops only where it differs from the nodes of more than two thirds of the other voters; from fewer it shows it and goes on | 6 | unit: `one_wrong_digest_stops_nobody`, `of_three_voters` |
-| 143 | A policy version a node doesn't know: in the root, or decided | It doesn't sync, and takes no such proposal up: a policy is decided only with two thirds of the voters' nodes knowing it | 1 | unit: `no_sync_under_an_unknown_policy`, `an_unknown_policy_isnt_taken_up` |
-| 144 | A partition, for any length of time | A side decides only with nodes of two thirds of all the voters on it. Where a third of them have nodes and votes on both sides, both may: every node then acts on the higher number | 7 | sim: `one_side_decides`; unit: `the_last_holds` |
-| 145 | None: a swarm that isn't federated | Everything as today | Optional | the existing tests, untouched; `bench_screening` |
+| 142 | A rule differs between versions (a bug) | Each side refuses what the other takes, or their stamps name two digests for the same changes: each logs and shows it. A node that finds itself apart from the nodes of more than two thirds of the other voters at its first start with a version writes nothing. One side upgrades and drops | not promised | sim: `a_side_drops_and_comes_back`, `two_digests_one_history`; unit: `a_node_checks_itself` |
+| 143 | Stamps a wrong digest, to keep the nodes that upgrade from writing; one of three voters does | A node stops only where it differs from the nodes of more than two thirds of the other voters; from fewer it shows it and goes on | 6 | unit: `one_wrong_digest_stops_nobody`, `of_three_voters` |
+| 144 | A policy version a node doesn't know: in the root, or decided | It doesn't sync, and takes no such proposal up: a policy is decided only with two thirds of the voters' nodes knowing it | 1 | unit: `no_sync_under_an_unknown_policy`, `an_unknown_policy_isnt_taken_up` |
+| 145 | A partition, for any length of time | A side decides only with nodes of two thirds of all the voters on it. Where a third of them have nodes and votes on both sides, both may: every node then acts on the higher number | 7 | sim: `one_side_decides`; unit: `the_last_holds` |
+| 146 | None: a swarm that isn't federated | Everything as today | Optional | the existing tests, untouched; `bench_screening` |
## The registry on it
```
@@ -2373,7 +2382,7 @@ it trusts for that.
## Stages
Each leaves the system working, and is a few patches with its tests, which leave
-their vectors. At every stage the existing tests pass untouched (145).
+their vectors. At every stage the existing tests pass untouched (146).
1. **A federated swarm's frame.** `--genesis-policy` (a file, written into the genesis
change with the roots, the voters and the users it starts with); a federated node
@@ -2381,7 +2390,7 @@ their vectors. At every stage the existing tests pass untouched (145).
yet, takes tokens and logins by key as its operator says, keeps ended sessions to
itself, stamps as the policy says, and writes a member entry of the policy's shape
and size. What the genesis change sets for the swarm as a whole is read from the
- policy. Tests: 127 to 130, 137, 140, 143, 145, and the policy's existing tests
+ policy. Tests: 127 to 130, 137, 141, 144, 146, and the policy's existing tests
under a policy from the genesis change. Those of a crafted change, and of a crafted
committer, exist already: screening refuses those in every swarm.
2. **Statements.** The users' registers (`create`, `key`, `node`, `vouch`, `release`);
@@ -2417,7 +2426,7 @@ their vectors. At every stage the existing tests pass untouched (145).
8. **Coming back.** The drop an operator asks for, a forked actor proven and shown
with what the roots' nodes hold, the budget and the share per party, the writers
counted per user, for the one a node's member entry names, a node keeping its
- writer over a clean stop. Tests: 124, 131 to 136, 138, 139.
+ writer over a clean stop. Tests: 124, 131 to 136, 138 to 140.
9. **The registry.** Import, export, and a federated swarm of the simulations with the
registry's kinds and a few hundred hosts. From here it can be tried: users, hosts,
names, a root that settles, names that become final. It isn't to be relied on yet.
@@ -2431,10 +2440,10 @@ their vectors. At every stage the existing tests pass untouched (145).
contested name is, a name the rules leave to the voters; a decision of the voters
before counted only in sight of the list that replaced them; a final decision. The
simulations start from a root change naming several voters. Tests: 24, 64, 68 to
- 87, 115, 116, 144.
+ 87, 115, 116, 145.
11. **Versions.** The digest with every stamp, a node checking itself before it
writes; for every swarm, a node that speaks the wire version before its own, and a
- handshake that says which epochs its node keeps. Tests: 141, 142.
+ handshake that says which epochs its node keeps. Tests: 142, 143.
12. **Remakes.** Compaction only; a node proposing and acking by `remakeChanges` and
`remakeWriters`, and following such a remake only, by its result; the snapshot
every node builds, with whatever can still count and how far each length of time
@@ -2448,7 +2457,7 @@ their vectors. At every stage the existing tests pass untouched (145).
to 110, 112 to 114.
13. **The policy by a decision.** The policy as a matter, a node that doesn't know it,
what it no longer covers: shown aside, taken away by its user only, dropped after
- a time, moved at a remake. Tests: 31, 51, 88, 89, 143.
+ a time, moved at a remake. Tests: 31, 51, 88, 89, 144.
14. **Going apart, and refusing.** A fork followed by an operator's word, with who
votes and who the roots are on its side. Refusing a decision: a node's bounds, the
epoch without the decision, what a node takes along. Tests: 117 to 122. From here