Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python
14.3 KB
Raw Blame
"""Shared process helpers for installed client CLI launchers."""

import errno
import os
import shutil
import socket
import subprocess
import sys
import time
from collections.abc import Mapping
from contextlib import ExitStack
from dataclasses import dataclass
from enum import StrEnum
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.parse import urlsplit
from urllib.request import Request

from free_claude_code.cli.local_http import open_local_request
from free_claude_code.cli.process_registry import (
    kill_pid_tree_best_effort,
    register_pid,
    unregister_pid,
)
from free_claude_code.config import paths
from free_claude_code.config.paths import server_startup_lock_path
from free_claude_code.core.interprocess_lock import InterprocessFileLock

PROXY_PREFLIGHT_PATH = "/health"
PROXY_PREFLIGHT_TIMEOUT_SECONDS = 1.5

SERVER_STARTUP_TIMEOUT_SECONDS = 30.0
SERVER_STARTUP_LOCK_TIMEOUT_SECONDS = 30.0
SERVER_STARTUP_POLL_SECONDS = 0.25


class ProxyState(StrEnum):
    """What one health probe learned about the local proxy."""

    HEALTHY = "healthy"
    # An HTTP server answered, so a proxy exists even if it is unhealthy.
    HTTP_ERROR = "http_error"
    # A listener accepted TCP but never answered: the app is still loading.
    STARTING = "starting"
    # Nothing accepted the connection, so no server is running.
    UNREACHABLE = "unreachable"
    # The listener closed a connection during a possible owner restart.
    CONNECTION_CLOSED = "connection_closed"
    NETWORK_ERROR = "network_error"


@dataclass(frozen=True, slots=True)
class ProxyProbe:
    state: ProxyState
    error: str | None = None


def _probe_proxy(proxy_root_url: str, *, deadline: float) -> ProxyProbe:
    """Observe the endpoint once without consuming the whole startup wait."""

    remaining = deadline - time.monotonic()
    if remaining <= 0:
        return ProxyProbe(ProxyState.STARTING, "readiness deadline expired")
    url = f"{proxy_root_url.rstrip('/')}{PROXY_PREFLIGHT_PATH}"
    request = Request(url, method="GET")
    try:
        with open_local_request(
            request, timeout=min(PROXY_PREFLIGHT_TIMEOUT_SECONDS, remaining)
        ) as response:
            status_code = response.status
    except HTTPError as exc:
        return ProxyProbe(ProxyState.HTTP_ERROR, f"returned HTTP {exc.code}")
    except (URLError, OSError) as exc:
        reason = exc.reason if isinstance(exc, URLError) else exc
        if isinstance(reason, TimeoutError):
            # Windows can time out connecting to an absent listener. Conversely,
            # FCC reserves a listening socket before the HTTP app is ready.
            remaining = deadline - time.monotonic()
            if remaining <= 0:
                return ProxyProbe(ProxyState.STARTING, str(reason))
            address = urlsplit(url)
            try:
                with socket.create_connection(
                    (address.hostname or "127.0.0.1", address.port or 80),
                    timeout=min(PROXY_PREFLIGHT_TIMEOUT_SECONDS, remaining),
                ):
                    pass
            except ConnectionRefusedError, TimeoutError:
                return ProxyProbe(ProxyState.UNREACHABLE, str(reason))
            except OSError as exc:
                return ProxyProbe(ProxyState.NETWORK_ERROR, str(exc))
            return ProxyProbe(ProxyState.STARTING, str(reason))
        if isinstance(reason, ConnectionRefusedError) or getattr(
            reason, "errno", None
        ) in {errno.ECONNREFUSED, 10061}:
            return ProxyProbe(ProxyState.UNREACHABLE, str(reason))
        if isinstance(reason, ConnectionError):
            return ProxyProbe(ProxyState.CONNECTION_CLOSED, str(reason))
        return ProxyProbe(ProxyState.NETWORK_ERROR, str(reason))
    if not 200 <= status_code < 300:
        return ProxyProbe(ProxyState.HTTP_ERROR, f"returned HTTP {status_code}")
    return ProxyProbe(ProxyState.HEALTHY)


def server_command() -> list[str]:
    """Run the installed platform owner with its normal process identity."""

    name = "fcc-desktop" if sys.platform in {"win32", "darwin"} else "fcc-server"
    suffix = ".exe" if sys.platform == "win32" else ""
    sibling = Path(sys.executable).parent / f"{name}{suffix}"
    if sibling.is_file() and os.access(sibling, os.X_OK):
        return [str(sibling), "--auto-started"]
    raise FileNotFoundError(
        f"Installed {name} command is missing or not executable: {sibling}"
    )


