rperf3-rs 0.6.0

//! UDP packet format with sequence numbers and timestamps for loss/jitter measurement.
//!
//! This module implements a custom packet format for UDP testing that includes:
//! - Sequence numbers for packet loss detection
//! - Timestamps for jitter measurement
//! - Magic marker for packet identification
//!
//! # Packet Format
//!
//! ```text
//! ┌──────────────┬──────────────┬──────────────┬──────────────┐
//! │    Magic     │  Sequence    │  Timestamp   │   Payload    │
//! │   (4 bytes)  │  (8 bytes)   │  (8 bytes)   │  (variable)  │
//! └──────────────┴──────────────┴──────────────┴──────────────┘
//! ```
//!
//! - **Magic**: 0x52504633 ("RPF3" in ASCII) - identifies rperf3 packets
//! - **Sequence**: 64-bit monotonically increasing packet number (big-endian)
//! - **Timestamp**: Send time in microseconds since UNIX epoch (big-endian)
//! - **Payload**: Zero-filled data for throughput testing
//!
//! # Packet Loss Measurement
//!
//! Packet loss is detected by tracking sequence number gaps. If the receiver sees
//! sequences [0, 1, 3, 5], it knows packets 2 and 4 were lost.
//!
//! # Jitter Measurement
//!
//! Jitter is calculated using RFC 3550 (RTP) algorithm:
//! ```text
//! J(i) = J(i-1) + (|D(i-1,i)| - J(i-1)) / 16
//! ```
//! where D(i-1,i) is the difference in relative transit times between packets.
//!
//! # Examples
//!
//! ```
//! use rperf3::udp_packet::{create_packet, parse_packet};
//!
//! // Create a packet with sequence 42 and 1024 bytes of payload
//! let packet = create_packet(42, 1024);
//! assert_eq!(packet.len(), 20 + 1024); // header + payload
//!
//! // Parse the packet
//! let (header, payload) = parse_packet(&packet).expect("Invalid packet");
//! assert_eq!(header.sequence, 42);
//! assert_eq!(payload.len(), 1024);
//! ```

use std::cell::RefCell;
use std::time::{Instant, SystemTime, UNIX_EPOCH};

// Thread-local cache for timestamp optimization
thread_local! {
    static TIMESTAMP_CACHE: RefCell<TimestampCache> = RefCell::new(TimestampCache::new());
}

/// Cache for timestamp to avoid expensive SystemTime::now() calls
#[derive(Debug)]
struct TimestampCache {
    /// Cached timestamp in microseconds
    cached_timestamp_us: u64,
    /// Instant when the cache was last updated
    last_update: Instant,
    /// How often to update the cache (in microseconds)
    update_interval_us: u64,
}

impl TimestampCache {
    fn new() -> Self {
        let now = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("Time went backwards")
            .as_micros() as u64;
        Self {
            cached_timestamp_us: now,
            last_update: Instant::now(),
            update_interval_us: 1000, // Update every 1ms
        }
    }

    /// Get current timestamp, using cache if fresh enough
    fn get_timestamp(&mut self) -> u64 {
        let elapsed_us = self.last_update.elapsed().as_micros() as u64;

        if elapsed_us >= self.update_interval_us {
            // Cache is stale, refresh it
            self.cached_timestamp_us = SystemTime::now()
                .duration_since(UNIX_EPOCH)
                .expect("Time went backwards")
                .as_micros() as u64;
            self.last_update = Instant::now();
            self.cached_timestamp_us
        } else {
            // Use cached value with estimated microseconds elapsed
            self.cached_timestamp_us + elapsed_us
        }
    }
}

/// Magic marker to identify rperf3 UDP packets
const RPERF3_UDP_MAGIC: u32 = 0x52504633; // "RPF3" in ASCII

