aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/architecture.md4
-rw-r--r--docs/measurements.md2
-rw-r--r--docs/operations.md16
-rw-r--r--docs/peers.md8
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.