zlayer_agent/

capability.rs

//! Daemon capability survey.
//!
//! Probes the runtime environment of the zlayer daemon (root vs. non-root,
//! host vs. nested in a container, cgroup v2 path, `CAP_NET_ADMIN`, presence
//! of `/dev/net/tun`, and writability of the cgroup root) and derives a coarse
//! [`DaemonMode`] from those signals.
//!
//! All probes are intentionally cheap and non-destructive — a handful of
//! syscalls, no allocations of kernel resources (no TUN interfaces, no cgroup
//! writes). The struct is safe to construct multiple times.
//!
//! Non-Linux targets report a fixed degraded survey since the kernel features
//! these probes target are Linux-only.

use std::sync::OnceLock;

use serde::{Deserialize, Serialize};

/// Coarse classification of the daemon's effective execution environment.
///
/// Derived from the boolean fields on [`DaemonCapabilities`].
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum DaemonMode {
    /// Host-level execution: all caps, can write cgroup root, can create overlay.
    Full,
    /// Inside a container: scoped to a sub-cgroup; some caps may be present.
    NestedAdaptive,
    /// Missing privileges required for any meaningful container creation.
    Degraded,
}

/// Snapshot of the daemon's effective capabilities and execution environment.
///
/// Construct via [`DaemonCapabilities::probe`]. Cheap to call repeatedly.
///
/// The struct intentionally exposes independent capability bits as separate
/// booleans rather than collapsing them into an enum — each bit corresponds to
/// an orthogonal kernel feature (cgroup write, `CAP_NET_ADMIN`, TUN access,
/// root-ness) and downstream code wants to inspect them independently when
/// deciding what to gate.
#[allow(clippy::struct_excessive_bools)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DaemonCapabilities {
    /// `true` if the process is running as uid 0.
    pub is_root: bool,
    /// `true` if the process appears to be inside a container (non-root cgroup
    /// v2 path).
    pub is_nested: bool,
    /// The cgroup v2 path of the current process, if any (e.g.
    /// `/system.slice/zlayer.service`). `None` on the cgroup root, on
    /// cgroup-v1-only hosts, on non-Linux, or on read errors.
    pub cgroup_parent: Option<String>,
    /// `true` if the cgroup root's `cgroup.subtree_control` has the
    /// owner-write bit set. Coarse, non-destructive signal — does not
    /// guarantee an actual write will succeed.
    pub can_write_cgroup_root: bool,
    /// `true` if `CAP_NET_ADMIN` is present in the process's *effective* set
    /// (Linux only).
    pub has_cap_net_admin: bool,
    /// `true` if `/dev/net/tun` can be opened r/w in non-blocking mode without
    /// EACCES/EPERM/ENOENT/ENXIO. The fd is dropped immediately.
    pub tun_device_available: bool,
    /// `true` if the daemon can build container rootfs as an overlayfs mount
    /// (shared read-only lowerdirs + per-container upperdir) instead of a full
    /// per-container copy of every layer. Requires ALL of: root or
    /// `CAP_SYS_ADMIN`, `overlay` listed in `/proc/filesystems`, and a probe
    /// overlay mount in a temp dir that succeeds and immediately unmounts.
    /// Computed once at startup (the result cannot change for a running daemon)
    /// and cached with the rest of the survey.
    pub overlayfs_rootfs_available: bool,
    /// `true` if the daemon can build a container rootfs as a ROOTLESS
    /// `fuse-overlayfs` mount — the userspace overlay backend that needs neither
    /// `CAP_SYS_ADMIN` nor `CAP_MKNOD`. It still gives the shared-layer dedup of
    /// the kernel path (shared read-only lowerdirs + a per-container upperdir),
    /// but represents whiteouts the rootless way fuse-overlayfs reads: a plain
    /// `.wh.<name>` regular file and the `user.overlay.opaque` xattr (both
    /// settable without privilege) instead of `0:0` char devices /
    /// `trusted.overlay.opaque`. Requires ALL of: the `fuse-overlayfs` binary on
    /// `PATH`, `/dev/fuse` openable, and a probe rootless mount that succeeds and
    /// immediately unmounts. Independent of root / `CAP_SYS_ADMIN` — this is the
    /// fallback the daemon uses when [`Self::overlayfs_rootfs_available`] is
    /// false. Computed once at startup and cached.
    pub fuse_overlayfs_rootfs_available: bool,
    /// Coarse classification derived from the above fields.
    pub effective_mode: DaemonMode,
}

/// Process-wide memoised capability survey. Seeded by the first call to
/// [`DaemonCapabilities::get`] or [`DaemonCapabilities::seed`].
static CAPS: OnceLock<DaemonCapabilities> = OnceLock::new();

impl DaemonCapabilities {
    /// Returns the process-wide capability snapshot, probing on first call.
    ///
    /// Subsequent calls return the same memoised instance — capabilities of a
    /// running daemon do not change at runtime, so re-probing would be wasted
    /// syscalls and could create the illusion that the daemon's behaviour can
    /// shift mid-flight.
    pub fn get() -> &'static Self {
        CAPS.get_or_init(Self::probe)
    }

    /// Eagerly seed the memoised survey with an explicit probe result.
    ///
    /// Useful at daemon startup to force the probe to happen at a known point
    /// (so the banner log appears in the expected place). Returns the stored
    /// instance — if the cache was already seeded, the existing value wins
    /// and the passed-in `caps` is dropped (probe is pure, so this is fine).
    ///
    /// # Panics
    ///
    /// In practice this never panics — `OnceLock::set` either stores the
    /// value or rejects it because the cell is already filled, and in both
    /// cases the subsequent `get()` returns `Some`. The `expect` exists only
    /// to satisfy the type system.
    pub fn seed(caps: Self) -> &'static Self {
        let _ = CAPS.set(caps);
        CAPS.get()
            .expect("CAPS is filled after set or was already filled")
    }

    /// Probe the running daemon's effective capabilities.
    ///
    /// Cheap — a handful of syscalls and no resource allocation. Prefer
    /// [`DaemonCapabilities::get`] when you want the process-wide memoised
    /// value; call this directly only when you intentionally want a fresh
    /// snapshot (e.g. tests).
    #[must_use]
    pub fn probe() -> Self {
        let is_root = zlayer_paths::is_root();
        let cgroup_parent = current_cgroup_v2_path();
        let is_nested = cgroup_parent.is_some();
        let can_write_cgroup_root = probe_can_write_cgroup_root();
        let has_cap_net_admin = probe_has_cap_net_admin();
        let tun_device_available = probe_tun_device_available();
        let overlayfs_rootfs_available = probe_overlayfs_rootfs_available(is_root);
        let fuse_overlayfs_rootfs_available = probe_fuse_overlayfs_rootfs_available();

        let effective_mode =
            if !is_nested && can_write_cgroup_root && has_cap_net_admin && tun_device_available {
                DaemonMode::Full
            } else if can_write_cgroup_root || cgroup_parent.is_some() {
                DaemonMode::NestedAdaptive
            } else {
                DaemonMode::Degraded
            };

        Self {
            is_root,
            is_nested,
            cgroup_parent,
            can_write_cgroup_root,
            has_cap_net_admin,
            tun_device_available,
            overlayfs_rootfs_available,
            fuse_overlayfs_rootfs_available,
            effective_mode,
        }
    }
}

