"""Bounded account-local activity persistence; standard library only. Use one ActivityLog per profile_root (one writer, thread safe):: activity = ActivityLog(profile_root / "activity.json") logs.extend(activity.load()) cursor = activity.sequence entry = activity.append({"message": safe_text(message), "debug": False}) Only allowlisted short fields are retained. The caller MUST apply safe_text to messages before append; this module cannot know account-specific secret values. Debug messages are never persisted. A tiny .seq sidecar reserves sequence blocks BEFORE publishing any entry, including debug. Restart skips unused reservations, so ids strictly increase across restarts but can have gaps. Both load() and sequence are idempotent reads; no timer, idle writes, flush or close is needed. Storage failures raise ActivityLogError with a path-free message. """ from __future__ import annotations from collections import deque from collections.abc import Mapping from datetime import datetime, timezone import json import os from pathlib import Path import tempfile import threading MAX_ENTRIES = 2000 MAX_MESSAGE_CHARS = 2048 MAX_BYTES = 2 * 1024 * 1024 _MAX_SEQUENCE = (1 << 53) - 1 # Browser cursors must remain exact integers. _LEVELS = frozenset({"debug", "info", "warning", "error", "critical"}) class ActivityLogError(RuntimeError): """Persistence failed; public error text contains no filesystem paths.""" def _encode(value): return json.dumps(value, ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode("utf-8") def _sequence(value): return value if type(value) is int and 0 <= value <= _MAX_SEQUENCE else 0 class ActivityLog: """Atomic snapshots capped by both count and serialized bytes. Construction does no IO. load() lazily restores nondebug entries and the reserved high-water mark; append() and sequence also load on first use. append() returns a NEW canonical dict with id == seq; caller ids are ignored. load() returns independent copies of nondebug entries, oldest first. Default file cap is 1 MiB, hard cap 2 MiB, each message <= 2048 characters. The .seq file is < 64 bytes and rewritten at most once per 256 appends in a running instance. Only real nondebug appends rewrite the bounded snapshot. """ def __init__(self, path, max_entries=MAX_ENTRIES, *, max_bytes=1024 * 1024, sequence_block_size=256): if type(max_entries) is not int or not 1 <= max_entries <= MAX_ENTRIES: raise ValueError("max_entries must be between 1 and 2000") if type(max_bytes) is not int or not 16384 <= max_bytes <= MAX_BYTES: raise ValueError("max_bytes must be between 16384 and 2097152") if type(sequence_block_size) is not int or not 1 <= sequence_block_size <= 65536: raise ValueError("sequence_block_size must be between 1 and 65536") self._path = Path(path) self._sequence_path = self._path.with_name(self._path.name + ".seq") self._max_entries = max_entries self._max_bytes = max_bytes self._block_size = sequence_block_size self._lock = threading.RLock() self._loaded = False self._sequence = self._reserved = 0 self._entries = deque() # (canonical dict, cached serialized bytes) @property def sequence(self): """Last emitted seq, or the restored reservation ceiling after restart.""" with self._lock: self._load() return self._sequence def load(self): """Restore once, without modifying either file; return nondebug copies.""" with self._lock: self._load() return [dict(entry) for entry, _ in self._entries] def append(self, entry, *, after_sequence=0): """Append caller-sanitized fields and return {time,message,debug,level,id,seq}. No seq is returned until its high-water mark is durable. If writing fails the event is not published and the in-memory cursor is unchanged. Unknown fields (tokens, headers, request bodies, paths, etc.) are dropped. after_sequence includes ids published by the caller during memory-only fallback; reserve above that cursor before publishing a recovered event. """ if not isinstance(entry, Mapping) or not isinstance(entry.get("message"), str): raise ValueError("Activity entry requires a sanitized string message") if "debug" in entry and type(entry["debug"]) is not bool: raise ValueError("Activity debug flag must be a boolean") if type(after_sequence) is not int or not 0 <= after_sequence <= _MAX_SEQUENCE: raise ValueError("Activity cursor must be a nonnegative safe integer") clean = self._clean(entry) with self._lock: self._load() next_sequence = max(self._sequence, after_sequence) + 1 if next_sequence > _MAX_SEQUENCE: raise ActivityLogError("Activity sequence exhausted") if next_sequence > self._reserved: reserved = min(_MAX_SEQUENCE, next_sequence + self._block_size - 1) self._write(self._sequence_path, _encode({"schema": 1, "sequence": reserved})) self._reserved = reserved clean["id"] = clean["seq"] = next_sequence if not clean["debug"]: entries = deque(self._entries) entries.append((clean, _encode(clean))) self._trim(entries, self._reserved) self._write(self._path, self._snapshot(entries, self._reserved)) self._entries = entries self._sequence = next_sequence return dict(clean) def log(self, message, *, debug=False): """Convenience helper for an already safe_text-sanitized message; int id.""" return self.append({"message": message, "debug": debug})["id"] @staticmethod def _clean(entry): level = entry.get("level", "info") level = level.lower() if isinstance(level, str) else "info" level = {"trace": "debug", "warn": "warning"}.get(level, level) debug = entry.get("debug", False) is True or level == "debug" level = "debug" if debug else level if level in _LEVELS else "info" stamp = entry.get("time") try: if not isinstance(stamp, str) or len(stamp) > 64: raise ValueError datetime.fromisoformat(stamp) except ValueError: stamp = datetime.now(timezone.utc).isoformat(timespec="milliseconds") message = entry["message"][:MAX_MESSAGE_CHARS].replace("\r", " ").replace("\n", " ") message = message.encode("utf-8", errors="replace").decode("utf-8") return {"time": stamp, "message": message, "debug": debug, "level": level} def _load(self): if self._loaded: return record = self._read(self._path, MAX_BYTES) watermark = self._read(self._sequence_path, 1024) high = _sequence(watermark.get("sequence")) if watermark.get("schema") == 1 else 0 entries = {} if record.get("schema") == 1: high = max(high, _sequence(record.get("sequence"))) rows = record.get("entries", []) if isinstance(rows, list): for row in rows: if not isinstance(row, dict): continue seq = _sequence(row.get("seq")) high = max(high, seq) if not seq or not isinstance(row.get("message"), str): continue if "debug" in row and type(row["debug"]) is not bool: continue clean = self._clean(row) if clean["debug"]: continue clean["id"] = clean["seq"] = seq entries[seq] = (clean, _encode(clean)) self._entries = deque(entries[seq] for seq in sorted(entries)[-self._max_entries:]) self._trim(self._entries, high) self._sequence = self._reserved = high self._loaded = True @staticmethod def _prefix(sequence): return b'{"schema":1,"sequence":' + str(sequence).encode("ascii") + b',"entries":[' def _trim(self, entries, sequence): size = len(self._prefix(sequence)) + 2 + sum(len(raw) for _, raw in entries) + max(0, len(entries) - 1) while entries and (len(entries) > self._max_entries or size > self._max_bytes): _, raw = entries.popleft() size -= len(raw) + (1 if entries else 0) def _snapshot(self, entries, sequence): return self._prefix(sequence) + b",".join(raw for _, raw in entries) + b"]}" @staticmethod def _check_path(path): for candidate in (path, *path.parents): if candidate.is_symlink() or getattr(candidate, "is_junction", lambda: False)(): raise ActivityLogError("Activity storage must not use linked paths") def _read(self, path, limit): try: self._check_path(path) with path.open("rb") as stream: data = stream.read(limit + 1) if len(data) > limit: return {} value = json.loads(data) return value if isinstance(value, dict) else {} except FileNotFoundError: return {} except (ValueError, UnicodeError, RecursionError): return {} except OSError: raise ActivityLogError("Unable to read activity storage") from None def _write(self, path, data): temporary = None try: self._check_path(path) path.parent.mkdir(parents=True, exist_ok=True) descriptor, name = tempfile.mkstemp(prefix=".activity-", suffix=".tmp", dir=path.parent) temporary = Path(name) with os.fdopen(descriptor, "wb") as stream: os.chmod(temporary, 0o600) stream.write(data) stream.flush() os.fsync(stream.fileno()) os.replace(temporary, path) if os.name != "nt": directory = os.open(path.parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)) try: os.fsync(directory) finally: os.close(directory) except OSError: raise ActivityLogError("Unable to save activity storage") from None finally: if temporary is not None: try: temporary.unlink(missing_ok=True) except OSError: pass