improve ws protocol struct naming and documentation

crates/ws/src/workers/socket.rs

@@ -906,8 +906,8 @@ impl<S: futures::AsyncRead + futures::AsyncWrite + Unpin> ConnectionWriter<S> {
                 #[cfg(feature = "metrics")]
                 {
                     let out_message_type = match &out_message {
-                        OutMessage::Offer(_) => "offer",
+                        OutMessage::OfferOutMessage(_) => "offer",
-                        OutMessage::Answer(_) => "offer_answer",
+                        OutMessage::AnswerOutMessage(_) => "offer_answer",
                         OutMessage::AnnounceResponse(_) => "announce",
                         OutMessage::ScrapeResponse(_) => "scrape",
                         OutMessage::ErrorResponse(_) => "error",

crates/ws/src/workers/swarm.rs

@@ -443,7 +443,7 @@ fn handle_announce_request(
         );
 
         for (offer, offer_receiver) in offers.into_iter().zip(offer_receivers) {
-            let middleman_offer = MiddlemanOfferToPeer {
+            let offer_out_message = OfferOutMessage {
                 action: AnnounceAction,
                 info_hash: request.info_hash,
                 peer_id: request.peer_id,
@@ -457,17 +457,19 @@ fn handle_announce_request(
                 pending_scrape_id: None,
             };
 
-            out_messages.push((meta, OutMessage::Offer(middleman_offer)));
+            out_messages.push((meta, OutMessage::OfferOutMessage(offer_out_message)));
             ::log::trace!("sending middleman offer to {:?}", meta);
         }
     }
 
     // If peer sent answer, send it on to relevant peer
-    if let (Some(answer), Some(answer_receiver_id), Some(offer_id)) =
+    if let (Some(answer), Some(answer_receiver_id), Some(offer_id)) = (
-        (request.answer, request.to_peer_id, request.offer_id)
+        request.answer,
-    {
+        request.answer_to_peer_id,
+        request.answer_offer_id,
+    ) {
         if let Some(answer_receiver) = torrent_data.peers.get(&answer_receiver_id) {
-            let middleman_answer = MiddlemanAnswerToPeer {
+            let answer_out_message = AnswerOutMessage {
                 action: AnnounceAction,
                 peer_id: request.peer_id,
                 info_hash: request.info_hash,
@@ -481,7 +483,7 @@ fn handle_announce_request(
                 pending_scrape_id: None,
             };
 
-            out_messages.push((meta, OutMessage::Answer(middleman_answer)));
+            out_messages.push((meta, OutMessage::AnswerOutMessage(answer_out_message)));
             ::log::trace!("sending middleman answer to {:?}", meta);
         }
     }

crates/ws_load_test/src/network.rs

@@ -6,7 +6,7 @@ use std::{
     time::Duration,
 };
 
-use aquatic_ws_protocol::{InMessage, JsonValue, OfferId, OutMessage, PeerId};
+use aquatic_ws_protocol::{InMessage, OfferId, OutMessage, PeerId, RtcAnswer};
 use async_tungstenite::{client_async, WebSocketStream};
 use futures::{SinkExt, StreamExt};
 use futures_rustls::{client::TlsStream, TlsConnector};
@@ -131,11 +131,13 @@ impl Connection {
                 // the request an offer answer
                 let request = if let InMessage::AnnounceRequest(mut r) = request {
                     if let Some((peer_id, offer_id)) = self.send_answer {
-                        r.to_peer_id = Some(peer_id);
+                        r.answer_to_peer_id = Some(peer_id);
-                        r.offer_id = Some(offer_id);
+                        r.answer_offer_id = Some(offer_id);
-                        r.answer = Some(JsonValue(::serde_json::json!(
+                        r.answer = Some(RtcAnswer {
-                            {"sdp": "abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-"}
+                            sdp: ::serde_json::json!(
-                        )));
+                                {"sdp": "abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-"}
+                            ),
+                        });
                         r.event = None;
                         r.offers = None;
                     }
@@ -182,7 +184,7 @@ impl Connection {
         };
 
         match OutMessage::from_ws_message(message) {
-            Ok(OutMessage::Offer(offer)) => {
+            Ok(OutMessage::OfferOutMessage(offer)) => {
                 self.load_test_state
                     .statistics
                     .responses_offer
@@ -192,7 +194,7 @@ impl Connection {
 
                 self.can_send = true;
             }
-            Ok(OutMessage::Answer(_)) => {
+            Ok(OutMessage::AnswerOutMessage(_)) => {
                 self.load_test_state
                     .statistics
                     .responses_answer

crates/ws_load_test/src/utils.rs

@@ -50,9 +50,11 @@ fn create_announce_request(
     for _ in 0..config.torrents.offers_per_request {
         offers.push(AnnounceRequestOffer {
             offer_id: OfferId(rng.gen()),
-            offer: JsonValue(::serde_json::json!(
+            offer: RtcOffer {
-                {"sdp": "abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-"}
+                sdp: ::serde_json::json!(
-            )),
+                    {"sdp": "abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-abcdefg-"}
+                )
+            },
         })
     }
 
@@ -65,8 +67,8 @@ fn create_announce_request(
         numwant: Some(offers.len()),
         offers: Some(offers),
         answer: None,
-        to_peer_id: None,
+        answer_to_peer_id: None,
-        offer_id: None,
+        answer_offer_id: None,
     })
 }
 

crates/ws_protocol/benches/bench_deserialize_announce_request.rs

@@ -15,7 +15,9 @@ pub fn bench(c: &mut Criterion) {
             offer_id.0[i] = i as u8;
 
             AnnounceRequestOffer {
-                offer: JsonValue(::serde_json::json!({ "sdp": "abcdef" })),
+                offer: RtcOffer {
+                    sdp: ::serde_json::json!({ "sdp": "abcdef" }),
+                },
                 offer_id,
             }
         })
@@ -30,9 +32,11 @@ pub fn bench(c: &mut Criterion) {
         event: Some(AnnounceEvent::Started),
         offers: Some(offers),
         numwant: Some(offers_len),
-        answer: Some(JsonValue(::serde_json::json!({ "sdp": "abcdef" }))),
+        answer: Some(RtcAnswer {
-        to_peer_id: Some(peer_id),
+            sdp: ::serde_json::json!({ "sdp": "abcdef" }),
-        offer_id: Some(OfferId(info_hash.0)),
+        }),
+        answer_to_peer_id: Some(peer_id),
+        answer_offer_id: Some(OfferId(info_hash.0)),
     });
 
     let ws_message = request.to_ws_message();

crates/ws_protocol/src/common.rs

@@ -30,10 +30,21 @@ pub struct OfferId(
     pub [u8; 20],
 );
 
-/// Some kind of nested structure from https://www.npmjs.com/package/simple-peer
+/// Nested structure with SDP offer from https://www.npmjs.com/package/simple-peer
+///
+/// Created using https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/createOffer
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(transparent)]
+pub struct RtcOffer {
-pub struct JsonValue(pub ::serde_json::Value);
+    pub sdp: ::serde_json::Value,
+}
+
+/// Nested structure with SDP answer from https://www.npmjs.com/package/simple-peer
+///
+/// Created using https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/createAnswer
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RtcAnswer {
+    pub sdp: ::serde_json::Value,
+}
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AnnounceAction;

crates/ws_protocol/src/incoming/announce.rs

@@ -0,0 +1,80 @@
+use serde::{Deserialize, Serialize};
+
+use crate::common::*;
+
+/// Announce request
+///
+/// Can optionally contain:
+/// - A number of WebRTC offers to be sent on to other peers. In this case,
+///   fields 'offers' and 'numwant' are set
+/// - An answer to a WebRTC offer from another peer. In this case, fields
+///   'answer', 'to_peer_id' and 'offer_id' are set.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AnnounceRequest {
+    /// Always "announce"
+    pub action: AnnounceAction,
+    pub info_hash: InfoHash,
+    pub peer_id: PeerId,
+    /// Bytes left
+    ///
+    /// Just called "left" in protocol. Is set to None in some cases, such as
+    /// when opening a magnet link
+    #[serde(rename = "left")]
+    pub bytes_left: Option<usize>,
+    /// Can be empty. Then, default is "update"
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub event: Option<AnnounceEvent>,
+
+    /// WebRTC offers (with offer id's) that peer wants sent on to random other peers
+    ///
+    /// Notes from reference implementation:
+    /// - Only when this is an array offers are sent to other peers
+    /// - Length of this is number of peers wanted?
+    /// - Max length of this is 10 in reference client code
+    /// - Not sent when announce event is stopped or completed
+    pub offers: Option<Vec<AnnounceRequestOffer>>,
+    /// Number of peers wanted
+    ///
+    /// Notes from reference implementation:
+    /// - Seems to only get sent by client when sending offers, and is also
+    ///   same as length of offers vector (or at least never smaller)
+    /// - Max length of this is 10 in reference client code
+    /// - Could probably be ignored, `offers.len()` should provide needed info
+    pub numwant: Option<usize>,
+
+    /// WebRTC answer to previous offer from other peer, to be passed on to it
+    ///
+    /// Notes from reference implementation:
+    /// - If empty, send response before sending offers (or possibly "skip
+    ///   sending update back"?)
+    /// - Else, send AnswerOutMessage to peer with "to_peer_id" as peer_id
+    pub answer: Option<RtcAnswer>,
+    /// Which peer to send answer to
+    #[serde(rename = "to_peer_id")]
+    pub answer_to_peer_id: Option<PeerId>,
+    /// OfferID of offer this is an answer to
+    #[serde(rename = "offer_id")]
+    pub answer_offer_id: Option<OfferId>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum AnnounceEvent {
+    Started,
+    Stopped,
+    Completed,
+    Update,
+}
+
+impl Default for AnnounceEvent {
+    fn default() -> Self {
+        Self::Update
+    }
+}
+
+/// Element of AnnounceRequest.offers
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AnnounceRequestOffer {
+    pub offer: RtcOffer,
+    pub offer_id: OfferId,
+}

crates/ws_protocol/src/incoming/scrape.rs

@@ -2,6 +2,19 @@ use serde::{Deserialize, Serialize};
 
 use crate::common::*;
 
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ScrapeRequest {
+    /// Always "scrape"
+    pub action: ScrapeAction,
+    /// Info hash or info hashes
+    ///
+    /// Notes from reference implementation:
+    /// - If omitted, scrape for all torrents, apparently
+    /// - Accepts a single info hash or an array of info hashes
+    #[serde(rename = "info_hash")]
+    pub info_hashes: Option<ScrapeRequestInfoHashes>,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(untagged)]
 pub enum ScrapeRequestInfoHashes {
@@ -17,13 +30,3 @@ impl ScrapeRequestInfoHashes {
         }
     }
 }
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct ScrapeRequest {
-    pub action: ScrapeAction,
-    // If omitted, scrape for all torrents, apparently
-    // There is some kind of parsing here too which accepts a single info hash
-    // and puts it into a vector
-    #[serde(rename = "info_hash")]
-    pub info_hashes: Option<ScrapeRequestInfoHashes>,
-}

crates/ws_protocol/src/lib.rs

@@ -11,12 +11,12 @@
 //! - Peer sends scrape request and receives scrape response
 
 pub mod common;
-pub mod request;
+pub mod incoming;
-pub mod response;
+pub mod outgoing;
 
 pub use common::*;
-pub use request::*;
+pub use incoming::*;
-pub use response::*;
+pub use outgoing::*;
 
 #[cfg(test)]
 mod tests {
@@ -35,8 +35,15 @@ mod tests {
         bytes
     }
 
-    fn sdp_json_value() -> JsonValue {
+    fn rtc_offer() -> RtcOffer {
-        JsonValue(::serde_json::json!({ "sdp": "test" }))
+        RtcOffer {
+            sdp: ::serde_json::json!({ "sdp": "test" }),
+        }
+    }
+    fn rtc_answer() -> RtcAnswer {
+        RtcAnswer {
+            sdp: ::serde_json::json!({ "sdp": "test" }),
+        }
     }
 
     impl Arbitrary for InfoHash {
@@ -68,26 +75,26 @@ mod tests {
         }
     }
 
-    impl Arbitrary for MiddlemanOfferToPeer {
+    impl Arbitrary for OfferOutMessage {
         fn arbitrary(g: &mut quickcheck::Gen) -> Self {
             Self {
                 action: AnnounceAction,
                 peer_id: Arbitrary::arbitrary(g),
                 info_hash: Arbitrary::arbitrary(g),
                 offer_id: Arbitrary::arbitrary(g),
-                offer: sdp_json_value(),
+                offer: rtc_offer(),
             }
         }
     }
 
-    impl Arbitrary for MiddlemanAnswerToPeer {
+    impl Arbitrary for AnswerOutMessage {
         fn arbitrary(g: &mut quickcheck::Gen) -> Self {
             Self {
                 action: AnnounceAction,
                 peer_id: Arbitrary::arbitrary(g),
                 info_hash: Arbitrary::arbitrary(g),
                 offer_id: Arbitrary::arbitrary(g),
-                answer: sdp_json_value(),
+                answer: rtc_answer(),
             }
         }
     }
@@ -96,7 +103,7 @@ mod tests {
         fn arbitrary(g: &mut quickcheck::Gen) -> Self {
             Self {
                 offer_id: Arbitrary::arbitrary(g),
-                offer: sdp_json_value(),
+                offer: rtc_offer(),
             }
         }
     }
@@ -106,7 +113,7 @@ mod tests {
             let has_offers_or_answer_or_neither: Option<bool> = Arbitrary::arbitrary(g);
 
             let mut offers: Option<Vec<AnnounceRequestOffer>> = None;
-            let mut answer: Option<JsonValue> = None;
+            let mut answer: Option<RtcAnswer> = None;
             let mut to_peer_id: Option<PeerId> = None;
             let mut offer_id: Option<OfferId> = None;
 
@@ -115,7 +122,7 @@ mod tests {
                     offers = Some(Arbitrary::arbitrary(g));
                 }
                 Some(false) => {
-                    answer = Some(sdp_json_value());
+                    answer = Some(rtc_answer());
                     to_peer_id = Some(Arbitrary::arbitrary(g));
                     offer_id = Some(Arbitrary::arbitrary(g));
                 }
@@ -133,8 +140,8 @@ mod tests {
                 offers,
                 numwant,
                 answer,
-                to_peer_id,
+                answer_to_peer_id: to_peer_id,
-                offer_id,
+                answer_offer_id: offer_id,
             }
         }
     }
@@ -206,8 +213,8 @@ mod tests {
             match (Arbitrary::arbitrary(g), Arbitrary::arbitrary(g)) {
                 (false, false) => Self::AnnounceResponse(Arbitrary::arbitrary(g)),
                 (true, false) => Self::ScrapeResponse(Arbitrary::arbitrary(g)),
-                (false, true) => Self::Offer(Arbitrary::arbitrary(g)),
+                (false, true) => Self::OfferOutMessage(Arbitrary::arbitrary(g)),
-                (true, true) => Self::Answer(Arbitrary::arbitrary(g)),
+                (true, true) => Self::AnswerOutMessage(Arbitrary::arbitrary(g)),
             }
         }
     }

crates/ws_protocol/src/outgoing/announce.rs

@@ -2,6 +2,7 @@ use serde::{Deserialize, Serialize};
 
 use crate::common::*;
 
+/// Plain response to an AnnounceRequest
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct AnnounceResponse {
     pub action: AnnounceAction,

crates/ws_protocol/src/outgoing/answer.rs

@@ -2,15 +2,16 @@ use serde::{Deserialize, Serialize};
 
 use crate::common::*;
 
-/// If announce request has answer = true, send this to peer with
+/// Message sent to peer when other peer has replied to its WebRTC offer
-/// peer id == "to_peer_id" field
+///
-/// Action field should be 'announce'
+/// Sent if fields answer, to_peer_id and offer_id are set in announce request
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct MiddlemanAnswerToPeer {
+pub struct AnswerOutMessage {
+    /// Always "announce"
     pub action: AnnounceAction,
     /// Note: if equal to client peer_id, client ignores answer
     pub peer_id: PeerId,
     pub info_hash: InfoHash,
-    pub answer: JsonValue,
+    pub answer: RtcAnswer,
     pub offer_id: OfferId,
 }

crates/ws_protocol/src/outgoing/error.rs

@@ -4,13 +4,6 @@ use serde::{Deserialize, Serialize};
 
 use crate::common::*;
 
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "lowercase")]
-pub enum ErrorResponseAction {
-    Announce,
-    Scrape,
-}
-
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct ErrorResponse {
     #[serde(rename = "failure reason")]
@@ -22,3 +15,10 @@ pub struct ErrorResponse {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub info_hash: Option<InfoHash>,
 }
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ErrorResponseAction {
+    Announce,
+    Scrape,
+}

crates/ws_protocol/src/outgoing/mod.rs

@@ -16,8 +16,8 @@ pub use scrape::*;
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(untagged)]
 pub enum OutMessage {
-    Offer(MiddlemanOfferToPeer),
+    OfferOutMessage(OfferOutMessage),
-    Answer(MiddlemanAnswerToPeer),
+    AnswerOutMessage(AnswerOutMessage),
     AnnounceResponse(AnnounceResponse),
     ScrapeResponse(ScrapeResponse),
     ErrorResponse(ErrorResponse),

crates/ws_protocol/src/outgoing/offer.rs

@@ -2,18 +2,21 @@ use serde::{Deserialize, Serialize};
 
 use crate::common::*;
 
-/// Apparently, these are sent to a number of peers when they are set
+/// Message sent to peer when other peer wants to initiate a WebRTC connection
-/// in an AnnounceRequest
+///
-/// action = "announce"
+/// One is sent for each offer in an announce request
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct MiddlemanOfferToPeer {
+pub struct OfferOutMessage {
+    /// Always "announce"
     pub action: AnnounceAction,
     /// Peer id of peer sending offer
-    /// Note: if equal to client peer_id, client ignores offer
+    ///
+    /// Note: if equal to client peer_id, reference client ignores offer
     pub peer_id: PeerId,
+    /// Torrent info hash
     pub info_hash: InfoHash,
     /// Gets copied from AnnounceRequestOffer
-    pub offer: JsonValue,
+    pub offer: RtcOffer,
     /// Gets copied from AnnounceRequestOffer
     pub offer_id: OfferId,
 }

crates/ws_protocol/src/outgoing/scrape.rs

@@ -7,7 +7,7 @@ use crate::common::*;
 pub struct ScrapeResponse {
     pub action: ScrapeAction,
     pub files: HashMap<InfoHash, ScrapeStatistics>,
-    // Looks like `flags` field is ignored in reference client
+    // It looks like `flags` field is ignored in reference client
     // pub flags: HashMap<String, usize>,
 }
 

crates/ws_protocol/src/request/announce.rs

@@ -1,60 +0,0 @@
-use serde::{Deserialize, Serialize};
-
-use crate::common::*;
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "lowercase")]
-pub enum AnnounceEvent {
-    Started,
-    Stopped,
-    Completed,
-    Update,
-}
-
-impl Default for AnnounceEvent {
-    fn default() -> Self {
-        Self::Update
-    }
-}
-
-/// Element of AnnounceRequest.offers
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct AnnounceRequestOffer {
-    pub offer: JsonValue,
-    pub offer_id: OfferId,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct AnnounceRequest {
-    pub action: AnnounceAction,
-    pub info_hash: InfoHash,
-    pub peer_id: PeerId,
-    /// Just called "left" in protocol. Is set to None in some cases, such as
-    /// when opening a magnet link
-    #[serde(rename = "left")]
-    pub bytes_left: Option<usize>,
-    /// Can be empty. Then, default is "update"
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub event: Option<AnnounceEvent>,
-
-    /// Only when this is an array offers are sent to random peers
-    /// Length of this is number of peers wanted?
-    /// Max length of this is 10 in reference client code
-    /// Not sent when announce event is stopped or completed
-    pub offers: Option<Vec<AnnounceRequestOffer>>,
-    /// Seems to only get sent by client when sending offers, and is also same
-    /// as length of offers vector (or at least never less)
-    /// Max length of this is 10 in reference client code
-    /// Could probably be ignored, `offers.len()` should provide needed info
-    pub numwant: Option<usize>,
-
-    /// If empty, send response before sending offers (or possibly "skip sending update back"?)
-    /// Else, send MiddlemanAnswerToPeer to peer with "to_peer_id" as peer_id.
-    /// I think using Option is good, it seems like this isn't always set
-    /// (same as `offers`)
-    pub answer: Option<JsonValue>,
-    /// Likely undefined if !(answer == true)
-    pub to_peer_id: Option<PeerId>,
-    /// Sent if answer is set
-    pub offer_id: Option<OfferId>,
-}