/// Decide whether capability state forces a fallback from overlay to host
/// networking. Pure and side-effect-free so it can be unit-tested without the
/// host's real capability state.
///
/// Returns `Some(reason)` when overlay networking cannot work and the daemon
/// must fall back to host networking (or hard-error if the operator passed
/// `--require-overlay`); returns `None` when overlay is viable.
///
/// Call this ONLY when the operator did not already request host networking —
/// an explicit `--host-network` is a deliberate choice, not a degraded state.
#[must_use]
pub fn capability_overlay_fallback(
    has_cap_net_admin: bool,
    tun_device_available: bool,
) -> Option<String> {
    match (has_cap_net_admin, tun_device_available) {
        (true, true) => None,
        (false, false) => Some(
            "CAP_NET_ADMIN is not in the daemon's effective set and /dev/net/tun is not available"
                .to_string(),
        ),
        (false, true) => Some("CAP_NET_ADMIN is not in the daemon's effective set".to_string()),
        (true, false) => Some("/dev/net/tun is not available".to_string()),
    }
}

/// Decide whether the daemon can run the overlay in fully rootless mode: the
/// overlay daemon wraps itself in its own user+network namespace (holding
/// `CAP_NET_ADMIN` over its OWN netns only) and uses pasta for egress, instead of
/// requiring host root or a setcap'd binary.
///
/// Rootless overlay is viable only when ALL hold:
/// - NOT already root (a root daemon should use the normal root overlay path),
/// - the process does NOT already hold effective `CAP_NET_ADMIN` (if it does, the
///   setcap/root overlay path is simpler and gives host-level networking),
/// - `/dev/net/tun` is openable (boringtun needs it for the TUN device), and
/// - the `pasta` (passt) egress helper is available on the host.
///
/// Pure and side-effect-free so it can be unit-tested without namespaces.
#[must_use]
#[allow(clippy::fn_params_excessive_bools)] // parallel capability probe flags, intentionally flat
pub fn can_rootless_overlay(
    is_root: bool,
    has_cap_net_admin: bool,
    tun_device_available: bool,
    pasta_available: bool,
) -> bool {
    !is_root && !has_cap_net_admin && tun_device_available && pasta_available
}

/// Pure parser for the contents of `/proc/self/cgroup`.
///
/// Finds the cgroup-v2 line (prefix `0::`) and returns the path suffix with
/// surrounding whitespace trimmed. Returns `None` when:
/// - the input has no `0::` line (cgroup-v1-only host), or
/// - the v2 path is exactly `/` (host root — bare-metal, no enclosing cgroup), or
/// - the input is empty.
#[cfg(target_os = "linux")]
fn parse_cgroup_v2_line(content: &str) -> Option<String> {
    for line in content.lines() {
        if let Some(rest) = line.strip_prefix("0::") {
            let trimmed = rest.trim();
            if trimmed.is_empty() || trimmed == "/" {
                return None;
            }
            return Some(trimmed.to_string());
        }
    }
    None
}

/// Returns the current process's cgroup-v2 path, if any.
///
/// On Linux reads `/proc/self/cgroup` and delegates to `parse_cgroup_v2_line`.
/// On non-Linux always returns `None`. Returns `None` on any read error or
/// when the process is at the cgroup-v2 root (bare-metal case).
#[cfg(target_os = "linux")]
#[must_use]
pub fn current_cgroup_v2_path() -> Option<String> {
    let content = std::fs::read_to_string("/proc/self/cgroup").ok()?;
    parse_cgroup_v2_line(&content)
}

#[cfg(not(target_os = "linux"))]
#[must_use]
pub fn current_cgroup_v2_path() -> Option<String> {
    None
}

/// Pure path computation: given a cgroup-v2 scope reported by
/// `/proc/self/cgroup`, return the sibling `<scope>/containers` parent that
/// should be used for new container cgroups.
///
/// If `scope` already ends with `/init` (the daemon has already been migrated
/// into the `init` leaf by a previous call), the `/init` suffix is stripped
/// and the result anchored at the real scope. This makes
/// [`ensure_daemon_leaf_and_container_parent`] idempotent.
#[cfg(target_os = "linux")]
fn compute_target_parent(scope: &str) -> String {
    let base = scope.strip_suffix("/init").unwrap_or(scope);
    let base = base.trim_end_matches('/');
    format!("{base}/containers")
}