/// UDP packet header with sequence number and timing information
///
/// This header is prepended to UDP payload to enable packet loss and jitter measurement.
/// The format is:
/// ```text
/// | Magic (4 bytes) | Sequence (8 bytes) | Timestamp (8 bytes) | Payload (variable) |
/// ```
#[derive(Debug, Clone, Copy)]
pub struct UdpPacketHeader {
    /// Magic marker to identify rperf3 packets
    pub magic: u32,
    /// Packet sequence number (monotonically increasing)
    pub sequence: u64,
    /// Send timestamp in microseconds since UNIX epoch
    pub timestamp_us: u64,
}

impl UdpPacketHeader {
    /// Size of the header in bytes
    pub const SIZE: usize = 20; // 4 (magic) + 8 (sequence) + 8 (timestamp)

    /// Creates a new UDP packet header
    ///
    /// # Arguments
    ///
    /// * `sequence` - Packet sequence number
    /// * `timestamp_us` - Send timestamp in microseconds
    ///
    /// # Examples
    ///
    /// ```
    /// use rperf3::udp_packet::UdpPacketHeader;
    ///
    /// let header = UdpPacketHeader::new(42, 1234567890);
    /// assert_eq!(header.sequence, 42);
    /// assert_eq!(header.timestamp_us, 1234567890);
    /// ```
    pub fn new(sequence: u64, timestamp_us: u64) -> Self {
        Self {
            magic: RPERF3_UDP_MAGIC,
            sequence,
            timestamp_us,
        }
    }

    /// Creates a header with the current timestamp
    ///
    /// # Arguments
    ///
    /// * `sequence` - Packet sequence number
    ///
    /// # Examples
    ///
    /// ```
    /// use rperf3::udp_packet::UdpPacketHeader;
    ///
    /// let header = UdpPacketHeader::with_current_time(100);
    /// assert_eq!(header.sequence, 100);
    /// // Timestamp should be recent (within last 10 seconds)
    /// assert!(header.timestamp_us > 0);
    /// ```
    pub fn with_current_time(sequence: u64) -> Self {
        let timestamp_us = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("Time went backwards")
            .as_micros() as u64;
        Self::new(sequence, timestamp_us)
    }

    /// Serializes the header to bytes (big-endian)
    ///
    /// # Returns
    ///
    /// 20-byte array containing the serialized header
    ///
    /// # Examples
    ///
    /// ```
    /// use rperf3::udp_packet::UdpPacketHeader;
    ///
    /// let header = UdpPacketHeader::new(42, 1234567890);
    /// let bytes = header.to_bytes();
    /// assert_eq!(bytes.len(), 20);
    ///
    /// // Verify round-trip serialization
    /// let parsed = UdpPacketHeader::from_bytes(&bytes).unwrap();
    /// assert_eq!(parsed.sequence, 42);
    /// assert_eq!(parsed.timestamp_us, 1234567890);
    /// ```
    pub fn to_bytes(&self) -> [u8; Self::SIZE] {
        let mut bytes = [0u8; Self::SIZE];
        bytes[0..4].copy_from_slice(&self.magic.to_be_bytes());
        bytes[4..12].copy_from_slice(&self.sequence.to_be_bytes());
        bytes[12..20].copy_from_slice(&self.timestamp_us.to_be_bytes());
        bytes
    }

    /// Deserializes a header from bytes
    ///
    /// # Arguments
    ///
    /// * `bytes` - Byte slice containing at least 20 bytes
    ///
    /// # Returns
    ///
    /// `Some(header)` if magic marker matches, `None` otherwise
    ///
    /// # Examples
    ///
    /// ```
    /// use rperf3::udp_packet::UdpPacketHeader;
    ///
    /// let header = UdpPacketHeader::new(100, 9876543210);
    /// let bytes = header.to_bytes();
    ///
    /// // Parse valid header
    /// let parsed = UdpPacketHeader::from_bytes(&bytes).unwrap();
    /// assert_eq!(parsed.sequence, 100);
    /// assert_eq!(parsed.timestamp_us, 9876543210);
    ///
    /// // Invalid magic marker returns None
    /// let mut bad_bytes = bytes;
    /// bad_bytes[0] = 0xFF;
    /// assert!(UdpPacketHeader::from_bytes(&bad_bytes).is_none());
    ///
    /// // Too short buffer returns None
    /// assert!(UdpPacketHeader::from_bytes(&[0u8; 10]).is_none());
    /// ```
    pub fn from_bytes(bytes: &[u8]) -> Option<Self> {
        if bytes.len() < Self::SIZE {
            return None;
        }

        let magic = u32::from_be_bytes(bytes[0..4].try_into().ok()?);
        if magic != RPERF3_UDP_MAGIC {
            return None;
        }

        let sequence = u64::from_be_bytes(bytes[4..12].try_into().ok()?);
        let timestamp_us = u64::from_be_bytes(bytes[12..20].try_into().ok()?);

        Some(Self {
            magic,
            sequence,
            timestamp_us,
        })
    }
}

