shep-daemon 0.25.2

The supervision engine behind shep: process spawning, restart policy, the log plane, watch and cron restarts, and the RPC server
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
//! This crate's only `unsafe` on unix: adopting a descriptor into a [`File`]
//!
//! Daemonization re-execs the CLI detached, and the child reports
//! `{pid, version}` on an inherited pipe; `open_resolving_no_symlinks` gets
//! its descriptor from `openat2`. Building an owning [`File`] from a raw
//! number is the one step std offers no safe path for.
//!
//! [`adopt_fd`] is `unsafe fn` rather than a safe wrapper: its ordering
//! precondition is a caller obligation it cannot check from inside.
//! [`adopt_handover_fd`] is safe because inheritance discharges it.
#![allow(unsafe_code)] // every unsafe site in this crate's unix build is in this file

use core::fmt;

use std::fs::File;
use std::io;
use std::os::fd::{AsFd, BorrowedFd, IntoRawFd};
use std::os::unix::io::{FromRawFd, RawFd};
#[cfg(target_os = "linux")]
use std::path::Path;

/// Lowest fd number this daemon will ever adopt. 0/1/2 are stdio; adopting
/// one into an owning [`File`] would steal it from whatever already holds it.
pub(crate) const RESERVED_FD_FLOOR: RawFd = 3;

/// Whether `fd` is a number this process could adopt at all: not stdio, and
/// open right now.
///
/// [`adopt_fd`]'s two checks without taking ownership, for the predecessor's
/// pre-exec rehearsal in `handover::adopt::dry_run`. Safe because it owns
/// nothing afterwards, so the recycling hazard has nowhere to land.
///
/// # Errors
/// - [`SysError::ReservedFd`]: `fd` is below 3 (stdio is owned elsewhere).
/// - [`SysError::BadFd`]: `fd` names no open descriptor in this process,
///   which is what a blob naming a descriptor that did not survive the exec
///   looks like.
pub fn adoptable_fd(fd: RawFd) -> Result<(), SysError> {
    if fd < RESERVED_FD_FLOOR {
        return Err(SysError::ReservedFd(fd));
    }
    // `F_GETFD` proves only that the number is open right now, never who
    // opened it; that half of the contract is `adopt_fd`'s caller's.
    nix::fcntl::fcntl(fd, nix::fcntl::FcntlArg::F_GETFD).map_err(|errno| SysError::BadFd {
        fd,
        errno: errno.to_string(),
    })?;
    Ok(())
}

/// Takes ownership of a descriptor inherited across `exec`.
///
/// # Errors
/// - [`SysError::ReservedFd`]: `fd` is below 3 (stdio is owned elsewhere).
/// - [`SysError::BadFd`]: `fd` names no open descriptor in this process.
///
/// # Safety
///
/// Call this before this process opens or closes any descriptor of its own.
/// `F_GETFD` proves only that a number is open now, never what it names, so
/// a later call can adopt a number the kernel recycled into something this
/// process already owns, and the returned [`File`] closes that on drop.
pub unsafe fn adopt_fd(fd: RawFd) -> Result<File, SysError> {
    adoptable_fd(fd)?;
    // SAFETY: `adoptable_fd` returned `Ok`, so `fd` is at or above
    // `RESERVED_FD_FLOOR` and names a descriptor open in this process. The
    // caller's `# Safety` contract is what proves it is the intended
    // inherited pipe; the returned `File` becomes that number's sole owner.
    Ok(unsafe { File::from_raw_fd(fd) })
}

/// Takes ownership of a descriptor a handover blob names.
///
/// [`adopt_fd`] for one situation: this process is a handover's successor and
/// `fd` was named in the handover blob before the `execve`. Safe because an
/// inherited descriptor is open before the new image runs, so no number this process opens later can collide with it; do
/// not call it on a descriptor number from anywhere else.
/// `handover::adopt::adopt` refuses a repeated number.
///
/// # Errors
/// - [`SysError::ReservedFd`]: `fd` is below 3 (stdio is owned elsewhere).
/// - [`SysError::BadFd`]: `fd` names no open descriptor in this process.
pub fn adopt_handover_fd(fd: RawFd) -> Result<File, SysError> {
    // SAFETY: `fd` was inherited across `execve` from this process's own
    // predecessor, which carried it and named it in the handover blob. It was
    // open before this image ran, so no number this process opens can share
    // it.
    unsafe { adopt_fd(fd) }
}