/// Migrate the current daemon process into a `<scope>/init` sub-cgroup and
/// return the sibling `<scope>/containers` path as the parent for future
/// container cgroups. Idempotent — safe to call multiple times.
///
/// Returns `None` on non-Linux, when `/proc/self/cgroup` can't be parsed,
/// when `/sys/fs/cgroup` is read-only, or when the mkdir/PID-write fails.
/// Callers should fall back to the raw `current_cgroup_v2_path()` value in
/// those cases (the auto-detect path will surface the underlying error).
#[cfg(target_os = "linux")]
#[must_use]
pub fn ensure_daemon_leaf_and_container_parent() -> Option<String> {
    let scope = current_cgroup_v2_path()?;
    let containers = compute_target_parent(&scope);
    // Idempotency: if we're already in `<base>/init`, just return the sibling.
    if scope.ends_with("/init") {
        let containers_fs = format!("/sys/fs/cgroup{containers}");
        match std::fs::create_dir_all(&containers_fs) {
            Ok(()) => {}
            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {}
            Err(_) => return None,
        }
        return Some(containers);
    }

    let scope = scope.trim_end_matches('/').to_string();
    let mount = "/sys/fs/cgroup";
    let init_dir = format!("{mount}{scope}/init");

    match std::fs::create_dir_all(&init_dir) {
        Ok(()) => {}
        Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {}
        Err(_) => return None,
    }

    let pid_path = format!("{init_dir}/cgroup.procs");
    let pid_str = format!("{}", std::process::id());
    if std::fs::write(&pid_path, &pid_str).is_err() {
        // Already migrated? Re-check /proc/self/cgroup before giving up.
        let now = current_cgroup_v2_path()?;
        if now != format!("{scope}/init") {
            return None;
        }
    }

    // Verify the migration actually moved us into <scope>/init.
    let after = current_cgroup_v2_path()?;
    if after != format!("{scope}/init") {
        return None;
    }

    let containers_dir = format!("{mount}{containers}");
    match std::fs::create_dir_all(&containers_dir) {
        Ok(()) => {}
        Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {}
        Err(_) => return None,
    }

    Some(containers)
}

#[cfg(not(target_os = "linux"))]
#[must_use]
pub fn ensure_daemon_leaf_and_container_parent() -> Option<String> {
    None
}

/// Top-level cgroup-v2 node (relative to the cgroup-v2 mount) under which a
/// writable root host daemon roots container cgroups. Kept deliberately
/// OUTSIDE the daemon's own systemd unit cgroup (`/system.slice/zlayer.service`)
/// so that containers which survive a daemon stop (`KillMode=process`) never
/// turn the unit's cgroup into a populated inner node. A populated inner node
/// makes systemd's re-fork of the daemon fail with `EBUSY`
/// (`Failed to spawn executor: Device or resource busy` / `Result: resources`),
/// wedging the restart loop until the orphans happen to die. Mirrors how
/// Docker/containerd root containers under their own top-level hierarchy
/// (`/sys/fs/cgroup/docker/...`) rather than under their service unit.
///
/// The name has no `.slice`/`.scope` suffix so systemd treats it as foreign
/// and never tries to reconcile or prune it.
#[cfg(target_os = "linux")]
const HOST_CONTAINER_ROOT: &str = "/zlayer";

/// Controllers delegated down the host container hierarchy so libcontainer can
/// apply cpu/memory/pids/io limits on the leaf container cgroup. Only those
/// actually available at each level (per `cgroup.controllers`) are enabled, so
/// a host missing a controller degrades gracefully instead of erroring.
#[cfg(target_os = "linux")]
const HOST_CGROUP_CONTROLLERS: &[&str] = &["cpu", "cpuset", "io", "memory", "pids"];

/// Pure path computation: the host-mode container parent, `<root>/containers`,
/// relative to the cgroup-v2 mount.
#[cfg(target_os = "linux")]
#[must_use]
fn compute_host_container_parent() -> String {
    format!("{HOST_CONTAINER_ROOT}/containers")
}

/// Enable every wanted controller that is actually available at `dir`
/// (a `/sys/fs/cgroup/...` path) by writing `+<ctrl>` tokens to its
/// `cgroup.subtree_control`. Best-effort: filtering to available controllers
/// avoids the `EINVAL` a single unavailable token would cause, and any write
/// error is ignored (libcontainer will surface a real failure later if a
/// required controller is genuinely missing).
#[cfg(target_os = "linux")]
fn enable_available_controllers(dir: &str) {
    let available =
        std::fs::read_to_string(format!("{dir}/cgroup.controllers")).unwrap_or_default();
    let tokens: Vec<String> = HOST_CGROUP_CONTROLLERS
        .iter()
        .filter(|c| available.split_whitespace().any(|a| a == **c))
        .map(|c| format!("+{c}"))
        .collect();
    if tokens.is_empty() {
        return;
    }
    let _ = std::fs::write(format!("{dir}/cgroup.subtree_control"), tokens.join(" "));
}

/// Ensure the top-level host container hierarchy exists and has controllers
/// delegated, returning the container parent path (`/zlayer/containers`,
/// relative to the cgroup-v2 mount) for libcontainer's `cgroupsPath`.
///
/// Only meaningful when the daemon can write the cgroup-v2 root (root host
/// daemon — `DaemonCapabilities::can_write_cgroup_root`). Returns `None` on
/// non-Linux, or when the mkdir fails (e.g. a read-only `/sys/fs/cgroup`),
/// in which case callers fall back to in-scope placement.
///
/// Unlike [`ensure_daemon_leaf_and_container_parent`], this does NOT migrate
/// the daemon PID: with containers rooted outside the unit cgroup, the unit
/// cgroup stays a clean leaf that systemd can always re-attach to on restart,
/// so no `init` leaf split is needed.
#[cfg(target_os = "linux")]
#[must_use]
pub fn ensure_host_container_parent() -> Option<String> {
    let mount = "/sys/fs/cgroup";
    let containers = compute_host_container_parent();
    let root_fs = format!("{mount}{HOST_CONTAINER_ROOT}");
    let containers_fs = format!("{mount}{containers}");

    for dir in [&root_fs, &containers_fs] {
        match std::fs::create_dir_all(dir) {
            Ok(()) => {}
            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {}
            Err(_) => return None,
        }
    }

    // Delegate controllers down both levels so libcontainer can set limits on
    // the leaf `<root>/containers/<id>` cgroup it creates.
    enable_available_controllers(&root_fs);
    enable_available_controllers(&containers_fs);

    Some(containers)
}

#[cfg(not(target_os = "linux"))]
#[must_use]
pub fn ensure_host_container_parent() -> Option<String> {
    None
}

