flexgate 0.1.0__py3-none-any.whl

flexgate/guardian.py

@@ -0,0 +1,252 @@
+"""Port Guardian.
+
+Monitors port 8765 and refuses to start the gateway if the port is already
+occupied. While running, it continuously monitors the port and logs an ERROR
+if a foreign process grabs it.
+
+Does NOT kill other processes — it only detects and reports.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import signal
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import NamedTuple
+
+logger = logging.getLogger("flexgate.guardian")
+
+
+# ── Types ────────────────────────────────────────────────────────────────────
+
+class PortOwner(NamedTuple):
+    pid: int
+    command: str
+
+
+# ── Config ───────────────────────────────────────────────────────────────────
+
+@dataclass
+class GuardianConfig:
+    port: int = 8765
+    interval: float = 3.0
+    strict: bool = True
+    guardian_pid_file: str = "flexgate.guardian.pid"
+    gateway_pid: int | None = None
+
+
+# ── Port ownership detection ──────────────────────────────────────────────────
+
+def _port_hex(port: int) -> str:
+    return f"{port:04X}"
+
+
+def check_port_owner(port: int) -> PortOwner | None:
+    """Return the PID+command of the process bound to `port`, or None.
+
+    Works on Linux by parsing /proc/net/tcp and matching socket inodes
+    against /proc/<pid>/fd/* symlinks.
+    """
+    target = f":{_port_hex(port)}"
+    inodes: set[int] = set()
+
+    for filename in ("/proc/net/tcp", "/proc/net/tcp6"):
+        try:
+            text = Path(filename).read_text()
+        except OSError:
+            continue
+        for line in text.splitlines()[1:]:  # skip header line
+            parts = line.split()
+            if len(parts) < 10:
+                continue
+            local_addr = parts[1].upper()
+            if not local_addr.endswith(target):
+                continue
+            try:
+                inodes.add(int(parts[9]))
+            except ValueError:
+                continue
+
+    if not inodes:
+        return None
+
+    for entry in Path("/proc").iterdir():
+        if not entry.name.isdigit():
+            continue
+        pid = int(entry.name)
+        fd_dir = Path(f"/proc/{pid}/fd")
+        try:
+            for fd in fd_dir.iterdir():
+                try:
+                    link = os.readlink(fd)
+                except OSError:
+                    continue
+                for inode in inodes:
+                    if link == f"socket:[{inode}]":
+                        comm_path = Path(f"/proc/{pid}/comm")
+                        try:
+                            comm = comm_path.read_text().strip()
+                        except OSError:
+                            comm = f"pid-{pid}"
+                        return PortOwner(pid=pid, command=comm)
+        except OSError:
+            continue
+
+    return None
+
+
+def is_port_free(port: int) -> tuple[bool, str]:
+    """Return (True, "") if the port is free, or (False, reason) if occupied."""
+    owner = check_port_owner(port)
+    if owner is None:
+        return True, ""
+    return False, f"Port {port} is already occupied by PID {owner.pid} ({owner.command})."
+
+
+# ── Guardian lifecycle ───────────────────────────────────────────────────────
+
+def _write_guardian_pid(pid: int, path: str) -> None:
+    Path(path).write_text(str(pid))
+
+
+def _remove_guardian_pid(path: str) -> None:
+    try:
+        Path(path).unlink()
+    except FileNotFoundError:
+        pass
+
+
+class PortGuardian:
+    """Background monitor for a single port.
+
+    In strict mode: exits immediately if the port is already occupied.
+    In monitor mode: logs an ERROR each time a foreign process binds the port.
+    """
+
+    def __init__(self, config: GuardianConfig) -> None:
+        self.config = config
+        self._running = True
+        self._occupied_at_start: bool | None = None
+
+    def _signal_stop(self, signum: int, _frame) -> None:
+        logger.info("Guardian received %s, shutting down", signal.Signals(signum).name)
+        self._running = False
+
+    def run(self) -> None:
+        cfg = self.config
+        pid_path = os.path.abspath(cfg.guardian_pid_file)
+
+        signal.signal(signal.SIGTERM, self._signal_stop)
+        signal.signal(signal.SIGINT, self._signal_stop)
+
+        logger.info(
+            "Guardian started, protecting port %d (strict=%s, interval=%.1fs)",
+            cfg.port, cfg.strict, cfg.interval,
+        )
+
+        # Strict mode: fail immediately if port is already taken
+        if cfg.strict:
+            free, reason = is_port_free(cfg.port)
+            if not free:
+                # Also print to stderr so it surfaces in CLI output
+                sys.stderr.write(f"[Guardian] ERROR: {reason}\n")
+                sys.stderr.write("[Guardian] Please stop that process first, then run 'flexgate service start' again.\n")
+                sys.stderr.flush()
+                _remove_guardian_pid(pid_path)
+                sys.exit(1)
+            logger.info("Port %d is free — gateway can bind", cfg.port)
+            self._occupied_at_start = False
+        else:
+            self._occupied_at_start = check_port_owner(cfg.port) is not None
+
+        _write_guardian_pid(os.getpid(), pid_path)
+
+        while self._running:
+            try:
+                self._check_and_alert()
+            except Exception as exc:
+                logger.exception("Error in guardian loop: %s", exc)
+
+            time.sleep(cfg.interval)
+
+        _remove_guardian_pid(pid_path)
+        logger.info("Guardian stopped")
+
+    def _check_and_alert(self) -> None:
+        owner = check_port_owner(self.config.port)
+        if owner is None:
+            return  # port is free
+        if self.config.gateway_pid and owner.pid == self.config.gateway_pid:
+            return  # port is held by the gateway itself — all good
+        logger.error(
+            "Port %d is now occupied by PID %d (%s). Gateway is now unreachable!",
+            self.config.port, owner.pid, owner.command,
+        )
+
+
+# ── Subprocess spawner (called from cli.py) ──────────────────────────────────
+
+def start_guardian_subprocess(
+    port: int,
+    interval: float,
+    strict: bool,
+    log_path: str,
+    pid_file: str,
+    gateway_pid: int | None = None,
+) -> subprocess.Popen:
+    """Spawn the guardian as a detached subprocess.
+
+    Redirects stdout/stderr to `log_path` so all guardian log lines
+    appear in flexgate.log alongside the gateway's own logs.
+    """
+    cmd = [
+        sys.executable, "-m", "flexgate.guardian",
+        str(port), str(interval), str(strict).lower(),
+    ]
+    if gateway_pid is not None:
+        cmd.append(str(gateway_pid))
+    log_file = open(log_path, "a")
+    proc = subprocess.Popen(
+        cmd,
+        stdout=log_file,
+        stderr=log_file,
+        start_new_session=True,
+    )
+    return proc
+
+
+# ── Entry point: python -m flexgate.guardian ────────────────────────────────
+
+if __name__ == "__main__":
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s flexgate.guardian: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    if len(sys.argv) not in (4, 5):
+        sys.stderr.write(f"Usage: python -m flexgate.guardian <port> <interval> <strict> [gateway_pid]\n")
+        sys.exit(1)
+
+    port = int(sys.argv[1])
+    interval = float(sys.argv[2])
+    strict = sys.argv[3] == "true"
+    gateway_pid = int(sys.argv[4]) if len(sys.argv) == 5 else None
+
+    from flexgate.config import FLEXGATE_HOME
+    pid_file = os.path.join(FLEXGATE_HOME, "flexgate.guardian.pid")
+
+    cfg = GuardianConfig(
+        port=port,
+        interval=interval,
+        strict=strict,
+        guardian_pid_file=pid_file,
+        gateway_pid=gateway_pid,
+    )
+    guardian = PortGuardian(cfg)
+    guardian.run()

flexgate/healthcheck.py

@@ -0,0 +1,197 @@
+"""Provider connectivity verification.
+
+Tests each unique ``(provider, model)`` combination referenced by the
+configured routes (default + schedule) by issuing a minimal
+``POST /v1/messages`` request with ``max_tokens=1``.
+
+This catches the common pre-flight failure modes before the gateway
+starts accepting traffic:
+
+* DNS / TCP / TLS unreachable (wrong base_url, no network)
+* Invalid or expired API key (401 / 403)
+* Provider-side outage (5xx)
+* Unknown model name for that provider (404 / 400)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+
+import httpx
+
+from flexgate.config import GatewayConfig, ProviderConfig
+
+logger = logging.getLogger("flexgate.healthcheck")
+
+# Fallback model used when a provider is referenced only by routes without
+# an explicit ``model:`` field. May produce a 404 but still exercises the
+# auth path.
+_FALLBACK_TEST_MODEL = "claude-haiku-4-5"
+
+# Heuristic placeholders that the default template ships with; we don't
+# want to hit upstream with these.
+_PLACEHOLDER_MARKERS = ("your-", "xxx", "changeme", "placeholder")
+
+
+@dataclass
+class CheckResult:
+    provider: str
+    model: str | None
+    ok: bool
+    status: int | None
+    message: str
+
+    @property
+    def target(self) -> str:
+        if self.model:
+            return f"{self.provider} / {self.model}"
+        return self.provider
+
+
+def _is_placeholder_key(key: str) -> bool:
+    if not key:
+        return True
+    low = key.lower()
+    return any(marker in low for marker in _PLACEHOLDER_MARKERS)
+
+
+def _collect_targets(config: GatewayConfig) -> list[tuple[ProviderConfig, str | None]]:
+    """Collect unique ``(provider, model)`` targets to verify.
+
+    De-duplicates across the default routes and every schedule entry. If a
+    provider is configured but never referenced by any route, it is still
+    probed once with no model override so misconfigured base_urls/keys are
+    surfaced.
+    """
+    seen: set[tuple[str, str | None]] = set()
+    targets: list[tuple[ProviderConfig, str | None]] = []
+
+    all_routes = list(config.routes)
+    for entry in config.schedule:
+        all_routes.extend(entry.routes)
+
+    for route in all_routes:
+        provider = config.providers.get(route.provider_name)
+        if provider is None:
+            continue
+        model = route.model or provider.default_model
+        key = (route.provider_name, model)
+        if key in seen:
+            continue
+        seen.add(key)
+        targets.append((provider, model))
+
+    covered = {name for name, _ in seen}
+    for name, prov in config.providers.items():
+        if name not in covered:
+            targets.append((prov, prov.default_model))
+
+    return targets
+
+
+async def _check_one(
+    client: httpx.AsyncClient,
+    provider: ProviderConfig,
+    model: str | None,
+    timeout: float,
+) -> CheckResult:
+    if _is_placeholder_key(provider.api_key):
+        return CheckResult(
+            provider.name, model, False, None,
+            "api_key looks like a placeholder — edit your config.yaml",
+        )
+
+    url = f"{provider.base_url}/v1/messages"
+    headers = {
+        "content-type": "application/json",
+        "x-api-key": provider.api_key,
+        "anthropic-version": "2023-06-01",
+    }
+    body = {
+        "model": model or _FALLBACK_TEST_MODEL,
+        "max_tokens": 1,
+        "messages": [{"role": "user", "content": "ping"}],
+    }
+
+    try:
+        resp = await client.post(url, headers=headers, json=body, timeout=timeout)
+    except httpx.ConnectError as exc:
+        return CheckResult(provider.name, model, False, None, f"connect error: {exc}")
+    except httpx.TimeoutException:
+        return CheckResult(provider.name, model, False, None, f"timeout after {timeout:g}s")
+    except httpx.HTTPError as exc:
+        return CheckResult(
+            provider.name, model, False, None,
+            f"{type(exc).__name__}: {exc}",
+        )
+
+    status = resp.status_code
+
+    if status == 200:
+        return CheckResult(provider.name, model, True, status, "ok")
+
+    # Try to extract a structured error message.
+    detail = ""
+    try:
+        data = resp.json()
+        if isinstance(data, dict):
+            err = data.get("error", data)
+            if isinstance(err, dict):
+                etype = err.get("type", "")
+                emsg = err.get("message", "")
+                detail = f"{etype}: {emsg}".strip(": ").strip()
+            else:
+                detail = str(err)[:200]
+    except ValueError:
+        text = (resp.text or "").strip()
+        if text:
+            detail = text[:200]
+
+    message = f"HTTP {status}" + (f" — {detail}" if detail else "")
+
+    # 401/403 → auth failure (fatal). 5xx → upstream issue (fatal).
+    # 4xx with valid auth (e.g. model-not-found when we used the fallback
+    # model) → connection works; report as warning if the route had no
+    # explicit model, otherwise still fail.
+    if status in (401, 403):
+        return CheckResult(provider.name, model, False, status, message)
+    if status >= 500:
+        return CheckResult(provider.name, model, False, status, message)
+    if model is None and status in (400, 404):
+        return CheckResult(
+            provider.name, model, True, status,
+            f"reachable (HTTP {status} on fallback model probe)",
+        )
+    return CheckResult(provider.name, model, False, status, message)
+
+
+async def check_providers_async(
+    config: GatewayConfig,
+    timeout: float = 15.0,
+) -> list[CheckResult]:
+    targets = _collect_targets(config)
+    if not targets:
+        return []
+    async with httpx.AsyncClient() as client:
+        tasks = [_check_one(client, p, m, timeout) for p, m in targets]
+        return await asyncio.gather(*tasks)
+
+
+def check_providers(
+    config: GatewayConfig,
+    timeout: float = 15.0,
+) -> list[CheckResult]:
+    """Synchronously run the connectivity checks."""
+    return asyncio.run(check_providers_async(config, timeout))
+
+
+def print_results(results: list[CheckResult]) -> None:
+    if not results:
+        print("  (no providers configured)")
+        return
+    width = max(len(r.target) for r in results)
+    for r in results:
+        marker = "✓" if r.ok else "✗"
+        print(f"  {marker} {r.target.ljust(width)}  {r.message}")

flexgate/main.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+
+import uvicorn
+
+from flexgate.config import load_config
+from flexgate.server import create_app
+
+
+class _FlexgateServer(uvicorn.Server):
+    def __init__(self, config: uvicorn.Config, config_path: str) -> None:
+        super().__init__(config)
+        self._config_path = config_path
+
+    async def startup(self, sockets=None) -> None:
+        await super().startup(sockets=sockets)
+        if self.started and os.environ.get("FLEXGATE_SERVICE") == "1":
+            try:
+                from flexgate.service import record_applied_state
+
+                record_applied_state(self._config_path)
+            except Exception:
+                logging.getLogger("flexgate").exception(
+                    "Failed to record applied service state"
+                )
+
+
+def run_server(config_path: str, port: int | None) -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    gateway_config = load_config(config_path)
+    port = port or gateway_config.server.port
+    app = create_app(gateway_config, config_path=config_path)
+    server_config = uvicorn.Config(
+        app,
+        host=gateway_config.server.host,
+        port=port,
+        log_level="info",
+    )
+    _FlexgateServer(server_config, config_path).run()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", default=None)
+    parser.add_argument("--port", type=int, default=None)
+    args = parser.parse_args()
+    run_server(args.config, args.port)

flexgate/migrate.py

@@ -0,0 +1,138 @@
+"""Config file schema versioning and automatic migrations.
+
+Every config.yaml carries a ``config_version`` integer. Each release that
+changes the config schema bumps :data:`CURRENT_CONFIG_VERSION` and registers
+one migration function per version step in :data:`MIGRATIONS`. Upgrading
+always walks the chain one step at a time (N → N+1 → … → current), so configs
+from any older release are upgraded through every intermediate rule.
+
+``flexgate doctor`` reports pending migrations; ``flexgate update`` applies
+them (with a timestamped backup) via :func:`migrate_config_file`.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import time
+from dataclasses import dataclass, field
+from typing import Callable
+
+CURRENT_CONFIG_VERSION = 1
+
+# ── per-step migration rules ──────────────────────────────────────
+# Each rule takes the raw config dict at version N and returns it upgraded
+# to version N+1. Rules must be idempotent and must not touch api keys.
+
+def _migrate_0_to_1(data: dict) -> dict:
+    """Stamp the initial versioned schema.
+
+    Legacy configs (written before versioning existed) have no
+    ``config_version`` key. The v1 schema is what 0.1.0 already parses, so
+    this step only guarantees the top-level sections exist and records the
+    version marker.
+    """
+    data.setdefault("server", {})
+    data.setdefault("providers", {})
+    data.setdefault("routes", [])
+    return data
+
+
+# version N → rule upgrading N to N+1
+MIGRATIONS: dict[int, Callable[[dict], dict]] = {
+    0: _migrate_0_to_1,
+}
+
+
+@dataclass
+class MigrationResult:
+    path: str
+    from_version: int
+    to_version: int
+    applied: list[str] = field(default_factory=list)  # human-readable steps
+    backup_path: str | None = None
+    changed: bool = False
+
+
+def detect_config_version(data: dict) -> int:
+    raw = data.get("config_version", 0)
+    try:
+        version = int(raw)
+    except (TypeError, ValueError):
+        raise ValueError(f"config_version must be an integer, got {raw!r}")
+    if version < 0:
+        raise ValueError(f"config_version must be >= 0, got {version}")
+    return version
+
+
+def pending_steps(version: int) -> list[int]:
+    """Migration steps needed to bring `version` up to CURRENT_CONFIG_VERSION."""
+    return [v for v in range(version, CURRENT_CONFIG_VERSION) if v in MIGRATIONS]
+
+
+def migrate_data(data: dict) -> tuple[dict, list[str]]:
+    """Apply all pending migrations in memory. Returns (data, applied steps)."""
+    version = detect_config_version(data)
+    if version > CURRENT_CONFIG_VERSION:
+        raise ValueError(
+            f"config_version {version} is newer than this flexgate supports "
+            f"({CURRENT_CONFIG_VERSION}) — upgrade flexgate first: flexgate update"
+        )
+    applied: list[str] = []
+    for step in pending_steps(version):
+        data = MIGRATIONS[step](data)
+        applied.append(f"v{step} → v{step + 1}: {MIGRATIONS[step].__doc__.splitlines()[0] if MIGRATIONS[step].__doc__ else 'migrate'}")
+    if applied or "config_version" not in data:
+        data["config_version"] = CURRENT_CONFIG_VERSION
+    return data, applied
+
+
+def read_raw_config(path: str) -> dict:
+    import yaml
+
+    with open(path) as f:
+        raw = yaml.safe_load(f)
+    if not isinstance(raw, dict):
+        raise ValueError(f"Config file {path} must be a YAML mapping")
+    return raw
+
+
+def migrate_config_file(path: str, *, backup: bool = True) -> MigrationResult:
+    """Migrate the config file on disk to CURRENT_CONFIG_VERSION.
+
+    Writes nothing when already current. Backs up to
+    ``<path>.bak-YYYYMMDD-HHMMSS`` before rewriting.
+    """
+    data = read_raw_config(path)
+    from_version = detect_config_version(data)
+    result = MigrationResult(path=path, from_version=from_version, to_version=CURRENT_CONFIG_VERSION)
+
+    if from_version == CURRENT_CONFIG_VERSION:
+        return result
+    if from_version > CURRENT_CONFIG_VERSION:
+        raise ValueError(
+            f"{path}: config_version {from_version} is newer than this flexgate "
+            f"supports ({CURRENT_CONFIG_VERSION}) — upgrade flexgate first"
+        )
+
+    data, applied = migrate_data(data)
+
+    if backup:
+        backup_path = f"{path}.bak-{time.strftime('%Y%m%d-%H%M%S')}"
+        shutil.copy2(path, backup_path)
+        result.backup_path = backup_path
+
+    # Keep config_version at the top for readability.
+    out = {"config_version": data.pop("config_version")}
+    out.update(data)
+
+    import yaml
+
+    tmp_path = f"{path}.tmp-{os.getpid()}"
+    with open(tmp_path, "w") as f:
+        yaml.dump(out, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+    os.replace(tmp_path, path)
+
+    result.applied = applied
+    result.changed = True
+    return result