from __future__ import annotations """Implementations for installed Free Claude Code commands.""" import errno import json import socket import threading import time import webbrowser from collections.abc import Callable from enum import StrEnum from typing import TYPE_CHECKING, Any from urllib.error import HTTPError, URLError from urllib.request import Request from loguru import logger from free_claude_code.cli.local_http import open_local_request from free_claude_code.cli.process_registry import kill_all_best_effort from free_claude_code.config.loader import ( ManagedConfigStore, clear_settings_cache, get_settings, ) from free_claude_code.config.paths import managed_env_path, server_owner_lock_path from free_claude_code.config.server_urls import local_admin_url, local_proxy_root_url from free_claude_code.config.settings import Settings from free_claude_code.core.interprocess_lock import InterprocessFileLock from .server_socket import ServerSockets if TYPE_CHECKING: import uvicorn SERVER_GRACEFUL_SHUTDOWN_SECONDS = 5 _BROWSER_HANDOFF_SECONDS = 5.0 def _start_admin_browser( settings: Settings, eligible: Callable[[], bool], *, instance_id: str ) -> threading.Event: """Hand off an optional browser action without keeping FCC alive.""" completed = threading.Event() url = local_admin_url(settings) browser_logger = logger.bind(instance_id=instance_id) def open_browser() -> None: try: if eligible() and not webbrowser.open(url): browser_logger.warning( "Could not open Admin in a browser. Open {} manually.", url ) except Exception as exc: browser_logger.warning( "Could not open Admin: {}. Open {} manually.", exc, url ) finally: completed.set() try: threading.Thread( target=open_browser, name="fcc-open-admin-browser", daemon=True ).start() except Exception as exc: browser_logger.warning( "Could not start the Admin browser: {}. Open {} manually.", exc, url ) completed.set() return completed def serve(*, console_logging: bool = True) -> None: """Start and supervise the FastAPI server.""" try: ServerSupervisor(console_logging=console_logging).run() except OSError as exc: if exc.errno == errno.EADDRINUSE: _log_port_in_use(get_settings()) else: logger.error("Could not start FCC: {}", exc) raise SystemExit(1) from None def _log_port_in_use(settings: Settings) -> None: """Explain a busy port, telling a running FCC apart from another program.""" status = None try: status = _external_fcc_status(settings, timeout=1.5) other_program = status is None except HTTPError as exc: # Admin rejects non-loopback requests, so a 403 cannot rule out FCC. other_program = exc.code != 403 except ValueError: other_program = True except OSError: other_program = False if status is not None and status["status"] == "running": logger.error( "FCC is already running on port {}. Use it at {}, or stop it before " "starting another instance.", settings.port, local_admin_url(settings), ) elif status is not None: logger.error( "The FCC instance on port {} is still stopping. Try again in a moment.", settings.port, ) elif other_program: logger.error( "Could not start FCC: port {} is already in use by another program. " "Stop that program, or set PORT to a free port in {}.", settings.port, managed_env_path(), ) else: logger.error( "Could not start FCC: port {} is already in use. If FCC is not already " "running, stop the program using it, or set PORT to a free port in {}.", settings.port, managed_env_path(), ) class ServerStatus(StrEnum): """Observable state of the server owned by a supervisor.""" STARTING = "Starting" RUNNING = "Running" STOPPING = "Stopping" STOPPED = "Stopped" class ServerSupervisor: """Own one FCC server lifecycle, including config-driven restarts.""" def __init__(self, *, console_logging: bool = True) -> None: self._console_logging = console_logging self._lock = threading.Lock() self._server: uvicorn.Server | None = None self._run_scheduled = False self._running = False self.stop_event = threading.Event() self._ready_settings: Settings | None = None self._ready_instance_id: str | None = None self._pending_admin = False self._auto_browser_opened = False self._owned_server = False self._restart_generation = 0 @property def status(self) -> ServerStatus: with self._lock: if self._run_scheduled: return ServerStatus.STARTING if not self._running: return ServerStatus.STOPPED if self._server is None: return ServerStatus.STARTING if self._server.should_exit: return ServerStatus.STOPPING if self._server.started: return ServerStatus.RUNNING return ServerStatus.STARTING def schedule_run(self) -> bool: """Reserve a worker run before its thread starts.""" with self._lock: if self.stop_event.is_set() or self._run_scheduled or self._running: return False self._run_scheduled = True return True def run( self, *, open_admin_browser: bool | None = None, existing_server: Callable[[Settings], bool] | None = None, ) -> None: """Block until stopped, applying only fully closed Admin restarts.""" with self._lock: self._run_scheduled = False if self._running: raise RuntimeError("The FCC server supervisor is already running.") if self.stop_event.is_set(): return self._running = True self._owned_server = False self._auto_browser_opened = False owner_lock = InterprocessFileLock(server_owner_lock_path()) try: try: if not owner_lock.acquire(): if existing_server and existing_server(load_server_settings()): return raise OSError( errno.EADDRINUSE, "Another FCC server already owns this configuration.", ) while not self._is_stop_requested(): with self._lock: restart_generation = self._restart_generation settings = load_server_settings() should_open_admin = ( settings.open_admin_browser if open_admin_browser is None else open_admin_browser ) and not self._auto_browser_opened try: restart = self._run_once( settings, open_admin_browser=should_open_admin, restart_generation=restart_generation, ) except OSError as exc: if ( exc.errno == errno.EADDRINUSE and existing_server and existing_server(settings) ): return raise if not restart: return clear_settings_cache() except KeyboardInterrupt: return finally: try: with self._lock: self._server = None self._running = False if self._owned_server: kill_all_best_effort() finally: owner_lock.release() def request_restart(self) -> bool: """Reload an active generation or coalesce into a scheduled fresh run.""" with self._lock: if self.stop_event.is_set(): return False if self._run_scheduled: self._restart_generation += 1 return True if not self._running: return False self._restart_generation += 1 if self._server is not None: self._server.should_exit = True return True def request_stop(self) -> None: """Permanently stop this supervisor after graceful runtime cleanup.""" with self._lock: self.stop_event.set() self._run_scheduled = False if self._server is not None: self._server.should_exit = True def _is_stop_requested(self) -> bool: with self._lock: return self.stop_event.is_set() def request_open_admin(self) -> None: with self._lock: if self.stop_event.is_set(): return self._pending_admin = True settings = self._ready_settings instance_id = self._ready_instance_id generation = self._restart_generation if settings is not None and instance_id is not None: self._open_admin(settings, generation, instance_id) def _open_admin( self, settings: Settings, generation: int, instance_id: str ) -> None: def eligible() -> bool: with self._lock: if ( self.stop_event.is_set() or self._restart_generation != generation or self._ready_settings is not settings ): return False self._pending_admin = False return True _start_admin_browser(settings, eligible, instance_id=instance_id) def _run_once( self, settings: Settings, *, open_admin_browser: bool, restart_generation: int, ) -> bool: with ServerSockets.reserve(settings.host, settings.port) as listeners: self._owned_server = True if self.stop_event.is_set(): return False return self._run_bound( settings, listeners.sockets, open_admin_browser=open_admin_browser, restart_generation=restart_generation, ) def _run_bound( self, settings: Settings, sockets: list[socket.socket], *, open_admin_browser: bool, restart_generation: int, ) -> bool: import uvicorn from free_claude_code.runtime.bootstrap import build_asgi_app from .uvicorn_server import RuntimeServer, uvicorn_log_config asgi_app = build_asgi_app( settings, restart_callback=self._request_runtime_restart, ) config = uvicorn.Config( asgi_app, host=settings.host, port=settings.port, log_level="debug", log_config=uvicorn_log_config(console=self._console_logging), timeout_graceful_shutdown=SERVER_GRACEFUL_SHUTDOWN_SECONDS, ) def on_started() -> None: with self._lock: if ( self._server is not server or self.stop_event.is_set() or self._restart_generation != restart_generation ): return self._ready_settings = settings self._ready_instance_id = asgi_app.runtime.instance_id should_open = open_admin_browser or self._pending_admin if open_admin_browser: self._auto_browser_opened = True asgi_app.runtime.http_started() if should_open: self._open_admin( settings, restart_generation, asgi_app.runtime.instance_id ) server = RuntimeServer( config, begin_shutdown=asgi_app.runtime.begin_shutdown, on_started=on_started, close_runtime=asgi_app.runtime.close, ) with self._lock: self._server = server if ( self.stop_event.is_set() or self._restart_generation != restart_generation ): server.should_exit = True try: with logger.contextualize(instance_id=asgi_app.runtime.instance_id): server.run(sockets=sockets) finally: with self._lock: if self._server is server: self._server = None self._ready_settings = None self._ready_instance_id = None with self._lock: restart_requested = self._restart_generation != restart_generation stop_requested = self.stop_event.is_set() return restart_requested and not stop_requested and asgi_app.runtime.is_closed def _request_runtime_restart(self) -> None: self.request_restart() def load_server_settings() -> Settings: """Return canonical settings after repairing invalid managed proxies.""" settings = get_settings() removed = ManagedConfigStore().repair_invalid_provider_proxies() if not removed: return settings logger.warning( "Removed invalid managed provider proxy settings from {}: {}. " "Configure valid proxy URLs in Admin if needed.", managed_env_path(), ", ".join(removed), ) clear_settings_cache() return get_settings() def _external_fcc_status( settings: Settings, *, timeout: float ) -> dict[str, Any] | None: """Return the status payload an FCC instance reports on this port, or None for other servers.""" url = f"{local_proxy_root_url(settings)}/admin/api/status" with open_local_request(Request(url), timeout=timeout) as response: payload = json.loads(response.read().decode("utf-8")) if not isinstance(payload, dict) or not ( isinstance(payload.get("instance_id"), str) and len(payload["instance_id"]) == 32 and payload.get("status") in {"running", "stopping"} and isinstance(payload.get("host"), str) and payload.get("port") == settings.port and isinstance(payload.get("provider_status"), list) and isinstance(payload.get("cached_models"), dict) ): return None return payload def open_admin_when_ready( settings: Settings, *, stop_event: threading.Event | None = None ) -> bool: """Recognize an external FCC instance and attempt to open its local Admin page.""" stop = stop_event or threading.Event() deadline = time.monotonic() + 30.0 while not stop.is_set() and time.monotonic() < deadline: try: status = _external_fcc_status(settings, timeout=1.5) if status is None: return False if status["status"] == "running" and not stop.is_set(): completed = _start_admin_browser( settings, lambda: not stop.is_set(), instance_id=status["instance_id"], ) # This extra launcher is about to exit: allow a brief URL handoff. handoff_deadline = time.monotonic() + _BROWSER_HANDOFF_SECONDS while not stop.is_set(): remaining = handoff_deadline - time.monotonic() if remaining <= 0 or completed.wait(min(0.05, remaining)): break return True except (HTTPError, ValueError, UnicodeError): return False except (URLError, OSError): pass stop.wait(0.15) return False