gunnar_server/

boot.rs

//! **Gunnar's end of PID 1.** Everything an OS-less PID 1 owes the kernel —
//! the signals, the reaper, the netlink writer, the DHCPv4 client and its
//! renewal, the resolver file, the stop sources and the power-off, the install
//! record, the graphics-console mirror, the boot narration's secret door, the
//! panic as a fault — is edda's `appliance-pid1` (0.1.5, lanes G4 and G6), the one PID 1
//! Gunnar and Holger both run. Gunnar's own `pid1.rs` and `dhcp.rs` were moved
//! there whole and deleted here (lane L10).
//!
//! What stays Gunnar's is what Gunnar says about itself: the variable the
//! kernel command line names the network in ([`NET_VAR`]), the host-name
//! prefix, the name the resolver is proven on, the T1 test seam's variable,
//! where the boot narration and the install line go (the console log tap and
//! the dashboard's `install.mode` row), and the panic's code (`GN-99`) with
//! Gunnar's own crash file and console line. The narrator (the `Stage` story,
//! the ESP and `/data` log lines) is [`crate::narrate`].

use std::path::{Path, PathBuf};

use anyhow::Result;

pub use appliance_pid1::net::DhcpSession;

/// The variable the kernel command line declares the network in:
/// `GUNNAR_NET=eth0:dhcp,eth1:dhcp` or `GUNNAR_NET=eth0:10.0.2.15/24:10.0.2.2`.
pub const NET_VAR: &str = "GUNNAR_NET";
/// The DHCP T1 test seam's variable (read only behind the appliance gate).
pub const T1_OVERRIDE_VAR: &str = "GUNNAR_DHCP_T1_OVERRIDE_SECS";
/// A box with no lease name is called `gunnar-<last three MAC bytes>`.
pub const HOSTNAME_PREFIX: &str = "gunnar";
/// The name the published resolver is proven on, once, at boot.
pub const RESOLVER_PROBE: &str = "github.com";
/// **The name this build asks** (AIRGAP B3, owner rule 2026-10-25): a DNS question for a
/// public name is an outbound call, so only a build with `resolver-probe` (every appliance
/// row names it) proves the resolver; a default build asks nothing.
pub const RESOLVER_PROBE_IN_THIS_BUILD: Option<&str> = if cfg!(feature = "resolver-probe") {
    Some(RESOLVER_PROBE)
} else {
    None
};
/// Gunnar's panic code.
pub const PANIC_CODE: &str = "GN-99";

/// The plans `GUNNAR_NET` declares (empty when it declares none).
pub fn net_plans() -> Result<Vec<appliance_pid1::net::NetConfig>> {
    appliance_pid1::net::NetConfig::from_env(NET_VAR)
}

/// Pure: **a bind by ROLE becomes this box's NIC** (the lean estate, A19 row 17):
/// `utility:<port>` is the last interface the net spec `net` (the medium's [`NET_VAR`])
/// declares that this box has (`exists`). Any other spelling is returned unchanged.
pub fn role_bound(
    spec: gunnar_common::bindspec::BindSpec,
    net: Option<&str>,
    exists: impl Fn(&str) -> bool,
) -> Result<gunnar_common::bindspec::BindSpec> {
    if !matches!(spec, gunnar_common::bindspec::BindSpec::Role { .. }) {
        return Ok(spec);
    }
    let declared: Vec<String> = match net.map(str::trim).filter(|n| !n.is_empty()) {
        Some(n) => appliance_pid1::net::NetConfig::parse_list(n)?
            .iter()
            .map(|c| c.interface().to_string())
            .collect(),
        None => Vec::new(),
    };
    spec.for_this_box(&declared, exists)
        .map_err(|why| anyhow::anyhow!("{NET_VAR}: {why}"))
}

/// [`role_bound`] on this box: its [`NET_VAR`] and the NICs the kernel has
/// (`/sys/class/net/<name>`).
pub fn role_bound_here(
    spec: gunnar_common::bindspec::BindSpec,
) -> Result<gunnar_common::bindspec::BindSpec> {
    let net = std::env::var(NET_VAR).ok();
    role_bound(spec, net.as_deref(), |i| {
        std::path::Path::new("/sys/class/net").join(i).exists()
    })
}

