Merge pull request #1 from 0x6b/specify-timeout

feat: specify ping timeout

Author: 0x6b

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "rgtping"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 description = "ping(8) equivalent for GTPv1-U (3GPP TS 29.281)."
 authors = ["kaoru <[email protected]>"]

Cargo.toml

@@ -8,40 +8,50 @@ ping(8) equivalent for GTPv1-U (3GPP TS 29.281).
 ## Features
 
 - Send GTPv1-U Echo request to multiple endpoints simultaneously.
-- Output is an array of JSON objects, one for each endpoint e.g.
+  - Output is an array of JSON objects, one for each endpoint e.g.
     ```json5
     [
       {
-        "target": "192.168.205.10:2152",
-        "sent": 10, // Number of packets sent
-        "received": 10, // Number of packets received
-        "packet_loss_percentage": 0.0, // Packet loss percentage
-        "duplicate_packets": 0, // Number of duplicate packets
-        "refused_packets": 0, // Number of refused packets (maybe incorrect)
-        "duration": 10164.467290999999, // Total duration in milliseconds
-        "min": 0.0, // Minimum RTT in milliseconds
-        "max": 53.558417, // Maximum RTT in milliseconds
-        "avg": 13.0501917, // Average RTT in milliseconds
-        "mdev": 14.24073989248037, // Standard deviation of RTT in milliseconds
-        "epoch_ms": 1726323245070 // epoch time of the start of the operation, in milliseconds
+        "target": "192.168.205.10:2152", /// Gtping target IP address
+        "epoch_ms": 1726372276714, /// Epoch time of the start of the command, in milliseconds
+        "duration": 3026.165084, /// Total duration in milliseconds
+        "sent": 3, /// Number of sent packets (including lost)
+        "received": 3, /// Number of received packets
+        "packet_loss_percentage": 0.0, /// Packet loss percentage
+        "duplicate_packets": 0, /// Number of duplicate packets
+        "refused_packets": 0, /// Number of refused packets
+        "min": 0.0, /// Minimum RTT in milliseconds
+        "max": 14.750917000000001, /// Maximum RTT in milliseconds
+        "avg": 5.607903, /// Average RTT in milliseconds
+        "mdev": 6.4650903803150355 /// Mean deviation of RTT in milliseconds
       }
+      // ...
     ]
     ```
 
 ## Usage
 
 ```console
-$ rgtping --help
+ping(8) equivalent for GTPv1-U (3GPP TS 29.281).
+
 Usage: rgtping [OPTIONS] [TARGET_IPS]...
 
 Arguments:
-  [TARGET_IPS]...  Array of IP address and port number (IP:port) to ping [default: 192.168.205.10:2152]
+  [TARGET_IPS]...  Array of IP address and port number (IP:port) to ping, delimited
+                   by a space
 
 Options:
-  -c, --count <COUNT>              Number of pings to send [default: 5]
-  -i, --interval-ms <INTERVAL_MS>  Interval between pings in milliseconds [default: 1000]
-  -h, --help                       Print help
-  -V, --version                    Print version
+  -c, --count <COUNT>
+          Number of pings to send [default: 5]
+  -i, --interval-ms <INTERVAL_MS>
+          Interval between pings in milliseconds [default: 1000]
+  -W, --timeout-ms <TIMEOUT_MS>
+          Time to wait for a response, in milliseconds. 0 means wait indefinitely
+          [default: 10000]
+  -h, --help
+          Print help
+  -V, --version
+          Print version
 ```
 
 ## Acknowledgement

README.md

@@ -2,22 +2,29 @@ use std::net::SocketAddr;
 
 use clap::Parser;
 
