feat: implement kernel receive timestamps on Linux/Android

Closes #2574.

Enable SO_TIMESTAMPNS on Linux and Android, parse SCM_TIMESTAMPNS
ancillary messages, and expose timestamps via RecvMeta::timestamp.

Increase CMSG_LEN from 88 to 96 bytes on Linux and Android.

Author: syszery

quinn-udp/src/lib.rs

@@ -118,6 +118,10 @@ pub struct RecvMeta {
     pub dst_ip: Option<IpAddr>,
     /// The interface index of the interface on which the datagram was received
     pub interface_index: Option<u32>,
+    /// Kernel receive timestamp in nanoseconds since the Unix epoch
+    ///
+    /// Populated on platforms: Linux, Android.
+    pub timestamp: Option<u64>,
 }
 
 impl Default for RecvMeta {
@@ -130,6 +134,7 @@ impl Default for RecvMeta {
             ecn: None,
             dst_ip: None,
             interface_index: None,
+            timestamp: None,
         }
     }
 }

quinn-udp/src/unix.rs

@@ -149,6 +149,12 @@ impl UdpSocketState {
                 // https://github.com/quinn-rs/quinn/pull/1354.
                 gro_segments = 64
             }
+
+            if let Err(_err) =
+                set_socket_option(&*io, libc::SOL_SOCKET, libc::SO_TIMESTAMPNS, OPTION_ON)
+            {
+                crate::log::debug!("Ignoring error setting SO_TIMESTAMPNS on socket: {_err:?}");
+            }
         }
         #[cfg(any(target_os = "freebsd", apple))]
         {
@@ -696,6 +702,12 @@ fn recv_single(
     Ok(1)
 }
 
+// Space for packet info, ECN, GRO, and SCM_TIMESTAMPNS ancillary data.
+// 96 bytes covers the worst-case currently supported Unix control messages.
+#[cfg(any(target_os = "linux", target_os = "android"))]
+const CMSG_LEN: usize = 96;
+
+#[cfg(not(any(target_os = "linux", target_os = "android")))]
 const CMSG_LEN: usize = 88;
 
 #[cfg_attr(apple_fast, allow(dead_code))] // Unused when apple_fast is enabled
@@ -894,6 +906,7 @@ fn decode_recv<M: cmsg::MsgHdr<ControlMessage = libc::cmsghdr>>(
         dst_ip: None,
         interface_index: None,
         stride: len,
+        timestamp: None,
     };
 
     let cmsg_iter = unsafe { cmsg::Iter::new(hdr) };
@@ -908,6 +921,7 @@ fn decode_recv<M: cmsg::MsgHdr<ControlMessage = libc::cmsghdr>>(
         ecn: EcnCodepoint::from_bits(ctrl.ecn_bits),
         dst_ip: ctrl.dst_ip,
         interface_index: ctrl.interface_index,
+        timestamp: ctrl.timestamp,
     })
 }
 
@@ -917,6 +931,7 @@ struct ControlMetadata {
     dst_ip: Option<IpAddr>,
     interface_index: Option<u32>,
     stride: usize,
+    timestamp: Option<u64>,
 }
 
 impl ControlMetadata {
@@ -973,6 +988,11 @@ impl ControlMetadata {
             (libc::SOL_UDP, libc::UDP_GRO) => unsafe {
                 self.stride = cmsg::decode::<libc::c_int, libc::cmsghdr>(cmsg) as usize;
             },
+            #[cfg(any(target_os = "linux", target_os = "android"))]
+            (libc::SOL_SOCKET, libc::SCM_TIMESTAMPNS) => {
+                let ts = unsafe { cmsg::decode::<libc::timespec, libc::cmsghdr>(cmsg) };
+                self.timestamp = Some((ts.tv_sec as u64) * 1_000_000_000 + (ts.tv_nsec as u64));
+            }
             _ => {}
         }
     }

quinn-udp/src/windows.rs

@@ -326,6 +326,7 @@ impl UdpSocketState {
             ecn: EcnCodepoint::from_bits(ecn_bits as u8),
             dst_ip,
             interface_index,
+            timestamp: None,
         };
         Ok(1)
     }

quinn-udp/tests/tests.rs

@@ -359,6 +359,26 @@ fn test_send_recv(send: &Socket, recv: &Socket, transmit: Transmit<'_>) {
         } else {
             assert_eq!(meta.ecn, transmit.ecn);
         }
+
+        // On Linux and Android, we expect the kernel to provide a receive timestamp
+        // since we explicitly enabled `SO_TIMESTAMPNS`.
+        #[cfg(any(target_os = "linux", target_os = "android"))]
+        {
+            assert!(
+                meta.timestamp.is_some(),
+                "Kernel timestamp should be present on Linux/Android"
+            );
+            assert!(
+                meta.timestamp.unwrap() > 0,
+                "Kernel timestamp should be non-zero"
+            );
+        }
+
+        // On other platforms, the timestamp should remain `None`.
+        #[cfg(not(any(target_os = "linux", target_os = "android")))]
+        {
+            assert!(meta.timestamp.is_none());
+        }
     }
     assert_eq!(datagrams, expected_datagrams);
 }