/// A descriptor this process holds open and knows only by number, borrowed
/// for as long as the value lives.
///
/// The handover blob names its descriptors as numbers, and `shep-handover`
/// carries a borrowed one. The owner of each is the supervisor's handle that
/// the blob was built from, which stays alive across the whole handover.
#[derive(Debug)]
pub(crate) struct OpenFd(RawFd);

impl OpenFd {
    /// Wrap `fd`, which must name a descriptor open right now.
    ///
    /// # Errors
    /// As [`adoptable_fd`].
    pub(crate) fn new(fd: RawFd) -> Result<Self, SysError> {
        adoptable_fd(fd)?;
        Ok(Self(fd))
    }
}

impl AsFd for OpenFd {
    fn as_fd(&self) -> BorrowedFd<'_> {
        // SAFETY: `new` found the number open, and its owner holds it open
        // for the whole handover, which is the only time this is borrowed.
        unsafe { BorrowedFd::borrow_raw(self.0) }
    }
}

/// Duplicate `fd` onto a fresh number, for a caller that needs to inspect a
/// descriptor it must not take.
///
/// The duplicate shares the open file description but not ownership, so
/// closing it leaves the original open. It is above stdio, so
/// [`adoptable_fd`] cannot refuse it as reserved. The caller owns the number
/// that comes back.
///
/// # Errors
/// `fd` names no open descriptor, or this process is at its descriptor limit.
pub(crate) fn duplicate_fd(fd: RawFd) -> io::Result<RawFd> {
    // `borrow_raw` panics on -1 and is unsound on a closed number, so ask the
    // kernel first.
    nix::fcntl::fcntl(fd, nix::fcntl::FcntlArg::F_GETFD)?;
    // SAFETY: the check above found `fd` open, and the borrow ends with the
    // clone, which is a separate descriptor.
    let borrowed = unsafe { BorrowedFd::borrow_raw(fd) };
    Ok(borrowed.try_clone_to_owned()?.into_raw_fd())
}

/// Whether `socket` has been marked to accept connections with `listen(2)`.
///
/// `false` for a socket that is not listening and for a descriptor that is not
/// a socket at all, which is how a number the kernel recycled into something
/// else reads.
pub(crate) fn is_listening_socket(socket: &impl AsFd) -> bool {
    // Darwin's `getsockopt` refuses `SO_ACCEPTCONN` with `ENOPROTOOPT`, so
    // there the TCP state is read instead.
    #[cfg(target_vendor = "apple")]
    {
        use std::os::fd::AsRawFd;

        // `TCPS_LISTEN` in xnu's `bsd/netinet/tcp_fsm.h`; libc does not export it.
        const TCPS_LISTEN: u8 = 1;

        let mut info = core::mem::MaybeUninit::<nix::libc::tcp_connection_info>::zeroed();
        let mut len = nix::libc::socklen_t::try_from(size_of::<nix::libc::tcp_connection_info>())
            .unwrap_or(nix::libc::socklen_t::MAX);
        // SAFETY: `socket` keeps the descriptor open for the call, and `info`
        // and `len` describe a writable `tcp_connection_info` the kernel fills.
        let read = unsafe {
            nix::libc::getsockopt(
                socket.as_fd().as_raw_fd(),
                nix::libc::IPPROTO_TCP,
                nix::libc::TCP_CONNECTION_INFO,
                info.as_mut_ptr().cast(),
                &raw mut len,
            )
        };
        // SAFETY: the buffer was zeroed, which is a valid `tcp_connection_info`
        // (plain integers), and the kernel only overwrites it.
        read == 0 && unsafe { info.assume_init() }.tcpi_state == TCPS_LISTEN
    }
    #[cfg(not(target_vendor = "apple"))]
    {
        nix::sys::socket::getsockopt(socket, nix::sys::socket::sockopt::AcceptConn).unwrap_or(false)
    }
}

