test: add test for Instant serialization

src/api/server.rs

@@ -1,3 +1,47 @@
+//! # API Server
+//!
+//! HTTP server for the tracker HTTP API.
+//!
+//! Endpoint example: 
+//!
+//! GET /api/torrent/:info_hash
+//!
+//! Get torrent details.
+//!
+//! ```s
+//! curl -s http://127.0.0.1:1212/api/torrent/4beb7001cb833968582c67f55cc59dcc6c8d3fe5?token=MyAccessToken | jq
+//! ```
+//!
+//! ```json
+//! {
+//!   "info_hash": "4beb7001cb833968582c67f55cc59dcc6c8d3fe5",
+//!   "seeders": 1,
+//!   "completed": 0,
+//!   "leechers": 0,
+//!   "peers": [
+//!     {
+//!       "peer_id": {
+//!         "id": "2d7142343431302d7358376d33786d2877674179",
+//!         "client": "qBittorrent"
+//!       },
+//!       "peer_addr": "192.168.1.88:17548",
+//!       "updated": 385,
+//!       "uploaded": 0,
+//!       "downloaded": 0,
+//!       "left": 0,
+//!       "event": "None"
+//!     }
+//!   ]
+//! }
+//! ```
+//!
+//! | Parameter | Description |
+//! |-----------|-------------|
+//! | info_hash | The info_hash of the torrent. |
+//!
+//! The `info_hash.peers.updated` are the number of milliseconds since the last update.
+//!
+
 use std::cmp::min;
 use std::collections::{HashMap, HashSet};
 use std::net::SocketAddr;

src/protocol/utils.rs

@@ -10,12 +10,57 @@ pub fn get_connection_id(remote_address: &SocketAddr) -> ConnectionId {
     }
 }
 
+/// It returns the current time in Unix Epoch.
 pub fn current_time() -> u64 {
     SystemTime::now()
         .duration_since(SystemTime::UNIX_EPOCH).unwrap()
         .as_secs()
 }
 
+/// Serializer for `std::time::Instant` type.
+/// Before serializing, it converts the instant to time elapse since that instant in milliseconds.
+///
+/// You can use it like this:
+///
+/// ```text
+/// #[serde(serialize_with = "ser_instant")]
+/// pub updated: std::time::Instant,
+/// ```
+///
 pub fn ser_instant<S: serde::Serializer>(inst: &std::time::Instant, ser: S) -> Result<S::Ok, S::Error> {
     ser.serialize_u64(inst.elapsed().as_millis() as u64)
 }
+
+#[cfg(test)]
+mod tests {
+    use std::time::Instant;
+    use serde::Serialize;
+
+    #[warn(unused_imports)]
+    use super::ser_instant;
+
+    #[derive(PartialEq, Eq, Debug, Clone, Serialize)]
+    struct S {
+        #[serde(serialize_with = "ser_instant")]
+        pub time: Instant,
+    }
+
+    #[test]
+    fn instant_types_can_be_serialized_as_elapsed_time_since_that_instant_in_milliseconds() {
+
+        use std::{thread, time};
+
+        let t1 = time::Instant::now();
+
+        let s = S { time: t1 };
+
+        // Sleep 10 milliseconds
+        let ten_millis = time::Duration::from_millis(10);
+        thread::sleep(ten_millis);
+
+        let json_serialized_value = serde_json::to_string(&s).unwrap();
+
+        // Json contains time duration since t1 instant in milliseconds
+        assert_eq!(json_serialized_value, r#"{"time":10}"#);
+    }
+}