def _spawn_server(
    env: Mapping[str, str],
) -> tuple[subprocess.Popen[bytes], Path | None]:
    """Detach the owner and retain errors raised before runtime logging starts."""
    command = server_command()
    log_path = paths.server_startup_log_path()
    output = subprocess.DEVNULL
    capture_path = None
    with ExitStack() as stack:
        try:
            log_path.parent.mkdir(parents=True, exist_ok=True)
            output = stack.enter_context(log_path.open("wb"))
            capture_path = log_path
        except OSError as exc:
            print(
                f"Could not capture startup output in {log_path}: {exc}\n"
                "FCC will start without early output capture.",
                file=sys.stderr,
            )
        return (
            subprocess.Popen(
                command,
                stdin=subprocess.DEVNULL,
                stdout=output,
                stderr=subprocess.STDOUT,
                env=dict(env),
                creationflags=(
                    getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
                    | getattr(subprocess, "DETACHED_PROCESS", 0)
                    if sys.platform == "win32"
                    else 0
                ),
                start_new_session=sys.platform != "win32",
            ),
            capture_path,
        )


def _startup_diagnostics(detail: str, path: Path | None) -> str:
    if path is None:
        return f"{detail}\nStartup output was not captured for this attempt."
    try:
        with path.open("rb") as output:
            output.seek(0, os.SEEK_END)
            output.seek(max(0, output.tell() - 2048))
            tail = output.read().decode("utf-8", errors="replace").strip()
    except OSError as exc:
        return f"{detail}\nCould not read startup output: {exc}"
    return f"{detail}\nStartup log: {path}" + (f"\n{tail}" if tail else "")


def _desktop_owner_running() -> bool:
    """A manually launched Desktop may own startup outside our launcher lock."""

    if sys.platform not in {"win32", "darwin"}:
        return False
    lock = InterprocessFileLock(paths.config_dir_path() / "desktop.lock")
    try:
        acquired = lock.acquire()
    except OSError:
        return False
    if acquired:
        lock.release()
    return not acquired


def _server_owner_running() -> bool:
    """The server may be between listener generations, regardless of entrypoint."""

    lock = InterprocessFileLock(paths.server_owner_lock_path())
    try:
        acquired = lock.acquire()
    except OSError:
        return False
    if acquired:
        lock.release()
    return not acquired


def _owner_running() -> bool:
    return _desktop_owner_running() or _server_owner_running()


def _stop_owned_process(process: subprocess.Popen[bytes]) -> None:
    if process.poll() is not None:
        return
    try:
        process.terminate()
        process.wait(timeout=2)
    except subprocess.TimeoutExpired:
        try:
            process.kill()
            process.wait(timeout=2)
        except OSError, subprocess.TimeoutExpired:
            pass
    except OSError:
        pass


def _unreachable_message(proxy_root_url: str, probe: ProxyProbe, detail: str) -> str:
    name = "fcc-desktop" if sys.platform in {"win32", "darwin"} else "fcc-server"
    return (
        f"Free Claude Code proxy is not reachable at {proxy_root_url}: {probe.error}\n"
        f"{detail}\n"
        f"Start it manually with: {name}"
    )


def _wait_for_server(
    proxy_root_url: str,
    process: subprocess.Popen[bytes] | None,
    *,
    deadline: float,
) -> ProxyProbe | str:
    """Poll until the spawned server answers, exits, or the budget runs out."""

    while time.monotonic() < deadline:
        probe = _probe_proxy(proxy_root_url, deadline=deadline)
        if probe.state in {
            ProxyState.HEALTHY,
            ProxyState.HTTP_ERROR,
            ProxyState.NETWORK_ERROR,
        }:
            return probe
        if (
            probe.state is ProxyState.CONNECTION_CLOSED
            and process is None
            and not _owner_running()
        ):
            return probe
        exit_code = process.poll() if process is not None else None
        if exit_code is not None:
            if _owner_running():
                # A manual owner may have won the bind/singleton race. Its actual
                # endpoint, not the duplicate's exit code, determines readiness.
                process = None
            else:
                name = (
                    "fcc-desktop"
                    if sys.platform in {"win32", "darwin"}
                    else "fcc-server"
                )
                return f"{name} exited with code {exit_code} before it was ready."
        remaining = deadline - time.monotonic()
        if remaining > 0:
            time.sleep(min(SERVER_STARTUP_POLL_SECONDS, remaining))
    return (
        "Free Claude Code did not become ready within "
        f"{SERVER_STARTUP_TIMEOUT_SECONDS:g} seconds. If FCC is already running, "
        "check its configured port or restart it."
    )