/// Creates a UDP packet with header and payload.
///
/// Constructs a complete UDP packet with the current timestamp and zero-filled payload.
/// The packet format is: `[header (20 bytes)][payload (payload_size bytes)]`.
///
/// # Arguments
///
/// * `sequence` - Packet sequence number (should be monotonically increasing)
/// * `payload_size` - Size of payload in bytes (excluding 20-byte header)
///
/// # Returns
///
/// A vector containing the complete packet (header + payload)
///
/// # Examples
///
/// ```
/// use rperf3::udp_packet::create_packet;
///
/// // Create a packet with sequence 0 and 1024 bytes of data
/// let packet = create_packet(0, 1024);
/// assert_eq!(packet.len(), 20 + 1024); // header + payload
/// ```
///
/// # Returns
///
/// Vector containing serialized header followed by zero-filled payload
pub fn create_packet(sequence: u64, payload_size: usize) -> Vec<u8> {
    let header = UdpPacketHeader::with_current_time(sequence);
    let mut packet = Vec::with_capacity(UdpPacketHeader::SIZE + payload_size);
    packet.extend_from_slice(&header.to_bytes());
    packet.resize(UdpPacketHeader::SIZE + payload_size, 0);
    packet
}

/// Creates a UDP packet with cached timestamp for high performance.
///
/// This is an optimized version of `create_packet` that uses a thread-local
/// timestamp cache to avoid expensive `SystemTime::now()` calls on every packet.
/// The timestamp is updated approximately every 1ms, which is sufficient for
/// jitter measurement while providing 20-30% performance improvement.
///
/// Use this function in high-throughput UDP sending loops where packet timestamps
/// don't need microsecond-level accuracy.
///
/// # Arguments
///
/// * `sequence` - Packet sequence number (should be monotonically increasing)
/// * `payload_size` - Size of payload in bytes (excluding 20-byte header)
///
/// # Returns
///
/// A vector containing the complete packet (header + payload)
///
/// # Performance
///
/// This function is 20-30% faster than `create_packet` for high-frequency calls
/// due to timestamp caching.
///
/// # Examples
///
/// ```
/// use rperf3::udp_packet::{create_packet_fast, parse_packet};
///
/// // Create packets in a high-performance loop
/// for seq in 0..100 {
///     let packet = create_packet_fast(seq, 1024);
///     assert_eq!(packet.len(), 20 + 1024);
///     
///     // Verify packet is valid
///     let (header, payload) = parse_packet(&packet).unwrap();
///     assert_eq!(header.sequence, seq);
///     assert_eq!(payload.len(), 1024);
/// }
/// ```
///
/// # Comparison with create_packet
///
/// ```
/// use rperf3::udp_packet::{create_packet, create_packet_fast, parse_packet};
///
/// // Both functions produce valid packets with the same format
/// let packet1 = create_packet(1, 1000);
/// let packet2 = create_packet_fast(1, 1000);
///
/// assert_eq!(packet1.len(), packet2.len());
///
/// // Both can be parsed successfully
/// let (header1, _) = parse_packet(&packet1).unwrap();
/// let (header2, _) = parse_packet(&packet2).unwrap();
///
/// assert_eq!(header1.sequence, header2.sequence);
/// // Timestamps may differ slightly due to caching
/// ```
pub fn create_packet_fast(sequence: u64, payload_size: usize) -> Vec<u8> {
    let timestamp_us = TIMESTAMP_CACHE.with(|cache| cache.borrow_mut().get_timestamp());

    let header = UdpPacketHeader::new(sequence, timestamp_us);
    let mut packet = Vec::with_capacity(UdpPacketHeader::SIZE + payload_size);
    packet.extend_from_slice(&header.to_bytes());
    packet.resize(UdpPacketHeader::SIZE + payload_size, 0);
    packet
}

