cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/public/web/server.py

@@ -0,0 +1,385 @@
+"""项目 AppServer，基于 Linglong 扩展服务注册、远程配置与内部管理路由。"""
+import asyncio
+import os
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Dict,
+    Optional,
+    Sequence,
+    Tuple,
+)
+
+from fastapi import (
+    APIRouter,
+    Request,
+)
+from fastapi.responses import ORJSONResponse
+
+from linglong_web import (
+    LinglongConfig,
+    LinglongConfigBase,
+)
+from linglong_web import (
+    HTTPClientConfig,
+    http_client,
+)
+from linglong_web import LinglongAppServer
+from linglong_web import BaseServerExtension
+from linglong_web import LinglongConst
+from linglong_web.utils import logger
+
+from cancan_microstack.public.const.app_consts import WebServerConst
+from cancan_microstack.public.schemas.service_registry import (
+    InstanceMetadata,
+    ServiceMetadata,
+    ServiceRegistryPayload,
+)
+from cancan_microstack.public.schemas.infra.status_types import InstanceStatus
+from cancan_microstack.public.web.config_value import ConfigValueResolver
+
+
+class AppServer(LinglongAppServer):
+    """项目 AppServer，实现服务注册、配置下发等行为 / Project specific AppServer."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._registry_keepalive_task: Optional[asyncio.Task] = None
+        self._config_value_resolver = ConfigValueResolver()
+
+    async def initialize(
+            self,
+            service_name: str,
+            router: APIRouter,
+            config_dict: Dict[str, type[LinglongConfigBase]],
+            scheduler_group=None,
+            middleware: Optional[list[Callable[[Request, Callable[[Request], Awaitable[Any]]], Awaitable[Any]]]] = None,
+            on_startup: Optional[Sequence[Callable[[], Any]]] = None,
+            on_shutdown: Optional[Sequence[Callable[[], Any]]] = None,
+            extensions: Sequence[BaseServerExtension] | None = None,
+    ) -> "AppServer":
+        await super().initialize(
+            service_name=service_name,
+            router=router,
+            config_dict=config_dict,
+            scheduler_group=scheduler_group,
+            middleware=middleware,
+            on_startup=on_startup,
+            on_shutdown=on_shutdown,
+            extensions=extensions,
+        )
+
+        self._initialize_config_value_resolver()
+
+        # controllersrv 等“宿主机控制服务”不参与服务注册/远程配置。
+        # Host controller services (e.g. controllersrv) do not participate in registry/remote config.
+        if not self._should_skip_registry():
+            self.register_shutdown_callback(self._deregister_from_infrasrv)
+        return self
+
+    def _initialize_config_value_resolver(self) -> None:
+        """初始化配置解析器并展开 ConfigValue 默认值 / Initialize resolver and materialize ConfigValue defaults."""
+        snapshot = LinglongConfig.snapshot()
+        self._config_value_resolver = ConfigValueResolver.from_snapshot(snapshot)
+        defaults = self._config_value_resolver.materialize_defaults()
+        if defaults:
+            LinglongConfig.apply_updates(defaults)
+            logger.info("ConfigValue wrappers initialized: %s", list(sorted(defaults.keys())))
+
+    async def on_startup(self):  # noqa: D401 - lifecycle override
+        await super().on_startup()
+        if not self._should_skip_registry():
+            self._registry_keepalive_task = asyncio.create_task(
+                self._registry_keepalive_loop(),
+                name=f"{self.service_name}-registry-keepalive",
+            )
+
+    async def on_shutdown(self) -> None:  # noqa: D401 - lifecycle override
+        if self._registry_keepalive_task:
+            self._registry_keepalive_task.cancel()
+            try:
+                await self._registry_keepalive_task
+            except asyncio.CancelledError:
+                pass
+            self._registry_keepalive_task = None
+        await super().on_shutdown()
+
+    async def _before_resources_initialized(self) -> None:
+        await self._fetch_service_config_from_remote(with_retry=True)
+
+    def _add_internal_routes(self) -> None:
+        if not self.app:
+            return
+        self.app.add_api_route("/internal/health", self._internal_health_check_handler, methods=["GET"])
+        self.app.add_api_route("/internal/config/update", self._internal_config_update_handler, methods=["POST"])
+
+    async def _internal_health_check_handler(self, request: Request):  # noqa: D401 - FastAPI handler
+        return ORJSONResponse({
+            "status": InstanceStatus.UP,
+            "service": self.service_name,
+            "instance_id": self.instance_id,
+        })
+
+    async def _internal_config_update_handler(self, request: Request):
+        try:
+            body = await request.json()
+        except Exception as exc:  # pragma: no cover - FastAPI already validates JSON
+            logger.error("Failed to parse config update payload: %s", exc, exc_info=True)
+            return ORJSONResponse({"status": "error", "message": str(exc)}, status_code=400)
+
+        config_payload = body.get("config") if isinstance(body, dict) else None
+        if not config_payload:
+            return ORJSONResponse({"status": "error", "message": "No config provided"}, status_code=400)
+
+        self._update_config(config_payload)
+        return ORJSONResponse({"status": "success", "message": "Config updated"})
+
+    async def _fetch_service_config_from_remote(self, with_retry: bool = False) -> None:
+        if self._should_skip_registry():
+            logger.info("%s is a special service, skip remote config fetch", self.service_name)
+            return
+
+        url = f"{LinglongConfig.INFRASRV_HOST}/v1/infrasrv/service_config"
+        params = {"service_name": self.service_name}
+        retries = 3 if with_retry else 0
+        for attempt in range(retries + 1):
+            try:
+                resp = await http_client.get(url, params=params, timeout=HTTPClientConfig.INTERNAL_SERVICE_TIMEOUT)
+                resp.raise_for_status()
+                data = await resp.json()
+                remote_config = data.get("data", {}) if isinstance(data, dict) else {}
+                if remote_config:
+                    logger.info("Fetched remote config keys: %s", list(remote_config.keys()))
+                    self._update_config(remote_config)
+                return
+            except Exception as exc:
+                is_dev = LinglongConfig.DEBUG
+                level = logger.warning if attempt < retries else logger.error
+                level(
+                    "Fetch remote config failed (attempt %s/%s): %s",
+                    attempt + 1,
+                    retries + 1,
+                    exc,
+                )
+                if attempt < retries:
+                    await asyncio.sleep(3)
+                elif is_dev:
+                    logger.info("Development mode: remote config fetch failure can be ignored")
+
+    def _update_config(self, remote_config: Dict[str, Any]) -> None:
+        if not remote_config:
+            return
+
+        processed: Dict[str, Any] = {}
+        for key, value in remote_config.items():
+            config_key = key.upper()
+            if not hasattr(LinglongConfig, config_key):
+                logger.warning("Unknown remote config key '%s', skipping", config_key)
+                continue
+
+            local_value = getattr(LinglongConfig, config_key)
+            try:
+                new_value = self._config_value_resolver.resolve_update_value(
+                    config_key=config_key,
+                    current_value=local_value,
+                    raw_value=value,
+                )
+                processed[config_key] = new_value
+            except Exception as exc:  # noqa: BLE001
+                logger.warning(
+                    "Failed to apply remote config for '%s': %s",
+                    config_key,
+                    exc,
+                )
+
+        if processed:
+            LinglongConfig.apply_updates(processed)
+            logger.info("Applied remote config: %s", list(processed.keys()))
+
+    async def _register_to_infrasrv(self) -> None:
+        register_host, container_hostname, network_alias, host_source = self._resolve_registration_host()
+        instance_metadata = InstanceMetadata(
+            container_hostname=container_hostname,
+            network_alias=network_alias,
+            register_host_source=host_source,
+            app_host_binding=self.host,
+        )
+        service_metadata = ServiceMetadata(
+            version="1.0.0",
+            environment=(
+                LinglongConst.ENVIRONMENT.DEVELOPMENT if LinglongConfig.DEBUG else LinglongConst.ENVIRONMENT.PRODUCTION),
+        )
+        payload = ServiceRegistryPayload(
+            service_name=self.service_name or "",
+            instance_id=self.instance_id or "",
+            host=register_host,
+            port=self.port or 0,
+            internal_port=self.port or 0,
+            health_check_url="/internal/health",
+            container_name=container_hostname or network_alias,
+            compose_service_name=network_alias,
+            service_metadata=service_metadata,
+            instance_metadata=instance_metadata,
+        )
+        payload_dict = payload.model_dump()
+        payload_dict["instance_metadata"] = instance_metadata.model_dump(exclude_none=True)
+
+        url = f"{LinglongConfig.INFRASRV_HOST}/v1/infrasrv/registry/register"
+        for attempt in range(4):
+            try:
+                resp = await http_client.post(
+                    url,
+                    json=payload_dict,
+                    timeout=HTTPClientConfig.INTERNAL_SERVICE_TIMEOUT,
+                )
+                if resp and resp.status == 200:
+                    logger.info("Service registered: %s (%s)", self.service_name, self.instance_id)
+                    return
+                logger.warning("Register service failed, status=%s", resp.status if resp else "N/A")
+            except Exception as exc:
+                logger.warning("register attempt %s failed: %s", attempt + 1, exc)
+            await asyncio.sleep(3)
+        logger.error("All attempts to register %s failed", self.service_name)
+
+    async def _register_keepalive_once(self) -> bool:
+        """执行一次保活注册 / Execute one keepalive registration tick."""
+        register_host, container_hostname, network_alias, host_source = self._resolve_registration_host()
+        instance_metadata = InstanceMetadata(
+            container_hostname=container_hostname,
+            network_alias=network_alias,
+            register_host_source=host_source,
+            app_host_binding=self.host,
+        )
+        service_metadata = ServiceMetadata(
+            version="1.0.0",
+            environment=(
+                LinglongConst.ENVIRONMENT.DEVELOPMENT if LinglongConfig.DEBUG else LinglongConst.ENVIRONMENT.PRODUCTION),
+        )
+        payload = ServiceRegistryPayload(
+            service_name=self.service_name or "",
+            instance_id=self.instance_id or "",
+            host=register_host,
+            port=self.port or 0,
+            internal_port=self.port or 0,
+            health_check_url="/internal/health",
+            container_name=container_hostname or network_alias,
+            compose_service_name=network_alias,
+            service_metadata=service_metadata,
+            instance_metadata=instance_metadata,
+        )
+        payload_dict = payload.model_dump()
+        payload_dict["instance_metadata"] = instance_metadata.model_dump(exclude_none=True)
+
+        url = f"{LinglongConfig.INFRASRV_HOST}/v1/infrasrv/registry/register"
+        try:
+            resp = await http_client.post(
+                url,
+                json=payload_dict,
+                timeout=HTTPClientConfig.INTERNAL_SERVICE_TIMEOUT,
+            )
+            if resp and resp.status == 200:
+                return True
+            logger.warning(
+                "Registry keepalive failed, status=%s, service=%s, instance=%s",
+                resp.status if resp else "N/A",
+                self.service_name,
+                self.instance_id,
+            )
+            return False
+        except Exception as exc:
+            logger.warning(
+                "Registry keepalive request failed for %s (%s): %s",
+                self.service_name,
+                self.instance_id,
+                exc,
+            )
+            return False
+
+    async def _registry_keepalive_loop(self) -> None:
+        """持续执行服务注册保活 / Keep registry heartbeat alive via periodic upsert."""
+        interval_seconds = int(getattr(LinglongConfig, "SERVICE_REGISTRY_KEEPALIVE_SECONDS", 30) or 30)
+        interval_seconds = max(interval_seconds, 5)
+
+        # 启动即执行一次注册 / Register immediately on startup
+        first_ok = await self._register_keepalive_once()
+        if first_ok:
+            logger.info("Service registered: %s (%s)", self.service_name, self.instance_id)
+        else:
+            logger.warning("Initial registry keepalive failed: %s (%s)", self.service_name, self.instance_id)
+
+        while True:
+            try:
+                await asyncio.sleep(interval_seconds)
+                await self._register_keepalive_once()
+            except asyncio.CancelledError:
+                break
+            except Exception as exc:
+                logger.warning(
+                    "Registry keepalive loop error for %s (%s): %s",
+                    self.service_name,
+                    self.instance_id,
+                    exc,
+                )
+
+    async def _deregister_from_infrasrv(self) -> None:
+        if self._should_skip_registry():
+            return
+        try:
+            url = f"{LinglongConfig.INFRASRV_HOST}/v1/infrasrv/registry/deregister"
+            params = {"service_name": self.service_name, "instance_id": self.instance_id}
+            resp = await http_client.delete(url, params=params, timeout=HTTPClientConfig.INTERNAL_SERVICE_TIMEOUT)
+            if resp and resp.status == 200:
+                logger.info("Service deregistered: %s (%s)", self.service_name, self.instance_id)
+            else:
+                logger.warning("Service deregister failed, status=%s", resp.status if resp else "N/A")
+        except Exception as exc:
+            logger.error("Deregister error: %s", exc)
+
+    def _resolve_registration_host(self) -> Tuple[str, Optional[str], str, str]:
+        container_hostname = (os.environ.get("HOSTNAME") or "").strip() or None
+        network_alias = self._build_network_alias()
+        host_source = "container_hostname"
+        register_host = container_hostname or network_alias
+
+        override_host = (os.environ.get("SERVICE_REGISTRY_HOST") or "").strip()
+        if override_host:
+            register_host = override_host
+            host_source = "env:SERVICE_REGISTRY_HOST"
+        elif (not container_hostname or
+              self._looks_like_container_hostname(container_hostname) or
+              container_hostname.lower() in WebServerConst.UNSAFE_HOSTS):
+            register_host = network_alias
+            host_source = "network_alias"
+        return register_host, container_hostname, network_alias, host_source
+
+    def _build_network_alias(self) -> str:
+        explicit_alias = os.environ.get("SERVICE_NETWORK_ALIAS")
+        if explicit_alias and explicit_alias.strip():
+            return explicit_alias.strip()
+        suffix = os.environ.get("SERVICE_NETWORK_SUFFIX", ".service")
+        base_name = self.service_name or ""
+        if base_name.endswith(suffix):
+            return base_name
+        return f"{base_name}{suffix}" if base_name else suffix.lstrip('.')
+
+    @staticmethod
+    def _looks_like_container_hostname(hostname: Optional[str]) -> bool:
+        if not hostname:
+            return False
+        candidate = hostname.strip().lower()
+        return bool(WebServerConst.CONTAINER_ID_PATTERN.fullmatch(candidate))
+
+    def _should_skip_registry(self) -> bool:
+        # controllersrv 是宿主机控制服务：不注册、不拉取远端配置、不发心跳。
+        # controllersrv is a host controller service: skip registry/remote config/heartbeat.
+        if bool(getattr(LinglongConfig, "IS_CONTROLLER_SERVICE", False)):
+            logger.info("%s is a controller service, skip service registry", self.service_name)
+            return True
+
+        # 可通过配置显式禁用服务注册（例如某些 BFF/工具型服务）。
+        # Allow explicit opt-out via config for services that should not register.
+        if bool(getattr(LinglongConfig, "SKIP_SERVICE_REGISTRY", False)):
+            logger.info("%s is configured to skip service registry", self.service_name)
+            return True
+        return False

cancan_microstack/runtime/compose_cmd.py

@@ -0,0 +1,228 @@
+"""Compose command detection & execution helpers.
+
+提供对 Docker/Podman Compose 的自动探测与执行。
+Provide auto-detection and execution helpers for Docker/Podman compose commands.
+
+Notes:
+- 用户不需要手动运行 `docker compose` / `podman compose`；cancan CLI 会在内部调用。
+  Users don't need to run `docker compose` / `podman compose` manually; cancan CLI will call it internally.
+- 本模块只依赖标准库，便于未来抽离成独立包。
+  This module uses stdlib only, so it can be extracted into a standalone package later.
+"""
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+from typing import IO
+from typing import Iterable
+
+
+@dataclass(frozen=True)
+class ComposeCommand:
+    """Compose 命令描述 / Compose command descriptor."""
+
+    argv_prefix: list[str]
+
+    def with_file(self, compose_file: Path) -> list[str]:
+        return [*self.argv_prefix, "-f", str(compose_file)]
+
+
+def _can_run(
+    cmd: list[str],
+    runner: Callable[..., subprocess.CompletedProcess[str]],
+    *,
+    timeout_seconds: float = 5.0,
+) -> bool:
+    """轻量检测命令是否可运行 / Lightweight check whether a command can run."""
+
+    try:
+        result = runner(
+            cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            check=False,
+            timeout=timeout_seconds,
+        )
+    except Exception:
+        return False
+
+    return result.returncode == 0
+
+
+def _first_existing(which: Callable[[str], str | None], names: Iterable[str]) -> str | None:
+    for name in names:
+        if which(name):
+            return name
+    return None
+
+
+def _daemon_ready_probe(prefix: list[str]) -> list[str] | None:
+    """Return a probe command that validates the engine daemon is reachable.
+
+    返回用于验证引擎 daemon 可用的 probe 命令。
+
+    Notes:
+    - `docker compose version` 只验证 CLI 存在，不保证 Docker daemon 可用。
+      `docker compose version` only checks CLI presence, not Docker daemon readiness.
+    - `podman compose version` 同理。
+      Same for podman.
+    """
+
+    if prefix[:2] == ["docker", "compose"] or prefix == ["docker-compose"]:
+        return ["docker", "info"]
+    if prefix[:2] == ["podman", "compose"] or prefix == ["podman-compose"]:
+        return ["podman", "info"]
+    return None
+
+
+def detect_compose_command(
+        *,
+        engine: str | None = None,
+        which: Callable[[str], str | None] = shutil.which,
+        runner: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
+) -> ComposeCommand:
+    """自动探测 Compose 命令（Docker 或 Podman）。
+
+    Auto-detect compose command (Docker or Podman).
+
+    Args:
+        engine: "docker" | "podman" | "auto" | None.
+            - None/"auto": try docker first then podman
+            - "docker": docker only
+            - "podman": podman only
+        which: injectable for tests.
+        runner: injectable for tests.
+
+    Returns:
+        ComposeCommand: argv prefix, e.g. ["docker", "compose"] or ["podman-compose"].
+
+    Raises:
+        RuntimeError: when no supported compose command is found.
+    """
+
+    normalized = (engine or os.environ.get("CANCAN_CONTAINER_ENGINE") or "auto").strip().lower()
+    if normalized not in {"auto", "docker", "podman"}:
+        normalized = "auto"
+
+    candidates: list[list[str]] = []
+
+    def add_docker_candidates() -> None:
+        # Prefer `docker compose` when docker exists.
+        # 优先使用 `docker compose`。
+        if which("docker"):
+            candidates.append(["docker", "compose"])
+        if which("docker-compose"):
+            candidates.append(["docker-compose"])
+
+    def add_podman_candidates() -> None:
+        # Prefer `podman compose` (Podman v4+ plugin). It avoids podman-compose pod semantics.
+        # 优先使用 `podman compose`（Podman v4+ 插件），避免 podman-compose 的 pod 语义与噪声报错。
+        if which("podman"):
+            candidates.append(["podman", "compose"])
+        if which("podman-compose"):
+            candidates.append(["podman-compose"])
+
+    if normalized == "docker":
+        add_docker_candidates()
+    elif normalized == "podman":
+        add_podman_candidates()
+    else:
+        # Auto mode: try Docker first only if Docker daemon is reachable; otherwise prefer Podman.
+        # 自动模式：只有当 Docker daemon 可用时才优先 Docker；否则优先 Podman，避免卡住。
+        add_docker_candidates()
+        add_podman_candidates()
+
+    for prefix in candidates:
+        # 1) CLI exists?
+        # 1) CLI 是否存在？
+        if not _can_run([*prefix, "version"], runner, timeout_seconds=5.0):
+            continue
+
+        # 2) Daemon reachable? (best-effort, fast timeout)
+        # 2) daemon 是否可用？（尽力而为，短超时）
+        probe = _daemon_ready_probe(prefix)
+        if probe is not None and _can_run(probe, runner, timeout_seconds=2.0):
+            return ComposeCommand(argv_prefix=prefix)
+
+        # If probe is not available, accept CLI presence.
+        # 若没有 probe，退化为“CLI 存在即接受”。
+        if probe is None:
+            return ComposeCommand(argv_prefix=prefix)
+
+    # Fallback: if some CLI exists but daemon probe failed (e.g. engine booting), return first CLI.
+    # 兜底：若 CLI 存在但 daemon probe 失败（例如引擎刚启动），返回第一个可用 CLI。
+    for prefix in candidates:
+        if _can_run([*prefix, "version"], runner, timeout_seconds=5.0):
+            return ComposeCommand(argv_prefix=prefix)
+
+    raise RuntimeError(
+        "No compose command found. Install Docker Desktop (docker compose) or Podman (podman compose / podman-compose)."
+    )
+
+
+def run_compose(
+        *,
+        compose_file: Path,
+        args: list[str],
+        workspace: Path,
+        engine: str | None = None,
+        runner: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
+) -> None:
+    """执行 compose 子命令 / Execute compose subcommand."""
+
+    cmd = detect_compose_command(engine=engine).with_file(compose_file)
+    full_cmd = [*cmd, *args]
+
+    runner(
+        full_cmd,
+        cwd=str(workspace),
+        check=True,
+        text=True,
+    )
+
+
+def run_compose_streaming(
+        *,
+        compose_file: Path,
+        args: list[str],
+        workspace: Path,
+        engine: str | None = None,
+        log_file: Path | None = None,
+) -> None:
+    """Run compose command and stream output to stdout while teeing to a log file.
+
+    执行 compose 命令，输出实时显示在终端，同时写入日志文件。
+    """
+
+    cmd = detect_compose_command(engine=engine).with_file(compose_file)
+    full_cmd = [*cmd, *args]
+
+    log_fp: IO[str] | None = None
+    if log_file is not None:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        log_fp = open(log_file, "a", encoding="utf-8")
+
+    try:
+        proc = subprocess.Popen(
+            full_cmd,
+            cwd=str(workspace),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
+
+        assert proc.stdout is not None
+        for line in proc.stdout:
+            print(line, end="")
+            if log_fp is not None:
+                log_fp.write(line)
+        rc = proc.wait()
+        if rc != 0:
+            raise subprocess.CalledProcessError(rc, full_cmd)
+    finally:
+        if log_fp is not None:
+            log_fp.close()