| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237 |
- """Shared plumbing for the extracted dashboard routers — thin wrappers over the
- late-binding seam in :mod:`hermes_cli.web_deps` (web_server owns helpers/state;
- every access resolves at call time so ``monkeypatch.setattr(<owning module>, ...)`` wins)."""
- from __future__ import annotations
- import asyncio
- import contextlib
- import logging
- import re
- import sqlite3
- import time
- from typing import Any, Callable, Dict, Optional
- from fastapi import HTTPException
- from hermes_cli.config_backend import ConfigLockedError, ConfigValueError, ConfigWriteError
- from hermes_cli.web_deps import LateState, late
- from hermes_cli.web_server_profiles import _profile_cli_args
- # Same logger the handlers used before extraction (identical logger object).
- log = logging.getLogger("hermes_cli.web_server")
- _profile_scope = late("_profile_scope", "hermes_cli.web_server_profiles")
- _config_profile_scope = late("_config_profile_scope", "hermes_cli.web_server_profiles")
- _spawn_hermes_action = late("_spawn_hermes_action", "hermes_cli.web_server_gateway")
- # Config read-modify-write serialization for off-loop handlers (live lock —
- # LateState supports ``with``-blocks).
- _CONFIG_MUTATION_LOCK = LateState("_CONFIG_MUTATION_LOCK")
- @contextlib.contextmanager
- def config_write_scope(profile: Optional[str]):
- """Profile scope, then the config mutation lock — the write-path nesting
- every config-mutating handler uses."""
- with _profile_scope(profile):
- with _CONFIG_MUTATION_LOCK:
- yield
- async def scoped_to_thread(profile: Optional[str], fn: Callable[[], Any]) -> Any:
- """Run ``fn()`` inside ``_profile_scope(profile)`` on a worker thread."""
- def _run():
- with _profile_scope(profile):
- return fn()
- return await asyncio.to_thread(_run)
- async def config_scoped_to_thread(profile: Optional[str], fn: Callable[[], Any]) -> Any:
- """Run ``fn()`` inside ``_config_profile_scope(profile)`` on a worker thread —
- home + secret scope without the process-global skills-module swap."""
- def _run():
- with _config_profile_scope(profile):
- return fn()
- return await asyncio.to_thread(_run)
- def destructive_profile(profile: Optional[str], route: str) -> Optional[str]:
- """The profile a DESTRUCTIVE or PRIVILEGED route acts on, or 400 when it is ambiguous.
- One backend serves every profile, so an omitted ``profile`` on a route that deletes,
- overwrites or privileges profile-owned data is not a default — it silently meant
- "whichever home this process launched with". Named profile: honoured. Omitted:
- rejected as soon as the process hosts more than one profile
- (``is_multiplex_active()``, decided once at boot by
- ``activate_multi_profile_hosting_eagerly``). A genuinely single-profile host has
- nothing to confuse, so there an omitted profile keeps meaning the launch profile
- and `curl` against a plain ``hermes serve`` is unchanged.
- "Privileged" is the same class as "destructive": arming an auto-approved shell hook
- in the wrong profile is at least as bad as removing one from it.
- """
- if (profile or "").strip():
- return profile
- from agent.secret_scope import is_multiplex_active
- if is_multiplex_active():
- raise HTTPException(
- status_code=400,
- detail=f"{route} requires an explicit profile: this backend serves several profiles, "
- "so an unnamed target would act on the wrong profile's data.")
- return profile
- def config_refusal_http(exc: ConfigWriteError) -> Optional[HTTPException]:
- """The HTTP error for an EXPECTED config-backend refusal, or None for an unexpected failure.
- A lock (403), a value the backend cannot store (400, or 413 when too large; ours or the
- plane's ``config_value_invalid``/``config_path_*``/``config_secret_literal``) and a lost CAS
- race (409) are the
- caller's to fix, and their messages are ours or the config plane's own refusal text (a path
- and the level that locks it; never a value or a credential), so they pass through (design
- §4.3: v1 shows the server's 403 message). Anything else stays opaque."""
- if isinstance(exc, ConfigLockedError):
- return HTTPException(status_code=403, detail=str(exc))
- if isinstance(exc, ConfigValueError):
- status = 413 if exc.code in ("config_level_too_large", "config_body_too_large") else 400
- return HTTPException(status_code=status, detail=str(exc))
- if exc.code == "config_version_conflict":
- return HTTPException(status_code=409, detail=str(exc))
- return None
- @contextlib.contextmanager
- def http_failure(log_msg: str, status: int, prefix: Optional[str] = None, *, detail: Optional[str] = None):
- """Map unexpected exceptions to an ``HTTPException``.
- ``HTTPException`` passes through; an expected config-backend refusal becomes its own status
- and message (:func:`config_refusal_http`); anything else is logged with ``log_msg`` (traceback),
- then re-raised as ``HTTPException(status, f"{prefix}: {exc}")`` — or ``detail`` when given
- (fixed message, exception text only in the log).
- """
- try:
- yield
- except HTTPException:
- raise
- except ConfigWriteError as exc:
- refusal = config_refusal_http(exc)
- if refusal is None:
- log.exception(log_msg)
- raise HTTPException(status_code=status, detail=detail if detail is not None else f"{prefix}: {exc}")
- raise refusal from exc
- except Exception as exc:
- log.exception(log_msg)
- raise HTTPException(status_code=status, detail=detail if detail is not None else f"{prefix}: {exc}")
- def spawn_profile_action(
- profile: Optional[str], argv: list, name: str, *, log_msg: str, prefix: str
- ) -> dict:
- """Spawn a background ``hermes -p <profile> <argv>`` action; a spawn
- failure is logged and becomes ``500 "<prefix>: <exc>"``."""
- with http_failure(log_msg, 500, prefix):
- proc = _spawn_hermes_action(_profile_cli_args(profile) + argv, name)
- return {"ok": True, "pid": proc.pid, "name": name}
- def require(value: Optional[str], detail: str) -> str:
- """Strip ``value``; 400 with ``detail`` when empty."""
- stripped = (value or "").strip()
- if not stripped:
- raise HTTPException(status_code=400, detail=detail)
- return stripped
- REDACTED_CREDENTIAL_WRITE_DETAIL = (
- "Refusing to save a redacted credential preview; re-enter the full secret to replace it."
- )
- def redacted_credential_preview(value: Any) -> Optional[str]:
- """Return a display-only credential sentinel that can never gain write authority."""
- if not value:
- return None
- from hermes_cli.config import redact_key
- return f"«redacted:{redact_key(str(value))}»"
- # Legacy bare masks (pre-sentinel pages, older Desktop builds) are recognised by the
- # producer shape of ``agent.redact.mask_secret`` — never by equality to the current
- # secret, which would authorise a stale preview after a rotation (#121002).
- _LEGACY_MASK_RE = re.compile(r".{4}\.\.\..{4}")
- def is_redacted_credential_preview(submitted: Any) -> bool:
- """Recognize current, stale and legacy dashboard previews by shape alone."""
- value = str(submitted or "")
- # Any ``«redacted…`` value is already-masked output (the same test agent.redact uses
- # to skip re-masking): our ``«redacted:…»`` sentinel, ``«redacted-secret»`` and the
- # vault marker ``«redacted-vault-secret»``. Then the legacy bare mask shapes.
- if value.startswith("«redacted"):
- return True
- return value == "***" or _LEGACY_MASK_RE.fullmatch(value) is not None
- # Corrupt-store reporting for polled read endpoints. The dashboard polls analytics every few
- # seconds; a persistently malformed state.db once produced ~520K identical tracebacks in 24 h
- # (#96591). One WARNING per store per interval, then debug; the caller gets an explicit status
- # instead of a 500. The file is never quarantined or renamed from here — that is `hermes doctor`'s job.
- _CORRUPT_STORE_WARN_INTERVAL_S = 300.0
- _corrupt_store_warned_at: dict[str, float] = {} # {db path: monotonic}
- CORRUPT_STORE_DETAIL = {
- "error": "state_db_corrupt",
- "message": "state.db corrupt — run `hermes doctor` (then `hermes doctor --fix` or `hermes sessions repair`).",
- }
- # One payload per persistence-cause bucket (``classify_persistence_error``); ``error`` codes
- # all follow the ``state_db_*`` scheme of the pre-existing ``state_db_corrupt``.
- # Same guidance as the deleted_wal / replaced turn explainers: `doctor --fix` while a holder
- # lives would repair the wrong generation in place, so it is deliberately NOT suggested here.
- DELETED_WAL_DETAIL = {
- "error": "state_db_deleted_wal",
- "message": "another Hermes process still holds an old copy of the session database's write-ahead log — "
- "quit every Hermes process on this profile, run `hermes doctor` (it names the holders), "
- "then start Hermes again. Do not run `hermes doctor --fix` while they run.",
- }
- STATE_DB_REPLACED_DETAIL = {
- "error": "state_db_replaced",
- "message": "state.db was replaced while Hermes was running — stop Hermes, run `hermes doctor`, "
- "then start it again. Do not run `hermes doctor --fix`, which would repair the wrong file in place.",
- }
- # Every other bucket a malformed image can classify as ("corrupt", "fts_index") is the corrupt payload.
- _STORE_STATUS_DETAIL_BY_CAUSE = {"deleted_wal": DELETED_WAL_DETAIL, "replaced": STATE_DB_REPLACED_DETAIL}
- def corrupt_store_status(db_path, exc) -> HTTPException:
- """The structured ``state_db_corrupt`` 503 for a malformed store, warning once per store per
- :data:`_CORRUPT_STORE_WARN_INTERVAL_S` (debug afterwards). Callers ``raise ... from exc``."""
- from hermes_state_errors import classify_persistence_error
- key, now = str(db_path), time.monotonic()
- last = _corrupt_store_warned_at.get(key)
- detail = _STORE_STATUS_DETAIL_BY_CAUSE.get(classify_persistence_error(exc), CORRUPT_STORE_DETAIL)
- if last is None or now - last >= _CORRUPT_STORE_WARN_INTERVAL_S:
- _corrupt_store_warned_at[key] = now
- log.warning("state.db at %s is unreadable (%s); dashboard reads return a status payload until it is "
- "repaired — run `hermes doctor`", db_path, exc)
- else:
- log.debug("state.db at %s still has error: %s", db_path, exc)
- return HTTPException(status_code=503, detail={**detail, "path": key})
- @contextlib.contextmanager
- def corrupt_store_as_status(db_path):
- """Map a corrupt-image ``sqlite3.DatabaseError`` or ``StateDbReplacedError`` from a state.db read to a 503 status
- payload, warning once per store per :data:`_CORRUPT_STORE_WARN_INTERVAL_S`.
- Busy/locked and every other error propagate unchanged."""
- from hermes_state_errors import StateDbReplacedError, classify_persistence_error, is_malformed_db_error
- try:
- yield
- except (sqlite3.DatabaseError, StateDbReplacedError) as exc:
- if not isinstance(exc, StateDbReplacedError) and not is_malformed_db_error(exc):
- raise
- raise corrupt_store_status(db_path, exc) from exc
|