/// Parses a UDP packet into header and payload
///
/// # Arguments
///
/// * `packet` - Received packet bytes
///
/// # Returns
///
/// `Some((header, payload))` if packet has valid header, `None` otherwise
///
/// # Examples
///
/// ```
/// use rperf3::udp_packet::{create_packet, parse_packet};
///
/// // Create and parse a packet
/// let packet = create_packet(123, 512);
/// let (header, payload) = parse_packet(&packet).expect("Valid packet");
///
/// assert_eq!(header.sequence, 123);
/// assert_eq!(payload.len(), 512);
/// assert!(header.timestamp_us > 0);
///
/// // Invalid packet returns None
/// assert!(parse_packet(&[0u8; 10]).is_none());
/// ```
pub fn parse_packet(packet: &[u8]) -> Option<(UdpPacketHeader, &[u8])> {
    let header = UdpPacketHeader::from_bytes(packet)?;
    let payload = &packet[UdpPacketHeader::SIZE..];
    Some((header, payload))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_header_serialization() {
        let header = UdpPacketHeader::new(42, 1234567890);
        let bytes = header.to_bytes();
        let parsed = UdpPacketHeader::from_bytes(&bytes).expect("Failed to parse header");

        assert_eq!(parsed.magic, RPERF3_UDP_MAGIC);
        assert_eq!(parsed.sequence, 42);
        assert_eq!(parsed.timestamp_us, 1234567890);
    }

    #[test]
    fn test_invalid_magic() {
        let mut bytes = [0u8; UdpPacketHeader::SIZE];
        bytes[0..4].copy_from_slice(&0x12345678u32.to_be_bytes());
        assert!(UdpPacketHeader::from_bytes(&bytes).is_none());
    }

    #[test]
    fn test_packet_creation() {
        let packet = create_packet(100, 1024);
        assert_eq!(packet.len(), UdpPacketHeader::SIZE + 1024);

        let (header, payload) = parse_packet(&packet).expect("Failed to parse packet");
        assert_eq!(header.sequence, 100);
        assert_eq!(payload.len(), 1024);
    }

    #[test]
    fn test_short_packet() {
        let short_packet = vec![0u8; 10];
        assert!(parse_packet(&short_packet).is_none());
    }

    #[test]
    fn test_packet_creation_fast() {
        // Test that create_packet_fast produces valid packets
        let packet = create_packet_fast(200, 1024);
        assert_eq!(packet.len(), UdpPacketHeader::SIZE + 1024);

        let (header, payload) = parse_packet(&packet).expect("Failed to parse packet");
        assert_eq!(header.sequence, 200);
        assert_eq!(payload.len(), 1024);

        // Timestamp should be reasonable (within last 10 seconds)
        let now = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_micros() as u64;
        let diff = now.saturating_sub(header.timestamp_us);
        assert!(diff < 10_000_000, "Timestamp too far in past"); // < 10 seconds
    }

    #[test]
    fn test_timestamp_cache_consistency() {
        // Multiple rapid calls should return similar timestamps
        // Using 10ms tolerance to account for slower CI/coverage environments
        let packet1 = create_packet_fast(1, 100);
        let packet2 = create_packet_fast(2, 100);

        let (header1, _) = parse_packet(&packet1).unwrap();
        let (header2, _) = parse_packet(&packet2).unwrap();

        let diff = header2.timestamp_us.saturating_sub(header1.timestamp_us);
        assert!(diff < 10_000, "Timestamps differ by more than 10ms"); // Should be very close in normal conditions
    }
}