docs: [torrust#271] crate docs for servers::udp mod

josecelano · Apr 6, 2023 · 44d6afc · 44d6afc
1 parent 6126679
commit 44d6afc
Show file tree

Hide file tree

Showing 8 changed files with 624 additions and 20 deletions.
diff --git a/cSpell.json b/cSpell.json
@@ -1,6 +1,7 @@
 {
     "words": [
         "appuser",
+        "Arvid",
         "AUTOINCREMENT",
         "automock",
         "Avicora",
@@ -21,6 +22,7 @@
         "chrono",
         "clippy",
         "completei",
+        "connectionless",
         "dockerhub",
         "downloadedi",
         "filesd",
@@ -47,6 +49,7 @@
         "nanos",
         "nextest",
         "nocapture",
+        "Norberg",
         "numwant",
         "oneshot",
         "ostr",
@@ -59,6 +62,7 @@
         "reqwest",
         "rerequests",
         "rngs",
+        "routable",
         "rusqlite",
         "rustfmt",
         "Rustls",
@@ -82,6 +86,7 @@
         "Vagaa",
         "Vuze",
         "whitespaces",
+        "XBTT",
         "Xtorrent",
         "Xunlei",
         "xxxxxxxxxxxxxxxxxxxxd",

diff --git a/src/servers/http/mod.rs b/src/servers/http/mod.rs
@@ -43,7 +43,7 @@
 //!
 //! Parameter | Type | Description | Required |  Default | Example
 //! ---|---|---|---|---|---
-//! [`info_hash`](crate::servers::http::v1::requests::announce::Announce::info_hash) | percent encoded of 40-byte array | The `Info Hash` of the torrent. | Yes | No | `%81%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00`
+//! [`info_hash`](crate::servers::http::v1::requests::announce::Announce::info_hash) | percent encoded of 20-byte array | The `Info Hash` of the torrent. | Yes | No | `%81%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00`
 //! `peer_addr` | string |The IP address of the peer. | No | No | `2.137.87.41`
 //! [`downloaded`](crate::servers::http::v1::requests::announce::Announce::downloaded) | positive integer |The number of bytes downloaded by the peer. | No | `0` | `0`
 //! [`uploaded`](crate::servers::http::v1::requests::announce::Announce::uploaded) | positive integer | The number of bytes uploaded by the peer. | No | `0` | `0`
@@ -220,7 +220,7 @@
 //!
 //! Parameter | Type | Description | Required |  Default | Example
 //! ---|---|---|---|---|---
-//! [`info_hash`](crate::servers::http::v1::requests::scrape::Scrape::info_hashes) | percent encoded of 40-byte array | The `Info Hash` of the torrent. | Yes | No | `%81%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00`
+//! [`info_hash`](crate::servers::http::v1::requests::scrape::Scrape::info_hashes) | percent encoded of 20-byte array | The `Info Hash` of the torrent. | Yes | No | `%81%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00`
 //!
 //! > **NOTICE**: you can scrape multiple torrents at the same time by passing
 //! multiple `info_hash` parameters.

diff --git a/src/servers/http/percent_encoding.rs b/src/servers/http/percent_encoding.rs
@@ -19,7 +19,7 @@ use crate::shared::bit_torrent::info_hash::{ConversionError, InfoHash};
 use crate::tracker::peer::{self, IdConversionError};
 
 /// Percent decodes a percent encoded infohash. Internally an
-/// [`InfoHash`](crate::shared::bit_torrent::info_hash::InfoHash) is a 40-byte array.
+/// [`InfoHash`](crate::shared::bit_torrent::info_hash::InfoHash) is a 20-byte array.
 ///
 /// For example, given the infohash `3b245504cf5f11bbdbe1201cea6a6bf45aee1bc0`,
 /// it's percent encoded representation is `%3B%24U%04%CF%5F%11%BB%DB%E1%20%1C%EAjk%F4Z%EE%1B%C0`.

diff --git a/src/servers/http/v1/requests/announce.rs b/src/servers/http/v1/requests/announce.rs
@@ -88,7 +88,7 @@ pub struct Announce {
 /// Errors that can occur when parsing the `Announce` request.
 ///
 /// The `info_hash` and `peer_id` query params are special because they contain
-/// binary data. The `info_hash` is a 40-byte SHA1 hash and the `peer_id` is a
+/// binary data. The `info_hash` is a 20-byte SHA1 hash and the `peer_id` is a
 /// 20-byte array.
 #[derive(Error, Debug)]
 pub enum ParseAnnounceQueryError {

diff --git a/src/servers/signals.rs b/src/servers/signals.rs
@@ -1,4 +1,4 @@
-/// This module contains functions to handle signals.
+//! This module contains functions to handle signals.
 use log::info;
 
 /// Resolves on `ctrl_c` or the `terminate` signal.

diff --git a/src/servers/udp/handlers.rs b/src/servers/udp/handlers.rs
@@ -56,15 +56,19 @@ pub async fn handle_request(request: Request, remote_addr: SocketAddr, tracker:
 
 /// # Errors
 ///
-/// This function dose not ever return an error.
+/// This function does not ever return an error.
 pub async fn handle_connect(remote_addr: SocketAddr, request: &ConnectRequest, tracker: &Tracker) -> Result<Response, Error> {
+    debug!("udp connect request: {:#?}", request);
+
     let connection_cookie = make(&remote_addr);
     let connection_id = into_connection_id(&connection_cookie);
 
-    let response = Response::from(ConnectResponse {
+    let response = ConnectResponse {
         transaction_id: request.transaction_id,
         connection_id,
-    });
+    };
+
+    debug!("udp connect response: {:#?}", response);
 
     // send stats event
     match remote_addr {
@@ -76,7 +80,7 @@ pub async fn handle_connect(remote_addr: SocketAddr, request: &ConnectRequest, t
         }
     }
 
-    Ok(response)
+    Ok(Response::from(response))
 }
 
 /// # Errors
@@ -124,8 +128,8 @@ pub async fn handle_announce(
     }
 
     #[allow(clippy::cast_possible_truncation)]
-    let announce_response = if remote_addr.is_ipv4() {
-        Response::from(AnnounceResponse {
+    if remote_addr.is_ipv4() {
+        let announce_response = AnnounceResponse {
             transaction_id: wrapped_announce_request.announce_request.transaction_id,
             announce_interval: AnnounceInterval(i64::from(tracker.config.announce_interval) as i32),
             leechers: NumberOfPeers(i64::from(response.swarm_stats.leechers) as i32),
@@ -144,9 +148,13 @@ pub async fn handle_announce(
                     }
                 })
                 .collect(),
-        })
+        };
+
+        debug!("udp announce response: {:#?}", announce_response);
+
+        Ok(Response::from(announce_response))
     } else {
-        Response::from(AnnounceResponse {
+        let announce_response = AnnounceResponse {
             transaction_id: wrapped_announce_request.announce_request.transaction_id,
             announce_interval: AnnounceInterval(i64::from(tracker.config.announce_interval) as i32),
             leechers: NumberOfPeers(i64::from(response.swarm_stats.leechers) as i32),
@@ -165,16 +173,20 @@ pub async fn handle_announce(
                     }
                 })
                 .collect(),
-        })
-    };
+        };
 
-    Ok(announce_response)
+        debug!("udp announce response: {:#?}", announce_response);
+
+        Ok(Response::from(announce_response))
+    }
 }
 
 /// # Errors
 ///
-/// This function dose not ever return an error.
+/// This function does not ever return an error.
 pub async fn handle_scrape(remote_addr: SocketAddr, request: &ScrapeRequest, tracker: &Tracker) -> Result<Response, Error> {
+    debug!("udp scrape request: {:#?}", request);
+
     // Convert from aquatic infohashes
     let mut info_hashes = vec![];
     for info_hash in &request.info_hashes {
@@ -217,10 +229,14 @@ pub async fn handle_scrape(remote_addr: SocketAddr, request: &ScrapeRequest, tra
         }
     }
 
-    Ok(Response::from(ScrapeResponse {
+    let response = ScrapeResponse {
         transaction_id: request.transaction_id,
         torrent_stats,
-    }))
+    };
+
+    debug!("udp scrape response: {:#?}", response);
+
+    Ok(Response::from(response))
 }
 
 fn handle_error(e: &Error, transaction_id: TransactionId) -> Response {