/// Opens `path` through `openat2` with `RESOLVE_NO_SYMLINKS`, so no component
/// of it may be a symlink at the moment of the open.
///
/// `path` is resolved from the working directory as given. Linux only: the
/// syscall is, and so is the 5.6 kernel it arrived in.
///
/// # Errors
/// What the syscall reported: `ELOOP` for a symlink in the path, `ENOSYS` on a
/// kernel below 5.6, `EPERM` under a seccomp filter that blocks it, and the
/// ordinary `open(2)` errors otherwise.
#[cfg(target_os = "linux")]
pub(crate) fn open_resolving_no_symlinks(
    path: &Path,
    flags: nix::fcntl::OFlag,
    mode: nix::sys::stat::Mode,
) -> io::Result<File> {
    use nix::fcntl::{OpenHow, ResolveFlag, openat2};

    let how = OpenHow::new()
        .flags(flags)
        .mode(mode)
        .resolve(ResolveFlag::RESOLVE_NO_SYMLINKS);
    let fd = openat2(nix::libc::AT_FDCWD, path, how)?;
    // SAFETY: `openat2` returned `Ok`, so `fd` is a descriptor the kernel just
    // opened for this call and nothing else holds; the returned `File`
    // becomes its sole owner.
    Ok(unsafe { File::from_raw_fd(fd) })
}

/// An environment block for a child whose `LISTEN_PID` is its own pid.
///
/// systemd's contract is that `LISTEN_PID` equals the pid of the process that
/// reads it, so the number exists only after the fork. [`set_listen_env`]
/// installs this block as the child's `environ` between the fork and the
/// exec, and [`Self::install`] writes the pid into it there.
// Not `setenv` in a `pre_exec` hook: std applies a `Command`'s env after every
// hook, and `setenv` allocates, which is unsafe between fork and exec in a
// threaded process. Everything the hook touches is allocated before the fork,
// and it only calls `getpid`, writes the digits and stores one pointer.
pub(crate) struct ListenEnv {
    /// Every `KEY=value\0` string back to back, then `LISTEN_PID=` and room
    /// for the digits. Held only to keep the allocation `table` and `pid_slot`
    /// point into alive; never resized once they exist.
    _block: Vec<u8>,
    /// `environ`'s shape: a null-terminated array of pointers into `block`.
    table: Vec<*mut core::ffi::c_char>,
    /// Where the digits go: the byte after `LISTEN_PID=`, inside `block`.
    pid_slot: *mut u8,
}

// SAFETY: the raw pointers address only `block`, which `self` owns and which
// does not move when `self` does. Sharing a `&ListenEnv` reads nothing through
// them, and `install` takes `&mut self`.
unsafe impl Send for ListenEnv {}
// SAFETY: as `Send`: a shared reference exposes no access through the pointers.
unsafe impl Sync for ListenEnv {}

/// Room for the largest `u32` in decimal, plus its NUL.
const PID_SLOT_LEN: usize = 11;

