netstack3_base/tcp/

timestamp.rs

// Copyright 2025 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

//! TCP Timestamp Option as defined in RFC 7323.

use core::cmp::{Ord, Ordering, PartialOrd};
use core::marker::PhantomData;
use core::ops::Add;
use core::time::Duration;
use derivative::Derivative;

/// A timestamp to be used in the TCP Timestamp Option.
///
/// Per RFC 7323 Section 5.2:
///   the "timestamps" are 32-bit unsigned integers in a modular 32-bit space.
///
/// Note: timestamps have no inherent units. The sender and receiver are each
/// free to decide upon the units relevant to the timestamps they generate.
/// However, per RFC 7323 Section 5.4:
///   (a)  The timestamp clock must not be "too slow". [...]
///   (b)  The timestamp clock must not be "too fast". [...]
///   Based upon these considerations, we choose a timestamp clock frequency in
///   the range 1 ms to 1 sec per tick.
#[derive(Debug, Derivative, Clone, Copy)]
#[derivative(Eq(bound = ""), PartialEq(bound = ""))]
pub struct Timestamp<U> {
    timestamp: u32,
    unit: PhantomData<U>,
}

/// A marker type indicating that the backing units of a [`Timestamp`] are
/// unknown.
#[derive(Debug, Clone, Copy)]
pub enum Unitless {}

/// A marker type indicating that the backing units of a [`Timestamp`] are
/// milliseconds.
///
/// Note: Based on the considerations from RFC 7323 section 5.4, milliseconds
/// are the most appropriate units to use for timestamps generated by ourselves.
/// This choice supports bandwidths up to 8 Tbps, and idle connections up to 24
/// days.
#[derive(Debug, Clone, Copy)]
pub enum Milliseconds {}

impl<U> Timestamp<U> {
    /// Constructs a new [`Timestamp`] from a raw [`u32`].
    pub const fn new(timestamp: u32) -> Self {
        Timestamp { timestamp, unit: PhantomData::<U> }
    }

    /// Retrieve the raw 32-bit timestamp value.
    pub const fn get(&self) -> u32 {
        let Timestamp { timestamp, unit: _ } = self;
        *timestamp
    }
}

impl<U> Ord for Timestamp<U> {
    fn cmp(&self, rhs: &Timestamp<U>) -> Ordering {
        let Timestamp { timestamp: lhs, unit: _ } = self;
        let Timestamp { timestamp: rhs, unit: _ } = rhs;
        // Per RFC 7323 Section 5.2:
        //   Thus, "less than" is defined the same way it is for TCP sequence
        //   numbers, and the same implementation techniques apply.  If s and t
        //   are timestamp values,
        //       s < t  if 0 < (t - s) < 2^31,
        //   computed in unsigned 32-bit arithmetic.
        let delta = rhs.wrapping_sub(*lhs);
        if delta == 0 {
            Ordering::Equal
        } else if delta > 0 && delta < (1 << 31) {
            Ordering::Less
        } else {
            Ordering::Greater
        }
    }
}

impl<U> PartialOrd for Timestamp<U> {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

impl Add<Duration> for Timestamp<Milliseconds> {
    type Output = Self;

