cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/cmd/infrasrv/run.py

@@ -0,0 +1,100 @@
+"""infrasrv startup entrypoint.
+
+用于容器内启动 infrasrv 服务（被 cmd/infrasrv/run.py 包装器调用）。
+Start infrasrv inside container (called by workspace cmd wrapper).
+"""
+
+import asyncio
+
+from linglong_web import ServerRouter
+from linglong_web.utils import logger
+
+from cancan_microstack.public.web.server import AppServer
+from cancan_microstack.services.infrasrv.application.logging.log_ingestion_service import get_log_ingestion_service
+from cancan_microstack.services.infrasrv.application.workflow.workflow_tasks import register_workflow_tasks
+from cancan_microstack.services.infrasrv.application.workflow.workflow_worker_runtime import (
+    start_inline_worker,
+    stop_inline_worker,
+)
+from cancan_microstack.services.infrasrv.conf.config import service_conf_dict
+from cancan_microstack.services.infrasrv.domain.hooks import get_hook_manager
+from cancan_microstack.services.infrasrv.domain.hooks.builtin_hooks import register_default_hooks
+from cancan_microstack.services.infrasrv.infrastructure.ddl_manager import init_ddl
+from cancan_microstack.services.infrasrv.interface.schedule.scheduler import scheduler_group
+from cancan_microstack.services.infrasrv.router import router_list
+
+
+async def initialize_infrasrv() -> None:
+    """infrasrv 的启动回调函数 / Startup callback for infrasrv."""
+
+    # DDL 自管理：检查并创建 infra 表
+    # DDL auto-init: check and create infra tables
+    logger.info("Checking and initializing infra tables...")
+    ddl_success = await init_ddl()
+    if not ddl_success:
+        logger.warning("DDL initialization failed, but continuing to start service...")
+
+    # 初始化预注册钩子
+    # Initialize pre-registration hooks
+    logger.info("Initializing pre-registration hooks...")
+    hook_manager = get_hook_manager()
+    register_default_hooks(hook_manager)
+    logger.info(f"Registered {len(hook_manager.get_hooks('pre_register'))} pre-registration hooks")
+
+
+async def register_workflow_tasks_on_startup() -> None:
+    """在服务启动阶段注册所有工作流任务 / Register workflow tasks during startup."""
+
+    register_workflow_tasks()
+    start_inline_worker()
+
+
+async def start_log_ingestion() -> None:
+    """启动日志消费服务 / Start log ingestion service."""
+
+    log_ingestion_service = get_log_ingestion_service()
+    await log_ingestion_service.start()
+
+
+async def stop_inline_worker_on_shutdown() -> None:
+    """停止内嵌 worker，确保 infrasrv 退出前清理资源 / Stop inline worker on shutdown."""
+
+    stop_inline_worker()
+
+
+async def stop_log_ingestion() -> None:
+    """停止日志消费服务 / Stop log ingestion service."""
+
+    log_ingestion_service = get_log_ingestion_service()
+    await log_ingestion_service.shutdown()
+
+
+async def main(host: str = "0.0.0.0", port: int = 8080) -> None:
+    """启动 infrasrv / Start infrasrv."""
+
+    router_factory = ServerRouter()
+    router_factory.initialize(router_list)
+
+    app = AppServer()
+
+    await app.initialize(
+        service_name="infrasrv",
+        router=router_factory.get_router(),
+        config_dict=service_conf_dict,
+        scheduler_group=scheduler_group,
+        on_startup=[
+            initialize_infrasrv,
+            start_log_ingestion,
+            register_workflow_tasks_on_startup,
+        ],
+        on_shutdown=[
+            stop_log_ingestion,
+            stop_inline_worker_on_shutdown,
+        ],
+    )
+
+    await app.start(host=host, port=port)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

cancan_microstack/cmd/opsbffsrv/__init__.py

@@ -0,0 +1,5 @@
+"""opsbffsrv entrypoints.
+
+该模块用于容器内启动 opsbffsrv 服务。
+Entry points for starting opsbffsrv inside containers.
+"""

cancan_microstack/cmd/opsbffsrv/run.py