impl ListenEnv {
    /// Builds the block from `vars`, with a `LISTEN_PID` entry still unset.
    ///
    /// # Errors
    /// - `InvalidInput` if a name is empty or holds `=`, or a name or value
    ///   holds a NUL, which are the cases `Command` refuses too.
    pub(crate) fn new(vars: &std::collections::BTreeMap<String, String>) -> io::Result<Self> {
        let mut block = Vec::new();
        let mut starts = Vec::with_capacity(vars.len() + 1);
        for (key, value) in vars {
            if key.is_empty() || key.contains('=') || key.contains('\0') || value.contains('\0') {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidInput,
                    format!("environment variable `{key}` cannot be passed to a child"),
                ));
            }
            starts.push(block.len());
            block.extend_from_slice(key.as_bytes());
            block.push(b'=');
            block.extend_from_slice(value.as_bytes());
            block.push(0);
        }
        starts.push(block.len());
        block.extend_from_slice(b"LISTEN_PID=");
        let slot_at = block.len();
        block.resize(slot_at + PID_SLOT_LEN, 0);

        // Every pointer derives from this one, taken after the last resize.
        let base = block.as_mut_ptr();
        // SAFETY: each offset is at most `block.len()`, so it stays inside the
        // allocation `base` points into.
        let mut table: Vec<*mut core::ffi::c_char> = starts
            .iter()
            .map(|at| unsafe { base.add(*at) }.cast())
            .collect();
        table.push(core::ptr::null_mut());
        // SAFETY: `slot_at + PID_SLOT_LEN` is `block.len()`.
        let pid_slot = unsafe { base.add(slot_at) };
        Ok(Self {
            _block: block,
            table,
            pid_slot,
        })
    }

    /// Writes this process's pid into `LISTEN_PID` and makes the block the
    /// process's environment. Runs in the forked child before the exec.
    fn install(&mut self) -> io::Result<()> {
        // SAFETY: `getpid` takes no arguments and cannot fail.
        let pid = unsafe { nix::libc::getpid() }.unsigned_abs();
        let mut reversed = [0u8; PID_SLOT_LEN];
        let (mut rest, mut len) = (pid, 0);
        loop {
            reversed[len] = b'0' + (rest % 10) as u8;
            rest /= 10;
            len += 1;
            if rest == 0 {
                break;
            }
        }
        debug_assert!(len < PID_SLOT_LEN, "a u32 is ten digits at most");
        for (at, digit) in reversed[..len].iter().rev().enumerate() {
            // SAFETY: `at < len < PID_SLOT_LEN`, and `pid_slot` addresses
            // `PID_SLOT_LEN` writable bytes of `self._block`.
            unsafe { self.pid_slot.add(at).write(*digit) };
        }
        // SAFETY: as above, `len < PID_SLOT_LEN`; this is the terminator.
        unsafe { self.pid_slot.add(len).write(0) };
        // SAFETY: `environ_slot` names this process's environment pointer. The
        // table is null-terminated and its strings are NUL-terminated and
        // live in `self._block`, which outlives the exec.
        unsafe { *environ_slot() = self.table.as_mut_ptr() };
        Ok(())
    }
}

/// The address of the process's `environ` pointer.
///
/// # Safety
/// Only meaningful in a process no other thread is reading the environment
/// of: a forked child between `fork` and `exec`.
#[cfg(target_vendor = "apple")]
unsafe fn environ_slot() -> *mut *mut *mut core::ffi::c_char {
    // SAFETY: the call takes no arguments and returns the process's slot.
    unsafe { nix::libc::_NSGetEnviron() }
}

/// The address of the process's `environ` pointer.
///
/// # Safety
/// As the macOS definition.
#[cfg(not(target_vendor = "apple"))]
unsafe fn environ_slot() -> *mut *mut *mut core::ffi::c_char {
    unsafe extern "C" {
        static mut environ: *mut *mut core::ffi::c_char;
    }
    // `environ` is the C library's own symbol, present on every unix target
    // that is not Apple. Taking its address with `&raw mut` is safe.
    &raw mut environ
}

/// Makes `command`'s child run with `env` as its whole environment, `LISTEN_PID`
/// included.
///
/// `command` must not have had `env`, `envs` or `env_clear` called: std
/// applies those after this hook and would replace the block.
pub(crate) fn set_listen_env(command: &mut std::process::Command, mut env: ListenEnv) {
    use std::os::unix::process::CommandExt as _;
    // SAFETY: `pre_exec` requires the closure to be async-signal-safe.
    // `ListenEnv::install` calls `getpid`, writes into memory allocated
    // before the fork and stores one pointer; it allocates, locks and panics
    // nowhere.
    unsafe { command.pre_exec(move || env.install()) };
}

