diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/architecture.md | 4 | ||||
| -rw-r--r-- | docs/measurements.md | 2 | ||||
| -rw-r--r-- | docs/operations.md | 16 | ||||
| -rw-r--r-- | docs/peers.md | 8 |
4 files changed, 22 insertions, 8 deletions
diff --git a/docs/architecture.md b/docs/architecture.md index 8fc152f..202495d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -78,10 +78,10 @@ it switched to the right document without trusting anyone. ## Modules **[`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) and the `Transport` trait; +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); [`mycelium/`](../src/transport/mycelium/) (with the `mycelium` feature) is the REST +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 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, diff --git a/docs/measurements.md b/docs/measurements.md index d54f07b..2adc9ed 100644 --- a/docs/measurements.md +++ b/docs/measurements.md @@ -185,7 +185,7 @@ clocks"); setting them is the operating system's job (NTP). ## Traffic Messages and payload bytes by direction (`sent`, `received`, `refused`) and kind -(`hello`, `helloReply`, `sync`, `status`, `statusReply`, `blob`, `identity` for WHO and +(`hello` for HELLO and SPEAKS, `helloReply`, `sync`, `status`, `statusReply`, `blob`, `identity` for WHO and ME, `paths` for PING and PONG, `probe` for PROBE and PROBE_REPLY, `plumtree` for PRUNE and GRAFT, `hyparview` for NEIGHBOUR, NEIGHBOUR_REPLY and DISCONNECT, `refusals` for REFUSALS). The layers below the node count WHO and ME, and the diff --git a/docs/operations.md b/docs/operations.md index e1b8e79..4b42992 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -98,10 +98,15 @@ One node at a time, restarting each 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. Mycelium logs it (`Peer speaks another wire version - (another build); ignoring its messages`, warn, once per peer); libp2p and Tor at debug - only (`Dropping a message that doesn't decode`). Until the first release, assume - every upgrade is such a change, and upgrade all nodes close together. + writing, and they merge then. Each logs it (`Peer speaks another wire version + (another build); ignoring its messages`, warn, once per peer). 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 logs it + as that warning, `version=0`, once of the peer, and reads the peer's other messages + where they are of its version. + Until the first release, assume every upgrade is such a change, and upgrade all nodes + close together. * **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 @@ -246,7 +251,8 @@ And from the log, at warn or error: read-only disk; * `The … file is readable by others than its owner; chmod 600 it`; * `Peer speaks another wire version (another build); ignoring its messages`: a node on - another build. + another build; with `version=0`, only a newer build's SPEAKS, which this build doesn't + read. ## What a node uses diff --git a/docs/peers.md b/docs/peers.md index e71d726..c63bebe 100644 --- a/docs/peers.md +++ b/docs/peers.md @@ -95,6 +95,14 @@ only valid identities (node IDs), and, once it knows the member list, only its own neighbours; their addresses are hints for its transport, and each gets a 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)). A build from before SPEAKS takes it +for a message of another wire version, and logs that once of the peer +([`operations.md`](operations.md), [Upgrading](operations.md#upgrading)). + Every HELLO carries a random id of the sender's current run, and the HELLO_REPLY echoes it. A reply with another id answers a HELLO from an earlier run (delivered late, or queued in Mycelium while the node was down) and is ignored. |