@@ -0,0 +1,96 @@
+"""opsbffsrv startup entrypoint.
+
+用于容器内启动 opsbffsrv 服务（被 cmd/opsbffsrv/run.py 包装器调用）。
+Start opsbffsrv inside container (called by workspace cmd wrapper).
+"""
+
+import asyncio
+
+from linglong_web import ServerRouter
+from linglong_web.utils import logger
+
+from cancan_microstack.public.web.server import AppServer
+from cancan_microstack.services.opsbffsrv.application.caddy.access_log_ingestion_service import (
+    get_caddy_access_log_ingestion_service,
+)
+from cancan_microstack.services.opsbffsrv.application.caddy.route_management_app import RouteManagementApp
+from cancan_microstack.services.opsbffsrv.conf.config import service_conf_dict, validate_auth_config
+from cancan_microstack.services.opsbffsrv.domain.auth.admin_init import ensure_admin_user
+from cancan_microstack.services.opsbffsrv.domain.caddy.default_routes import init_default_routes
+from cancan_microstack.services.opsbffsrv.infrastructure.ddl_manager import init_ddl
+from cancan_microstack.services.opsbffsrv.interface.middleware.auth_middleware import auth_middleware
+from cancan_microstack.services.opsbffsrv.router import router_list
+
+
+async def initialize_opsbffsrv() -> None:
+    """opsbffsrv 的启动回调函数 / Startup callback for opsbffsrv."""
+
+    # 认证关键配置 fail-fast 校验（生产缺 Fernet key 直接拒绝启动）。
+    # Fail-fast validation of auth-critical config (refuse to start in prod without Fernet key).
+    validate_auth_config()
+
+    # DDL 自管理：检查并创建 ops 表
+    # DDL auto-init: check and create ops tables
+    logger.info("Checking and initializing ops tables...")
+    ddl_success = await init_ddl()
+    if not ddl_success:
+        logger.warning("DDL initialization failed, but continuing to start service...")
+
+    # 初始化 admin 用户
+    # Initialize admin user
+    logger.info("Checking and initializing admin user...")
+    await ensure_admin_user()
+
+    # 初始化默认路由
+    # Initialize default routes
+    await init_default_routes()
+
+    # 同步路由到 Caddy
+    # Sync routes to Caddy on startup
+    logger.info("Syncing routes to Caddy on startup...")
+    route_app = RouteManagementApp()
+    sync_result = await route_app.sync_all_routes()
+    if sync_result.get("status") != "success":
+        # Caddy may be intentionally not started in some dev flows.
+        # Some environments start opsbffsrv before caddy, so treat this as non-fatal.
+        logger.warning("Sync routes to Caddy on startup skipped/failed: %s", sync_result)
+    else:
+        logger.info("Routes synced to Caddy successfully.")
+
+    # 启动 Caddy 访问日志采集服务
+    # Start Caddy access log ingestion service
+    ingestion_service = get_caddy_access_log_ingestion_service()
+    await ingestion_service.start()
+
+
+async def shutdown_opsbffsrv() -> None:
+    """opsbffsrv 的关闭回调函数 / Shutdown callback for opsbffsrv."""
+    ingestion_service = get_caddy_access_log_ingestion_service()
+    await ingestion_service.shutdown()
+
+
+async def main(host: str = "0.0.0.0", port: int = 8080) -> None:
+    """启动 opsbffsrv / Start opsbffsrv."""
+
+    router_factory = ServerRouter()
+    router_factory.initialize(router_list)
+
+    app = AppServer()
+
+    await app.initialize(
+        service_name="opsbffsrv",
+        router=router_factory.get_router(),
+        config_dict=service_conf_dict,
+        on_startup=[initialize_opsbffsrv],
+        on_shutdown=[shutdown_opsbffsrv],
+    )
+
+    # 注册认证中间件
+    # Register authentication middleware
+    app.app.middleware("http")(auth_middleware)
+
+    await app.start(host=host, port=port)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

cancan_microstack/core/__init__.py

@@ -0,0 +1,5 @@
+"""Internal helpers for Cancan Microstack."""
+from .assets import AssetManager, AssetRecord
+from .compose_builder import ComposeBuilder
+from .microstack import CancanMicrostack
+from .runner import ServiceRunner

cancan_microstack/core/assets.py