    fn add(self, rhs: Duration) -> Self::Output {
        let Timestamp { timestamp: lhs, unit } = self;
        let rhs: u128 = rhs.as_millis();
        // The following `as` coercion is sound because `Timestamp` exists in
        // modular 32-bit space. This drops the higher order bits from the
        // original value, which is representative of the `Timestamp` wrapping
        // around.
        let rhs = rhs as u32;
        Timestamp { timestamp: lhs.wrapping_add(rhs), unit }
    }
}

/// The TCP timestamp option as defined in RFC 7323, Section 3.
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub struct TimestampOption {
    /// The timestamp value.
    pub(super) ts_val: Timestamp<Unitless>,
    /// The timestamp echo reply.
    pub(super) ts_echo_reply: Timestamp<Unitless>,
}

/// Like `TimestampOption` but with units appropriate for a timestamp option
/// sent by us.
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub struct TxTimestampOption {
    /// The timestamp value.
    ///
    /// The timestamps sent by us use `Milliseconds`.
    pub ts_val: Timestamp<Milliseconds>,
    /// The timestamp echo reply.
    pub ts_echo_reply: Timestamp<Unitless>,
}

/// Like `TimestampOption` but with units appropriate for a timestamp option
/// sent by the peer.
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub struct RxTimestampOption {
    /// The timestamp value.
    pub ts_val: Timestamp<Unitless>,
    /// The timestamp echo reply.
    ///
    /// The timestamps sent by us use `Milliseconds` so any "echoed" timestamps
    /// we receive from the peer should also be `Milliseconds`.
    pub ts_echo_reply: Timestamp<Milliseconds>,
}

impl From<TxTimestampOption> for TimestampOption {
    fn from(timestamp: TxTimestampOption) -> TimestampOption {
        let TxTimestampOption { ts_val, ts_echo_reply } = timestamp;
        // NB: Drop the units from `ts_val`.
        let ts_val = Timestamp::<Unitless>::new(ts_val.timestamp);
        TimestampOption { ts_val, ts_echo_reply }
    }
}

impl From<TimestampOption> for RxTimestampOption {
    fn from(timestamp: TimestampOption) -> RxTimestampOption {
        let TimestampOption { ts_val, ts_echo_reply } = timestamp;
        // NB: Assume `Millisecond` units for `ts_echo_reply`.
        let ts_echo_reply = Timestamp::<Milliseconds>::new(ts_echo_reply.timestamp);
        RxTimestampOption { ts_val, ts_echo_reply }
    }
}

impl From<&packet_formats::tcp::options::TimestampOption> for TimestampOption {
    fn from(timestamp: &packet_formats::tcp::options::TimestampOption) -> TimestampOption {
        Self {
            ts_val: Timestamp::new(timestamp.ts_val()),
            ts_echo_reply: Timestamp::new(timestamp.ts_echo_reply()),
        }
    }
}

impl From<&TimestampOption> for packet_formats::tcp::options::TimestampOption {
    fn from(timestamp: &TimestampOption) -> packet_formats::tcp::options::TimestampOption {
        let TimestampOption { ts_val, ts_echo_reply } = timestamp;
        packet_formats::tcp::options::TimestampOption::new(ts_val.get(), ts_echo_reply.get())
    }
}

#[cfg(any(test, feature = "testutils"))]
mod testutils {
    use super::*;

    impl TimestampOption {
        /// Construct a new `TimestampOption` for use in tests.
        pub const fn new(ts_val: Timestamp<Unitless>, ts_echo_reply: Timestamp<Unitless>) -> Self {
            TimestampOption { ts_val, ts_echo_reply }
        }
    }

    impl<U> Timestamp<U> {
        /// Convert the timestamp into one without units.
        pub const fn discard_unit(self) -> Timestamp<Unitless> {
            let Timestamp { timestamp, unit: _ } = self;
            Timestamp { timestamp, unit: PhantomData }
        }
    }
}

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

    use test_case::test_case;

    #[test_case(1, 2 => Ordering::Less; "less_than")]
    #[test_case(1, 1 => Ordering::Equal; "equal_to")]
    #[test_case(2, 1 => Ordering::Greater; "greater_than")]
    #[test_case(u32::MAX, 0 => Ordering::Less; "wrapped")]
    #[test_case(0, (1<<31) - 1 => Ordering::Less; "last_in_bounds")]
    #[test_case(0, 1<<31 => Ordering::Greater; "first_out_of_bounds")]
    fn timestamp_ordering(lhs: u32, rhs: u32) -> Ordering {
        let lhs = Timestamp::<Unitless>::new(lhs);
        let rhs = Timestamp::<Unitless>::new(rhs);
        lhs.cmp(&rhs)
    }

    #[test_case(1, 1 => 2; "add")]
    #[test_case(u32::MAX, 1 => 0; "wrap_in_add")]
    #[test_case(1, (u32::MAX as u64) + 1 => 1; "wrap_in_duration")]
    fn timestamp_add_millis(lhs: u32, rhs: u64) -> u32 {
        let lhs = Timestamp::<Milliseconds>::new(lhs);
        let rhs = Duration::from_millis(rhs);
        let result = lhs + rhs;
        result.get()
    }
}