+/// Command line arguments
 #[derive(Debug, Parser)]
 #[clap(author, version, about)]
 pub struct Args {
     /// Array of IP address and port number (IP:port) to ping, delimited by a space
-    #[arg(default_value = "192.168.205.10:2152", value_delimiter = ' ')]
+    #[arg(value_delimiter = ' ')]
     pub target_ips: Vec<SocketAddr>,
     /// Number of pings to send
     #[arg(short, long, default_value = "5")]
     pub count: u64,
     /// Interval between pings in milliseconds
     #[arg(short, long, default_value = "1000")]
     pub interval_ms: u64,
+    /// Time to wait for a response, in milliseconds. 0 means wait indefinitely.
+    #[arg(short = 'W', long, default_value = "10000")]
+    pub timeout_ms: u64,
 }
 
 impl Args {
-    pub fn new() -> Self {
+    /// Parse command line arguments and return the result. It's just a wrapper around
+    /// `clap::Parser::parse()` so that we can call it from the `main()` function without importing
+    /// `clap` at the top level.
+    pub fn from_cli() -> Self {
         Args::parse()
     }
 }

src/args.rs

@@ -1,25 +1,30 @@
 mod args;
 
-use anyhow::Error;
+use anyhow::{Error, Result};
 use args::Args;
 use env_logger::Env;
 use rgtping::{Pinger, Stats};
 use tokio::spawn;
 
 #[tokio::main]
-async fn main() -> anyhow::Result<()> {
+async fn main() -> Result<()> {
     env_logger::Builder::from_env(Env::default().default_filter_or("info")).init();
-    let args = Args::new();
+    let args = Args::from_cli();
 
+    // Holds the pinger instances
     let mut pingers = Vec::with_capacity(args.target_ips.len());
+    // Holds the handles to the spawned threads which actually send the pings
     let mut handles = Vec::with_capacity(args.target_ips.len());
+    // Holds the results of the pings from each handle
     let mut results = Vec::with_capacity(args.target_ips.len());
 
+    // Create a pinger for each target IP
     for target in args.target_ips {
-        let pinger = Pinger::new(target, args.count, args.interval_ms).await?;
+        let pinger = Pinger::new(target, args.count, args.interval_ms, args.timeout_ms).await?;
         pingers.push(pinger);
     }
 
+    // Spawn a thread for each pinger to send the pings
     for mut pinger in pingers {
         let handle = spawn(async move {
             pinger.ping().await?;
@@ -28,10 +33,12 @@ async fn main() -> anyhow::Result<()> {
         handles.push(handle);
     }
 
+    // Wait for all the threads to finish and collect the results
     for handle in handles {
         results.push(handle.await??);
     }
 
+    // Print the results in JSON format
     println!("{}", serde_json::to_string_pretty(&results)?);
 
     Ok(())

src/main.rs

@@ -1,4 +1,5 @@
 use std::{
+    io,
     net::SocketAddr,
     ops::Add,
     time::{Duration, SystemTime},
@@ -16,6 +17,8 @@ use crate::Stats;
 
 const TRACK_PINGS_SIZE: usize = 1024;
 
+/// Pinger struct to send and receive GTPv1-U packets. All fields are private, so you can only
+/// create a new instance using the `new` method.
 #[derive(Debug)]
 pub struct Pinger {
     // UDP socket to send and receive GTPv1-U packets
@@ -30,34 +33,50 @@ pub struct Pinger {
     send_buf: Vec<u8>,
     // Internal buffer to store received data
     recv_buf: [u8; 1024],
-    // number of sent packets (including lost)
+    // Number of sent packets (including lost)
     sent: u64,
-    // number of received packets
+    // Number of received packets
     received: u64,
-    // track times needed to send packets for statistics
+    // Array to track times needed to send packets for statistics
     send_times: [f64; TRACK_PINGS_SIZE],
-    // track received packets to detect duplicates
+    // Array to track received packets to detect duplicates
     received_packets: [u64; TRACK_PINGS_SIZE],
-    // number of duplicate packets
+    // Number of duplicate packets
     duplicate_packets: u64,
-    // number of refused packets
+    // Number of refused packets
     refused_packets: u64,
-    // epoch time of the start of the operation, in milliseconds
+    // Epoch time of the start of the operation, in milliseconds
     epoch_ms: u128,
-    // start time of the command for statistics
+    // Start time of the command for statistics
     start_time: Instant,
-    // last ping time to calculate RTT
+    // Last ping time to calculate RTT
     last_ping_time: Instant,
-    // last receive time to calculate RTT
+    // Last receive time to calculate RTT
     last_receive_time: Instant,
-    // interval between pings in milliseconds
-    interval_ms: Duration,
-    // number of pings to send
+    // Interval between pings in milliseconds
+    interval: Duration,
+    // Time to wait for a response in milliseconds
+    timeout: Duration,
+    // Number of pings to send
     count: u64,
 }
 
 impl Pinger {
-    pub async fn new(peer: SocketAddr, count: u64, interval_ms: u64) -> Result<Self> {
+    /// Create a new Pinger instance.
+    ///
+    /// # Arguments
+    ///
+    /// - `peer`: [`SocketAddr`] of the peer to ping
+    /// - `count`: Number of pings to send
+    /// - `interval_ms`: Interval between pings in milliseconds
+    /// - `timeout_ms`: Time to wait for a response, in milliseconds. 0 means wait (almost)
+    ///   indefinitely.
+    pub async fn new(
+        peer: SocketAddr,
+        count: u64,
+        interval_ms: u64,
+        timeout_ms: u64,
+    ) -> Result<Self> {
         let mut packet = Gtpv1Header {
             msgtype: ECHO_REQUEST,
             sequence_number: Some(0),
@@ -73,8 +92,8 @@ impl Pinger {
         let pinger = Pinger {
             socket: UdpSocket::bind("0.0.0.0:0").await?,
             peer,
-            seq: 0,
             packet,
+            seq: 0,
             send_buf: Vec::with_capacity(header_size as usize),
             recv_buf: [0; 1024],
             sent: 0,
@@ -87,13 +106,17 @@ impl Pinger {
             start_time: now,
             last_ping_time: now,
             last_receive_time: now,
-            interval_ms: Duration::from_millis(interval_ms),
+            interval: Duration::from_millis(interval_ms),
+            timeout: Duration::from_millis(if timeout_ms == 0 { u64::MAX } else { timeout_ms }),
             count,
         };
         debug!("Pinger created for {}", pinger.peer);
         Ok(pinger)
     }
 
+    /// Send `count` pings to the peer and wait for a response. This method will send a ping, wait
+    /// for a response, and then sleep for `interval` milliseconds. If a response is not received
+    /// within `timeout` milliseconds, the method will continue to the next ping.
     pub async fn ping(&mut self) -> Result<()> {
         debug!("Start pinging for {}", self.peer);
         for _ in 0..self.count {
@@ -114,7 +137,7 @@ impl Pinger {
                     );
                 }
                 Err(e) => {
-                    if e.kind() == std::io::ErrorKind::ConnectionRefused {
+                    if e.kind() == io::ErrorKind::ConnectionRefused {
                         error!("Connection refused");
                     }
                     self.refused_packets += 1;
@@ -127,8 +150,12 @@ impl Pinger {
             self.last_ping_time = Instant::now();
 
             trace!("Waiting for response");
+            // To implement the timeout, we use tokio::select! macro. This macro allows us to
+            // wait for multiple futures to complete, and then execute the branch that completes
+            // first. In this case, we wait for the timeout to expire or for a response to be
+            // received.
             tokio::select! {
-                _ = async { sleep_until(Instant::now().add(self.interval_ms)).await } => {
+                _ = async { sleep_until(Instant::now().add(self.timeout)).await } => {
                     debug!("Timed out");
                 }
                 result = self.socket.recv_from(&mut self.recv_buf) => {
@@ -174,12 +201,12 @@ impl Pinger {
                             }
                             self.received += 1;
 
-                            sleep(self.interval_ms).await;
+                            sleep(self.interval).await;
                         },
                         Err(_) => {
                             error!("Port closed");
                             self.seq += 1;
-                            sleep(self.interval_ms).await;
+                            sleep(self.interval).await;
                             continue;
                         }
                     }
@@ -201,6 +228,7 @@ impl Pinger {
         Ok(())
     }
 
+    /// Calculate statistics from the pings sent and received.
     pub fn calculate_stats(&self) -> Stats {
         let mut min = 0f64;
         let mut max = 0f64;

src/pinger.rs

@@ -2,23 +2,37 @@ use std::fmt::Display;
 
 use serde::Serialize;
 
+/// Holds results from a series of GTP ping commands
 #[derive(Debug, Serialize)]
 pub struct Stats {
+    /// Gtping target IP address
     pub target: String,
+    /// Epoch time of the start of the command, in milliseconds
+    pub epoch_ms: u128,
+    /// Total duration in milliseconds
+    pub duration: f64,
+    /// Number of sent packets (including lost)
     pub sent: u64,
+    /// Number of received packets
     pub received: u64,
+    /// Packet loss percentage
     pub packet_loss_percentage: f64,
+    /// Number of duplicate packets
     pub duplicate_packets: u64,
+    /// Number of refused packets
     pub refused_packets: u64,
-    pub duration: f64,
+    /// Minimum RTT in milliseconds
     pub min: f64,
+    /// Maximum RTT in milliseconds
     pub max: f64,
+    /// Average RTT in milliseconds
     pub avg: f64,
+    /// Mean deviation of RTT in milliseconds
     pub mdev: f64,
-    pub epoch_ms: u128,
 }
 
 impl Display for Stats {
+    /// Formats the statistics in a human-readable format, as close as possible to ping
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         let mut s = String::new();
         s.push('\n');