/// **Everything PID 1 owes the system before the listeners bind**: edda's
/// `net::bring_up_network_with` over `GUNNAR_NET`, with Gunnar's host-name
/// prefix, its resolver probe and the boot narration handed to the console log
/// tap. A boot DHCP that failed and is asked again in the background lands the
/// same way ([`late_lease`], appliance-pid1 0.1.5): said through the boot
/// narration, renewed on Gunnar's T1 seam and its resolver proven.
pub fn bring_up_network() -> Result<Vec<DhcpSession>> {
    let narrate = |note: &str| ship_boot_narration(note);
    let how = appliance_pid1::net::Bringup {
        hostname_prefix: HOSTNAME_PREFIX,
        resolver_probe: RESOLVER_PROBE_IN_THIS_BUILD,
        narrate: &narrate,
    };
    appliance_pid1::net::bring_up_network_with(net_plans()?, &how, late_lease())
}

/// What a late DHCP lease (the boot's failed ask, retried in the background)
/// says and renews on: the boot narration's own door and Gunnar's T1 seam.
pub fn late_lease() -> appliance_pid1::net::LateLease {
    appliance_pid1::net::LateLease {
        narrate: ship_boot_narration,
        t1_override_var: Some(T1_OVERRIDE_VAR),
    }
}

/// The kernel's story to the boot log the installer collects (edda's
/// `narration::ship_boot_narration`, tapped into `gunnar_common::logqueue`).
pub fn ship_boot_narration(network_note: &str) {
    appliance_pid1::narration::ship_boot_narration(network_note, &|l: &str| {
        gunnar_common::logqueue::tap_line(l)
    });
}

/// Keep the boot's lease alive, forever (edda's `runtime::dhcp_renewal`, with
/// Gunnar's T1 test seam).
#[cfg(feature = "dhcp-client")]
pub async fn dhcp_renewal(session: DhcpSession) {
    appliance_pid1::runtime::dhcp_renewal(
        session,
        appliance_pid1::runtime::dhcp_t1_override(T1_OVERRIDE_VAR),
    )
    .await
}

/// With `dhcp-client` off there is no lease to renew: the session type is
/// uninhabited, so this cannot be called.
#[cfg(not(feature = "dhcp-client"))]
pub async fn dhcp_renewal(session: DhcpSession) {
    match session {}
}

/// **Say whether this /data is the one the box had before its last install**
/// (edda's `install::announce_install_mode`): the set's shape is read off the
/// md sysfs under `data_root` (`dashboard::probe::disk_kind`), and the line is
/// said as the structured `install.mode` event the dashboard's `install` row
/// keys on. Silent when the record is absent.
pub fn announce_install_mode(data_root: &Path) {
    if !Path::new(appliance_pid1::install::INSTALL_RECORD).exists() {
        return;
    }
    let set = crate::dashboard::probe::disk_kind(data_root)
        .and_then(|k| k.set)
        .map(|s| {
            format!(
                "{}\u{d7}{}",
                s.members,
                crate::dashboard::fmt_bytes(s.member_bytes)
            )
        });
    appliance_pid1::install::announce_install_mode(set.as_deref(), &install_mode_event);
}

/// One `install.mode` line (`install.mode mode=… kept=… …`) as the structured
/// event the dashboard reads: each `key=value` token a field, `-` when absent.
pub fn install_mode_event(line: &str) {
    let f = install_mode_fields(line);
    tracing::info!(
        event = "install.mode",
        mode = %f[0],
        kept = %f[1],
        kept_partno = %f[2],
        kept_gib = %f[3],
        kept_set = %f[4],
        "install record read off {}",
        appliance_pid1::install::INSTALL_RECORD
    );
}

/// `mode`, `kept`, `kept_partno`, `kept_gib`, `kept_set` off an edda
/// `install.mode` line, `-` for each one it does not name. Pure.
pub fn install_mode_fields(line: &str) -> [String; 5] {
    let get = |k: &str| {
        line.split_whitespace()
            .find_map(|t| t.strip_prefix(k).and_then(|r| r.strip_prefix('=')))
            .unwrap_or("-")
            .to_owned()
    };
    [
        get("mode"),
        get("kept"),
        get("kept_partno"),
        get("kept_gib"),
        get("kept_set"),
    ]
}

