"""In-memory ring buffer holding the most recent curator run's execution log. Now sharded per-user — each ``user_id`` gets its own deque so users only see their own curator activity from the Web UI. The buffer is intentionally process-local and non-persistent. The Gateway exposes it over ``GET /api/curator/logs`` with the active user id resolved from the request context. All public functions swallow internal exceptions so a logging failure can never break the curator run itself. """ from __future__ import annotations import logging import threading from collections import deque from datetime import UTC, datetime from typing import Any logger = logging.getLogger(__name__) _MAX_RECORDS = 200 # Reserved bucket key for "no user context" callers (legacy code paths or # tests). Real curator runs always supply a concrete user_id. _DEFAULT_BUCKET = "__default__" _lock = threading.Lock() _buffers: dict[str, deque[dict[str, Any]]] = {} def _bucket_key(user_id: str | None) -> str: return user_id or _DEFAULT_BUCKET def _get_or_create(user_id: str | None) -> deque[dict[str, Any]]: key = _bucket_key(user_id) buffer = _buffers.get(key) if buffer is None: buffer = deque(maxlen=_MAX_RECORDS) _buffers[key] = buffer return buffer def _now_iso() -> str: return datetime.now(UTC).isoformat() def start_new_run(user_id: str | None = None) -> None: """Clear the user's buffer and emit a ``run_started`` record.""" try: with _lock: buffer = _get_or_create(user_id) buffer.clear() buffer.append({"ts": _now_iso(), "level": "info", "message": "run_started"}) except Exception: logger.debug("curator_log.start_new_run failed", exc_info=True) def record(level: str, message: str, *, user_id: str | None = None, **fields: Any) -> None: """Append a single log record to the user's buffer. Never raises.""" try: entry: dict[str, Any] = { "ts": _now_iso(), "level": str(level or "info"), "message": str(message), } if fields: entry.update({k: v for k, v in fields.items() if k not in entry}) with _lock: buffer = _get_or_create(user_id) buffer.append(entry) except Exception: logger.debug("curator_log.record failed", exc_info=True) def get_recent(user_id: str | None = None) -> list[dict[str, Any]]: """Return a snapshot of records for ``user_id``. Never raises.""" try: with _lock: buffer = _buffers.get(_bucket_key(user_id)) if buffer is None: return [] return list(buffer) except Exception: logger.debug("curator_log.get_recent failed", exc_info=True) return [] def clear(user_id: str | None = None) -> None: """Drop a user's records. With ``user_id=None`` drops the default bucket. Use ``clear_all()`` for cross-user cleanup (tests). """ try: with _lock: buffer = _buffers.get(_bucket_key(user_id)) if buffer is not None: buffer.clear() except Exception: logger.debug("curator_log.clear failed", exc_info=True) def clear_all() -> None: """Drop every user's records. Used by tests.""" try: with _lock: _buffers.clear() except Exception: logger.debug("curator_log.clear_all failed", exc_info=True)