zc2 0.0.45

P2P compute broker with credit-based billing, WAL, and broker mesh support
//! "Model A" — `zc` auto-runs a local broker on demand.
//!
//! Several commands (`workers`, `discovery`) target `ZAKURO_BROKER` which
//! defaults to `zc://localhost` (a scan of loopback 9000-9010, see
//! `broker::uri::resolve`). Historically, if nothing was listening there the
//! command just failed with "no local broker...". This module makes the
//! *default* case self-service: when the user didn't ask for a specific
//! broker, we make sure one exists — reusing it if already running, quietly
//! spawning one in the background otherwise — and only fail hard when the
//! user explicitly named a broker target that isn't reachable.

use std::time::Duration;

const SCAN_START: u16 = 9000;
const SCAN_END: u16 = 9010;
const DEFAULT_PORT: u16 = 9000;

/// Should we auto-spawn a local broker, or respect an explicit target?
///
/// Pure decision function: auto-spawn only applies to the *default* case —
/// no explicit `zc://...` argument on the command line, and no
/// `ZAKURO_BROKER` env var override. If the user named a target explicitly
/// (either way), we never auto-spawn — we use their target and let it fail
/// with the normal error if unreachable.
pub fn should_auto_spawn(explicit_cli: Option<&str>, env_broker: Option<&str>) -> bool {
    explicit_cli.is_none() && env_broker.is_none()
}

/// Probe loopback `PORT/health` for PORT in `SCAN_START..=SCAN_END`. Returns
/// the base URL of the first broker that responds, as the probe reports it.
///
/// Generic over the probe function so this is testable without opening real
/// sockets: production code passes a real HTTP GET, tests pass a fake.
fn find_running_broker<F>(mut probe: F) -> Option<String>
where
    F: FnMut(u16) -> Option<String>,
{
    (SCAN_START..=SCAN_END).find_map(&mut probe)
}

/// A port is "a running broker" only when its `/health` body identifies as
/// `zakuro-broker`. Any other 2xx on loopback 9000-9010 (a MinIO console on
/// 9001 was the real case) used to be adopted as the broker, and every
/// following request then died parsing HTML as JSON. The answering address
/// comes back with it, so callers dial the family the broker actually binds
/// instead of re-resolving `localhost`.
fn real_probe(port: u16) -> Option<String> {
    crate::broker::uri::probe_local_addr(port).map(|(base, _)| base)
}

/// The local broker if one is already running, without starting one: for
/// callers that must not have side effects (the full-screen session).
pub fn find_local_broker() -> Option<String> {
    find_running_broker(real_probe)
}

/// The command that auto-spawns the local broker on `port`. It sets no
/// `ZAKURO_P2P`: the child inherits the caller's, and an explicit value always
/// wins. Unset, the spawned `zc broker` turns P2P on for any mesh route itself
/// (`broker::p2p_default`).
fn broker_command(exe: &std::path::Path, port: u16) -> std::process::Command {
    let mut cmd = std::process::Command::new(exe);
    cmd.arg("-d").arg("broker").arg(port.to_string());
    cmd.stdin(std::process::Stdio::null());
    cmd.stdout(std::process::Stdio::null());
    cmd.stderr(std::process::Stdio::null());
    // Its own process group: closing the terminal that ran `zc ls` must not
    // take the broker down with it.
    #[cfg(unix)]
    std::os::unix::process::CommandExt::process_group(&mut cmd, 0);
    cmd
}

/// How long a freshly spawned broker gets to answer `/health`. It binds its
/// port first, then runs the dashboard handshake, which can take a while on a
/// slow or absent network.
const SPAWN_DEADLINE: Duration = Duration::from_secs(30);

/// The port to start a broker on: the first one in the scan range that
/// nothing else holds. Nothing may listen on IPv4, where the broker binds, or
/// on `[::1]`, where `localhost` lands first on macOS. `taken` decides for one
/// port. Pure over it, so the choice is testable without sockets.
fn pick_port(mut taken: impl FnMut(u16) -> bool) -> Option<u16> {
    (SCAN_START..=SCAN_END).find(|&p| !taken(p))
}