/// **A panic on the appliance ends as a fault** (`GN-99`): edda's
/// `fault::install_panic_fault`, armed only as PID 1 with the narrator
/// installed (never in a test, a laptop's `gunnar-solo` or a container), the
/// crash record under `data`. `shout` is the binary's every-console writer.
///
/// Gunnar's own half rides in `say`: the panic line on every console with
/// Gunnar's wording, its own `crash/panic-<ms>.txt` (`slow::record_crash`),
/// and every fault line through the narrator (console, ESP, `/data`'s boot
/// log) — `shout` when no narrator is installed.
pub fn install_panic_fault(data: Option<PathBuf>, shout: fn(&str)) {
    // The crash record (`crash/fault.txt`) holds the narrator's memory under
    // the fault line, as `narrate::fault`'s record does (appliance-pid1 0.1.5).
    appliance_pid1::fault::narration_from(crate::narrate::memory);
    let p = appliance_pid1::fault::PanicFault {
        code: PANIC_CODE,
        meaning: crate::narrate::code_meaning(PANIC_CODE).unwrap_or("the app panicked"),
        data,
    };
    appliance_pid1::fault::install_panic_fault(
        p,
        || appliance_pid1::net::is_init() && crate::narrate::narrator().is_some(),
        move |line: &str| say_panic_line(line, shout),
    );
}

