Function check_port_available

crates/openshell-core/src/forward.rs:626–674

Check whether a local port is available for forwarding. Uses a two-pronged check: 1. Attempts to bind ` : ` — catches same-family conflicts. 2. Runs `lsof -i : -sTCP:LISTEN` — catches cross-family conflicts (e.g. an IPv6 wildcard listener blocking a port the IPv4 bind test would miss). If the port is already in use the error message includes an actionable hint: - If an exis

(spec: &ForwardSpec)

/// - Otherwise, show the `lsof` output and suggest `kill` to terminate the
///   owning process.
pub fn check_port_available(spec: &ForwardSpec) -> Result<()> {
    let port = spec.port;

    // Fast path: try binding on the requested address.  If this fails, the
    // port is definitely taken on this address family.
    let bind_ok = TcpListener::bind((spec.bind_addr.as_str(), port)).is_ok();

    // Also ask the OS whether *any* process is listening on this port,
    // regardless of address family.  This catches situations where e.g. a
    // server binds [::]:8080 but our IPv4 bind test succeeds.
    let lsof_output = lsof_listeners(port);
    let lsof_occupied = lsof_output.is_some();

    if bind_ok && !lsof_occupied {
        return Ok(());
    }

    // Port is occupied.  Check if it belongs to a tracked openshell forward.
    if let Ok(forwards) = list_forwards()
        && let Some(fwd) = forwards
            .iter()
            .find(|f| f.port == port && f.validated_alive)
    {
        return Err(miette::miette!(
            "Port {port} is already forwarded to sandbox '{}'.\n\
             Stop it with: openshell forward stop {port} {}",
            fwd.sandbox_name,
            fwd.sandbox_name,
        ));
    }

    // Build a helpful error with lsof details when available.
    if let Some(output) = lsof_output {
        return Err(miette::miette!(
            "Port {port} is already in use by another process.\n\n\
             {output}\n\n\
             To free the port, find the PID above and run:\n  \
             kill <PID>\n\n\
             Or find it yourself with:\n  \
             lsof -i :{port} -sTCP:LISTEN",
        ));
    }

    Err(miette::miette!(
        "Port {port} is already in use by another process.\n\
         Find it with: lsof -i :{port} -sTCP:LISTEN\n\
         Then terminate it with: kill <PID>",
    ))
}

/// Run `lsof` to check for any process listening on `port`.
///