talk about "transport" unless mycelium is meant

9 files changed, 37 insertions, 32 deletions

diff --git a/src/swarm/auth.rs b/src/swarm/auth.rs
index 46efd77..3bfbd4d 100644
--- a/src/swarm/auth.rs
+++ b/src/swarm/auth.rs
@@ -1,9 +1,10 @@
 //! Swarm membership by pre-shared key.
 //!
-//! Mycelium authenticates the sender of every message (`src_pk` can't be forged), so we
-//! always know *who* talks to us. With a swarm key configured, only nodes that also know
-//! the key may take part: HELLO and HELLO_REPLY carry a tag proving it, and until a peer
-//! has sent a valid one, everything else it sends is ignored.
+//! The transport authenticates the sender of every message (for Mycelium, `src_pk`
+//! can't be forged), so we always know *who* talks to us. With a swarm key configured,
+//! only nodes that also know the key may take part: HELLO and HELLO_REPLY carry a tag
+//! proving it, and until a peer has sent a valid one, everything else it sends is
+//! ignored.
 //!
 //! The tag is `HMAC-SHA256(key, label ‖ swarm_id ‖ from_pk ‖ to_pk)`. It needs no
 //! challenge: it is bound to both keys, and only `from_pk` can send as `from_pk`, so a
diff --git a/src/swarm/blob.rs b/src/swarm/blob.rs
index c13bcd9..ec99c93 100644
--- a/src/swarm/blob.rs
+++ b/src/swarm/blob.rs
@@ -1,12 +1,12 @@
 //! Blobs: content-addressed bytes fetched in chunks from several peers at once.
 //!
-//! Large transfers can't go in one Mycelium message (it must arrive within Mycelium's
-//! five-minute deadline), and a blob every node holds identically can come from many
-//! of them. A blob is an Automerge change by its hash (e.g. an epoch's snapshot change,
-//! which every node on that epoch holds byte for byte), or content by its BLAKE3 hash
-//! (e.g. the new document of a `replace` or `import` remake), or the changes between two
-//! sets of heads (a delta: what a peer lacks, when one sync message would be too large;
-//! `swarm::sync`).
+//! Large transfers can't go in one message (it must arrive within the transport's
+//! delivery limit, five minutes for Mycelium), and a blob every node holds identically
+//! can come from many of them. A blob is an Automerge change by its hash (e.g. an
+//! epoch's snapshot change, which every node on that epoch holds byte for byte), or
+//! content by its BLAKE3 hash (e.g. the new document of a `replace` or `import`
+//! remake), or the changes between two sets of heads (a delta: what a peer lacks, when
+//! one sync message would be too large; `swarm::sync`).
 //!
 //! * Serving: a request without chunks gets the manifest (size, chunk size, a BLAKE3
 //!   hash per chunk); one with chunks gets each chunk as a message of its own. A node