/// Depth-first remove a cgroup-v2 directory tree rooted at `dir`.
///
/// A cgroup-v2 parent cannot be `rmdir`'d while it still has child cgroups, so
/// child directories are removed first (post-order). Best-effort throughout:
/// a `NotFound` is treated as success (idempotent), and any other error is
/// logged at `warn!` but does not abort the recursion — reaping as many leaves
/// as possible is better than bailing on the first `EBUSY`.
#[cfg(target_os = "linux")]
fn remove_cgroup_tree(dir: &std::path::Path) {
    // Best-effort: evacuate any survivors before attempting rmdir. `cgroup.kill`
    // (kernel >= 5.14) SIGKILLs the whole subtree atomically; ignore failure on
    // older kernels or when the file is absent.
    let _ = std::fs::write(dir.join("cgroup.kill"), "1");

    match std::fs::read_dir(dir) {
        Ok(entries) => {
            for entry in entries.flatten() {
                let path = entry.path();
                if entry.file_type().is_ok_and(|t| t.is_dir()) {
                    // Child cgroup: recurse first — a v2 parent can't be
                    // rmdir'd while children exist.
                    remove_cgroup_tree(&path);
                } else {
                    // On real cgroupfs the control files (cgroup.procs, etc.)
                    // are removed implicitly by rmdir, so this is normally a
                    // NotFound no-op; on a plain filesystem (and in tests) it
                    // unlinks the leftover so the dir can be removed.
                    let _ = std::fs::remove_file(&path);
                }
            }
        }
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return,
        Err(e) => {
            tracing::warn!(cgroup = %dir.display(), error = %e, "cgroup read_dir failed");
        }
    }

    match std::fs::remove_dir(dir) {
        Ok(()) => {}
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
        Err(e) => {
            tracing::warn!(cgroup = %dir.display(), error = %e, "cgroup rmdir failed");
        }
    }
}

/// Reap the host-mode leaf cgroup for `container_id` under `base`
/// (`<base>/zlayer/containers/<container_id>`), depth-first.
///
/// Split out from [`remove_host_container_cgroup`] so the recursion can be
/// exercised by a unit test against a temp directory instead of the real
/// `/sys/fs/cgroup` mount. Idempotent: a missing leaf is a no-op.
#[cfg(target_os = "linux")]
fn remove_host_container_cgroup_at(base: &str, container_id: &str) {
    let leaf = std::path::PathBuf::from(base).join(format!("zlayer/containers/{container_id}"));
    if !leaf.exists() {
        return;
    }
    remove_cgroup_tree(&leaf);
}

/// Best-effort removal of the host-mode container cgroup at
/// `/sys/fs/cgroup/zlayer/containers/<container_id>`.
///
/// libcontainer's `delete()` normally reaps the leaf cgroup, but
/// systemd-cgroup races and cgroup-v2 unified hiccups can leave a stale, empty
/// directory behind. Because the next `create_container` rebuilds the same
/// `<root>/containers/<id>` path, that orphan trips libcontainer's `build()`
/// with `could not delete` on restart/scale. This reaps it directly at the
/// real path (the old `read_dir`-the-mount scan never matched two levels down).
///
/// Idempotent (`NotFound` is ignored) and best-effort (`EBUSY`/other errors are
/// logged, not propagated). No-op on non-Linux.
#[cfg(target_os = "linux")]
pub fn remove_host_container_cgroup(container_id: &str) {
    remove_host_container_cgroup_at("/sys/fs/cgroup", container_id);
}

#[cfg(not(target_os = "linux"))]
pub fn remove_host_container_cgroup(_container_id: &str) {}

#[cfg(target_os = "linux")]
fn probe_can_write_cgroup_root() -> bool {
    use std::ffi::CString;

    let Ok(path) = CString::new("/sys/fs/cgroup/cgroup.subtree_control") else {
        return false;
    };
    // SAFETY: access(2) is a read-only syscall that takes a pointer to a
    // NUL-terminated C string. The kernel does not retain the pointer.
    #[allow(unsafe_code)]
    let rc = unsafe { libc::access(path.as_ptr(), libc::W_OK) };
    rc == 0
}

#[cfg(not(target_os = "linux"))]
fn probe_can_write_cgroup_root() -> bool {
    false
}

#[cfg(target_os = "linux")]
fn probe_has_cap_net_admin() -> bool {
    // CAP_NET_ADMIN is bit 12 in the Linux capability bitmask.
    // We need it in the EFFECTIVE set (`CapEff`), not just the bounding set
    // (`CapBnd`). A regular user process has full CapBnd by default but empty
    // CapPrm/CapEff — checking PR_CAPBSET_READ gives a false positive that
    // makes the daemon think it can create TUN/WG interfaces when it cannot.
    const CAP_NET_ADMIN_BIT: u64 = 1 << 12;
    let Ok(status) = std::fs::read_to_string("/proc/self/status") else {
        return false;
    };
    for line in status.lines() {
        if let Some(hex) = line.strip_prefix("CapEff:") {
            let trimmed = hex.trim();
            if let Ok(eff) = u64::from_str_radix(trimmed, 16) {
                return eff & CAP_NET_ADMIN_BIT != 0;
            }
            return false;
        }
    }
    false
}

#[cfg(not(target_os = "linux"))]
fn probe_has_cap_net_admin() -> bool {
    false
}

#[cfg(target_os = "linux")]
fn probe_tun_device_available() -> bool {
    use std::os::unix::fs::OpenOptionsExt;

    // Opening /dev/net/tun without any ioctls is benign and does not allocate
    // a TUN interface. The fd is dropped immediately when this scope ends.
    // Any open error — missing device, no perms, kernel module not loaded,
    // FD exhaustion — means we can't actually use TUN. Treat as unavailable.
    std::fs::OpenOptions::new()
        .read(true)
        .write(true)
        .custom_flags(libc::O_NONBLOCK)
        .open("/dev/net/tun")
        .is_ok()
}

#[cfg(not(target_os = "linux"))]
fn probe_tun_device_available() -> bool {
    false
}

/// `CAP_SYS_ADMIN` bit (21) in the Linux capability bitmask. Required to call
/// `mount(2)` for the overlay probe.
#[cfg(target_os = "linux")]
const CAP_SYS_ADMIN_BIT: u64 = 1 << 21;

