cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/core/runner.py

@@ -0,0 +1,56 @@
+"""Service runner utilities for controllersrv.
+
+在启动服务前自动完成 workspace & overrides bootstrap，再按入口点动态加载。
+Run bundled services after bootstrapping workspace/overrides and resolving entrypoints.
+"""
+import asyncio
+import inspect
+from importlib import import_module
+from pathlib import Path
+from typing import Dict
+
+from cancan_microstack.runtime.overrides import bootstrap_from_workspace
+
+
+class ServiceRunner:
+    """加载并执行内置服务入口点 / Load and execute bundled service entrypoints."""
+
+    _ENTRYPOINTS: Dict[str, str] = {
+        "controllersrv": "cancan_microstack.cmd.controllersrv.run:main",
+        "infrasrv": "cancan_microstack.cmd.infrasrv.run:main",
+        "opsbffsrv": "cancan_microstack.cmd.opsbffsrv.run:main",
+    }
+
+    def run(
+            self,
+            service_name: str,
+            *,
+            host: str = "0.0.0.0",
+            port: int = 8080,
+            workspace: str | Path | None = None,
+    ) -> None:
+        asyncio.run(self.run_async(service_name, host=host, port=port, workspace=workspace))
+
+    async def run_async(
+            self,
+            service_name: str,
+            *,
+            host: str = "0.0.0.0",
+            port: int = 8080,
+            workspace: str | Path | None = None,
+    ) -> None:
+        workspace_path = Path(workspace).expanduser().resolve() if workspace else None
+        bootstrap_from_workspace(workspace_path)
+        entry = self._ENTRYPOINTS.get(service_name)
+        if not entry:
+            raise ValueError(f"Unknown service '{service_name}'")
+        module_name, func_name = entry.split(":")
+        module = import_module(module_name)
+        func = getattr(module, func_name)
+        result = func(host=host, port=port)
+        if inspect.isawaitable(result):
+            await result
+        elif callable(result):  # pragma: no cover - defensive
+            maybe = result()
+            if inspect.isawaitable(maybe):
+                await maybe

cancan_microstack/core/stack_manager.py

