standkit 0.3.7__py3-none-any.whl

standkit_hub/agent_control.py

@@ -0,0 +1,216 @@
+"""
+Запуск/остановка ЛОКАЛЬНОГО ``standkit_agent`` как дочернего процесса из хаба
+(``standkit_hub/server.py`` — ``POST /api/agent/start``/``POST /api/agent/stop``).
+
+Логика спавна намеренно БЕЗ веб-слоя (чистые функции + один класс-контроллер
+поверх ``standkit.platform``), чтобы:
+  - её можно было тестировать без реального HTTP-сервера (см.
+    tests/test_hub_agent_control.py);
+  - агент по-прежнему запускался как самостоятельный процесс через
+    ``sys.executable -m standkit_agent`` (не импортом в тот же процесс хаба) —
+    падение агента не должно ронять диспетчер, и наоборот.
+
+Секреты (``token_ref``/``readonly_token_ref``) передаются агенту ТОЛЬКО как
+ссылки (``--token-ref``/``--readonly-token-ref``) — сам standkit_agent
+резолвит их через свой Secret-first контракт (standkit.secrets). Значения
+секретов через argv никогда не передаются.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from standkit.platform import ProcessError, is_alive, spawn_hidden, stop
+from standkit_hub.config import HubConfig
+
+_PID_FILE_NAME = "standkit-hub-agent.pid"
+_LOG_FILE_NAME = "standkit-hub-agent.log"
+
+
+class AgentControlError(Exception):
+    """Ошибка запуска/остановки локального агента (сообщение пригодно для показа пользователю)."""
+
+
+def build_agent_argv(config: HubConfig, *, python_executable: Optional[str] = None) -> list[str]:
+    """
+    Собирает argv команды запуска ``standkit_agent`` по полям ``HubConfig``.
+
+    Чистая функция без побочных эффектов — вся логика маппинга полей в флаги
+    вынесена сюда специально, чтобы её можно было проверить в тесте без
+    реального subprocess.Popen.
+    """
+    python_executable = python_executable or sys.executable
+    argv = [
+        python_executable,
+        "-m",
+        "standkit_agent",
+        "--host",
+        config.agent_host,
+        "--port",
+        str(config.agent_port),
+    ]
+
+    if config.registry_path:
+        argv += ["--registry", config.registry_path]
+
+    # token_ref обязателен для standkit_agent (required=True в его argparse) —
+    # но здесь мы не форсируем это молча: validate_agent_config() отдельно
+    # проверяет обязательность ДО спавна, чтобы дать понятную ошибку в хабе, а
+    # не "агент упал сразу после старта" без объяснений.
+    if config.token_ref:
+        argv += ["--token-ref", config.token_ref]
+    if config.readonly_token_ref:
+        argv += ["--readonly-token-ref", config.readonly_token_ref]
+
+    if config.run_dir:
+        argv += ["--run-dir", config.run_dir]
+    if config.log_dir:
+        argv += ["--log-dir", config.log_dir]
+    if config.audit_log:
+        argv += ["--audit-log", config.audit_log]
+
+    if config.tls_cert:
+        argv += ["--tls-cert", config.tls_cert]
+    if config.tls_key:
+        argv += ["--tls-key", config.tls_key]
+    if config.tls_client_ca:
+        argv += ["--tls-client-ca", config.tls_client_ca]
+
+    if config.insecure:
+        argv.append("--insecure")
+
+    argv += ["--lockout-max-failures", str(config.lockout_max_failures)]
+    argv += ["--lockout-window", str(config.lockout_window_sec)]
+
+    return argv
+
+
+def validate_agent_config(config: HubConfig) -> list[str]:
+    """
+    Возвращает список понятных проблем конфигурации ДО попытки запуска
+    (пустой список — можно запускать). Не бросает исключений — вызывающий
+    код (хаб) сам решает, как показать список пользователю.
+    """
+    problems: list[str] = []
+    if not config.token_ref:
+        problems.append(
+            "Не задана ссылка на control-токен агента (token_ref) — заполните её на "
+            "панели «Агент по умолчанию» и задайте сам секрет через редактор секретов."
+        )
+    if not config.registry_path:
+        problems.append("Не задан путь к реестру стендов (registry_path).")
+    return problems
+
+
+@dataclass
+class AgentStartResult:
+    pid: int
+    log_path: str
+
+
+class AgentController:
+    """
+    Управляет ОДНИМ локальным процессом ``standkit_agent``, запущенным из хаба.
+
+    pid запущенного процесса персистится в pid-файле (в ``run_dir`` конфига,
+    либо ``~/.standkit/run``), чтобы диспетчер мог обнаружить уже запущенный
+    им ранее процесс и после собственного перезапуска (не только в течение
+    жизни одного объекта Python).
+    """
+
+    def __init__(self, config: HubConfig):
+        self.config = config
+        self._pid: Optional[int] = None
+
+    # --- пути ---
+
+    def _run_dir(self) -> Path:
+        return Path(self.config.run_dir) if self.config.run_dir else Path.home() / ".standkit" / "run"
+
+    def _log_dir(self) -> Path:
+        return Path(self.config.log_dir) if self.config.log_dir else Path.home() / ".standkit" / "logs"
+
+    def _pid_file(self) -> Path:
+        return self._run_dir() / _PID_FILE_NAME
+
+    def _log_file(self) -> Path:
+        return self._log_dir() / _LOG_FILE_NAME
+
+    def _load_pid(self) -> Optional[int]:
+        if self._pid is not None:
+            return self._pid
+        pid_file = self._pid_file()
+        if not pid_file.exists():
+            return None
+        try:
+            self._pid = int(pid_file.read_text(encoding="utf-8").strip())
+        except (ValueError, OSError):
+            return None
+        return self._pid
+
+    # --- состояние ---
+
+    def is_running(self) -> bool:
+        """Проверяет, жив ли процесс агента, ранее запущенный этим контроллером (по pid-файлу)."""
+        pid = self._load_pid()
+        if pid is None:
+            return False
+        return is_alive(pid)
+
+    # --- управление ---
+
+    def start(self) -> AgentStartResult:
+        """
+        Запускает локальный агент. Бросает ``AgentControlError`` с понятным
+        текстом, если конфигурация невалидна (см. ``validate_agent_config``),
+        агент уже запущен, либо ОС отказала в спавне процесса — никогда не
+        роняет вызывающий код хаба исключением ОС "как есть".
+        """
+        problems = validate_agent_config(self.config)
+        if problems:
+            raise AgentControlError("; ".join(problems))
+        if self.is_running():
+            raise AgentControlError("Локальный агент уже запущен")
+
+        argv = build_agent_argv(self.config)
+        log_path = self._log_file()
+
+        try:
+            pid = spawn_hidden(argv, Path.cwd(), log_path)
+        except ProcessError as exc:
+            raise AgentControlError(f"Не удалось запустить локальный агент: {exc}") from exc
+
+        pid_file = self._pid_file()
+        pid_file.parent.mkdir(parents=True, exist_ok=True)
+        pid_file.write_text(str(pid), encoding="utf-8")
+        self._pid = pid
+
+        return AgentStartResult(pid=pid, log_path=str(log_path))
+
+    def stop(self, *, timeout: float = 10.0) -> bool:
+        """
+        Останавливает процесс агента (если он был запущен этим контроллером).
+        Возвращает True, если процесс на момент вызова считается остановленным
+        (в т.ч. если он и так уже не был жив).
+        """
+        pid = self._load_pid()
+        if pid is None:
+            return True
+
+        try:
+            stopped = stop(pid, timeout=timeout)
+        except ProcessError as exc:
+            raise AgentControlError(f"Не удалось остановить локальный агент: {exc}") from exc
+
+        pid_file = self._pid_file()
+        if pid_file.exists():
+            try:
+                pid_file.unlink()
+            except OSError:
+                pass
+        self._pid = None
+
+        return stopped

standkit_hub/client.py

@@ -0,0 +1,159 @@
+"""
+Федеративный клиент хаба: агрегирует стенды из локального ядра (transport=local)
+и с удалённых агентов (transport=agent, по HTTP) в единый список для отрисовки.
+
+Намеренно НЕ импортирует веб-слой хаба — это чистый сетевой/доменный слой,
+который можно тестировать и переиспользовать (например, из CLI) без
+``http.server``. Используется только stdlib (``urllib``) — как и
+standkit_agent.server, без сторонних HTTP-клиентов.
+
+TODO(следующая итерация):
+  - параллельный (не последовательный) опрос агентов — сейчас FederatedClient
+    ходит к агентам по очереди, что при N агентах и таймаутах масштабируется
+    плохо; кандидат — concurrent.futures.ThreadPoolExecutor;
+  - кэширование/дебаунс частых опросов (polling из хаба по таймеру);
+  - TLS/проверка сертификата агента (см. TODO в standkit_agent.server).
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Optional
+
+from standkit import health, lifecycle
+from standkit.models import StandStatus, Transport
+from standkit.registry import Registry
+from standkit.secrets import SecretError, get_secret
+
+
+@dataclass
+class RemoteCallError(Exception):
+    """Ошибка сетевого вызова к агенту (недоступен, таймаут, неверный токен и т.п.)."""
+
+    agent_url: str
+    detail: str
+
+    def __str__(self) -> str:  # pragma: no cover - тривиально
+        return f"Ошибка обращения к агенту {self.agent_url}: {self.detail}"
+
+
+def _agent_request(agent_url: str, path: str, token: str, *, method: str = "GET", timeout: float = 5.0) -> dict:
+    url = agent_url.rstrip("/") + path
+    req = urllib.request.Request(url, method=method)
+    req.add_header("Authorization", f"Bearer {token}")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        raise RemoteCallError(agent_url, f"HTTP {exc.code}") from exc
+    except (urllib.error.URLError, TimeoutError, OSError, ValueError) as exc:
+        raise RemoteCallError(agent_url, str(exc)) from exc
+
+
+class FederatedClient:
+    """
+    Единая точка входа для хаба: даёт список стендов реестра со статусами,
+    независимо от того, локальный стенд или он живёт за агентом.
+    """
+
+    def __init__(self, registry: Registry):
+        self.registry = registry
+
+    def list_stand_names(self) -> list[str]:
+        return self.registry.names()
+
+    def status(self, name: str) -> StandStatus:
+        """
+        Возвращает статус одного стенда, маршрутизируя запрос по ``transport``:
+        локально через standkit.health, либо по HTTP к соответствующему агенту.
+        """
+        stand = self.registry.get(name)
+
+        if stand.transport == Transport.LOCAL:
+            pf = lifecycle.pidfile_path(stand)
+            return health.check_stand(stand, pidfile=pf)
+
+        if stand.transport == Transport.AGENT:
+            if not stand.agent_url or not stand.agent_secret_ref:
+                raise RemoteCallError(stand.agent_url or "?", "не задан agent_url/agent_secret_ref")
+            token = get_secret(stand.agent_secret_ref)
+            data = _agent_request(stand.agent_url, f"/stand/{name}/status", token)
+            return StandStatus.from_dict(data)
+
+        raise NotImplementedError(
+            f"Транспорт {stand.transport.value!r} для стенда '{name}' пока не реализован (TODO)"
+        )
+
+    def status_all(self) -> dict[str, StandStatus]:
+        """
+        Опрашивает все стенды реестра. Ошибки отдельных стендов не прерывают
+        общий опрос — недоступный стенд получает StandStatus с UNKNOWN-пробами
+        и текстом ошибки в ``details``.
+
+        TODO: см. модульный TODO — сделать параллельным.
+        """
+        result: dict[str, StandStatus] = {}
+        for name in self.registry.names():
+            try:
+                result[name] = self.status(name)
+            except (RemoteCallError, SecretError, NotImplementedError) as exc:
+                result[name] = StandStatus(name=name, details={"error": str(exc)})
+        return result
+
+    def start(self, name: str) -> Optional[int]:
+        """Запускает стенд. Возвращает pid, если транспорт его предоставляет (см. ``_dispatch_action``)."""
+        return self._dispatch_action(name, "start")
+
+    def stop(self, name: str) -> Optional[bool]:
+        return self._dispatch_action(name, "stop")
+
+    def restart(self, name: str) -> Optional[int]:
+        """Перезапускает стенд. Возвращает pid, если транспорт его предоставляет."""
+        return self._dispatch_action(name, "restart")
+
+    def _dispatch_action(self, name: str, action: str):
+        """
+        Диспетчеризует start/stop/restart по транспорту и ПРОКИДЫВАЕТ результат
+        наверх (для "local" — то, что вернул ``standkit.lifecycle`` — pid для
+        start/restart, bool для stop; для "agent" — ``pid`` из JSON-ответа
+        агента, если есть), чтобы UI хаба мог показать pid успешного старта, а
+        не только голое "ok".
+        """
+        stand = self.registry.get(name)
+
+        if stand.transport == Transport.LOCAL:
+            fn = getattr(lifecycle, action)
+            return fn(stand)
+
+        if stand.transport == Transport.AGENT:
+            if not stand.agent_url or not stand.agent_secret_ref:
+                raise RemoteCallError(stand.agent_url or "?", "не задан agent_url/agent_secret_ref")
+            token = get_secret(stand.agent_secret_ref)
+            data = _agent_request(stand.agent_url, f"/stand/{name}/{action}", token, method="POST")
+            return data.get("pid") if isinstance(data, dict) else None
+
+        raise NotImplementedError(
+            f"Транспорт {stand.transport.value!r} для стенда '{name}' пока не реализован (TODO)"
+        )
+
+    def logs(self, name: str, n: int = 100) -> list[str]:
+        stand = self.registry.get(name)
+
+        if stand.transport == Transport.LOCAL:
+            from standkit import logs as _logs
+
+            return _logs.tail(lifecycle.log_path(stand), n)
+
+        if stand.transport == Transport.AGENT:
+            if not stand.agent_url or not stand.agent_secret_ref:
+                raise RemoteCallError(stand.agent_url or "?", "не задан agent_url/agent_secret_ref")
+            token = get_secret(stand.agent_secret_ref)
+            data = _agent_request(stand.agent_url, f"/stand/{name}/logs?n={n}", token)
+            return list(data.get("lines", []))
+
+        raise NotImplementedError(
+            f"Транспорт {stand.transport.value!r} для стенда '{name}' пока не реализован (TODO)"
+        )