/// Makes `command`'s child lead a new session with its fd 0, a terminal's
/// slave, as the controlling terminal.
///
/// Run after std has installed the child's stdio, so fd 0 is already the
/// slave. The child leads its own process group too, which is why a pty
/// spawn must not also set `process_group`: `setsid` fails for a group leader.
pub(crate) fn take_terminal_on_exec(command: &mut std::process::Command) {
    use std::os::unix::process::CommandExt as _;
    // SAFETY: `pre_exec` requires the closure to be async-signal-safe.
    // `take_terminal` makes two raw syscalls, `setsid` and `ioctl(TIOCSCTTY)`,
    // and builds an `io::Error` from an errno; it allocates, locks and panics
    // nowhere.
    unsafe { command.pre_exec(take_terminal) };
}

/// `setsid`, then `TIOCSCTTY` on fd 0.
fn take_terminal() -> io::Result<()> {
    rustix::process::setsid()?;
    // SAFETY: fd 0 is open for the whole call: std dup2'd the slave onto it
    // before running the pre-exec hooks, and nothing closes it before the
    // exec.
    let terminal = unsafe { BorrowedFd::borrow_raw(0) };
    rustix::process::ioctl_tiocsctty(terminal)?;
    Ok(())
}

/// Makes `command`'s child write `0` to `procs`, an open `cgroup.procs`, so it
/// joins that cgroup between the fork and the exec.
///
/// Joined before the exec rather than after the spawn: a cgroup accounts only
/// for a process that was inside it before it forked. `procs` must be opened
/// before the spawn, as the child may have dropped privilege by then, and the
/// hook must be added before any fd mapping, which can overwrite its number.
#[cfg(target_os = "linux")]
pub(crate) fn join_cgroup_on_exec(command: &mut std::process::Command, procs: File) {
    use std::os::fd::AsRawFd as _;
    use std::os::unix::process::CommandExt as _;
    let fd = procs.as_raw_fd();
    // SAFETY: `pre_exec` requires the closure to be async-signal-safe. This one
    // only calls `write(2)` on `fd`, which `procs` keeps open and the closure
    // owns, and builds an `io::Error` from an errno without allocating.
    unsafe {
        command.pre_exec(move || {
            let _keep_open = &procs;
            write_zero(fd)
        });
    }
}

/// Writes one `0` to `fd`, retrying on `EINTR`.
#[cfg(target_os = "linux")]
fn write_zero(fd: RawFd) -> io::Result<()> {
    loop {
        // SAFETY: `fd` is open for the whole call, as `join_cgroup_on_exec`'s
        // closure owns it, and the buffer is one byte that outlives the call.
        let written = unsafe { nix::libc::write(fd, b"0".as_ptr().cast(), 1) };
        match written {
            1 => return Ok(()),
            -1 => {
                let error = io::Error::last_os_error();
                if error.kind() != io::ErrorKind::Interrupted {
                    return Err(error);
                }
            }
            _ => return Err(io::Error::from_raw_os_error(nix::libc::EIO)),
        }
    }
}

/// Errors adopting an inherited descriptor.
///
/// `#[non_exhaustive]`: a future adoption check would need its own variant
/// rather than stretching [`Self::BadFd`] past what `fcntl` reported.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SysError {
    /// The descriptor number cannot be adopted: negative, or below 3
    /// (stdio is owned elsewhere).
    ReservedFd(RawFd),
    /// The descriptor is not open in this process (carries the errno name).
    BadFd {
        /// The descriptor number that was rejected.
        fd: RawFd,
        /// The OS error name/message `fcntl` reported.
        errno: String,
    },
}

impl fmt::Display for SysError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::ReservedFd(fd) if *fd < 0 => {
                write!(f, "fd {fd} is negative and cannot name a descriptor")
            }
            Self::ReservedFd(fd) => {
                write!(f, "fd {fd} is reserved for stdio and cannot be adopted")
            }
            Self::BadFd { fd, errno } => {
                write!(
                    f,
                    "fd {fd} is not an open descriptor in this process: {errno}"
                )
            }
        }
    }
}

impl core::error::Error for SysError {}

#[cfg(test)]
mod tests {
    use super::*;
    use std::io::Read;
    use std::os::unix::io::{AsRawFd, IntoRawFd};