/// What Gunnar does with each line edda's panic hook says. See [`install_panic_fault`].
fn say_panic_line(line: &str, shout: fn(&str)) {
    if let Some(text) = line.strip_prefix("PANIC: ") {
        let text = format!("\ngunnar PANIC (exit 101): {text}\n");
        shout(&text);
        // And written down, off the stripe: a console message is gone the moment
        // the VNC session closes. A no-op before `ServerStores::open` registered
        // the diagnostics directory.
        if let Some(path) = crate::slow::record_crash(&text) {
            shout(&format!(
                "gunnar: crash record written to {}\n",
                path.display()
            ));
        }
        return;
    }
    match crate::narrate::narrator() {
        Some(n) => n.say(line),
        None => shout(&format!("gunnar: {line}\n")),
    }
}

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

    /// ★ **The control plane's `utility:<port>` becomes this box's utility NIC** (the lean
    /// estate, A19 row 17): read from the net spec the medium declares and the NICs the box
    /// has, before anything binds. A spelling that is not a role passes unchanged.
    #[test]
    fn the_utility_role_becomes_the_nic_this_box_has() {
        use gunnar_common::bindspec::BindSpec;
        let role: BindSpec = "utility:50051".parse().unwrap();
        let iface = |i: &str| BindSpec::Interface {
            interface: i.into(),
            port: 50051,
        };
        assert_eq!(
            role_bound(role.clone(), Some("eth0:dhcp,eth1:dhcp"), |_| true).unwrap(),
            iface("eth1")
        );
        assert_eq!(
            role_bound(role.clone(), Some("eth0:dhcp,eth1:dhcp"), |i| i == "eth0").unwrap(),
            iface("eth0")
        );
        assert!(role_bound(role.clone(), None, |_| true)
            .unwrap_err()
            .to_string()
            .contains(NET_VAR));
        let kept: BindSpec = "127.0.0.1:50051".parse().unwrap();
        assert_eq!(role_bound(kept.clone(), None, |_| false).unwrap(), kept);
    }

    /// The names Gunnar gives edda's PID 1 are the ones every medium, kit and
    /// test already spells.
    #[test]
    fn gunnar_names_its_network_variable_its_host_and_its_panic() {
        assert_eq!(NET_VAR, "GUNNAR_NET");
        assert_eq!(T1_OVERRIDE_VAR, "GUNNAR_DHCP_T1_OVERRIDE_SECS");
        assert_eq!(
            appliance_pid1::net::hostname_for(
                HOSTNAME_PREFIX,
                None,
                [0, 0x11, 0x22, 0xaa, 0xbb, 0xcc]
            ),
            "gunnar-aabbcc"
        );
        assert_eq!(
            appliance_pid1::net::hostname_for(HOSTNAME_PREFIX, Some("vm1.example"), [0; 6]),
            "vm1.example"
        );
        assert_eq!(RESOLVER_PROBE, "github.com");
        assert_eq!(PANIC_CODE, "GN-99");
        assert_eq!(
            crate::narrate::code_meaning(PANIC_CODE),
            Some("the app panicked")
        );
    }

    /// edda's `install.mode` line becomes the fields the dashboard's `install`
    /// row reads, for every shape the record can spell — never a fabricated value.
    #[test]
    fn the_install_line_becomes_the_dashboards_fields() {
        use appliance_pid1::install::InstallRecord;
        let p = InstallRecord::parse(
            "mode=upgrade\nkept=korp-data\nkept_partno=3\nkept_bytes=241591910400\n",
        )
        .line(None);
        assert_eq!(
            install_mode_fields(&p),
            ["upgrade", "korp-data", "3", "225.0", "-"].map(String::from)
        );
        let s = InstallRecord::parse("mode=upgrade\nkept=data-set\n").line(Some("4\u{d7}75G"));
        assert_eq!(
            install_mode_fields(&s),
            ["upgrade", "data-set", "-", "-", "4\u{d7}75G"].map(String::from)
        );
        let s = InstallRecord::parse("mode=upgrade\nkept=data-set\n").line(None);
        assert_eq!(
            install_mode_fields(&s),
            ["upgrade", "data-set", "-", "-", "-"].map(String::from)
        );
        let f = InstallRecord::parse("mode=fresh\n").line(None);
        assert_eq!(
            install_mode_fields(&format!("{f} (install record read off the ESP)")),
            ["fresh", "-", "-", "-", "-"].map(String::from)
        );
    }

    /// ★ **A late lease is said, renewed on Gunnar's T1 seam and its resolver
    /// proven** (lane L10, appliance-pid1 0.1.5): the boot hands edda a
    /// `LateLease` whose line goes through the same boot narration door as the
    /// boot lease's (into the log the installer collects) and whose renewal reads
    /// `GUNNAR_DHCP_T1_OVERRIDE_SECS`; the resolver probe rides on the `Bringup`
    /// edda copies onto the retry. edda's `late_lease_tests` prove what it does
    /// with these; this proves Gunnar hands them over.
    #[test]
    fn a_late_lease_is_narrated_into_the_installers_boot_log() {
        let late = late_lease();
        assert_eq!(late.t1_override_var, Some(T1_OVERRIDE_VAR));
        // The installer's boot log exists with the pairing door (`wg-client`).
        #[cfg(feature = "wg-client")]
        {
            crate::installer_listener::capture();
            (late.narrate)("network up: eth0 10.0.2.15/24 gw Some(10.0.2.2) via DHCP from 10.0.2.2 (lease 3600s) — after the boot's failure, 7 asks l10-late");
            let log = crate::installer_listener::BOOT_LOG
                .since(0, usize::MAX)
                .lines
                .join("\n");
            assert!(
                log.contains("after the boot's failure, 7 asks l10-late"),
                "the late line reaches the boot log: {log}"
            );
        }
        let src = include_str!("boot.rs");
        let up = &src[src.find("pub fn bring_up_network()").unwrap()..];
        let up = &up[..up.find("\n}\n").unwrap()];
        assert!(
            up.contains("bring_up_network_with(net_plans()?, &how, late_lease())"),
            "{up}"
        );
        assert!(
            up.contains("resolver_probe: RESOLVER_PROBE_IN_THIS_BUILD,"),
            "{up}"
        );
    }

    /// `GUNNAR_NET` is parsed by edda with Gunnar's variable: absent is no plan,
    /// and the estate's two-NIC declaration is two plans, eth0 first.
    #[test]
    fn gunnar_net_is_read_from_its_own_variable() {
        // Not set in a test process: no plans, and no interface touched.
        if std::env::var_os(NET_VAR).is_none() {
            assert!(net_plans().unwrap().is_empty());
        }
        let plans = appliance_pid1::net::NetConfig::parse_list(
            "eth0:81.27.107.63/23:81.27.106.1,eth1:10.13.8.78/22",
        )
        .unwrap();
        assert_eq!(
            plans.iter().map(|p| p.interface()).collect::<Vec<_>>(),
            ["eth0", "eth1"]
        );
    }
}

/// **AIRGAP B3** (owner rule 2026-10-25): the boot's resolver proof is a DNS question for
/// [`RESOLVER_PROBE`], a public name, so a default build asks none; the `resolver-probe`
/// feature (named by every appliance row) asks it as before.
#[cfg(test)]
mod airgap {
    #[test]
    fn the_bring_up_asks_the_name_this_build_names() {
        let src = include_str!("boot.rs");
        let up = &src[src.find("pub fn bring_up_network()").unwrap()..];
        let up = &up[..up.find("\n}\n").unwrap()];
        assert!(
            up.contains("resolver_probe: RESOLVER_PROBE_IN_THIS_BUILD,"),
            "{up}"
        );
    }

    #[cfg(not(feature = "resolver-probe"))]
    #[test]
    fn a_default_build_proves_no_resolver_and_asks_no_public_name() {
        assert_eq!(super::RESOLVER_PROBE_IN_THIS_BUILD, None);
    }

    #[cfg(feature = "resolver-probe")]
    #[test]
    fn a_resolver_probe_build_asks_github_com_as_before() {
        assert_eq!(super::RESOLVER_PROBE_IN_THIS_BUILD, Some("github.com"));
    }
}