flexgate 0.1.0__py3-none-any.whl

flexgate/config.py

@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+
+from flexgate.migrate import CURRENT_CONFIG_VERSION, detect_config_version
+
+FLEXGATE_HOME = os.path.expanduser("~/.flexgate")
+
+
+def get_default_config_path() -> str:
+    """Config path priority: FLEXGATE_CONFIG env > ~/.flexgate/config.yaml."""
+    env = os.environ.get("FLEXGATE_CONFIG")
+    if env:
+        return env
+    return os.path.join(FLEXGATE_HOME, "config.yaml")
+
+
+def ensure_home_dir() -> None:
+    os.makedirs(FLEXGATE_HOME, exist_ok=True)
+
+
+@dataclass
+class ProviderConfig:
+    name: str
+    base_url: str
+    api_key: str
+    available_models: list[str] = field(default_factory=list)
+
+    @property
+    def default_model(self) -> str | None:
+        return self.available_models[0] if self.available_models else None
+
+
+@dataclass
+class RouteConfig:
+    pattern: re.Pattern[str]
+    provider_name: str
+    model: str | None = None
+
+
+@dataclass
+class ServerConfig:
+    host: str = "127.0.0.1"
+    port: int = 8765
+
+
+@dataclass
+class ClaudeSettings:
+    default_opus_model: str = "claude-opus-4-7"
+    default_sonnet_model: str = "claude-sonnet-4-6"
+    default_haiku_model: str = "claude-haiku-4-5"
+    api_timeout_ms: int = 3000000
+
+
+@dataclass
+class InfisicalConfig:
+    project_id: str = ""
+    env: str = "dev"
+
+
+@dataclass
+class ScheduleEntry:
+    name: str
+    start_minutes: int
+    end_minutes: int
+    routes: list[RouteConfig] = field(default_factory=list)
+
+
+@dataclass
+class GatewayConfig:
+    server: ServerConfig = field(default_factory=ServerConfig)
+    providers: dict[str, ProviderConfig] = field(default_factory=dict)
+    routes: list[RouteConfig] = field(default_factory=list)
+    schedule: list[ScheduleEntry] = field(default_factory=list)
+    claude_settings: ClaudeSettings = field(default_factory=ClaudeSettings)
+    infisical: InfisicalConfig = field(default_factory=InfisicalConfig)
+
+
+def _parse_hhmm(value: str) -> int:
+    """Parse 'HH:MM' string to minutes since midnight."""
+    parts = value.strip().split(":")
+    if len(parts) != 2:
+        raise ValueError(f"Invalid time format '{value}', expected 'HH:MM'")
+    h, m = int(parts[0]), int(parts[1])
+    if not (0 <= h <= 24 and 0 <= m <= 59):
+        raise ValueError(f"Time out of range: '{value}'")
+    return h * 60 + m
+
+
+def _parse_routes(raw_routes: list[dict], providers: dict[str, ProviderConfig]) -> list[RouteConfig]:
+    routes: list[RouteConfig] = []
+    for r in raw_routes:
+        prov_name = r["provider"]
+        if prov_name not in providers:
+            raise ValueError(f"Route references unknown provider '{prov_name}'")
+        model = r.get("model")
+        if model is None and not providers[prov_name].available_models:
+            raise ValueError(
+                f"Route '{r['pattern']}' omits 'model' but provider '{prov_name}' "
+                f"has no 'available_models' to fall back to. "
+                f"Add 'available_models' to provider '{prov_name}' or set an explicit 'model' on the route."
+            )
+        routes.append(RouteConfig(
+            pattern=re.compile(r["pattern"]),
+            provider_name=prov_name,
+            model=model,
+        ))
+    return routes
+
+
+def load_config(path: str | None = None) -> GatewayConfig:
+    import yaml
+
+    if path is None:
+        path = get_default_config_path()
+
+    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")
+
+    config_version = detect_config_version(raw)
+    if config_version > CURRENT_CONFIG_VERSION:
+        raise ValueError(
+            f"{path} was written by a newer flexgate (config_version {config_version} > "
+            f"{CURRENT_CONFIG_VERSION}). Run 'flexgate update' to upgrade."
+        )
+
+    cfg = GatewayConfig()
+
+    srv = raw.get("server", {})
+    host = srv.get("host", "127.0.0.1")
+    port = srv.get("port", 8765)
+    if not isinstance(host, str) or not host:
+        raise ValueError("server.host must be a non-empty string")
+    if isinstance(port, bool) or not isinstance(port, int) or not (1 <= port <= 65535):
+        raise ValueError("server.port must be an integer between 1 and 65535")
+    cfg.server = ServerConfig(
+        host=host,
+        port=port,
+    )
+
+    for name, prov in raw.get("providers", {}).items():
+        available = prov.get("available_models", []) or []
+        if not isinstance(available, list):
+            raise ValueError(
+                f"Provider '{name}': 'available_models' must be a list of model names"
+            )
+        cfg.providers[name] = ProviderConfig(
+            name=name,
+            base_url=prov["base_url"].rstrip("/"),
+            api_key=prov["api_key"],
+            available_models=[str(m) for m in available],
+        )
+
+    cfg.routes = _parse_routes(raw.get("routes", []), cfg.providers)
+
+    for entry in raw.get("schedule", []):
+        cfg.schedule.append(ScheduleEntry(
+            name=entry.get("name", ""),
+            start_minutes=_parse_hhmm(entry["start"]),
+            end_minutes=_parse_hhmm(entry["end"]),
+            routes=_parse_routes(entry.get("routes", []), cfg.providers),
+        ))
+
+    cs = raw.get("claude_settings", {})
+    if cs:
+        cfg.claude_settings = ClaudeSettings(
+            default_opus_model=cs.get("default_opus_model", cfg.claude_settings.default_opus_model),
+            default_sonnet_model=cs.get("default_sonnet_model", cfg.claude_settings.default_sonnet_model),
+            default_haiku_model=cs.get("default_haiku_model", cfg.claude_settings.default_haiku_model),
+            api_timeout_ms=cs.get("api_timeout_ms", cfg.claude_settings.api_timeout_ms),
+        )
+
+    inf = raw.get("infisical", {})
+    if inf:
+        cfg.infisical = InfisicalConfig(
+            project_id=str(inf.get("project_id", "")),
+            env=str(inf.get("env", "dev")),
+        )
+
+    return cfg
+
+
+def _serialize_routes(routes: list[RouteConfig]) -> list[dict]:
+    result: list[dict] = []
+    for route in routes:
+        r: dict = {"pattern": route.pattern.pattern, "provider": route.provider_name}
+        if route.model:
+            r["model"] = route.model
+        result.append(r)
+    return result
+
+
+def _format_hhmm(minutes: int) -> str:
+    return f"{minutes // 60:02d}:{minutes % 60:02d}"
+
+
+def save_config(cfg: GatewayConfig, path: str | None = None) -> None:
+    import yaml
+
+    if path is None:
+        path = get_default_config_path()
+
+    data: dict = {
+        "config_version": CURRENT_CONFIG_VERSION,
+        "server": {
+            "host": cfg.server.host,
+            "port": cfg.server.port,
+        },
+        "providers": {},
+        "claude_settings": {
+            "default_opus_model": cfg.claude_settings.default_opus_model,
+            "default_sonnet_model": cfg.claude_settings.default_sonnet_model,
+            "default_haiku_model": cfg.claude_settings.default_haiku_model,
+            "api_timeout_ms": cfg.claude_settings.api_timeout_ms,
+        },
+        "routes": _serialize_routes(cfg.routes),
+    }
+
+    if cfg.infisical.project_id:
+        data["infisical"] = {
+            "project_id": cfg.infisical.project_id,
+            "env": cfg.infisical.env,
+        }
+
+    for name, prov in cfg.providers.items():
+        entry: dict = {
+            "base_url": prov.base_url,
+            "api_key": prov.api_key,
+        }
+        if prov.available_models:
+            entry["available_models"] = list(prov.available_models)
+        data["providers"][name] = entry
+
+    if cfg.schedule:
+        schedule_data: list[dict] = []
+        for entry in cfg.schedule:
+            schedule_data.append({
+                "name": entry.name,
+                "start": _format_hhmm(entry.start_minutes),
+                "end": _format_hhmm(entry.end_minutes),
+                "routes": _serialize_routes(entry.routes),
+            })
+        data["schedule"] = schedule_data
+
+    with open(path, "w") as f:
+        yaml.dump(data, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
+
+TIER_PATTERNS: dict[str, str] = {
+    "opus": "^claude-opus",
+    "sonnet": "^claude-sonnet",
+    "haiku": "^claude-haiku",
+}
+
+DEFAULT_CONFIG_TEMPLATE = """\
+server:
+  host: "127.0.0.1"
+  port: 8765
+
+# Each provider must declare `available_models`. The first entry is used as the
+# fallback model whenever a route below omits its own `model:` field.
+providers:
+  zai:
+    base_url: "https://api.z.ai/api/anthropic"
+    api_key: "your-zai-api-key"
+    available_models:
+      - "glm-5.1"      # used as fallback when a route omits `model`
+      - "glm-4.6"
+  minimax:
+    base_url: "https://api.minimaxi.com/anthropic"
+    api_key: "your-minimax-api-key"
+    available_models:
+      - "MiniMax-M3"
+
+claude_settings:
+  default_opus_model: "claude-opus-4-7"
+  default_sonnet_model: "claude-sonnet-4-6"
+  default_haiku_model: "claude-haiku-4-5"
+  api_timeout_ms: 3000000
+
+# Infisical secret sync (optional): enables `flexgate sync` to pull provider
+# api_keys from Infisical. Each provider is a folder under /providers named
+# exactly after the provider, holding an API_KEY secret
+# (e.g. /providers/minimax-tmy/API_KEY). An optional MODELS secret holds
+# comma-separated model names. New folders are auto-imported by matching
+# their name prefix against known base_urls (see KNOWN_BASE_URLS in
+# flexgate/registry.py); unrecognized prefixes produce a warning.
+# infisical:
+#   project_id: "your-infisical-project-id"
+#   env: "dev"
+
+# Routes are matched top-to-bottom; first match wins.
+# `model:` is optional — when omitted, the provider's first available_models
+# entry is used. A provider referenced without `model` MUST have available_models.
+routes:
+  - pattern: "^claude-opus"
+    provider: zai
+    model: "glm-5.1"
+  - pattern: "^claude-sonnet"
+    provider: minimax
+    model: "MiniMax-M3"
+  - pattern: "^claude-haiku"
+    provider: minimax
+    model: "MiniMax-M3"
+  - pattern: ".*"           # catch-all, falls back to minimax's first available model
+    provider: minimax
+"""

flexgate/doctor.py

@@ -0,0 +1,241 @@
+"""``flexgate doctor`` — diagnose common installation and config problems.
+
+Runs a series of read-only checks and prints OK / WARN / FAIL per item.
+Exit code is 1 when any check FAILs, so it can gate a release or CI job.
+It never modifies anything; fixes are applied by ``flexgate update``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import sys
+from dataclasses import dataclass
+
+from flexgate import __version__
+from flexgate.config import load_config
+from flexgate.migrate import (
+    CURRENT_CONFIG_VERSION,
+    detect_config_version,
+    pending_steps,
+    read_raw_config,
+)
+from flexgate.update import fetch_latest_version
+
+OK, WARN, FAIL, SKIP = "OK", "WARN", "FAIL", "SKIP"
+
+
+@dataclass
+class Finding:
+    status: str
+    label: str
+    detail: str = ""
+
+
+def _check_python(findings: list[Finding]) -> None:
+    v = sys.version_info
+    if v >= (3, 11):
+        findings.append(Finding(OK, "Python", f"{v.major}.{v.minor}.{v.micro}"))
+    else:
+        findings.append(Finding(FAIL, "Python", f"{v.major}.{v.minor}.{v.micro} — flexgate requires >= 3.11"))
+
+
+def _check_package(findings: list[Finding], offline: bool) -> None:
+    if offline:
+        findings.append(Finding(SKIP, "Package update", "skipped (--offline)"))
+        return
+    latest = fetch_latest_version()
+    if latest is None:
+        findings.append(Finding(SKIP, "Package update", "PyPI unreachable"))
+    elif latest == __version__:
+        findings.append(Finding(OK, "Package update", f"{__version__} is the latest release"))
+    else:
+        findings.append(Finding(WARN, "Package update",
+                                f"{__version__} → {latest} available — run 'flexgate update'"))
+
+
+def _load_validated_config(config_path: str, findings: list[Finding]):
+    """Add findings for config existence/parse/schema. Returns GatewayConfig or None."""
+    if not os.path.exists(config_path):
+        findings.append(Finding(FAIL, "Config file",
+                                f"{config_path} not found — run 'flexgate config init'"))
+        return None
+    findings.append(Finding(OK, "Config file", config_path))
+
+    try:
+        raw = read_raw_config(config_path)
+    except Exception as e:
+        findings.append(Finding(FAIL, "Config YAML", f"cannot parse: {e}"))
+        return None
+
+    try:
+        version = detect_config_version(raw)
+    except ValueError as e:
+        findings.append(Finding(FAIL, "Config schema", str(e)))
+        return None
+
+    if version > CURRENT_CONFIG_VERSION:
+        findings.append(Finding(FAIL, "Config schema",
+                                f"v{version} is newer than this flexgate (v{CURRENT_CONFIG_VERSION}) "
+                                f"— upgrade flexgate first: flexgate update"))
+        return None
+    steps = pending_steps(version)
+    if steps:
+        findings.append(Finding(WARN, "Config schema",
+                                f"v{version} is outdated — run 'flexgate update' "
+                                f"to migrate to v{CURRENT_CONFIG_VERSION}"))
+    else:
+        findings.append(Finding(OK, "Config schema", f"v{version} (current)"))
+
+    try:
+        config = load_config(config_path)
+    except Exception as e:
+        findings.append(Finding(FAIL, "Config semantics", str(e)))
+        return None
+    findings.append(Finding(OK, "Config semantics", "providers/routes validate"))
+    return config
+
+
+def _check_providers(config, findings: list[Finding]) -> None:
+    from flexgate.healthcheck import _is_placeholder_key
+
+    if not config.providers:
+        findings.append(Finding(FAIL, "Providers", "none configured"))
+        return
+
+    placeholders = [name for name, p in config.providers.items() if _is_placeholder_key(p.api_key)]
+    if placeholders:
+        findings.append(Finding(WARN, "Provider keys",
+                                f"placeholder api_key in: {', '.join(placeholders)}"))
+    else:
+        findings.append(Finding(OK, "Provider keys", f"{len(config.providers)} provider(s) configured"))
+
+
+def _check_routes(config, findings: list[Finding]) -> None:
+    if not config.routes:
+        findings.append(Finding(WARN, "Routes", "no routes — unmatched models will 404"))
+        return
+    catch_all_idx = [i for i, r in enumerate(config.routes) if r.pattern.pattern == ".*"]
+    if catch_all_idx and catch_all_idx[0] < len(config.routes) - 1:
+        shadowed = [r.pattern.pattern for r in config.routes[catch_all_idx[0] + 1:]]
+        findings.append(Finding(WARN, "Routes",
+                                f"catch-all '.*' is not last; unreachable: {', '.join(shadowed)}"))
+    elif not catch_all_idx:
+        findings.append(Finding(WARN, "Routes", "no catch-all '.*' route — unmatched models will 404"))
+    else:
+        findings.append(Finding(OK, "Routes", f"{len(config.routes)} route(s), catch-all last"))
+
+
+def _check_port(config, findings: list[Finding]) -> None:
+    host, port = config.server.host, config.server.port
+    with socket.socket() as sock:
+        sock.settimeout(1.0)
+        occupied = sock.connect_ex((host, port)) == 0
+
+    from flexgate.service import service_active, service_installed
+
+    if occupied:
+        if service_active():
+            findings.append(Finding(OK, "Port", f"{host}:{port} serving (service active)"))
+        else:
+            findings.append(Finding(WARN, "Port",
+                                    f"{host}:{port} is in use but the flexgate service is not active "
+                                    f"— another process may hold it"))
+    else:
+        if service_installed() and not service_active():
+            findings.append(Finding(WARN, "Port",
+                                    f"service installed but not running — 'flexgate service start'"))
+        else:
+            findings.append(Finding(OK, "Port", f"{host}:{port} free"))
+
+
+def _check_systemd(findings: list[Finding]) -> None:
+    from flexgate.service import (
+        UNIT_MARKER,
+        _systemd_user_available,
+        _unit_path,
+        service_active,
+        service_installed,
+    )
+
+    available, reason = _systemd_user_available()
+    if not available:
+        findings.append(Finding(WARN, "systemd", reason))
+        return
+    if not service_installed():
+        findings.append(Finding(WARN, "systemd service",
+                                "not installed — 'flexgate service install'"))
+        return
+    try:
+        with open(_unit_path()) as f:
+            content = f.read()
+        if UNIT_MARKER not in content:
+            findings.append(Finding(WARN, "systemd service",
+                                    "unit predates the current format — reinstall with "
+                                    "'flexgate service install'"))
+            return
+    except OSError as e:
+        findings.append(Finding(FAIL, "systemd service", f"cannot read unit file: {e}"))
+        return
+    if service_active():
+        findings.append(Finding(OK, "systemd service", "installed and active"))
+    else:
+        findings.append(Finding(WARN, "systemd service",
+                                "installed but not active — 'flexgate service start'"))
+
+
+def _check_claude_settings(config, findings: list[Finding]) -> None:
+    settings_path = os.path.expanduser("~/.claude/settings.json")
+    if not os.path.exists(settings_path):
+        findings.append(Finding(SKIP, "Claude settings", "~/.claude/settings.json not found"))
+        return
+    try:
+        with open(settings_path) as f:
+            settings = json.load(f)
+    except Exception as e:
+        findings.append(Finding(WARN, "Claude settings", f"cannot parse: {e}"))
+        return
+    base_url = (settings.get("env") or {}).get("ANTHROPIC_BASE_URL", "")
+    expected = f"http://{config.server.host}:{config.server.port}"
+    if base_url.rstrip("/") == expected:
+        findings.append(Finding(OK, "Claude settings", f"ANTHROPIC_BASE_URL → {expected}"))
+    else:
+        findings.append(Finding(WARN, "Claude settings",
+                                f"ANTHROPIC_BASE_URL is {base_url!r}, expected {expected!r} "
+                                f"— 'flexgate settings apply'"))
+
+
+def run_doctor(config_path: str, *, offline: bool = False) -> int:
+    print(f"flexgate doctor — version {__version__}, config schema v{CURRENT_CONFIG_VERSION}\n")
+
+    findings: list[Finding] = []
+    _check_python(findings)
+    _check_package(findings, offline)
+
+    config = _load_validated_config(config_path, findings)
+    if config is not None:
+        _check_providers(config, findings)
+        _check_routes(config, findings)
+        _check_port(config, findings)
+        _check_claude_settings(config, findings)
+    _check_systemd(findings)
+
+    width = max(len(f.label) for f in findings)
+    for f in findings:
+        line = f"[{f.status:4s}] {f.label:{width}s}"
+        if f.detail:
+            line += f"  {f.detail}"
+        print(line)
+
+    fails = sum(1 for f in findings if f.status == FAIL)
+    warns = sum(1 for f in findings if f.status == WARN)
+    print()
+    if fails:
+        print(f"{fails} problem(s) must be fixed; {warns} warning(s).")
+        return 1
+    if warns:
+        print(f"No blocking problems; {warns} warning(s). 'flexgate update' fixes outdated versions.")
+    else:
+        print("Everything looks healthy.")
+    return 0