@@ -0,0 +1,123 @@
+"""Asset loading helpers for Cancan Microstack.
+
+资产加载与导出工具，确保包内资源可以安全复制到工作区后再被 Docker 使用。
+Asset loading/export helpers that materialize packaged resources into the caller's workspace
+so Docker (which only sees mounted paths) can read them.
+"""
+import shutil
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from typing import (
+    Iterable,
+    List,
+)
+
+
+@dataclass(frozen=True)
+class AssetRecord:
+    """描述存储在包中的静态资产 / Describe packaged static asset."""
+
+    logical_name: str
+    path: Path
+    is_dir: bool
+
+
+class AssetManager:
+    """资产管理：枚举、导出、解析包内静态文件。
+
+    Asset management facade to list, export, and resolve packaged static files.
+    """
+
+    def __init__(self, package: str = "cancan_microstack.assets") -> None:
+        self._package = package
+
+    def list_assets(self, subdir: str | None = None) -> List[AssetRecord]:
+        """列出可用资产（可选限定子目录）/ List available assets (optional subdir filter)."""
+
+        # 重要：不要用 resources.as_file(...) 的路径来反推 logical_name。
+        # 因为当资源来自 zip/轮子时，不同节点可能被物化到不同的临时目录，
+        # 这会导致 relative_to 失败，从而丢失前缀（例如返回 "infra" 而不是 "ddl/infra"）。
+        # Important: do NOT derive logical_name from as_file(...) paths.
+        # When packaged (zip/wheel), each node may be materialized into a different temp dir,
+        # making relative_to() fail and losing prefixes.
+        traversable = resources.files(self._package)
+        prefix = ""
+        if subdir:
+            prefix = "/".join(self._split(subdir))
+            traversable = traversable.joinpath(*self._split(subdir))
+        records: List[AssetRecord] = []
+
+        def _walk(node, current_prefix: str) -> None:
+            for child in node.iterdir():
+                if child.name.startswith("__pycache__") or child.name == ".DS_Store":
+                    continue
+                logical_name = f"{current_prefix}/{child.name}" if current_prefix else child.name
+                with resources.as_file(child) as located:
+                    path = Path(located)
+                    records.append(
+                        AssetRecord(
+                            logical_name=logical_name,
+                            path=path,
+                            is_dir=path.is_dir(),
+                        )
+                    )
+                    if child.is_dir():
+                        _walk(child, logical_name)
+
+        _walk(traversable, prefix)
+        return records
+
+    def export_asset(self, logical_name: str, destination: Path, overwrite: bool = False) -> Path:
+        """导出资产到工作区路径；目录用 copytree，文件用 copy2。
+
+        Export asset into a workspace path so Docker can see it via bind/volume mounts.
+        Directories use ``shutil.copytree``; files use ``shutil.copy2``.
+        """
+
+        traversable = resources.files(self._package).joinpath(*self._split(logical_name))
+        if not traversable.exists():  # pragma: no cover - defensive guard
+            raise FileNotFoundError(f"Asset '{logical_name}' not found")
+
+        with resources.as_file(traversable) as asset_path:
+            resolved = Path(asset_path)
+            if resolved.is_dir():
+                if destination.exists():
+                    if not overwrite:
+                        raise FileExistsError(destination)
+                    shutil.rmtree(destination)
+                shutil.copytree(resolved, destination)
+            else:
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                if destination.exists() and not overwrite:
+                    raise FileExistsError(destination)
+                shutil.copy2(resolved, destination)
+        return destination
+
+    def read_text(self, logical_name: str) -> str:
+        """读取资产文本 / Read text content from asset."""
+
+        traversable = resources.files(self._package).joinpath(*self._split(logical_name))
+        return traversable.read_text(encoding="utf-8")
+
+    def resolve_path(self, logical_name: str) -> Path:
+        """将资产实体化为可访问的文件路径 / Materialize and return a filesystem path."""
+
+        traversable = resources.files(self._package).joinpath(*self._split(logical_name))
+        if not traversable.exists():
+            raise FileNotFoundError(logical_name)
+        with resources.as_file(traversable) as asset_path:
+            return Path(asset_path)
+
+    def _split(self, logical_name: str) -> Iterable[str]:
+        return [segment for segment in logical_name.split('/') if segment]
+
+    def _logical_name(self, path: Path) -> str:
+        base = resources.files(self._package)
+        with resources.as_file(base) as root_path:
+            root = Path(root_path)
+            try:
+                rel = path.relative_to(root)
+            except ValueError:  # pragma: no cover - fallback for zipped resources
+                return path.name
+            return str(rel)