/// `true` if `CAP_SYS_ADMIN` is in the process's *effective* set. Same
/// `/proc/self/status` `CapEff:` parse as [`probe_has_cap_net_admin`] — the
/// effective set, not the bounding set, is what `mount(2)` actually checks.
#[cfg(target_os = "linux")]
fn probe_has_cap_sys_admin() -> bool {
    let Ok(status) = std::fs::read_to_string("/proc/self/status") else {
        return false;
    };
    for line in status.lines() {
        if let Some(hex) = line.strip_prefix("CapEff:") {
            if let Ok(eff) = u64::from_str_radix(hex.trim(), 16) {
                return eff & CAP_SYS_ADMIN_BIT != 0;
            }
            return false;
        }
    }
    false
}

/// Pure parser for `/proc/filesystems`: `true` if `overlay` is a registered
/// filesystem. Each line is either `\t<fs>` or `nodev\t<fs>`; overlay is a
/// `nodev` filesystem. Split out so the logic is unit-testable without the
/// host's real `/proc`.
#[cfg(target_os = "linux")]
fn proc_filesystems_has_overlay(content: &str) -> bool {
    content
        .lines()
        .any(|line| line.split_whitespace().next_back() == Some("overlay"))
}

/// Probe whether the daemon can use an overlayfs rootfs.
///
/// Returns `true` iff ALL hold:
/// 1. the daemon is root OR holds effective `CAP_SYS_ADMIN` (needed for
///    `mount(2)`),
/// 2. `overlay` is registered in `/proc/filesystems`, and
/// 3. a real probe overlay mount in a fresh temp dir succeeds (and is then
///    immediately unmounted).
///
/// The mount probe is the authoritative signal — kernels can list `overlay`
/// yet reject the mount (e.g. inside an unprivileged userns, or on a backing
/// filesystem overlay won't accept). Doing a real mount+unmount once at startup
/// is cheap and removes the guesswork.
#[cfg(target_os = "linux")]
fn probe_overlayfs_rootfs_available(is_root: bool) -> bool {
    if !is_root && !probe_has_cap_sys_admin() {
        return false;
    }
    let Ok(content) = std::fs::read_to_string("/proc/filesystems") else {
        return false;
    };
    if !proc_filesystems_has_overlay(&content) {
        return false;
    }
    probe_overlay_mount_roundtrip()
}

#[cfg(not(target_os = "linux"))]
fn probe_overlayfs_rootfs_available(_is_root: bool) -> bool {
    false
}

/// Attempt a throwaway overlay mount (lower+upper+work+merged, all under one
/// temp dir) and immediately unmount it. Returns `true` only if both the mount
/// and unmount succeed. Best-effort cleanup of the temp dir on every path.
#[cfg(target_os = "linux")]
fn probe_overlay_mount_roundtrip() -> bool {
    use nix::mount::{mount, umount2, MntFlags, MsFlags};

    let Ok(base) = tempfile::Builder::new()
        .prefix("zlayer-ovl-probe-")
        .tempdir()
    else {
        return false;
    };
    let lower = base.path().join("lower");
    let upper = base.path().join("upper");
    let work = base.path().join("work");
    let merged = base.path().join("merged");
    for d in [&lower, &upper, &work, &merged] {
        if std::fs::create_dir_all(d).is_err() {
            return false;
        }
    }

    let opts = format!(
        "lowerdir={},upperdir={},workdir={}",
        lower.display(),
        upper.display(),
        work.display()
    );

    let mounted = mount(
        Some("overlay"),
        &merged,
        Some("overlay"),
        MsFlags::empty(),
        Some(opts.as_str()),
    )
    .is_ok();

    if !mounted {
        return false;
    }

    // Unmount; lazy-detach as a fallback so the probe never leaves a mount
    // behind even if the eager umount races. tempdir Drop then removes the
    // tree. The probe is "available" only if we both mounted AND cleaned up.
    umount2(&merged, MntFlags::empty()).is_ok() || umount2(&merged, MntFlags::MNT_DETACH).is_ok()
}

/// Locate an executable named `name` on `PATH`, returning its full path.
///
/// Pure helper (a `:`-split scan of the `PATH` env var) so the probe logic can
/// be unit-tested by passing an explicit `path_var`. A candidate must exist and
/// be a regular file or symlink; the executable bit is not checked here (the
/// later spawn surfaces a non-executable file as a real error). Linux-only —
/// the fuse path is Linux-only.
#[cfg(target_os = "linux")]
fn which_in(name: &str, path_var: &str) -> Option<std::path::PathBuf> {
    if name.is_empty() {
        return None;
    }
    for dir in path_var.split(':').filter(|d| !d.is_empty()) {
        let candidate = std::path::Path::new(dir).join(name);
        if candidate.exists() {
            return Some(candidate);
        }
    }
    None
}

/// `fuse-overlayfs` binary path, resolved from the process `PATH`. Linux-only.
#[cfg(target_os = "linux")]
fn fuse_overlayfs_binary() -> Option<std::path::PathBuf> {
    let path_var = std::env::var("PATH").ok()?;
    which_in("fuse-overlayfs", &path_var)
}

/// The fusermount helper to use for unmounting a `fuse-overlayfs` mount,
/// preferring the FUSE3 `fusermount3` and falling back to `fusermount`.
/// Returns the resolved binary path, or `None` if neither is on `PATH`.
/// Linux-only.
#[cfg(target_os = "linux")]
#[must_use]
pub fn fusermount_binary() -> Option<std::path::PathBuf> {
    let path_var = std::env::var("PATH").ok()?;
    which_in("fusermount3", &path_var).or_else(|| which_in("fusermount", &path_var))
}

#[cfg(not(target_os = "linux"))]
#[must_use]
pub fn fusermount_binary() -> Option<std::path::PathBuf> {
    None
}

/// `true` if `/dev/fuse` can be opened read/write — the FUSE control device a
/// userspace `fuse-overlayfs` daemon needs to back its mount. Opening it is
/// benign and allocates no FUSE connection; the fd is dropped immediately. Any
/// error (missing node, no perms, module not loaded) means rootless fuse-overlay
/// is unusable. Linux-only.
#[cfg(target_os = "linux")]
fn probe_dev_fuse_available() -> bool {
    std::fs::OpenOptions::new()
        .read(true)
        .write(true)
        .open("/dev/fuse")
        .is_ok()
}

