Skip to main content

rusty_time_clock/
net.rs

1//! Socket readiness — the poll-before-recv seam.
2//!
3//! Two reasons this exists, both structural:
4//!
5//! 1. The daemon's event loop (M3+) multiplexes sockets and timers; readiness
6//!    polling is the primitive it is built on.
7//! 2. Simulation rigs that virtualize time (clknetsim) advance the simulated
8//!    clock while a process blocks in `poll`/`select` — a plain blocking `recv`
9//!    returns `EWOULDBLOCK` there and can never see a packet. Discovered by the
10//!    TIMECORP interception probe (`tools/corpus/wsl_interception_probe.sh`).
11//!
12//! On Windows the blocking-`recv` + `SO_RCVTIMEO` path is sound and WSAPoll adds
13//! nothing, so `wait_readable` reports ready immediately and the socket timeout
14//! governs.
15
16use crate::ClockError;
17use std::net::UdpSocket;
18use std::time::Duration;
19
20/// Wait until `socket` has data to read, or the timeout passes. Returns
21/// `Ok(true)` if readable, `Ok(false)` on timeout.
22#[cfg(unix)]
23pub fn wait_readable(socket: &UdpSocket, timeout: Duration) -> Result<bool, ClockError> {
24    use std::os::fd::AsRawFd;
25
26    let mut pfd = libc::pollfd {
27        fd: socket.as_raw_fd(),
28        events: libc::POLLIN,
29        revents: 0,
30    };
31    let timeout_ms = timeout.as_millis().min(i32::MAX as u128) as libc::c_int;
32    loop {
33        // SAFETY: pfd is a valid, exclusively-owned pollfd array of length 1 for
34        // the duration of the call.
35        let rc = unsafe { libc::poll(&mut pfd, 1, timeout_ms) };
36        if rc > 0 {
37            return Ok(pfd.revents & (libc::POLLIN | libc::POLLERR | libc::POLLHUP) != 0);
38        }
39        if rc == 0 {
40            return Ok(false);
41        }
42        let err = std::io::Error::last_os_error();
43        if err.kind() == std::io::ErrorKind::Interrupted {
44            continue;
45        }
46        return Err(ClockError {
47            op: "poll",
48            detail: err.to_string(),
49        });
50    }
51}
52
53#[cfg(windows)]
54pub fn wait_readable(_socket: &UdpSocket, _timeout: Duration) -> Result<bool, ClockError> {
55    // SO_RCVTIMEO on the socket governs; recv itself blocks correctly here.
56    Ok(true)
57}
58
59/// One received datagram: how many bytes, from whom, and — where the kernel
60/// provides it — when it actually arrived.
61#[derive(Clone, Copy, Debug)]
62pub struct Received {
63    pub len: usize,
64    pub peer: std::net::SocketAddr,
65    /// Kernel receive timestamp in Unix seconds, when `SO_TIMESTAMPING` is
66    /// enabled and the stack supplied one.
67    ///
68    /// This is the timestamp that matters for accuracy: it is taken when the
69    /// packet reaches the kernel, not when userspace happens to be scheduled
70    /// to read it. The gap between those two is scheduling latency, and on a
71    /// busy machine it is the single largest error in an otherwise good
72    /// exchange.
73    /// Kernel receive time, in whole NANOSECONDS since the Unix epoch.
74    ///
75    /// Integer, not seconds-as-f64. The kernel hands over an exact `timespec`;
76    /// folding it into an f64 of seconds-since-1970 rounds it to the 238 ns
77    /// gap between representable values at today's epoch, and to 477 ns once
78    /// Unix time crosses 2^31 in February 2038. The wire resolution this
79    /// timestamp is compared against is 2^-32 s — 0.233 ns — so that
80    /// conversion was discarding three orders of magnitude before any
81    /// arithmetic happened.
82    pub kernel_rx_ns: Option<i64>,
83}
84
85/// Ask the kernel to attach receive timestamps to datagrams on this socket.
86///
87/// Requests hardware timestamps too; the kernel simply does not supply them
88/// where the NIC cannot, and `Received::kernel_rx_ns` is `None` then. Failure is
89/// not fatal — the caller falls back to reading the clock after `recv`, which
90/// is what every implementation did before this existed.
91#[cfg(target_os = "linux")]
92pub fn enable_rx_timestamps(socket: &UdpSocket) -> Result<(), ClockError> {
93    use std::os::fd::AsRawFd;
94
95    // SOF_TIMESTAMPING_* bits. Named here rather than pulled from a binding
96    // crate because the set we want is small and fixed.
97    const RX_HARDWARE: libc::c_int = 1 << 0;
98    const RX_SOFTWARE: libc::c_int = 1 << 3;
99    const SOFTWARE: libc::c_int = 1 << 4;
100    const RAW_HARDWARE: libc::c_int = 1 << 6;
101
102    let flags: libc::c_int = RX_SOFTWARE | SOFTWARE | RX_HARDWARE | RAW_HARDWARE;
103    // SAFETY: setsockopt with a valid fd, level, name, and a pointer to an
104    // int of the declared length.
105    let rc = unsafe {
106        libc::setsockopt(
107            socket.as_raw_fd(),
108            libc::SOL_SOCKET,
109            libc::SO_TIMESTAMPING,
110            (&raw const flags).cast::<libc::c_void>(),
111            core::mem::size_of::<libc::c_int>() as libc::socklen_t,
112        )
113    };
114    if rc != 0 {
115        return Err(ClockError {
116            op: "setsockopt(SO_TIMESTAMPING)",
117            detail: std::io::Error::last_os_error().to_string(),
118        });
119    }
120    Ok(())
121}
122
123#[cfg(not(target_os = "linux"))]
124pub fn enable_rx_timestamps(_socket: &UdpSocket) -> Result<(), ClockError> {
125    // Windows has SIO_TIMESTAMPING (Win10 2004+) and macOS has SO_TIMESTAMP;
126    // neither is wired yet, and the caller's fallback is correct meanwhile.
127    Err(ClockError {
128        op: "enable_rx_timestamps",
129        detail: "kernel receive timestamps are not implemented on this platform".into(),
130    })
131}
132
133/// Adopt a listening socket the service manager already opened, if there is one.
134///
135/// systemd's socket activation passes descriptors starting at fd 3, which lets
136/// the socket be bound by systemd (as root, on port 123) while the daemon runs
137/// unprivileged — the only thing rtimed would otherwise need root for besides
138/// the clock itself.
139///
140/// Lives in this crate rather than the daemon because adopting a raw descriptor
141/// is a platform-seam operation, and this is the one crate permitted `unsafe`.
142pub fn activated_udp_socket() -> Option<UdpSocket> {
143    #[cfg(target_os = "linux")]
144    {
145        use std::os::fd::FromRawFd;
146
147        if !should_adopt_activated(
148            std::env::var("LISTEN_PID").ok().as_deref(),
149            std::env::var("LISTEN_FDS").ok().as_deref(),
150            std::process::id(),
151        ) {
152            return None;
153        }
154        // SAFETY: fd 3 is the first activated descriptor per systemd's
155        // protocol, and the check above confirmed the set was passed to this
156        // process. Ownership is taken exactly once, here.
157        Some(unsafe { UdpSocket::from_raw_fd(3) })
158    }
159    #[cfg(not(target_os = "linux"))]
160    {
161        None
162    }
163}
164
165/// Should we adopt the activated descriptor set?
166///
167/// Pure, so the decision is tested with explicit inputs rather than by mutating
168/// the process environment — which is `unsafe` in edition 2024 and races with
169/// every other test in the binary.
170///
171/// `LISTEN_PID` is the load-bearing check: a descriptor inherited from a parent
172/// sits at fd 3 just as an activated one does, and adopting it would hijack
173/// whatever the parent had open there.
174pub fn should_adopt_activated(
175    listen_pid: Option<&str>,
176    listen_fds: Option<&str>,
177    our_pid: u32,
178) -> bool {
179    let for_us = listen_pid
180        .and_then(|p| p.parse::<u32>().ok())
181        .map(|pid| pid == our_pid)
182        .unwrap_or(false);
183    let count = listen_fds.and_then(|n| n.parse::<i32>().ok()).unwrap_or(0);
184    for_us && count >= 1
185}
186
187/// Datagrams a single batch may collect. Past a few dozen the syscall saving
188/// per message is already amortised, and the buffer stops fitting in cache.
189pub const BATCH_SIZE: usize = 32;
190
191/// Reusable working memory for `recv_batch`.
192///
193/// The kernel needs an array of headers, one address slot and one control
194/// block per datagram. None of it carries information between calls -- it is
195/// all overwritten by the next `recvmmsg` -- so it is allocated once by the
196/// caller and reused, exactly as the packet buffers already are, instead of
197/// being built and thrown away on every receive.
198#[cfg(target_os = "linux")]
199#[derive(Default)]
200pub struct BatchScratch {
201    /// Whether to ask the kernel for control data (receive timestamps).
202    ///
203    /// Only worth paying for if the caller reads `Received::kernel_rx_ns`. The
204    /// server does not — it stamps the batch itself — so it asks for none, and
205    /// the kernel skips the control-message machinery for every datagram.
206    want_control: bool,
207    iovecs: Vec<libc::iovec>,
208    addrs: Vec<libc::sockaddr_storage>,
209    msgs: Vec<libc::mmsghdr>,
210    controls: Vec<[u8; CONTROL_LEN]>,
211}
212
213#[cfg(target_os = "linux")]
214impl BatchScratch {
215    /// Scratch that collects kernel receive timestamps.
216    pub fn new() -> Self {
217        let mut scratch = BatchScratch {
218            want_control: true,
219            ..BatchScratch::default()
220        };
221        scratch.ensure(BATCH_SIZE);
222        scratch
223    }
224
225    /// Scratch for a caller that does not read `Received::kernel_rx_ns`.
226    pub fn without_timestamps() -> Self {
227        let mut scratch = BatchScratch::default();
228        scratch.ensure(BATCH_SIZE);
229        scratch
230    }
231
232    /// Grow to hold `count` datagrams. After the first call this does nothing.
233    fn ensure(&mut self, count: usize) {
234        if self.msgs.len() >= count {
235            return;
236        }
237        // SAFETY: every one of these is a plain-old-data C struct for which an
238        // all-zero bit pattern is a valid, inert value; each is fully
239        // initialised before the kernel sees it.
240        self.iovecs
241            .resize(count, unsafe { core::mem::zeroed::<libc::iovec>() });
242        self.addrs.resize(count, unsafe {
243            core::mem::zeroed::<libc::sockaddr_storage>()
244        });
245        self.msgs
246            .resize(count, unsafe { core::mem::zeroed::<libc::mmsghdr>() });
247        self.controls.resize(count, [0u8; CONTROL_LEN]);
248    }
249}
250
251/// Non-Linux placeholder, so callers have one shape on every platform.
252#[cfg(not(target_os = "linux"))]
253#[derive(Default)]
254pub struct BatchScratch;
255
256#[cfg(not(target_os = "linux"))]
257impl BatchScratch {
258    pub fn new() -> Self {
259        BatchScratch
260    }
261
262    /// Same shape as the Linux constructor. There is no control-message
263    /// machinery to decline here, so the two are identical — the method exists
264    /// so callers compile unchanged on every platform.
265    pub fn without_timestamps() -> Self {
266        BatchScratch
267    }
268}
269
270/// Receive up to `bufs.len()` datagrams in **one** syscall on Linux
271/// (`recvmmsg`), falling back to a single `recv_from` elsewhere.
272///
273/// This is the server-throughput lever the mission plan calls out: a
274/// one-request-per-syscall server spends most of its CPU crossing the kernel
275/// boundary, not answering NTP. The scalar path is kept as the oracle — both
276/// must produce identical results, and the batch tests assert that.
277#[cfg(target_os = "linux")]
278pub fn recv_batch(
279    socket: &UdpSocket,
280    bufs: &mut [[u8; 1024]],
281    scratch: &mut BatchScratch,
282    out: &mut Vec<Received>,
283) -> Result<usize, ClockError> {
284    use std::os::fd::AsRawFd;
285
286    out.clear();
287    let count = bufs.len().min(BATCH_SIZE);
288    if count == 0 {
289        return Ok(0);
290    }
291    scratch.ensure(count);
292
293    // Point each header at this call's buffers and reset the two lengths the
294    // kernel writes back. Nothing is allocated and nothing is zeroed: the
295    // kernel reports how many bytes it put in the address and the control
296    // block, so stale bytes beyond those lengths are never read.
297    //
298    // The previous form built all four arrays per call -- two of them with
299    // `vec![zeroed; 32]`, which is ~4 KiB of sockaddr and 4 KiB of control
300    // buffer memset on every `recvmmsg`, plus four allocations -- to hand the
301    // kernel scratch space it immediately overwrites.
302    let BatchScratch {
303        want_control,
304        iovecs,
305        addrs,
306        msgs,
307        controls,
308    } = scratch;
309    for i in 0..count {
310        iovecs[i] = libc::iovec {
311            iov_base: bufs[i].as_mut_ptr().cast::<libc::c_void>(),
312            iov_len: bufs[i].len(),
313        };
314    }
315    for i in 0..count {
316        let hdr = &mut msgs[i].msg_hdr;
317        hdr.msg_name = (&mut addrs[i] as *mut libc::sockaddr_storage).cast::<libc::c_void>();
318        hdr.msg_namelen = core::mem::size_of::<libc::sockaddr_storage>() as libc::socklen_t;
319        hdr.msg_iov = (&mut iovecs[i]) as *mut libc::iovec;
320        hdr.msg_iovlen = 1;
321        if *want_control {
322            hdr.msg_control = controls[i].as_mut_ptr().cast::<libc::c_void>();
323            hdr.msg_controllen = CONTROL_LEN as _;
324        } else {
325            hdr.msg_control = core::ptr::null_mut();
326            hdr.msg_controllen = 0;
327        }
328        msgs[i].msg_len = 0;
329    }
330
331    // SAFETY: msgs is a valid array of `count` mmsghdr, each pointing at a
332    // live iovec and sockaddr_storage owned by this frame for the duration of
333    // the call. MSG_DONTWAIT keeps this non-blocking; readiness is the
334    // caller's job.
335    let received = unsafe {
336        libc::recvmmsg(
337            socket.as_raw_fd(),
338            msgs.as_mut_ptr(),
339            count as libc::c_uint,
340            // glibc and musl disagree on this parameter's integer type, so let
341            // the cast take whichever the target's signature declares.
342            libc::MSG_DONTWAIT as _,
343            core::ptr::null_mut(),
344        )
345    };
346    if received < 0 {
347        let err = std::io::Error::last_os_error();
348        if matches!(
349            err.kind(),
350            std::io::ErrorKind::WouldBlock | std::io::ErrorKind::Interrupted
351        ) {
352            return Ok(0);
353        }
354        return Err(ClockError {
355            op: "recvmmsg",
356            detail: err.to_string(),
357        });
358    }
359
360    for msg in msgs.iter().take(received as usize) {
361        let len = msg.msg_len as usize;
362        // SAFETY: the kernel filled msg_name with a sockaddr of msg_namelen
363        // bytes; we only read the family and the matching variant.
364        let peer =
365            unsafe { sockaddr_to_rust(&*(msg.msg_hdr.msg_name as *const libc::sockaddr_storage)) };
366        if let Some(peer) = peer {
367            // SAFETY: the kernel filled msg_control with msg_controllen bytes
368            // of well-formed cmsgs, or set the length to zero.
369            let kernel_rx_ns = unsafe { kernel_timestamp(&msg.msg_hdr) };
370            out.push(Received {
371                len,
372                peer,
373                kernel_rx_ns,
374            });
375        }
376    }
377    Ok(out.len())
378}
379
380/// Bytes reserved per datagram for control messages. One SCM_TIMESTAMPING
381/// carries three timespecs; this leaves room for it and a little slack.
382#[cfg(target_os = "linux")]
383const CONTROL_LEN: usize = 128;
384
385/// Pull the receive timestamp out of a message's control data.
386///
387/// `SCM_TIMESTAMPING` carries three timespecs: [0] software, [1] legacy
388/// hardware (deprecated), [2] raw hardware. Software is preferred when
389/// present because it is already on the system timescale; the raw hardware
390/// stamp is on the NIC's own timescale and needs a PHC correlation before it
391/// means anything, which is why it is not simply used when available.
392///
393/// # Safety
394/// `hdr` must be a msghdr the kernel has just filled, with `msg_control`
395/// pointing at `msg_controllen` valid bytes.
396#[cfg(target_os = "linux")]
397unsafe fn kernel_timestamp(hdr: &libc::msghdr) -> Option<i64> {
398    if hdr.msg_controllen == 0 || hdr.msg_control.is_null() {
399        return None;
400    }
401    // SAFETY: caller's contract; CMSG_FIRSTHDR handles an empty buffer.
402    let mut cmsg = unsafe { libc::CMSG_FIRSTHDR(hdr) };
403    while !cmsg.is_null() {
404        // SAFETY: cmsg came from CMSG_FIRSTHDR/CMSG_NXTHDR and is in range.
405        let header = unsafe { &*cmsg };
406        if header.cmsg_level == libc::SOL_SOCKET && header.cmsg_type == libc::SCM_TIMESTAMPING {
407            // SAFETY: SCM_TIMESTAMPING data is three timespecs.
408            let stamps = unsafe { libc::CMSG_DATA(cmsg).cast::<libc::timespec>() };
409            for index in [0usize, 2] {
410                // SAFETY: index is within the three-element array above.
411                let ts = unsafe { *stamps.add(index) };
412                if ts.tv_sec != 0 || ts.tv_nsec != 0 {
413                    // Exact. i64 nanoseconds hold Unix time until the year
414                    // 2262; f64 seconds lose 238 ns of it today.
415                    return Some(ts.tv_sec as i64 * 1_000_000_000 + ts.tv_nsec as i64);
416                }
417            }
418        }
419        // SAFETY: as above.
420        cmsg = unsafe { libc::CMSG_NXTHDR(hdr, cmsg) };
421    }
422    None
423}
424
425#[cfg(target_os = "linux")]
426/// Fill a `sockaddr_storage` from a Rust address, returning its length.
427#[cfg(target_os = "linux")]
428fn rust_to_sockaddr(
429    addr: &std::net::SocketAddr,
430    out: &mut libc::sockaddr_storage,
431) -> libc::socklen_t {
432    match addr {
433        std::net::SocketAddr::V4(v4) => {
434            // SAFETY: sockaddr_storage is sized and aligned for sockaddr_in,
435            // which is the whole reason it exists; every field is written.
436            let sin = unsafe { &mut *(out as *mut _ as *mut libc::sockaddr_in) };
437            sin.sin_family = libc::AF_INET as libc::sa_family_t;
438            sin.sin_port = v4.port().to_be();
439            sin.sin_addr.s_addr = u32::from(*v4.ip()).to_be();
440            core::mem::size_of::<libc::sockaddr_in>() as libc::socklen_t
441        }
442        std::net::SocketAddr::V6(v6) => {
443            // SAFETY: as above, for sockaddr_in6.
444            let sin6 = unsafe { &mut *(out as *mut _ as *mut libc::sockaddr_in6) };
445            sin6.sin6_family = libc::AF_INET6 as libc::sa_family_t;
446            sin6.sin6_port = v6.port().to_be();
447            sin6.sin6_addr.s6_addr = v6.ip().octets();
448            sin6.sin6_flowinfo = v6.flowinfo();
449            sin6.sin6_scope_id = v6.scope_id();
450            core::mem::size_of::<libc::sockaddr_in6>() as libc::socklen_t
451        }
452    }
453}
454
455/// Send many datagrams in **one** syscall on Linux (`sendmmsg`).
456///
457/// The receive side has been batched since M5; the send side was not, so a
458/// server that collected up to 32 requests with one `recvmmsg` then answered
459/// them with 32 separate `sendto` calls. Under load the reply path was the
460/// syscall-heavy half of the loop.
461///
462/// It also makes the transmit timestamp *more* honest for interleaved mode
463/// rather than less: the packets genuinely do leave in one syscall, so one
464/// clock reading taken immediately afterwards describes all of them, where the
465/// old loop stamped each reply after its own `sendto` and attributed the
466/// accumulated delay of the whole loop to the last client in the batch.
467///
468/// Returns how many datagrams the kernel accepted.
469#[cfg(target_os = "linux")]
470pub fn send_batch(
471    socket: &UdpSocket,
472    messages: &[(&[u8], std::net::SocketAddr)],
473    scratch: &mut BatchScratch,
474) -> Result<usize, ClockError> {
475    send_batch_by(socket, messages, |m| m.0, |m| m.1, scratch)
476}
477
478/// `send_batch` reading each datagram out of the caller's own items.
479///
480/// The slice form needs a `&[(&[u8], SocketAddr)]`, which a caller holding
481/// replies in some other shape can only produce by building a temporary vector
482/// every batch — an allocation, a copy of every element, and a free, to
483/// describe data it already had. Accessors remove it.
484#[cfg(target_os = "linux")]
485pub fn send_batch_by<T>(
486    socket: &UdpSocket,
487    items: &[T],
488    payload: impl Fn(&T) -> &[u8],
489    peer: impl Fn(&T) -> std::net::SocketAddr,
490    scratch: &mut BatchScratch,
491) -> Result<usize, ClockError> {
492    use std::os::fd::AsRawFd;
493
494    let count = items.len().min(BATCH_SIZE);
495    if count == 0 {
496        return Ok(0);
497    }
498    scratch.ensure(count);
499    let BatchScratch {
500        iovecs,
501        addrs,
502        msgs,
503        ..
504    } = scratch;
505
506    for (i, item) in items.iter().enumerate().take(count) {
507        let bytes = payload(item);
508        iovecs[i] = libc::iovec {
509            iov_base: bytes.as_ptr() as *mut libc::c_void,
510            iov_len: bytes.len(),
511        };
512        let namelen = rust_to_sockaddr(&peer(item), &mut addrs[i]);
513        let hdr = &mut msgs[i].msg_hdr;
514        hdr.msg_name = (&mut addrs[i] as *mut libc::sockaddr_storage).cast::<libc::c_void>();
515        hdr.msg_namelen = namelen;
516        hdr.msg_iov = (&mut iovecs[i]) as *mut libc::iovec;
517        hdr.msg_iovlen = 1;
518        hdr.msg_control = core::ptr::null_mut();
519        hdr.msg_controllen = 0;
520        msgs[i].msg_len = 0;
521    }
522
523    // SAFETY: msgs is a valid array of `count` mmsghdr, each naming a live
524    // iovec and sockaddr owned by `scratch`, which outlives the call. The
525    // payloads are borrowed for the duration of `messages`.
526    let sent = unsafe {
527        libc::sendmmsg(
528            socket.as_raw_fd(),
529            msgs.as_mut_ptr(),
530            count as libc::c_uint,
531            libc::MSG_DONTWAIT as _,
532        )
533    };
534    if sent < 0 {
535        let err = std::io::Error::last_os_error();
536        if matches!(
537            err.kind(),
538            std::io::ErrorKind::WouldBlock | std::io::ErrorKind::Interrupted
539        ) {
540            return Ok(0);
541        }
542        return Err(ClockError {
543            op: "sendmmsg",
544            detail: err.to_string(),
545        });
546    }
547    Ok(sent as usize)
548}
549
550/// Non-Linux fallback: one datagram per call, same shape as the batch path.
551#[cfg(not(target_os = "linux"))]
552pub fn send_batch(
553    socket: &UdpSocket,
554    messages: &[(&[u8], std::net::SocketAddr)],
555    scratch: &mut BatchScratch,
556) -> Result<usize, ClockError> {
557    send_batch_by(socket, messages, |m| m.0, |m| m.1, scratch)
558}
559
560/// Non-Linux fallback: one datagram per call, same shape as the batch path.
561#[cfg(not(target_os = "linux"))]
562pub fn send_batch_by<T>(
563    socket: &UdpSocket,
564    items: &[T],
565    payload: impl Fn(&T) -> &[u8],
566    peer: impl Fn(&T) -> std::net::SocketAddr,
567    _scratch: &mut BatchScratch,
568) -> Result<usize, ClockError> {
569    let mut sent = 0;
570    for item in items {
571        match socket.send_to(payload(item), peer(item)) {
572            Ok(_) => sent += 1,
573            Err(e)
574                if matches!(
575                    e.kind(),
576                    std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut
577                ) =>
578            {
579                break;
580            }
581            Err(e) => {
582                return Err(ClockError {
583                    op: "send_to",
584                    detail: e.to_string(),
585                });
586            }
587        }
588    }
589    Ok(sent)
590}
591
592#[cfg(target_os = "linux")]
593fn sockaddr_to_rust(storage: &libc::sockaddr_storage) -> Option<std::net::SocketAddr> {
594    use std::net::{Ipv4Addr, Ipv6Addr, SocketAddrV4, SocketAddrV6};
595    match storage.ss_family as libc::c_int {
596        libc::AF_INET => {
597            // SAFETY: family says this is a sockaddr_in.
598            let sin = unsafe { &*(storage as *const _ as *const libc::sockaddr_in) };
599            let ip = Ipv4Addr::from(u32::from_be(sin.sin_addr.s_addr));
600            Some(std::net::SocketAddr::V4(SocketAddrV4::new(
601                ip,
602                u16::from_be(sin.sin_port),
603            )))
604        }
605        libc::AF_INET6 => {
606            // SAFETY: family says this is a sockaddr_in6.
607            let sin6 = unsafe { &*(storage as *const _ as *const libc::sockaddr_in6) };
608            let ip = Ipv6Addr::from(sin6.sin6_addr.s6_addr);
609            Some(std::net::SocketAddr::V6(SocketAddrV6::new(
610                ip,
611                u16::from_be(sin6.sin6_port),
612                sin6.sin6_flowinfo,
613                sin6.sin6_scope_id,
614            )))
615        }
616        _ => None,
617    }
618}
619
620/// Non-Linux fallback: one datagram per call, same shape as the batch path so
621/// the server loop above it is identical on every platform.
622#[cfg(not(target_os = "linux"))]
623pub fn recv_batch(
624    socket: &UdpSocket,
625    bufs: &mut [[u8; 1024]],
626    _scratch: &mut BatchScratch,
627    out: &mut Vec<Received>,
628) -> Result<usize, ClockError> {
629    out.clear();
630    let Some(buf) = bufs.first_mut() else {
631        return Ok(0);
632    };
633    match socket.recv_from(buf) {
634        Ok((len, peer)) => {
635            out.push(Received {
636                len,
637                peer,
638                kernel_rx_ns: None,
639            });
640            Ok(1)
641        }
642        Err(e)
643            if matches!(
644                e.kind(),
645                std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut
646            ) =>
647        {
648            Ok(0)
649        }
650        Err(e) => Err(ClockError {
651            op: "recv_from",
652            detail: e.to_string(),
653        }),
654    }
655}
656
657#[cfg(test)]
658mod tests {
659    use super::*;
660
661    #[test]
662    fn timeout_and_readable_paths() {
663        let a = UdpSocket::bind("127.0.0.1:0").expect("bind a");
664        let b = UdpSocket::bind("127.0.0.1:0").expect("bind b");
665        // Nothing pending on Unix: times out quickly. On Windows the shim
666        // reports ready by design; recv's own timeout governs there.
667        let quick = wait_readable(&a, Duration::from_millis(50)).expect("wait");
668        if cfg!(unix) {
669            assert!(!quick, "empty socket reported readable");
670        } else {
671            assert!(quick);
672        }
673        b.send_to(b"x", a.local_addr().expect("addr"))
674            .expect("send");
675        let ready = wait_readable(&a, Duration::from_millis(2000)).expect("wait");
676        assert!(ready, "pending datagram not reported readable");
677    }
678
679    #[test]
680    fn batch_receive_returns_every_datagram_with_its_sender() {
681        let server = UdpSocket::bind("127.0.0.1:0").expect("bind server");
682        let server_addr = server.local_addr().expect("addr");
683        server
684            .set_read_timeout(Some(Duration::from_millis(500)))
685            .expect("timeout");
686
687        let client = UdpSocket::bind("127.0.0.1:0").expect("bind client");
688        let client_addr = client.local_addr().expect("client addr");
689        let sent = 5usize;
690        for i in 0..sent {
691            client.send_to(&[i as u8; 16], server_addr).expect("send");
692        }
693
694        // Collect until we have them all or we stop making progress: the batch
695        // path may return fewer than were sent in one call.
696        let mut bufs = [[0u8; 1024]; BATCH_SIZE];
697        let mut out = Vec::new();
698        let mut total = 0usize;
699        let mut idle = 0;
700        while total < sent && idle < 20 {
701            if !wait_readable(&server, Duration::from_millis(200)).expect("wait") {
702                idle += 1;
703                continue;
704            }
705            let n =
706                recv_batch(&server, &mut bufs, &mut BatchScratch::new(), &mut out).expect("batch");
707            if n == 0 {
708                idle += 1;
709                continue;
710            }
711            for received in out.iter().take(n) {
712                assert_eq!(received.len, 16, "wrong length reported");
713                assert_eq!(
714                    received.peer, client_addr,
715                    "batch reported the wrong sender"
716                );
717            }
718            total += n;
719        }
720        assert_eq!(total, sent, "batch receive lost datagrams");
721    }
722
723    #[test]
724    fn activation_is_refused_unless_the_descriptors_are_ours() {
725        // The happy path: systemd names us and passes one descriptor.
726        assert!(should_adopt_activated(Some("42"), Some("1"), 42));
727        // A descriptor set meant for a different process must never be
728        // adopted — fd 3 inherited from a parent looks identical otherwise.
729        assert!(!should_adopt_activated(Some("41"), Some("1"), 42));
730        // No environment at all: the ordinary case, run from a shell.
731        assert!(!should_adopt_activated(None, None, 42));
732        // Named but nothing passed.
733        assert!(!should_adopt_activated(Some("42"), Some("0"), 42));
734        // Garbage must not be read as consent.
735        assert!(!should_adopt_activated(Some("not-a-pid"), Some("1"), 42));
736        assert!(!should_adopt_activated(Some("42"), Some("many"), 42));
737    }
738
739    #[test]
740    fn batch_receive_on_an_empty_socket_returns_zero_not_an_error() {
741        let s = UdpSocket::bind("127.0.0.1:0").expect("bind");
742        s.set_read_timeout(Some(Duration::from_millis(50)))
743            .expect("timeout");
744        let mut bufs = [[0u8; 1024]; 4];
745        let mut out = Vec::new();
746        assert_eq!(
747            recv_batch(&s, &mut bufs, &mut BatchScratch::new(), &mut out).expect("batch"),
748            0
749        );
750        assert!(out.is_empty());
751    }
752}