    #[test]
    fn a_listening_tcp_socket_reads_as_one() {
        let listening = std::net::TcpListener::bind("127.0.0.1:0").unwrap();

        assert!(is_listening_socket(&listening));
    }

    #[test]
    fn a_bound_tcp_socket_that_never_listened_does_not_read_as_one() {
        use nix::sys::socket::{
            AddressFamily, SockFlag, SockType, SockaddrIn, bind, socket as open_socket,
        };

        let bound = open_socket(
            AddressFamily::Inet,
            SockType::Stream,
            SockFlag::empty(),
            None,
        )
        .unwrap();
        bind(
            bound.as_raw_fd(),
            &SockaddrIn::from(std::net::SocketAddrV4::new(
                std::net::Ipv4Addr::LOCALHOST,
                0,
            )),
        )
        .unwrap();

        assert!(!is_listening_socket(&bound));
    }

    #[test]
    fn a_connected_socket_and_a_file_do_not() {
        let (connected, _peer) = std::os::unix::net::UnixStream::pair().unwrap();
        let file = tempfile::tempfile().unwrap();

        assert!(!is_listening_socket(&connected));
        assert!(!is_listening_socket(&file));
    }

    #[test]
    fn a_real_inherited_descriptor_is_adopted_and_owned() {
        // `into_raw_fd` leaves the descriptor in the state an exec-inherited
        // one is in: live, and owned by nobody.
        let (parent, child) = std::os::unix::net::UnixStream::pair().unwrap();
        let fd = child.into_raw_fd();
        {
            // SAFETY: this test process has opened nothing else of its own
            // between creating the pair and adopting it.
            let mut adopted = unsafe { adopt_fd(fd) }.unwrap();
            std::io::Write::write_all(&mut adopted, b"hello\n").unwrap();
        } // dropping the File closes the descriptor
        let mut read = String::new();
        let mut parent = parent;
        parent.read_to_string(&mut read).unwrap();
        assert_eq!(
            read, "hello\n",
            "EOF proves the adopted descriptor was closed on drop"
        );
    }

    #[test]
    fn stdio_numbers_are_refused() {
        for fd in 0..3 {
            // SAFETY: adopt_fd refuses fd < 3 before touching anything, so
            // there is no precondition to uphold for a call that never adopts.
            let result = unsafe { adopt_fd(fd) };
            assert_eq!(result.unwrap_err(), SysError::ReservedFd(fd));
        }
    }

    #[test]
    fn a_negative_fd_is_refused_with_an_accurate_message() {
        // SAFETY: `adopt_fd` refuses fd < 3 before touching anything.
        let err = unsafe { adopt_fd(-1) }.unwrap_err();
        assert_eq!(err, SysError::ReservedFd(-1));
        assert!(
            err.to_string().contains("negative"),
            "a negative fd is not \"reserved for stdio\": {err}"
        );
    }

    #[test]
    fn a_closed_descriptor_is_refused_instead_of_adopted() {
        // A high number, not the pair's own: unix hands out the lowest free
        // fd, so once this one is closed no concurrent test in this binary is
        // handed it back ahead of the ~2048 lower free ones. That floor is
        // what makes the second adoption a real `BadFd` probe, not a race.
        const PROBE_FD: RawFd = 2048;
        let (a, _b) = std::os::unix::net::UnixStream::pair().unwrap();
        let parked = nix::fcntl::fcntl(a.as_raw_fd(), nix::fcntl::FcntlArg::F_DUPFD(PROBE_FD))
            .expect("duplicating onto a high fd number must succeed");
        assert!(
            parked >= PROBE_FD,
            "F_DUPFD must return a number at or above its floor, got {parked}"
        );
        // SAFETY: `parked` is a descriptor this test just created and owns
        // outright; `a` keeps its own separate descriptor and its own Drop.
        drop(unsafe { adopt_fd(parked) }.unwrap()); // adopt once, closing it
        // SAFETY: `parked` is closed now, and being >= PROBE_FD it cannot be
        // reallocated while lower numbers remain free, so this second
        // attempt probes a genuinely closed descriptor. BadFd is expected to
        // refuse it before `from_raw_fd` ever runs.
        let second = unsafe { adopt_fd(parked) };
        assert!(matches!(second, Err(SysError::BadFd { .. })));
    }