/// Probe whether the daemon can use a ROOTLESS `fuse-overlayfs` rootfs.
///
/// Returns `true` iff ALL hold:
/// 1. the `fuse-overlayfs` binary is on `PATH`,
/// 2. `/dev/fuse` is openable r/w, and
/// 3. a real probe `fuse-overlayfs` mount in a fresh temp dir succeeds (and is
///    then immediately unmounted via `fusermount`).
///
/// Deliberately independent of root / `CAP_SYS_ADMIN`: this is the path that
/// lets an unprivileged daemon still get shared-layer dedup. The mount probe is
/// authoritative — a host can have the binary and `/dev/fuse` yet reject the
/// mount (e.g. no `user_allow_other`, a hardened FUSE sysctl, or a sandbox), so
/// a real mount+unmount once at startup removes the guesswork. Mirrors the
/// kernel-overlay probe's "actually do it once" philosophy.
#[cfg(target_os = "linux")]
fn probe_fuse_overlayfs_rootfs_available() -> bool {
    let Some(bin) = fuse_overlayfs_binary() else {
        return false;
    };
    if !probe_dev_fuse_available() {
        return false;
    }
    let Some(fusermount) = fusermount_binary() else {
        return false;
    };
    probe_fuse_overlay_mount_roundtrip(&bin, &fusermount)
}

#[cfg(not(target_os = "linux"))]
fn probe_fuse_overlayfs_rootfs_available() -> bool {
    false
}