@@ -0,0 +1,186 @@
+"""Stack lifecycle manager.
+
+提供“整栈 up/down/status”的统一入口：
+- controllersrv 在宿主机后台运行（daemon + pidfile）
+- 其他服务通过 docker/podman compose 运行
+
+Provide a unified stack lifecycle entry:
+- controllersrv runs on host as a background daemon (pidfile-managed)
+- other services run via docker/podman compose
+"""
+import time
+import urllib.request
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+from ..runtime.compose_cmd import run_compose_streaming
+from ..runtime.host_daemon import default_daemon_paths
+from ..runtime.host_daemon import start_daemon
+from ..runtime.host_daemon import stop_daemon
+from .microstack import CancanMicrostack
+
+
+@dataclass(frozen=True)
+class StackOptions:
+    """整栈运行参数 / Stack runtime options."""
+
+    workspace: Path
+    service_file: Path | None
+    overrides: Sequence[Path]
+    output: Path | None
+    bootstrap: bool
+    engine: str | None
+
+    controllersrv_host: str
+    controllersrv_port: int
+    with_controllersrv: bool
+
+
+class StackManager:
+    """整栈生命周期管理 / Stack lifecycle manager."""
+
+    def get_controllersrv_daemon_paths(self, workspace: Path):
+        """Get default daemon paths for controllersrv.
+
+        获取 controllersrv 的默认 daemon 路径。
+        """
+
+        return default_daemon_paths(workspace, name="controllersrv")
+
+    def __init__(self, stack: CancanMicrostack | None = None) -> None:
+        self._stack = stack or CancanMicrostack()
+
+    def build(self, options: StackOptions) -> Path:
+        """生成 compose 文件 / Build compose file."""
+
+        if options.bootstrap:
+            # CLI 的 bootstrap 逻辑目前在 cli/main.py 中。
+            # Here we only build compose; bootstrap happens in CLI layer.
+            pass
+
+        return self._stack.build_compose(
+            workspace=options.workspace,
+            service_file=options.service_file,
+            overrides=options.overrides,
+            output=options.output,
+        )
+
+    def start_controllersrv(self, options: StackOptions) -> int:
+        """后台启动 controllersrv / Start controllersrv as host daemon."""
+
+        paths = default_daemon_paths(options.workspace, name="controllersrv")
+
+        argv = [
+            sys.executable,
+            "-m",
+            "cancan_microstack.cli",
+            "services",
+            "run",
+            "controllersrv",
+            "--host",
+            options.controllersrv_host,
+            "--port",
+            str(options.controllersrv_port),
+            "--workspace",
+            str(options.workspace),
+        ]
+
+        env = {}
+        if options.engine:
+            # Propagate engine preference into controllersrv (Dragonfly auto-detect is Docker-first).
+            # 将引擎偏好传给 controllersrv（Dragonfly 的 auto-detect 是 Docker-first）。
+            env["CANCAN_CONTAINER_ENGINE"] = options.engine
+
+        return start_daemon(argv=argv, workspace=options.workspace, paths=paths, env=env)
+
+    def wait_controllersrv_ready(
+        self,
+        *,
+        host: str,
+        port: int,
+        timeout_seconds: float = 8.0,
+    ) -> bool:
+        """Wait until controllersrv internal health is reachable.
+
+        等待 controllersrv 的 /internal/health 可访问。
+        """
+
+        url = f"http://{host}:{port}/internal/health"
+        deadline = time.time() + timeout_seconds
+        last_error: Exception | None = None
+        while time.time() < deadline:
+            try:
+                with urllib.request.urlopen(url, timeout=1.0) as resp:
+                    if 200 <= resp.status < 300:
+                        return True
+            except Exception as exc:
+                last_error = exc
+            time.sleep(0.2)
+
+        _ = last_error
+        return False
+
+    def stop_controllersrv(self, workspace: Path) -> bool:
+        """停止 controllersrv daemon / Stop controllersrv daemon."""
+
+        paths = default_daemon_paths(workspace, name="controllersrv")
+        return stop_daemon(paths=paths)
+
+    def compose_up(
+        self,
+        *,
+        workspace: Path,
+        compose_file: Path,
+        engine: str | None = None,
+        build: bool = False,
+    ) -> None:
+        """启动容器栈 / Bring up container stack."""
+
+        log_file = workspace / "server_log_data" / "stack" / "compose.up.log"
+        args = ["up", "-d"]
+        if build:
+            args.append("--build")
+        run_compose_streaming(
+            compose_file=compose_file,
+            args=args,
+            workspace=workspace,
+            engine=engine,
+            log_file=log_file,
+        )
+
+    def compose_down(
+        self,
+        *,
+        workspace: Path,
+        compose_file: Path,
+        engine: str | None = None,
+        remove_volumes: bool = False,
+    ) -> None:
+        """关闭容器栈 / Bring down container stack."""
+
+        args = ["down"]
+        if remove_volumes:
+            args.append("--volumes")
+
+        log_file = workspace / "server_log_data" / "stack" / "compose.down.log"
+        run_compose_streaming(
+            compose_file=compose_file,
+            args=args,
+            workspace=workspace,
+            engine=engine,
+            log_file=log_file,
+        )
+
+    def compose_ps(self, *, workspace: Path, compose_file: Path, engine: str | None = None) -> None:
+        """查看 compose 状态 / Show compose status."""
+
+        log_file = workspace / "server_log_data" / "stack" / "compose.ps.log"
+        run_compose_streaming(
+            compose_file=compose_file,
+            args=["ps"],
+            workspace=workspace,
+            engine=engine,
+            log_file=log_file,
+        )

cancan_microstack/public/__init__.py

@@ -0,0 +1,7 @@
+"""Cancan Microstack public helpers.
+
+该包封装了 const/logging/web/schema 等公共能力，供 controllersrv / infrasrv /
+opsbffsrv 以及业务服务共享使用。
+This package bundles shared public modules (const, logging, web, schemas) for
+controllersrv / infrasrv / opsbffsrv and any business service consuming Cancan.
+"""

cancan_microstack/public/api/__init__.py

@@ -0,0 +1 @@
+"""Core API clients for Cancan Microstack services."""

cancan_microstack/public/api/controllersrv_client.py