cancan_microstack/core/compose_builder.py

@@ -0,0 +1,102 @@
+"""Compose stack builder merging infra assets with service overlays.
+
+把内置 infra compose 与业务/覆盖文件进行深度合并，生成最终可运行的栈。
+Deep-merge infra compose with service/override files to produce a runnable stack.
+"""
+import copy
+from pathlib import Path
+from typing import (
+    Any,
+    Dict,
+    Iterable,
+    Sequence,
+)
+
+import yaml
+
+from .assets import AssetManager
+
+
+class ComposeBuilder:
+    """合并内置 infra compose 与工作区覆盖层 / Merge infra compose with workspace overlays."""
+
+    def __init__(self, asset_manager: AssetManager | None = None,
+                 base_asset: str = "docker/docker-compose.infra.yml") -> None:
+        self.asset_manager = asset_manager or AssetManager()
+        self.base_asset = base_asset
+
+    def build(
+            self,
+            *,
+            workspace: Path,
+            service_file: Path | None = None,
+            overrides: Sequence[Path] | None = None,
+            output_file: Path | None = None,
+    ) -> Path:
+        """生成合并后的 docker compose 文件 / Generate merged docker compose file."""
+
+        workspace = workspace.expanduser().resolve()
+        output_path = (output_file or workspace / "compose.cancan.yml").resolve()
+        overrides = overrides or []
+
+        base_model = self._load_asset_yaml(self.base_asset)
+        merged = base_model
+        if service_file and service_file.exists():
+            merged = self._deep_merge(merged, self._load_yaml(service_file))
+
+        for override in overrides:
+            if override.exists():
+                merged = self._deep_merge(merged, self._load_yaml(override))
+
+        # Docker Compose V2 ignores the deprecated `version` field and warns.
+        # Docker Compose V2 会忽略已弃用的 `version` 字段并产生警告，因此统一移除。
+        merged.pop("version", None)
+
+        # Avoid network name collisions with pre-existing networks that were not created by Compose.
+        # If a network is not marked as external, letting Compose generate a project-scoped name is safer.
+        # 避免与历史遗留网络（非 compose 创建，缺少 label）发生冲突。
+        # 若网络不是 external，则移除固定 name，让 compose 自动生成项目级网络名。
+        networks = merged.get("networks")
+        if isinstance(networks, dict):
+            for _, net_cfg in networks.items():
+                if isinstance(net_cfg, dict) and not net_cfg.get("external"):
+                    net_cfg.pop("name", None)
+
+        # When a service has a build definition, prefer local build and do not pull the image.
+        # 对于带 build 的服务，默认使用本地构建，避免先去 pull 同名镜像。
+        services = merged.get("services")
+        if isinstance(services, dict):
+            for _, svc_cfg in services.items():
+                if isinstance(svc_cfg, dict) and "build" in svc_cfg:
+                    svc_cfg.setdefault("pull_policy", "never")
+
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with output_path.open("w", encoding="utf-8") as fp:
+            yaml.safe_dump(merged, fp, sort_keys=False)
+        return output_path
+
+    def _load_yaml(self, path: Path) -> Dict[str, Any]:
+        with path.open("r", encoding="utf-8") as fp:
+            data = yaml.safe_load(fp) or {}
+        if not isinstance(data, dict):  # pragma: no cover - defensive
+            raise ValueError(f"Compose file must be a mapping: {path}")
+        return data
+
+    def _load_asset_yaml(self, logical_name: str) -> Dict[str, Any]:
+        asset_path = self.asset_manager.resolve_path(logical_name)
+        return self._load_yaml(asset_path)
+
+    def _deep_merge(self, base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+        result = copy.deepcopy(base)
+        for key, value in override.items():
+            if key not in result:
+                result[key] = copy.deepcopy(value)
+                continue
+            if isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = self._deep_merge(result[key], value)
+            else:
+                result[key] = copy.deepcopy(value)
+        return result
+
+    def collect_override_paths(self, raw_values: Iterable[str]) -> Sequence[Path]:
+        return [Path(item).expanduser().resolve() for item in raw_values]

cancan_microstack/core/doctor.py

@@ -0,0 +1,152 @@
+"""`cancan doctor` — pre-flight environment & configuration checks.
+
+在 `cancan stack up` 之前一次性诊断常见的"起不来"原因：容器引擎、端口占用、
+工作区识别、运行时资产是否就绪、生产弱默认值。
+
+Diagnose the common "stack won't come up" causes before `cancan stack up`:
+container engine, port conflicts, workspace detection, bootstrapped runtime
+assets, and weak production defaults. Stdlib-only.
+"""
+from __future__ import annotations
+
+import socket
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..runtime.compose_cmd import detect_compose_command
+from ..runtime.workspace import detect_workspace_root
+
+OK = "ok"
+WARN = "warn"
+FAIL = "fail"
+
+_GLYPH = {OK: "✓", WARN: "!", FAIL: "✗"}
+
+# Host-published ports declared in the bundled infra compose.
+_HOST_PORTS = {
+    8080: "caddy (local dev gateway)",
+    22100: "controllersrv (host daemon)",
+    25432: "postgres",
+    26379: "redis",
+    27017: "mongo",
+    35672: "rabbitmq amqp",
+    35673: "rabbitmq management",
+}
+
+# Weak local-dev defaults that must not survive into production.
+_WEAK_DEFAULTS = {
+    "POSTGRES_PASSWORD": "postgres123",
+    "RABBITMQ_PASSWORD": "admin123",
+    "MONGO_INITDB_ROOT_PASSWORD": "admin123",
+    "MONGO_EXPRESS_PASSWORD": "admin123",
+    "RABBITMQ_MGMT_PASSWORD": "admin123",
+}
+
+
+@dataclass
+class Check:
+    status: str
+    title: str
+    detail: str = ""
+
+
+def _port_in_use(port: int, host: str = "127.0.0.1") -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(0.3)
+        return sock.connect_ex((host, port)) == 0
+
+
+def _parse_env_file(path: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    try:
+        for raw in path.read_text(encoding="utf-8").splitlines():
+            line = raw.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, _, v = line.partition("=")
+            values[k.strip()] = v.strip()
+    except OSError:
+        pass
+    return values
+
+
+def collect_checks(workspace: Path) -> list[Check]:
+    checks: list[Check] = []
+
+    # 1) container engine + daemon
+    try:
+        cmd = detect_compose_command()
+        checks.append(Check(OK, "Container engine", " ".join(cmd.argv_prefix)))
+    except Exception as exc:
+        checks.append(Check(FAIL, "Container engine", f"no usable docker/podman compose: {exc}"))
+
+    # 2) host port availability
+    busy = [f"{p} ({_HOST_PORTS[p]})" for p in sorted(_HOST_PORTS) if _port_in_use(p)]
+    if busy:
+        checks.append(Check(WARN, "Host ports", "in use (a previous stack? other apps?): " + ", ".join(busy)))
+    else:
+        checks.append(Check(OK, "Host ports", "all stack ports free"))
+
+    # 3) workspace detection
+    try:
+        root = detect_workspace_root(start=workspace)
+        checks.append(Check(OK, "Workspace root", str(root)))
+    except Exception:
+        checks.append(Check(WARN, "Workspace root", f"no workspace marker found under {workspace}; run `cancan init`"))
+
+    # 4) bootstrapped runtime assets
+    expected = {
+        ".env": workspace / ".env",
+        "ddl/create_db.sql": workspace / "ddl" / "create_db.sql",
+        "builds/caddy": workspace / "builds" / "caddy",
+        "builds/service/Dockerfile": workspace / "builds" / "service" / "Dockerfile",
+    }
+    missing = [name for name, p in expected.items() if not p.exists()]
+    if missing:
+        checks.append(Check(WARN, "Runtime assets", "missing (run `cancan stack up --bootstrap` or `cancan init`): " + ", ".join(missing)))
+    else:
+        checks.append(Check(OK, "Runtime assets", "bootstrapped"))
+
+    # 5) weak defaults / required secrets in .env
+    env_path = workspace / ".env"
+    if env_path.exists():
+        env = _parse_env_file(env_path)
+        weak = [k for k, default in _WEAK_DEFAULTS.items() if env.get(k, default) == default]
+        if not env.get("AUTH_TOTP_FERNET_KEY"):
+            checks.append(Check(FAIL, "AUTH_TOTP_FERNET_KEY", "empty in .env — opsbffsrv will refuse to start in prod mode"))
+        else:
+            checks.append(Check(OK, "AUTH_TOTP_FERNET_KEY", "set"))
+        if weak:
+            checks.append(Check(WARN, "Weak default secrets", "still default (CHANGE FOR PRODUCTION): " + ", ".join(weak)))
+        else:
+            checks.append(Check(OK, "Secrets", "no known weak defaults in .env"))
+    else:
+        checks.append(Check(WARN, "Config (.env)", "not found; `cancan init` / `stack up --bootstrap` will create it"))
+
+    return checks
+
+
+def run_doctor(workspace: Path) -> int:
+    """运行诊断并打印结果，返回退出码（有 FAIL=2，仅 WARN=0）。
+    Run checks, print a report, return an exit code (FAIL → 2, otherwise 0).
+    """
+
+    checks = collect_checks(workspace)
+    print("cancan doctor — environment check\n")
+    for c in checks:
+        line = f"  [{_GLYPH[c.status]}] {c.title}"
+        if c.detail:
+            line += f": {c.detail}"
+        print(line)
+
+    fails = sum(1 for c in checks if c.status == FAIL)
+    warns = sum(1 for c in checks if c.status == WARN)
+    print()
+    if fails:
+        print(f"✗ {fails} blocking issue(s), {warns} warning(s). Fix the ✗ items before `cancan stack up`.")
+        return 2
+    if warns:
+        print(f"! {warns} warning(s). The stack can start, but review the ! items (especially before production).")
+        return 0
+    print("✓ All checks passed.")
+    return 0

cancan_microstack/core/microstack.py

@@ -0,0 +1,71 @@
+"""High level orchestration helpers."""
+from pathlib import Path
+from typing import Sequence
+
+from .assets import AssetManager
+from .compose_builder import ComposeBuilder
+from .runner import ServiceRunner
+
+
+class CancanMicrostack:
+    """Convenience facade bundling assets, compose builder, and service runner."""
+
+    def __init__(self) -> None:
+        self.assets = AssetManager()
+        self.compose_builder = ComposeBuilder(self.assets)
+        self.runner = ServiceRunner()
+
+    def build_compose(
+            self,
+            *,
+            workspace: Path,
+            service_file: Path | None = None,
+            overrides: Sequence[Path] | None = None,
+            output: Path | None = None,
+    ) -> Path:
+        self._log(
+            "Building Cancan compose file",
+            workspace=workspace,
+            service_file=service_file,
+            overrides=overrides,
+            output=output,
+        )
+        return self.compose_builder.build(
+            workspace=workspace,
+            service_file=service_file,
+            overrides=overrides,
+            output_file=output,
+        )
+
+    def export_asset(self, logical_name: str, destination: Path, overwrite: bool = False) -> Path:
+        self._log("Exporting asset", logical_name=logical_name, destination=destination)
+        return self.assets.export_asset(logical_name, destination, overwrite)
+
+    def run_service(
+            self,
+            service_name: str,
+            host: str = "0.0.0.0",
+            port: int = 8080,
+            workspace: Path | None = None,
+    ) -> None:
+        self._log(
+            "Starting managed service",
+            service=service_name,
+            host=host,
+            port=port,
+            workspace=workspace,
+        )
+        self.runner.run(service_name, host=host, port=port, workspace=workspace)
+
+    async def run_service_async(
+            self,
+            service_name: str,
+            host: str = "0.0.0.0",
+            port: int = 8080,
+            workspace: Path | None = None,
+    ) -> None:
+        await self.runner.run_async(service_name, host=host, port=port, workspace=workspace)
+
+    def _log(self, message: str, **fields) -> None:
+        extras = " ".join(f"{k}={v}" for k, v in fields.items() if v is not None)
+        print(f"[cancan] {message} {extras}".strip())