aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/architecture.md17
-rw-r--r--docs/guides/federation/upgrades.md9
-rw-r--r--docs/operations.md35
-rw-r--r--docs/peers.md10
4 files changed, 43 insertions, 28 deletions
diff --git a/docs/architecture.md b/docs/architecture.md
index f70f132..f462fe7 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -79,9 +79,9 @@ it switched to the right document without trusting anyone.
**[`transport/`](../src/transport/)** — [`mod.rs`](../src/transport/mod.rs) defines the message types (HELLO, HELLO_REPLY, sync
envelope, STATUS/STATUS_REPLY, PING/PONG, blob messages, PROBE/PROBE_REPLY, REFUSALS, SPEAKS) and the `Transport` trait;
-[`wire.rs`](../src/transport/wire.rs) is the wire format (a version byte, bumped with every change to the format,
-and a kind byte, then the message in MessagePack, derived from the types in [`mod.rs`](../src/transport/mod.rs)
-with codecs for hashes and IDs; SPEAKS, outside the versions, is laid out as no build changes); [`mycelium/`](../src/transport/mycelium/) (with the `mycelium` feature) is the REST
+[`wire.rs`](../src/transport/wire.rs) is the wire format (a version byte, a new version with every change to the format,
+several spoken side by side, and a kind byte, then the message in MessagePack, derived from the types in [`mod.rs`](../src/transport/mod.rs)
+with codecs for hashes and IDs; SPEAKS, WHO and ME, outside the versions, are laid out as no build changes); [`mycelium/`](../src/transport/mycelium/) (with the `mycelium` feature) is the REST
client (polling inbox, outbound POST, one topic, `continuum`, for every message), with
[`mycelium/daemon.rs`](../src/transport/mycelium/daemon.rs) running the daemon (an external one by its URL, or one it starts
and supervises); [`libp2p/`](../src/transport/libp2p/) (with the `libp2p` feature) is libp2p as a transport,
@@ -288,11 +288,12 @@ places that rely on it.
* **Conflicts are errors; overrides are named.** A contradiction in the configuration
or at the API refuses with a message that names the `force` value that would
override it, in one camelCase vocabulary everywhere.
-* **Builds tell each other apart.** Every change of the wire format bumps its version,
- and a node ignores messages of another version instead of misreading them: across a
- change, the swarm is split until every node runs it, and merges then. A release's
- version says whether it is such a change ([`operations.md`](operations.md),
- [Upgrading](operations.md#upgrading)).
+* **Builds tell each other apart.** Every change of the wire format is a new version; a
+ build speaks several side by side and writes each node the newest both speak, and a
+ node ignores messages of a version it doesn't speak instead of misreading them. Where
+ two releases share none, the swarm is split until every node runs the later, and
+ merges then. A release's version says whether it is such a change
+ ([`operations.md`](operations.md), [Upgrading](operations.md#upgrading)).
## Where the complexity sits
diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md
index 6ffde67..9025164 100644
--- a/docs/guides/federation/upgrades.md
+++ b/docs/guides/federation/upgrades.md
@@ -10,10 +10,11 @@ design's ([`federation.md`](../../federation.md),
A node of a federated swarm upgrades as any node does
([`operations.md`](../../operations.md), [Upgrading](../../operations.md#upgrading)),
restarted with its files, and a release's version says how: a patch or a minor release one
-node at a time, a major one every node close together. Across a change of the wire
-format, a major one, upgraded nodes and the others don't talk, and the swarm is split
-until all are upgraded; a remake needs the same Automerge on every node, and one with
-another rejoins instead of switching. Before 1.0.0, take every upgrade as a major one.
+node at a time, a major one every node close together. Nodes write each other the newest
+wire version both speak; where two releases share none, a major one, upgraded nodes and
+the others don't talk, and the swarm is split until all are upgraded. A remake needs the
+same Automerge on every node, and one with another rejoins instead of switching. Before
+1.0.0, a release's tag says whether it is a flag day.
Nobody runs every node of a federated swarm: each party's operators upgrade its nodes. A
patch or minor release each party takes when it likes; for a major one, agree on when,
diff --git a/docs/operations.md b/docs/operations.md
index 0f906eb..4f3d6f2 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -125,20 +125,27 @@ continuum --version
A node upgrades by restarting with its files. What to know:
-* **The wire format.** Each change to it bumps a version byte, and nodes ignore
- messages of another version. Across such a change, upgraded nodes and the others
- don't talk: the swarm is split until every node is upgraded, both sides go on
- writing, and they merge then. Each logs it, at warn, once per peer, naming both
- versions and the node to upgrade (`Peer speaks another wire version: a newer build
- (wire version 53; this one speaks 52): upgrade this node to talk with it; ignoring its
- messages`, or of an older build, `upgrade that node`). With each handshake, a
- node says which versions it speaks, and the newest revision of the federation it knows
- (SPEAKS, outside the versions; [`peers.md`](peers.md),
- [Handshake and join](peers.md#handshake-and-join)); a build from before SPEAKS, before
- 0.0.1, logs it as another wire version, `version=0`, once of the peer, and reads the
- peer's other messages where they are of its version.
- A node speaks one version, so every change of the format is a major release; before
- 1.0.0, take every upgrade as one, and upgrade all nodes close together.
+* **The wire format.** Each change to it is a new version (the first byte of every
+ message), and a build speaks several side by side, from the oldest to the newest
+ `--version` names: it reads each, and writes to each node the newest both speak. A
+ node says which versions it speaks, and the newest revision of the federation it knows,
+ ahead of each proof of who it is and with each handshake (SPEAKS, outside the versions,
+ as are the proofs; [`peers.md`](peers.md),
+ [Handshake and join](peers.md#handshake-and-join)); it writes a node the oldest it
+ speaks until that node says. So a release whose versions meet the last one's rolls out
+ node by node, in any order: a release adds a version and keeps the older ones, and a
+ later one leaves the oldest out. A release's tag says whether it rolls out so
+ ([`development.md`](development.md), [Releasing](development.md#releasing)).
+ Nodes sharing no version don't talk: the swarm is split until every node is upgraded,
+ both sides go on writing, and they merge then. Each logs it, at warn, once per peer,
+ naming both versions and the node to upgrade (`Peer speaks another wire version: a
+ newer build (wire version 54; this one speaks 52): upgrade this node to talk with it;
+ ignoring its messages`, or of an older build, `upgrade that node`). 0.0.1 logs `Peer
+ speaks another wire version (another build); ignoring its messages`, with the peer's
+ version and its own (`ours`): upgrade the node whose version is the lower. A
+ build from before SPEAKS, before 0.0.1, logs SPEAKS as another wire version,
+ `version=0`, once of the peer, and reads the peer's other messages where they are of
+ its version.
* **Automerge.** A remake needs every node to build the same snapshot, byte for byte,
so the same Automerge version everywhere; a node with another one rejoins instead of
switching ([`remakes.md`](remakes.md), [Limits](remakes.md#limits)). Don't remake while
diff --git a/docs/peers.md b/docs/peers.md
index 34023db..a03d15f 100644
--- a/docs/peers.md
+++ b/docs/peers.md
@@ -44,6 +44,12 @@ there are that node's; messages from an address no node proved itself at are dro
and the address is asked WHO (at most every 5 s), so after a restart the first message
from a peer brings its proof back.
+Ahead of each WHO and each ME goes a SPEAKS ([Handshake and join](#handshake-and-join)),
+and WHO and ME read alike in every wire version: so once two nodes proved themselves to
+each other, each knows which versions the other speaks, and writes it the newest both
+do, at each of its addresses ([`operations.md`](operations.md),
+[Upgrading](operations.md#upgrading)). Until a node says, it is written the oldest.
+
A seed is an address (or something the transport resolves to one: a Mycelium public
key, IPv6 address or host name); it is asked WHO, and its ME names the node. Where other
nodes are comes from HELLO_REPLYs and the member list: hints, which are asked WHO before
@@ -98,8 +104,8 @@ HELLO.
Before each HELLO and each HELLO_REPLY, a node sends SPEAKS: the wire versions it speaks
and the newest revision of the federation it knows, as its build has them. It stands
outside the wire versions, laid out as no build changes, so that a peer on another build
-reads it too, once that peer reads the node's WHO and ME
-([Node IDs and addresses](#node-ids-and-addresses)): what each peer said shows as its
+reads it too; it goes ahead of each WHO and ME as well
+([Node IDs and addresses](#node-ids-and-addresses)). What each peer said shows as its
`knows` in `GET /peers`, the node's own as `localKnows`, and in `GET /events/counts` for
the nodes a federated store's parties list. A build from before SPEAKS takes it for a
message of another wire version, and logs that once of the peer