@@ -0,0 +1,277 @@
+"""
+controllersrv API 客户端 / controllersrv API client
+"""
+import http
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+    Sequence,
+    Tuple,
+    Type,
+    Union,
+    cast,
+)
+
+from pydantic import (
+    BaseModel,
+    ValidationError,
+)
+
+from linglong_web.utils import logger
+from linglong_web import (
+    http_client,
+    HTTPClientConfig,
+)
+from cancan_microstack.public.schemas.common import (
+    APIError,
+    APIResponse,
+)
+from cancan_microstack.public.schemas.controllersrv.responses import (
+    EnqueueSuccessResponse,
+    EnqueueErrorResponse,
+    TaskListResponse,
+    TaskStatusResponse,
+)
+from cancan_microstack.public.schemas.controllersrv.validation import ValidationResult
+
+ServiceOperationResponse = Union[
+    EnqueueSuccessResponse,
+    EnqueueErrorResponse,
+    ValidationResult,
+]
+
+
+class ControllerSrvApiClient:
+    """
+    用于与 controllersrv 通信的基础客户端 / TableBase client for communicating with controllersrv
+    
+    提供通用的 HTTP 调用与响应解析逻辑，具体业务端可在子类中扩展
+    Provides generic HTTP invocation and response parsing logic for subclasses to extend
+    """
+
+    SERVICE_OPERATION_MODELS: Tuple[Type[BaseModel], ...] = (
+        EnqueueSuccessResponse,
+        EnqueueErrorResponse,
+        ValidationResult,
+    )
+    TASK_STATUS_MODELS: Tuple[Type[BaseModel], ...] = (TaskStatusResponse,)
+    TASK_LIST_MODELS: Tuple[Type[BaseModel], ...] = (TaskListResponse,)
+
+    def __init__(self, base_url: str):
+        """
+        初始化 API 客户端 / Initialise API client
+        
+        Args:
+            base_url: controllersrv 的基础 URL / TableBase URL of controllersrv
+        """
+
+        self.base_url = base_url
+        logger.info(f"ControllerSrvApiClient initialized with base_url: {self.base_url}")
+
+    async def _make_request(
+            self,
+            method: http.HTTPMethod,
+            endpoint: str,
+            json_data: Optional[Dict[str, Any]] = None,
+            params: Optional[Dict[str, Any]] = None,
+            response_models: Sequence[Type[BaseModel]] = (),
+    ) -> APIResponse[Optional[BaseModel]]:
+        """
+        通用请求方法 / Generic request executor
+        
+        Args:
+            method: HTTP 方法枚举 / HTTP method enum
+            endpoint: API 路径 / API path
+            json_data: 请求体（POST 使用）/ Request payload for POST
+            params: 查询参数（GET 使用）/ Query parameters for GET
+            response_models: 可用于解析 data 字段的模型列表
+                               Models used to deserialize the data payload
+        """
+
+        url = f"{self.base_url}{endpoint}"
+        try:
+            http_callable = getattr(http_client, method.value.lower())
+            response = await http_callable(
+                url=url,
+                params=params,
+                json=json_data,
+                timeout=HTTPClientConfig.INTERNAL_SERVICE_TIMEOUT,
+            )
+        except Exception as exc:
+            logger.error(f"Error calling controllersrv API [{endpoint}]: {exc}", exc_info=True)
+            return APIResponse(success=False, error=APIError(code="HTTP_EXCEPTION", msg=str(exc)))
+
+        if response is None:
+            logger.error(f"Failed to call controllersrv API [{endpoint}]: no response object")
+            return APIResponse(success=False, error=APIError(code="HTTP_NO_RESPONSE", msg="No response received"))
+
+        if response.status != 200:
+            error_message = f"HTTP error: {response.status}"
+            logger.error(f"controllersrv API [{endpoint}] returned non-200 status: {response.status}")
+            return APIResponse(success=False, error=APIError(code=str(response.status), msg=error_message))
+
+        try:
+            payload = await response.json()
+        except Exception as exc:
+            logger.error(f"Failed to parse controllersrv response JSON for [{endpoint}]: {exc}", exc_info=True)
+            return APIResponse(success=False, error=APIError(code="JSON_DECODE_ERROR", msg=str(exc)))
+
+        if not isinstance(payload, dict):
+            logger.error(f"Unexpected controllersrv response format for [{endpoint}]: {payload}")
+            return APIResponse(success=False, error=APIError(code="INVALID_PAYLOAD", msg="Response is not a dict"))
+
+        success = bool(payload.get("success"))
+        error_content = payload.get("error") or {}
+        api_error = self._create_api_error(error_content)
+        raw_data = payload.get("data")
+        parsed_data = self._parse_response_data(raw_data, response_models, endpoint)
+
+        if parsed_data is None and raw_data is not None and response_models:
+            logger.error(
+                "Failed to parse controllersrv response data for [%s]: %s",
+                endpoint,
+                raw_data,
+            )
+
+        logger.debug(
+            "controllersrv API [%s] completed: success=%s, code=%s",
+            endpoint,
+            success,
+            api_error.code,
+        )
+
+        return APIResponse(success=success, error=api_error, data=parsed_data)
+
+    @staticmethod
+    def _create_api_error(error_content: Any) -> APIError:
+        """构造 APIError 对象 / Build APIError object"""
+
+        if isinstance(error_content, dict):
+            code = str(error_content.get("code", "50000"))
+            msg = str(error_content.get("msg", ""))
+        else:
+            code = "50000"
+            msg = str(error_content) if error_content is not None else ""
+        return APIError(code=code, msg=msg)
+
+    def _parse_response_data(
+            self,
+            data: Any,
+            response_models: Sequence[Type[BaseModel]],
+            endpoint: str,
+    ) -> Optional[BaseModel]:
+        """
+        将 data 字段反序列化为 Pydantic 模型 / Deserialize data payload into Pydantic model
+        """
+
+        if data is None or not response_models:
+            return None
+
+        if not isinstance(data, (dict, list)):
+            logger.error(f"controllersrv API [{endpoint}] returned non-serialisable data: {data}")
+            return None
+
+        for model in response_models:
+            try:
+                if isinstance(data, model):
+                    return data
+                return model.model_validate(data)
+            except ValidationError:
+                continue
+
+        return None
+
+    async def restart_services(
+            self,
+            service_names: List[str],
+            serial_number: str,
+    ) -> APIResponse[Optional[ServiceOperationResponse]]:
+        """
+        调用 controllersrv 重启服务 / Call controllersrv to restart services
+        """
+
+        payload = {"service_names": service_names, "serial_number": serial_number}
+        response = await self._make_request(
+            http.HTTPMethod.POST,
+            "/service/restart",
+            json_data=payload,
+            response_models=self.SERVICE_OPERATION_MODELS,
+        )
+        return cast(APIResponse[Optional[ServiceOperationResponse]], response)
+
+    async def start_services(
+            self,
+            service_names: List[str],
+            serial_number: str,
+    ) -> APIResponse[Optional[ServiceOperationResponse]]:
+        """
+        调用 controllersrv 启动服务 / Call controllersrv to start services
+        """
+
+        payload = {"service_names": service_names, "serial_number": serial_number}
+        response = await self._make_request(
+            http.HTTPMethod.POST,
+            "/service/start",
+            json_data=payload,
+            response_models=self.SERVICE_OPERATION_MODELS,
+        )
+        return cast(APIResponse[Optional[ServiceOperationResponse]], response)
+
+    async def stop_services(
+            self,
+            service_names: List[str],
+            serial_number: str,
+    ) -> APIResponse[Optional[ServiceOperationResponse]]:
+        """
+        调用 controllersrv 停止服务 / Call controllersrv to stop services
+        """
+        logger.info(f"Stopping services: {service_names} with serial number: {serial_number}")
+        payload = {"service_names": service_names, "serial_number": serial_number}
+        response = await self._make_request(
+            http.HTTPMethod.POST,
+            "/service/stop",
+            json_data=payload,
+            response_models=self.SERVICE_OPERATION_MODELS,
+        )
+        return cast(APIResponse[Optional[ServiceOperationResponse]], response)
+
+    async def get_operation_status(
+            self,
+            serial_number: str,
+    ) -> APIResponse[Optional[TaskStatusResponse]]:
+        """
+        查询异步操作状态 / Query asynchronous operation status
+        """
+
+        response = await self._make_request(
+            http.HTTPMethod.GET,
+            "/task/status",
+            params={"serial_number": serial_number},
+            response_models=self.TASK_STATUS_MODELS,
+        )
+        return cast(APIResponse[Optional[TaskStatusResponse]], response)
+
+    async def list_operations(
+            self,
+            status: Optional[str] = None,
+            limit: int = 100,
+    ) -> APIResponse[Optional[TaskListResponse]]:
+        """
+        列出异步操作 / List asynchronous operations
+        """
+
+        params: Dict[str, Any] = {}
+        if status:
+            params["status"] = status
+        if limit:
+            params["limit"] = limit
+
+        response = await self._make_request(
+            http.HTTPMethod.GET,
+            "/task/list",
+            params=params,
+            response_models=self.TASK_LIST_MODELS,
+        )
+        return cast(APIResponse[Optional[TaskListResponse]], response)