    #[test]
    fn a_fd_this_process_never_owned_is_refused() {
        // fd 4096 is a number this process never owns: fd-table limits sit far
        // below it, so `F_GETFD` fails deterministically even under a parallel harness.
        // SAFETY: adopt_fd's F_GETFD probe rejects it before `from_raw_fd` ever runs,
        // so there is no ordering precondition to uphold for a call that never adopts.
        let err = unsafe { adopt_fd(4096) }.unwrap_err();
        assert!(
            matches!(err, SysError::BadFd { fd: 4096, .. }),
            "a fd this process never owned must be refused as BadFd: {err:?}"
        );
    }

    #[test]
    fn a_listen_child_reads_its_own_pid_in_a_block_that_replaces_the_environment() {
        let vars = std::collections::BTreeMap::from([("FOO".to_string(), "bar baz".to_string())]);
        let mut command = std::process::Command::new("/bin/sh");
        command.args([
            "-c",
            r#"printf '%s|%s|%s|[%s]' "$LISTEN_PID" "$$" "$FOO" "$HOME""#,
        ]);
        set_listen_env(&mut command, ListenEnv::new(&vars).unwrap());

        let out = command.output().unwrap();

        let text = String::from_utf8(out.stdout).unwrap();
        let parts: Vec<&str> = text.split('|').collect();
        assert_eq!(
            parts[0], parts[1],
            "LISTEN_PID is the child's own pid: {text}"
        );
        assert!(parts[0].parse::<u32>().is_ok(), "{text}");
        assert_eq!((parts[2], parts[3]), ("bar baz", "[]"), "{text}");
    }

    #[test]
    fn two_children_of_one_block_each_read_their_own_pid() {
        let mut pids = Vec::new();
        for _ in 0..2 {
            let mut command = std::process::Command::new("/bin/sh");
            command.args(["-c", r#"printf '%s' "$LISTEN_PID""#]);
            set_listen_env(&mut command, ListenEnv::new(&Default::default()).unwrap());
            let out = command.output().unwrap();
            pids.push(String::from_utf8(out.stdout).unwrap());
        }
        assert_ne!(pids[0], pids[1]);
    }

    #[test]
    fn a_name_or_value_a_command_would_refuse_is_refused_up_front() {
        for (key, value) in [("", "v"), ("A=B", "v"), ("A\0B", "v"), ("A", "v\0")] {
            let vars = std::collections::BTreeMap::from([(key.to_string(), value.to_string())]);
            let error = ListenEnv::new(&vars).err().expect("refused");
            assert_eq!(error.kind(), io::ErrorKind::InvalidInput, "{key:?}");
        }
    }

    /// The property that closes the race: whatever resolved the path before,
    /// a link in it when the syscall runs is refused. A caller's own walk
    /// cannot stand in for this, since a link can appear after it.
    #[cfg(target_os = "linux")]
    #[test]
    fn a_symlink_in_the_path_is_refused_by_the_syscall_itself() {
        use nix::fcntl::OFlag;
        use nix::sys::stat::Mode;

        let dir = tempfile::tempdir().unwrap();
        let real = dir.path().join("real");
        std::fs::create_dir(&real).unwrap();
        std::os::unix::fs::symlink(&real, dir.path().join("logs")).unwrap();
        let flags = OFlag::O_WRONLY | OFlag::O_CREAT | OFlag::O_CLOEXEC;
        let mode = Mode::from_bits_truncate(0o600);

        let refused = open_resolving_no_symlinks(&dir.path().join("logs/web-out.log"), flags, mode);

        assert_eq!(
            refused.unwrap_err().raw_os_error(),
            Some(nix::libc::ELOOP),
            "a link met mid-path must be ELOOP"
        );
        assert!(!real.join("web-out.log").exists());
        open_resolving_no_symlinks(&real.join("web-out.log"), flags, mode)
            .expect("the same file by its real path opens");
    }
}