def ensure_proxy_available(
    proxy_root_url: str, *, env: Mapping[str, str]
) -> str | None:
    """Return an error message when the proxy is down and cannot be started here.

    A missing server is started once, under an interprocess lock, so concurrent
    launchers share one platform owner instead of racing to bind the same port.
    """

    probe = _probe_proxy(
        proxy_root_url, deadline=time.monotonic() + SERVER_STARTUP_TIMEOUT_SECONDS
    )
    if probe.state is ProxyState.HEALTHY:
        return None
    if probe.state in {ProxyState.HTTP_ERROR, ProxyState.NETWORK_ERROR} or (
        probe.state is ProxyState.CONNECTION_CLOSED and not _owner_running()
    ):
        return _unreachable_message(
            proxy_root_url, probe, "The configured endpoint failed its health check."
        )
    lock = InterprocessFileLock(server_startup_lock_path())
    try:
        acquired = lock.acquire(wait=True, timeout=SERVER_STARTUP_LOCK_TIMEOUT_SECONDS)
    except OSError as exc:
        return _unreachable_message(
            proxy_root_url, probe, f"Could not acquire the startup lock: {exc}"
        )
    process = None
    capture_path = None
    try:
        # The startup budget starts now: time spent waiting for another
        # launcher's attempt must not shorten this launcher's own attempt.
        deadline = time.monotonic() + SERVER_STARTUP_TIMEOUT_SECONDS
        # Another launcher may have started the server while this one waited.
        probe = _probe_proxy(proxy_root_url, deadline=deadline)
        if probe.state is ProxyState.HEALTHY:
            return None
        if probe.state in {ProxyState.HTTP_ERROR, ProxyState.NETWORK_ERROR} or (
            probe.state is ProxyState.CONNECTION_CLOSED and not _owner_running()
        ):
            return _unreachable_message(
                proxy_root_url,
                probe,
                "The configured endpoint failed its health check.",
            )
        if not acquired:
            return _unreachable_message(
                proxy_root_url,
                probe,
                "Another launcher is still starting the server; retry shortly.",
            )
        if (
            probe.state is ProxyState.UNREACHABLE
            and time.monotonic() < deadline
            and not _owner_running()
        ):
            try:
                process, capture_path = _spawn_server(env)
            except OSError as exc:
                return _unreachable_message(
                    proxy_root_url, probe, f"Could not start FCC: {exc}"
                )
            print(
                f"Starting Free Claude Code at {proxy_root_url} "
                "(it keeps running after this client exits).",
                file=sys.stderr,
            )
        outcome = _wait_for_server(proxy_root_url, process, deadline=deadline)
        if isinstance(outcome, str):
            if process is not None:
                if process.poll() is None:
                    outcome += "\nFCC was left running for inspection."
                outcome = _startup_diagnostics(outcome, capture_path)
            return _unreachable_message(proxy_root_url, probe, outcome)
        if outcome.state is ProxyState.HEALTHY:
            return None
        return _unreachable_message(
            proxy_root_url, outcome, "Could not use the FCC endpoint."
        )
    except BaseException:
        if process is not None:
            _stop_owned_process(process)
        raise
    finally:
        lock.release()


def resolve_client_binary(
    *,
    binary_name: str,
    display_name: str,
    install_hint: str,
) -> str:
    """Resolve an installed client binary or exit with a user-facing hint."""

    client_command = shutil.which(binary_name)
    if client_command is None:
        print(
            f"Could not find {display_name} command: {binary_name}",
            file=sys.stderr,
        )
        print(install_hint, file=sys.stderr)
        raise SystemExit(127)
    return client_command


def run_client_process(
    *,
    command: list[str],
    env: Mapping[str, str],
    binary_name: str,
    display_name: str,
    install_hint: str,
) -> None:
    """Run a client CLI command and mirror its exit code."""

    process: subprocess.Popen[bytes] | None = None
    try:
        process = subprocess.Popen(command, env=dict(env))
        if process.pid:
            register_pid(process.pid)
        return_code = process.wait()
    except FileNotFoundError:
        print(
            f"Could not find {display_name} command: {binary_name}",
            file=sys.stderr,
        )
        print(install_hint, file=sys.stderr)
        raise SystemExit(127) from None
    except KeyboardInterrupt:
        if process is not None and process.pid:
            kill_pid_tree_best_effort(process.pid)
            process.wait()
        raise
    finally:
        if process is not None and process.pid:
            unregister_pid(process.pid)

    raise SystemExit(return_code)