/// Attempt a throwaway rootless `fuse-overlayfs` mount and immediately unmount
/// it. Returns `true` only if both the mount and the unmount succeed. The
/// backing FUSE daemon self-daemonizes (reparenting to PID 1), so the spawned
/// `fuse-overlayfs` process returns promptly and we wait on it. Best-effort
/// cleanup of the temp dir on every path. Linux-only.
#[cfg(target_os = "linux")]
fn probe_fuse_overlay_mount_roundtrip(bin: &std::path::Path, fusermount: &std::path::Path) -> bool {
    let Ok(base) = tempfile::Builder::new()
        .prefix("zlayer-fuse-ovl-probe-")
        .tempdir()
    else {
        return false;
    };
    let lower = base.path().join("lower");
    let upper = base.path().join("upper");
    let work = base.path().join("work");
    let merged = base.path().join("merged");
    for d in [&lower, &upper, &work, &merged] {
        if std::fs::create_dir_all(d).is_err() {
            return false;
        }
    }

    let opts = format!(
        "lowerdir={},upperdir={},workdir={}",
        lower.display(),
        upper.display(),
        work.display()
    );

    let mounted = std::process::Command::new(bin)
        .arg("-o")
        .arg(&opts)
        .arg(&merged)
        .stdin(std::process::Stdio::null())
        .stdout(std::process::Stdio::null())
        .stderr(std::process::Stdio::null())
        .status()
        .is_ok_and(|s| s.success());

    if !mounted {
        return false;
    }

    // Unmount via fusermount; tempdir Drop then removes the tree. The probe is
    // "available" only if we both mounted AND cleaned up.
    std::process::Command::new(fusermount)
        .arg("-u")
        .arg(&merged)
        .stdin(std::process::Stdio::null())
        .stdout(std::process::Stdio::null())
        .stderr(std::process::Stdio::null())
        .status()
        .is_ok_and(|s| s.success())
}

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

    #[test]
    fn probe_does_not_panic_and_is_nested_agrees_with_cgroup_parent() {
        let caps = DaemonCapabilities::probe();
        assert_eq!(caps.is_nested, caps.cgroup_parent.is_some());
    }

    #[cfg(target_os = "linux")]
    #[test]
    fn probe_has_cap_net_admin_matches_cap_eff() {
        // Just confirm the probe agrees with what /proc/self/status reports.
        // The actual capability state depends on how the test is run (regular
        // user vs root vs setcap'd binary), but the probe MUST agree with the
        // CapEff line — that's the whole point of the bug fix.
        let status = std::fs::read_to_string("/proc/self/status").unwrap();
        let cap_eff_line = status
            .lines()
            .find(|l| l.starts_with("CapEff:"))
            .expect("CapEff: present in /proc/self/status");
        let hex = cap_eff_line.trim_start_matches("CapEff:").trim();
        let eff: u64 = u64::from_str_radix(hex, 16).unwrap();
        let expected = (eff & (1u64 << 12)) != 0;
        assert_eq!(super::probe_has_cap_net_admin(), expected);
    }

    /// Pure classifier reproducing the logic in `probe()`. Kept in the test
    /// module so the table below can assert behaviour without depending on
    /// the host's actual capability state.
    #[allow(clippy::fn_params_excessive_bools)]
    fn classify(
        is_nested: bool,
        can_write_cgroup_root: bool,
        has_cap_net_admin: bool,
        tun_device_available: bool,
        cgroup_parent_is_some: bool,
    ) -> DaemonMode {
        if !is_nested && can_write_cgroup_root && has_cap_net_admin && tun_device_available {
            DaemonMode::Full
        } else if can_write_cgroup_root || cgroup_parent_is_some {
            DaemonMode::NestedAdaptive
        } else {
            DaemonMode::Degraded
        }
    }

    #[test]
    fn effective_mode_full_requires_all_four_signals() {
        // Full: every signal must be set the right way.
        assert_eq!(
            classify(false, true, true, true, false),
            DaemonMode::Full,
            "all four signals set should be Full"
        );
        // Drop any single signal and Full must no longer apply.
        assert_ne!(classify(true, true, true, true, true), DaemonMode::Full);
        assert_ne!(classify(false, false, true, true, false), DaemonMode::Full);
        assert_ne!(classify(false, true, false, true, false), DaemonMode::Full);
        assert_ne!(classify(false, true, true, false, false), DaemonMode::Full);
    }

    #[test]
    fn effective_mode_nested_adaptive_when_writable_or_has_parent() {
        // Writable root but missing other Full signals → NestedAdaptive.
        assert_eq!(
            classify(false, true, false, false, false),
            DaemonMode::NestedAdaptive
        );
        // Nested under a parent cgroup, no other signals → NestedAdaptive.
        assert_eq!(
            classify(true, false, false, false, true),
            DaemonMode::NestedAdaptive
        );
    }

    #[test]
    fn effective_mode_degraded_when_no_writable_path() {
        // No root write, no parent, nothing usable.
        assert_eq!(
            classify(false, false, false, false, false),
            DaemonMode::Degraded
        );
        // is_nested=true but no parent and no root write — still Degraded
        // (the is_nested signal alone, without a resolved parent, does not
        // give us a writable cgroup to anchor under).
        assert_eq!(
            classify(true, false, false, false, false),
            DaemonMode::Degraded
        );
    }

    #[test]
    fn overlay_fallback_none_only_when_both_present() {
        assert!(super::capability_overlay_fallback(true, true).is_none());
    }

    #[test]
    fn overlay_fallback_reports_missing_cap_net_admin() {
        let reason = super::capability_overlay_fallback(false, true).expect("should fall back");
        assert!(reason.contains("CAP_NET_ADMIN"));
    }

    #[test]
    fn overlay_fallback_reports_missing_tun() {
        let reason = super::capability_overlay_fallback(true, false).expect("should fall back");
        assert!(reason.contains("/dev/net/tun"));
    }

    #[test]
    fn overlay_fallback_reports_both_missing() {
        let reason = super::capability_overlay_fallback(false, false).expect("should fall back");
        assert!(reason.contains("CAP_NET_ADMIN"));
        assert!(reason.contains("/dev/net/tun"));
    }

    #[test]
    fn rootless_overlay_requires_nonroot_no_cap_tun_and_pasta() {
        // Happy path: non-root, no cap, tun present, pasta present.
        assert!(super::can_rootless_overlay(false, false, true, true));
    }

    #[test]
    fn rootless_overlay_rejected_when_root() {
        assert!(!super::can_rootless_overlay(true, false, true, true));
    }

    #[test]
    fn rootless_overlay_rejected_when_already_has_cap_net_admin() {
        assert!(!super::can_rootless_overlay(false, true, true, true));
    }

    #[test]
    fn rootless_overlay_rejected_without_tun() {
        assert!(!super::can_rootless_overlay(false, false, false, true));
    }

    #[test]
    fn rootless_overlay_rejected_without_pasta() {
        assert!(!super::can_rootless_overlay(false, false, true, false));
    }

    #[test]
    fn serializes_round_trip_via_serde_json() {
        let caps = DaemonCapabilities::probe();
        let json = serde_json::to_string(&caps).expect("serialize");
        let parsed: DaemonCapabilities = serde_json::from_str(&json).expect("deserialize");
        assert_eq!(parsed.is_root, caps.is_root);
        assert_eq!(parsed.is_nested, caps.is_nested);
        assert_eq!(parsed.cgroup_parent, caps.cgroup_parent);
        assert_eq!(parsed.can_write_cgroup_root, caps.can_write_cgroup_root);
        assert_eq!(parsed.has_cap_net_admin, caps.has_cap_net_admin);
        assert_eq!(parsed.tun_device_available, caps.tun_device_available);
        assert_eq!(
            parsed.overlayfs_rootfs_available,
            caps.overlayfs_rootfs_available
        );
        assert_eq!(
            parsed.fuse_overlayfs_rootfs_available,
            caps.fuse_overlayfs_rootfs_available
        );
        assert_eq!(parsed.effective_mode, caps.effective_mode);
    }

    #[cfg(target_os = "linux")]
    mod fuse_probe {
        use super::super::{fusermount_binary, which_in};

        #[test]
        fn which_in_finds_binary_in_first_matching_dir() {
            // Build a temp dir holding a fake binary and confirm the PATH scan
            // resolves it to the full path.
            let tmp = tempfile::tempdir().unwrap();
            let bin = tmp.path().join("fuse-overlayfs");
            std::fs::write(&bin, b"#!/bin/sh\n").unwrap();
            let other = tempfile::tempdir().unwrap();
            // PATH: a non-matching dir first, then the dir with the binary.
            let path_var = format!("{}:{}", other.path().display(), tmp.path().display());
            assert_eq!(
                which_in("fuse-overlayfs", &path_var).as_deref(),
                Some(bin.as_path())
            );
        }

        #[test]
        fn which_in_none_when_absent_and_ignores_empty_segments() {
            let tmp = tempfile::tempdir().unwrap();
            // Leading/trailing/empty colon segments must be skipped, not joined
            // against (which would otherwise resolve `/fuse-overlayfs`).
            let path_var = format!(":{}:", tmp.path().display());
            assert!(which_in("fuse-overlayfs", &path_var).is_none());
            // An empty name never resolves.
            assert!(which_in("", &path_var).is_none());
        }

        #[test]
        fn fusermount_binary_resolves_or_none_without_panic() {
            // On this box one of fusermount3/fusermount is typically present,
            // but we only assert the call is total (no panic) and, when it does
            // resolve, that it points at an existing file.
            if let Some(p) = fusermount_binary() {
                assert!(
                    p.exists(),
                    "resolved fusermount must exist: {}",
                    p.display()
                );
            }
        }
    }

    #[cfg(target_os = "linux")]
    mod proc_filesystems {
        use super::super::proc_filesystems_has_overlay;

        #[test]
        fn detects_overlay_as_nodev_filesystem() {
            // Real-world shape: nodev entries are tab-indented with a "nodev"
            // marker; overlay is one of them.
            let content = "nodev\tsysfs\nnodev\ttmpfs\nnodev\toverlay\n\text4\n";
            assert!(proc_filesystems_has_overlay(content));
        }

        #[test]
        fn absent_when_overlay_not_listed() {
            let content = "nodev\tsysfs\nnodev\ttmpfs\n\text4\n\txfs\n";
            assert!(!proc_filesystems_has_overlay(content));
        }

        #[test]
        fn does_not_match_substring_overlayfs() {
            // A different fs whose name merely contains "overlay" must not match
            // (we compare the whole final token, not a substring).
            let content = "nodev\toverlayfs2\n\text4\n";
            assert!(!proc_filesystems_has_overlay(content));
        }

        #[test]
        fn empty_input_is_false() {
            assert!(!proc_filesystems_has_overlay(""));
        }
    }

    /// The overlay probe must not panic and must be internally consistent:
    /// availability implies the daemon is root or holds `CAP_SYS_ADMIN`. The
    /// concrete bool depends on how the test runs (root vs not), so we only
    /// assert the implication, not a fixed value.
    #[cfg(target_os = "linux")]
    #[test]
    fn overlay_probe_consistent_with_privilege() {
        let caps = DaemonCapabilities::probe();
        if caps.overlayfs_rootfs_available {
            assert!(
                caps.is_root || super::probe_has_cap_sys_admin(),
                "overlay availability must imply root or CAP_SYS_ADMIN"
            );
        }
    }

    #[test]
    fn daemon_mode_serde_uses_snake_case() {
        assert_eq!(
            serde_json::to_string(&DaemonMode::Full).unwrap(),
            "\"full\""
        );
        assert_eq!(
            serde_json::to_string(&DaemonMode::NestedAdaptive).unwrap(),
            "\"nested_adaptive\""
        );
        assert_eq!(
            serde_json::to_string(&DaemonMode::Degraded).unwrap(),
            "\"degraded\""
        );
    }

    #[cfg(target_os = "linux")]
    mod target_parent {
        use super::super::compute_target_parent;

        #[test]
        fn idempotent_when_already_under_init() {
            // Pre-fix path: scope is the systemd-run scope itself.
            assert_eq!(
                compute_target_parent(
                    "/user.slice/user-1000.slice/user@1000.service/app.slice/run-p123.scope"
                ),
                "/user.slice/user-1000.slice/user@1000.service/app.slice/run-p123.scope/containers"
            );
            // Already migrated: scope ends with /init — strip and re-anchor.
            assert_eq!(
                compute_target_parent(
                    "/user.slice/user-1000.slice/user@1000.service/app.slice/run-p123.scope/init"
                ),
                "/user.slice/user-1000.slice/user@1000.service/app.slice/run-p123.scope/containers"
            );
            // Trailing slash on either form is harmless.
            assert_eq!(compute_target_parent("/foo/bar/"), "/foo/bar/containers");
            assert_eq!(
                compute_target_parent("/foo/bar/init"),
                "/foo/bar/containers"
            );
        }
    }

    #[cfg(target_os = "linux")]
    mod host_parent {
        use super::super::{compute_host_container_parent, HOST_CONTAINER_ROOT};

        #[test]
        fn host_parent_is_top_level_and_outside_any_unit() {
            // Host-mode containers must live under a top-level node, NOT under
            // `/system.slice/zlayer.service/...`, so a KillMode=process
            // survivor can never wedge the unit's restart with EBUSY.
            assert_eq!(compute_host_container_parent(), "/zlayer/containers");
            assert!(compute_host_container_parent().starts_with(HOST_CONTAINER_ROOT));
            assert!(!compute_host_container_parent().contains("zlayer.service"));
            assert!(!compute_host_container_parent().contains(".slice"));
        }
    }

    #[cfg(target_os = "linux")]
    mod host_cgroup_reap {
        use super::super::remove_host_container_cgroup_at;
        use std::fs;

        // Reproduces the recreate bug: a previous instance left an empty
        // cgroup tree at `<root>/zlayer/containers/<id>` (with a nested child
        // cgroup, as a v2 leaf with delegated controllers can have). The reaper
        // must depth-first remove the children and then the leaf so the next
        // create_container starts from a clean slot.
        #[test]
        fn reaps_stale_empty_cgroup_tree_depth_first() {
            let base = tempfile::tempdir().expect("tempdir");
            let base_path = base.path().to_str().unwrap();
            let id = "zata-storage-rep-1";

            let leaf = base.path().join(format!("zlayer/containers/{id}"));
            // A nested child cgroup dir — a v2 parent cannot be rmdir'd while
            // children exist, which is exactly what the recursion must handle.
            let child = leaf.join("child-scope");
            fs::create_dir_all(&child).expect("create nested cgroup tree");
            // Simulate cgroup-v2 control files present in the leaf.
            fs::write(leaf.join("cgroup.procs"), "").unwrap();
            fs::write(child.join("cgroup.procs"), "").unwrap();
            assert!(leaf.exists(), "precondition: stale leaf exists");

            remove_host_container_cgroup_at(base_path, id);

            assert!(
                !leaf.exists(),
                "stale cgroup leaf must be reaped (depth-first removal of children + leaf)"
            );
            // The `containers` parent itself is left intact (shared across ids).
            assert!(
                base.path().join("zlayer/containers").exists(),
                "shared containers parent must survive"
            );
        }

        #[test]
        fn idempotent_when_leaf_absent() {
            let base = tempfile::tempdir().expect("tempdir");
            let base_path = base.path().to_str().unwrap();
            // No leaf created — must be a no-op, not a panic.
            remove_host_container_cgroup_at(base_path, "never-existed");
        }
    }

    #[cfg(target_os = "linux")]
    mod cgroup_parser {
        use super::super::parse_cgroup_v2_line;

        #[test]
        fn parse_cgroup_v2_root_returns_none() {
            assert_eq!(parse_cgroup_v2_line("0::/\n"), None);
        }

        #[test]
        fn parse_cgroup_v2_path_returns_some() {
            assert_eq!(
                parse_cgroup_v2_line("0::/system.slice/forgejo-runner.service\n"),
                Some("/system.slice/forgejo-runner.service".to_string())
            );
        }

        #[test]
        fn parse_cgroup_v2_hybrid_finds_v2_line() {
            let input = "12:devices:/user.slice\n11:memory:/user.slice\n0::/foo\n";
            assert_eq!(parse_cgroup_v2_line(input), Some("/foo".to_string()));
        }

        #[test]
        fn parse_cgroup_v2_no_newline() {
            assert_eq!(parse_cgroup_v2_line("0::/bar"), Some("/bar".to_string()));
        }

        #[test]
        fn parse_cgroup_v2_missing_returns_none() {
            assert_eq!(parse_cgroup_v2_line(""), None);
        }
    }
}