fn port_taken(port: u16) -> bool {
    let v4_free = std::net::TcpListener::bind(("0.0.0.0", port)).is_ok();
    let v6_answers = std::net::TcpStream::connect_timeout(
        &std::net::SocketAddr::from((std::net::Ipv6Addr::LOCALHOST, port)),
        Duration::from_millis(200),
    )
    .is_ok();
    !v4_free || v6_answers
}

/// Where an auto-started broker writes its output, so a failed start can say
/// why instead of "run `zc broker` manually".
fn spawn_log_path() -> Option<std::path::PathBuf> {
    crate::credentials::dir().map(|d| d.join("autobroker.log"))
}

/// The last `n` non-empty lines of `path`, indented for an error message.
fn log_tail(path: &std::path::Path, n: usize) -> String {
    let text = std::fs::read_to_string(path).unwrap_or_default();
    let lines: Vec<&str> = text.lines().filter(|l| !l.trim().is_empty()).collect();
    lines[lines.len().saturating_sub(n)..]
        .iter()
        .map(|l| format!("\n    {}", l.trim_end()))
        .collect()
}

/// Ensure a local broker is reachable, spawning one in the background if
/// needed. Returns the broker's base URL (e.g. `http://127.0.0.1:9000`) on
/// success.
///
/// `verbose` mirrors the convention used elsewhere in this crate (see
/// `BrokerConfig.verbose` in `main.rs`) — only chatter when actually doing
/// something (spawning), not when silently reusing an existing broker.
///
/// The spawn never assumes port 9000 is ours. A port held by something else
/// (a MinIO container, or a broker that stopped answering) is skipped. The
/// child is watched: if it exits or never comes up, it is killed, never left
/// running headless, and its own last log lines become the error.
pub fn ensure_local_broker(verbose: bool) -> Result<String, String> {
    // 1. Reuse an already-running broker if there is one.
    if let Some(url) = find_running_broker(real_probe) {
        return Ok(url);
    }

    // 2. None answers: start one on a port nothing else holds.
    let port = pick_port(port_taken).ok_or_else(|| {
        format!(
            "no local broker answers, and every port {}-{} is taken by something else; \
             free one, or point ZAKURO_BROKER at a broker",
            SCAN_START, SCAN_END
        )
    })?;
    if verbose {
        if port == DEFAULT_PORT {
            println!("  starting local broker…");
        } else {
            println!(
                "  starting local broker on port {} (port {} is held by another process)…",
                port, DEFAULT_PORT
            );
        }
    }

    let exe = std::env::current_exe()
        .map_err(|e| format!("could not resolve current executable: {}", e))?;

    // Make sure ZAKURO_API_KEY (if any) is available to the child — it
    // inherits the parent's env by default, but load_into_env() may have
    // populated the *parent's* env from disk credentials just before this
    // runs, so re-run it defensively in case ensure_local_broker() is ever
    // called before that happens.
    crate::credentials::load_into_env();
    crate::broker::apply_user_broker_defaults();

    let log_path = spawn_log_path();
    let mut cmd = broker_command(&exe, port);
    if let Some(path) = &log_path {
        if let Some(dir) = path.parent() {
            let _ = std::fs::create_dir_all(dir);
        }
        if let Ok(f) = std::fs::File::create(path) {
            if let Ok(f2) = f.try_clone() {
                cmd.stdout(f2);
            }
            cmd.stderr(f);
        }
    }
    let mut child = cmd
        .spawn()
        .map_err(|e| format!("could not spawn local broker: {}", e))?;

    let see_log = |what: &str| match &log_path {
        Some(p) => format!(
            "{}; its log ({}) ends with:{}",
            what,
            p.display(),
            log_tail(p, 8)
        ),
        None => format!("{}; run `zc broker` to see why", what),
    };

    // 3. Poll until it comes up, it exits, or the deadline passes.
    let deadline = std::time::Instant::now() + SPAWN_DEADLINE;
    while std::time::Instant::now() < deadline {
        if let Some(url) = real_probe(port) {
            return Ok(url);
        }
        if let Ok(Some(status)) = child.try_wait() {
            return Err(see_log(&format!("the local broker exited ({})", status)));
        }
        std::thread::sleep(Duration::from_millis(400));
    }

    // Never leave a broker behind that nothing can reach.
    let _ = child.kill();
    let _ = child.wait();
    Err(see_log(&format!(
        "the local broker did not answer on port {} within {}s",
        port,
        SPAWN_DEADLINE.as_secs()
    )))
}

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

    #[test]
    fn should_auto_spawn_when_nothing_explicit() {
        assert!(should_auto_spawn(None, None));
    }

    #[test]
    fn should_not_auto_spawn_with_explicit_cli_arg() {
        assert!(!should_auto_spawn(Some("zc://node-foo"), None));
    }

    #[test]
    fn should_not_auto_spawn_with_env_broker_set() {
        assert!(!should_auto_spawn(None, Some("zc://node-foo")));
    }

    #[test]
    fn should_not_auto_spawn_with_both_set() {
        assert!(!should_auto_spawn(
            Some("zc://node-foo"),
            Some("zc://node-bar")
        ));
    }

    /// The spawn sets no `ZAKURO_P2P`, so the caller's explicit value reaches
    /// the child untouched: `ZAKURO_P2P=false` stays off on the host route.
    /// Unset, the child still peers there and on the proxy route.
    #[test]
    fn an_explicit_zakuro_p2p_false_stays_false_on_the_host_route() {
        use crate::broker::p2p_default_from;
        use crate::vpn::fixtures::{host_route, proxy_route};
        let cmd = broker_command(std::path::Path::new("zc"), 9000);
        assert_eq!(cmd.get_args().collect::<Vec<_>>(), ["-d", "broker", "9000"]);
        assert!(
            cmd.get_envs().all(|(k, _)| k != "ZAKURO_P2P"),
            "the auto-spawn must not override the caller's ZAKURO_P2P"
        );
        assert!(!p2p_default_from(Some("false"), &host_route()));
        assert!(p2p_default_from(None, &host_route()));
        assert!(p2p_default_from(None, &proxy_route()));
    }

    #[test]
    fn find_running_broker_reuses_first_hit() {
        let seen = std::cell::RefCell::new(Vec::new());
        let url = find_running_broker(|port| {
            seen.borrow_mut().push(port);
            (port == 9003).then(|| format!("http://127.0.0.1:{port}"))
        });
        assert_eq!(url, Some("http://127.0.0.1:9003".to_string()));
        // Probed in order and stopped at the first hit.
        assert_eq!(*seen.borrow(), vec![9000, 9001, 9002, 9003]);
    }

    /// Port 9000 held by MinIO (or a broker that stopped answering) must not
    /// be where the new broker is started and then waited on.
    #[test]
    fn pick_port_skips_taken_ports() {
        assert_eq!(pick_port(|_| false), Some(9000));
        assert_eq!(pick_port(|p| p <= 9001), Some(9002));
        assert_eq!(pick_port(|_| true), None);
    }

    #[test]
    fn log_tail_keeps_the_last_non_empty_lines() {
        let dir = std::env::temp_dir().join(format!("zc-autobroker-{}", std::process::id()));
        std::fs::create_dir_all(&dir).unwrap();
        let p = dir.join("b.log");
        std::fs::write(&p, "a\n\nb\nc\n").unwrap();
        assert_eq!(log_tail(&p, 2), "\n    b\n    c");
        assert_eq!(log_tail(&dir.join("missing"), 2), "");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn find_running_broker_none_when_all_fail() {
        let url = find_running_broker(|_port| None);
        assert_eq!(url, None);
    }
}