@@ -85,7 +85,7 @@ pub(crate) struct Blobs {
 /// A sync message larger than this many chunks is sent as a delta blob instead
 /// (`swarm::sync`): below it, a blob costs more round trips than it saves; above it, a
 /// lost message costs too much to send again whole, and a slow link may not deliver it
-/// within Mycelium's deadline.
+/// within the transport's delivery limit.
 const DELTA_THRESHOLD_CHUNKS: usize = 16;
 
 /// The largest sync message accepted: the threshold of a sender with the largest chunks
diff --git a/src/swarm/peer/handshake.rs b/src/swarm/peer/handshake.rs
index 109a42f..4c657ad 100644
--- a/src/swarm/peer/handshake.rs
+++ b/src/swarm/peer/handshake.rs
@@ -109,7 +109,7 @@ pub(super) async fn retry_hello_if_due(state: &AppState, peer: &str) -> Result<(
 }
 
 /// Sends a HELLO without holding any lock, then schedules the next retry.
-/// Success and failure both end in AwaitingReply: Mycelium accepting the message
+/// Success and failure both end in AwaitingReply: the transport accepting the message
 /// says nothing about whether the peer received it.
 async fn transmit_hello(state: &AppState, peer: &str) -> Result<()> {
     let swarm_id = state.swarm_id().await;
diff --git a/src/swarm/peer/inbound.rs b/src/swarm/peer/inbound.rs
index 745e646..a1f6646 100644
--- a/src/swarm/peer/inbound.rs
+++ b/src/swarm/peer/inbound.rs
@@ -31,8 +31,8 @@ pub(crate) async fn handle_message(
         return Ok(());
     }
 
-    // A reply to a HELLO from an earlier run of ours (late, or queued in Mycelium while
-    // we were down) says nothing about now; the peer answers our current HELLO.
+    // A reply to a HELLO from an earlier run of ours (late, or queued by the transport
+    // while we were down) says nothing about now; the peer answers our current HELLO.
     if let transport::ParsedMessage::HelloReply(reply) = &message
         && reply.run_id != state.run_id
     {
diff --git a/src/swarm/peer/keepalive.rs b/src/swarm/peer/keepalive.rs
index b22d954..ce2951b 100644
--- a/src/swarm/peer/keepalive.rs
+++ b/src/swarm/peer/keepalive.rs
@@ -29,7 +29,7 @@ const FAREWELL_TIMEOUT: Duration = Duration::from_secs(2);
 
 /// At shutdown: one last PING to each neighbour, saying we aren't ready. A neighbour
 /// catching up from us picks another source now, instead of once we go dormant. Bounded
-/// in time: our Mycelium may be gone already.
+/// in time: our transport may be gone already.
 pub(crate) async fn farewell(state: &AppState) {
     state.stopping.store(true, Ordering::Release);
     let mut pings = tokio::task::JoinSet::new();
diff --git a/src/swarm/relay.rs b/src/swarm/relay.rs
index b1cc0a7..202ae40 100644
--- a/src/swarm/relay.rs
+++ b/src/swarm/relay.rs
@@ -36,7 +36,7 @@ use crate::transport::{self, HeadsSummary};
 const PULL_TIMEOUT: Duration = Duration::from_secs(15);
 
 /// How long an announcement waits for further changes to ride along. Added once per
-/// hop to propagation; well below a round trip over Mycelium.
+/// hop to propagation; well below a round trip over the transport.
 const ANNOUNCE_DELAY: Duration = Duration::from_millis(200);
 
 /// After changes from `from` were applied and our heads changed: tell our other
diff --git a/src/swarm/source.rs b/src/swarm/source.rs
index e7f06fb..699b03b 100644
--- a/src/swarm/source.rs
+++ b/src/swarm/source.rs
@@ -5,9 +5,9 @@
 //! document gets the whole document from each of its peers, and a node that is merely
 //! behind gets the missing changes from each. Automerge can't deduplicate across peers.
 //! So one suitable peer becomes the source, preferably the closest by round-trip time
-//! (a clearly closer one gets a 1 s head start to claim it, else the first to ask);
-//! the others wait until the initial sync is done, and then only exchange heads. Messages from waiting
-//! peers are still applied; we just don't answer them yet.
+//! (a clearly closer one gets a 1 s head start to claim it, else the first to ask); the
+//! others wait until the initial sync is done, and then only exchange heads. Messages
+//! from waiting peers are still applied; we just don't answer them yet.
 //!
 //! A source must be ready and willing to sync with us, as far as we know (its sync
 //! messages and keepalives say so). It counts as alive while any message from it
@@ -20,14 +20,14 @@
 //! big answer lost on the way, a stuck sync state) would keep us catching up forever.
 //! So it is also given up after three of our sync messages in a row went unanswered,
 //! once nothing from it can still be on the way: no sync message from it for
-//! `Timing::delivery_limit`, after which Mycelium has delivered or dropped anything it
-//! sent before. It isn't chosen again for another `delivery_limit`, so another peer
-//! takes over rather than the same one stalling again; if it is the only candidate,
-//! catching up waits that long before trying it again. It also gets a fresh HELLO: a
-//! joining node learns of other peers only from HELLO_REPLYs, and the one it got from
-//! this peer may have listed none (a peer lists only its neighbours, which a new member
-//! isn't until its registration has spread). Meanwhile, every minute without a sync message from it is logged as a
-//! warning.
+//! `Timing::delivery_limit`, after which the transport has delivered or dropped
+//! anything it sent before. It isn't chosen again for another `delivery_limit`, so
+//! another peer takes over rather than the same one stalling again; if it is the only
+//! candidate, catching up waits that long before trying it again. It also gets a fresh
+//! HELLO: a joining node learns of other peers only from HELLO_REPLYs, and the one it
+//! got from this peer may have listed none (a peer lists only its neighbours, which a
+//! new member isn't until its registration has spread). Meanwhile, every minute without
+//! a sync message from it is logged as a warning.
 
 use std::sync::atomic::Ordering;
 use std::time::Duration;
diff --git a/src/swarm/sync.rs b/src/swarm/sync.rs
index 4e382ec..011f049 100644
--- a/src/swarm/sync.rs
+++ b/src/swarm/sync.rs
@@ -162,7 +162,8 @@ async fn deliver_sync_to_peer(state: &AppState, peer: &str) -> Result<()> {
                             return transport::SyncBody::Message(payload);
                         }
                         // Too large for one message: all or nothing, and on a slow link
-                        // within Mycelium's deadline. The peer fetches it in chunks.
+                        // within the transport's delivery limit. The peer fetches it in
+                        // chunks.
                         let from = peer_state.sync.withdraw_for_delta();
                         let spec = transport::DeltaSpec::new(from, replica.heads().to_vec());
                         info!(
@@ -213,7 +214,7 @@ async fn deliver_sync_to_peer(state: &AppState, peer: &str) -> Result<()> {
         (session, encoded)
     };
 
-    // Off the sync worker: a slow send (a large message, a busy Mycelium) mustn't hold
+    // Off the sync worker: a slow send (a large message, a busy transport) mustn't hold
     // up every other peer's. One message per peer is in flight (`sending`), so a peer's
     // messages still go out in order.
     let state = state.clone();
@@ -240,7 +241,10 @@ async fn send_generated(
         Ok(()) => {
             let regenerate = peer_state_mutex.lock().await.sync.send_succeeded(session);
 
-            trace!(regenerate, "Outbound sync message accepted by Mycelium");
+            trace!(
+                regenerate,
+                "Outbound sync message accepted by the transport"
+            );
 
             if regenerate {
                 state
diff --git a/src/swarm/throughput.rs b/src/swarm/throughput.rs
index f1b9b14..85a3fc8 100644
--- a/src/swarm/throughput.rs
+++ b/src/swarm/throughput.rs
@@ -19,7 +19,7 @@ use tokio::time::Instant;
 
 use crate::transport::traffic::Traffic;
 
-/// Smallest exchange that counts: some dozens of Mycelium chunks.
+/// Smallest exchange that counts: some dozens of small packets (Mycelium's: 1300 bytes).
 const MIN_BYTES: u64 = 32 * 1024;
 const WEIGHT: f64 = 0.25;