standkit_hub/config.py

@@ -0,0 +1,156 @@
+"""
+Конфиг веб-дашборда standkit (``standkit-hub.json``) — ВСЕ параметры,
+которые иначе пришлось бы задавать флагами ``--host``/``--port``/... в
+терминале при запуске headless-агента, плюс параметры самого хаба (реестр,
+каталоги, интервал автообновления, список удалённых агентов федерации).
+
+Намеренно НЕ импортирует ничего из ``http.server``/веб-слоя — модуль должен
+быть тестируемым в изоляции (см. tests/test_hub_config.py). Отдаётся/
+принимается фронтендом хаба через ``GET/POST /api/settings`` (см.
+standkit_hub/server.py).
+
+Путь конфига — та же папка BPMkit, что и реестр стендов (см.
+standkit.registry.bpmkit_config_dir):
+    Windows: %APPDATA%\\BPMkit\\standkit-hub.json
+    POSIX:   ~/.config/BPMkit/standkit-hub.json  (или $XDG_CONFIG_HOME/BPMkit/...)
+
+Секреты (control/readonly-токены агентов) в конфиге хранятся ТОЛЬКО как ссылки
+(``*_ref``) на standkit.secrets — значения самих секретов сюда никогда не
+попадают.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field, fields
+from pathlib import Path
+from typing import Any, Optional
+
+from standkit.registry import bpmkit_config_dir, default_registry_path
+
+_CONFIG_FILE_NAME = "standkit-hub.json"
+
+# Значения по умолчанию для параметров запуска локального агента (совпадают
+# с default'ами standkit_agent/__main__.py — см. DEFAULT_LOCKOUT_* там же).
+_DEFAULT_AGENT_HOST = "127.0.0.1"
+_DEFAULT_AGENT_PORT = 8765
+_DEFAULT_LOCKOUT_MAX_FAILURES = 5
+_DEFAULT_LOCKOUT_WINDOW_SEC = 300.0
+_DEFAULT_REFRESH_INTERVAL_SEC = 10
+
+
+@dataclass
+class RemoteAgent:
+    """Одна запись федерации удалённых агентов (мульти-агентная панель хаба)."""
+
+    name: str = ""
+    url: str = ""
+    # Ссылка на секрет токена (standkit.secrets), НЕ сам токен.
+    token_ref: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "RemoteAgent":
+        return cls(
+            name=str(data.get("name", "")),
+            url=str(data.get("url", "")),
+            token_ref=str(data.get("token_ref", "")),
+        )
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "url": self.url, "token_ref": self.token_ref}
+
+
+@dataclass
+class HubConfig:
+    """
+    Все настраиваемые пользователем параметры веб-дашборда, чтобы не лазить
+    в PowerShell/``--help``.
+
+    Поля сгруппированы по смыслу:
+    - реестр/каталоги/автообновление — сам хаб;
+    - agents — федерация удалённых standkit-агентов, которых показывает хаб;
+    - agent_* / tls_* / lockout_* / insecure / audit_log — дефолты для запуска
+      ЛОКАЛЬНОГО агента из хаба (зеркалят флаги standkit_agent/__main__.py
+      один в один, чтобы форма настроек их полностью покрывала).
+    """
+
+    # --- Хаб ---
+    registry_path: str = field(default_factory=lambda: str(default_registry_path()))
+    run_dir: str = ""
+    log_dir: str = ""
+    refresh_interval_sec: int = _DEFAULT_REFRESH_INTERVAL_SEC
+
+    # --- Федерация удалённых агентов ---
+    agents: list[RemoteAgent] = field(default_factory=list)
+
+    # --- Дефолты запуска локального агента (standkit_agent) ---
+    agent_host: str = _DEFAULT_AGENT_HOST
+    agent_port: int = _DEFAULT_AGENT_PORT
+    token_ref: str = ""
+    readonly_token_ref: str = ""
+    tls_cert: str = ""
+    tls_key: str = ""
+    tls_client_ca: str = ""
+    insecure: bool = False
+    audit_log: str = ""
+    lockout_max_failures: int = _DEFAULT_LOCKOUT_MAX_FAILURES
+    lockout_window_sec: float = _DEFAULT_LOCKOUT_WINDOW_SEC
+
+    # --- чтение/запись ---
+
+    @classmethod
+    def config_path(cls) -> Path:
+        """Канонический путь к файлу конфига хаба (та же папка, что и реестр кита)."""
+        return bpmkit_config_dir() / _CONFIG_FILE_NAME
+
+    @classmethod
+    def load(cls, path: Optional[str | Path] = None) -> "HubConfig":
+        """
+        Читает конфиг из ``path`` (по умолчанию — ``config_path()``).
+
+        Если файла нет — возвращает конфиг с дефолтами (в т.ч.
+        ``registry_path = default_registry_path()``); это нормальная ситуация
+        при первом запуске хаба. Файл читается как ``utf-8-sig`` (терпим к BOM
+        — тот же принцип, что и в standkit.registry.Registry.load).
+        """
+        p = Path(path) if path is not None else cls.config_path()
+        if not p.exists():
+            return cls()
+
+        raw = p.read_text(encoding="utf-8-sig")
+        try:
+            data = json.loads(raw) if raw.strip() else {}
+        except json.JSONDecodeError:
+            # Битый конфиг хаба не должен ронять запуск диспетчера — тихо
+            # откатываемся на дефолты (в отличие от реестра, это не
+            # критичные для управления стендами данные).
+            return cls()
+
+        return cls.from_dict(data)
+
+    def save(self, path: Optional[str | Path] = None) -> None:
+        """Пишет конфиг в ``path`` (по умолчанию — ``config_path()``), создавая папку при необходимости."""
+        p = Path(path) if path is not None else self.config_path()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        text = json.dumps(self.to_dict(), ensure_ascii=False, indent=2)
+        p.write_text(text, encoding="utf-8")
+
+    # --- сериализация ---
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "HubConfig":
+        known = {f.name for f in fields(cls)}
+        kwargs: dict[str, Any] = {}
+        for key, value in data.items():
+            if key not in known:
+                continue
+            if key == "agents":
+                kwargs[key] = [RemoteAgent.from_dict(a) for a in value]
+            else:
+                kwargs[key] = value
+        return cls(**kwargs)
+
+    def to_dict(self) -> dict:
+        result = asdict(self)
+        result["agents"] = [a.to_dict() for a in self.agents]
+        return result