"""Web UI build resource caps (issue #63338). ``npm run build`` in ``web/`` runs the TypeScript solution builder plus Vite 8's Rust-native bundler (Rolldown). On small hosts (2–4 vCPU VPS, ~4–10 GB RAM) that combination saturates every CPU (200%+ ``top`` readings) and can OOM the box or freeze SSH sessions for the ~20 s build window. Rolldown does not expose a JS-level worker/thread option, but its native binding parallelizes with rayon, which honours ``RAYON_NUM_THREADS`` — and V8's heap is capped via ``--max-old-space-size``. The defaults are deliberately conservative: bounded to half the available cores so one build can never monopolize a small host, and a heap ceiling sized from the container/cgroup limit (75% of it, same shape as the TUI launcher's sizing) so a constrained container gets a graceful V8 allocation failure instead of a silent cgroup OOM kill. User overrides always win: an explicit ``NODE_OPTIONS`` ``--max-old-space-size`` or ``RAYON_NUM_THREADS`` in the environment is left untouched, and ``HERMES_WEB_BUILD_MAX_OLD_SPACE_SIZE`` / ``HERMES_WEB_BUILD_THREADS`` allow tailoring without code changes. """ from __future__ import annotations import os # Never let the heap ceiling drop below this on constrained-but-usable hosts: # below ~1 GB V8 spends the build GC-thrashing instead of making progress. _MIN_WEB_BUILD_HEAP_MB = 1024 # Ceiling even on huge machines; the dashboard bundle is small and a larger cap # only inflates the resident set (and OOM risk on shared VPS hosts). _MAX_WEB_BUILD_HEAP_MB = 4096 # Likewise for parallelism: rolldown caps its own JS-plugin workers at 8, and # beyond ~half-a-dozen threads the small dashboard graph doesn't speed up. _MAX_WEB_BUILD_THREADS = 8 _TRUTHY = {"1", "true", "yes", "on"} def _cgroup_memory_limit_mb() -> int | None: """Return the cgroup memory limit in MB, or None when unconstrained.""" limit = None for path in ( "/sys/fs/cgroup/memory.max", # cgroup v2 "/sys/fs/cgroup/memory/memory.limit_in_bytes", # cgroup v1 ): try: with open(path, "r", encoding="utf-8-sig") as f: raw = f.read().strip() except OSError: continue if raw == "max": return None try: value = int(raw) except ValueError: continue if value <= 0 or value >= (1 << 50): # the v1 "unlimited" sentinel return None limit = value break if limit is None: return None return limit // (1024 * 1024) def _available_cores() -> int: try: return max(1, len(os.sched_getaffinity(0))) # type: ignore[attr-defined] except AttributeError: return max(1, os.cpu_count() or 1) def _bounded_threads() -> int: """Half the cores, clamped to [1, _MAX_WEB_BUILD_THREADS].""" return max(1, min(_MAX_WEB_BUILD_THREADS, _available_cores() // 2 or 1)) def _bounded_heap_mb() -> int: """Heap ceiling from the cgroup limit, clamped to [_MIN, _MAX].""" limit_mb = _cgroup_memory_limit_mb() if not limit_mb: return _MAX_WEB_BUILD_HEAP_MB return max(_MIN_WEB_BUILD_HEAP_MB, min(_MAX_WEB_BUILD_HEAP_MB, int(limit_mb * 0.75))) def _env_flag(env: dict[str, str], name: str) -> bool: return str(env.get(name, "")).strip().lower() in _TRUTHY def web_build_limits(env: dict[str, str] | None = None) -> dict[str, str]: """Return a copy of *env* bounding the web dashboard build's CPU and heap (#63338). Never overrides the user: an existing ``NODE_OPTIONS`` containing ``--max-old-space-size`` or an existing ``RAYON_NUM_THREADS`` is preserved. ``HERMES_WEB_BUILD_LIGHT=1`` tightens the caps (1 thread, 1 GB heap) for hosts that cannot spare full CPU during the build. """ env = dict(env if env is not None else os.environ) light = light_build_requested(env) # --- V8 heap cap --------------------------------------------------------- tokens = env.get("NODE_OPTIONS", "").split() if not any(t.startswith("--max-old-space-size=") for t in tokens): explicit = (env.get("HERMES_WEB_BUILD_MAX_OLD_SPACE_SIZE") or "").strip() try: heap_mb = int(explicit) if explicit else ( _MIN_WEB_BUILD_HEAP_MB if light else _bounded_heap_mb() ) except ValueError: heap_mb = _MIN_WEB_BUILD_HEAP_MB if light else _bounded_heap_mb() heap_mb = max(_MIN_WEB_BUILD_HEAP_MB, heap_mb) tokens.append(f"--max-old-space-size={heap_mb}") env["NODE_OPTIONS"] = " ".join(t for t in tokens if t).strip() # --- Native bundler parallelism cap ------------------------------------- if not env.get("RAYON_NUM_THREADS"): explicit = (env.get("HERMES_WEB_BUILD_THREADS") or "").strip() try: threads = int(explicit) if explicit else (1 if light else _bounded_threads()) except ValueError: threads = 1 if light else _bounded_threads() env["RAYON_NUM_THREADS"] = str(max(1, threads)) return env def apply_web_build_limits(env: dict[str, str]) -> dict[str, str]: """Apply :func:`web_build_limits` into *env* (in place) and return it.""" env.update(web_build_limits(env)) return env def light_build_requested(env: dict[str, str] | None = None) -> bool: """True when the caller asked for the minimal-footprint web build. ``HERMES_WEB_BUILD_LIGHT=1``: caps tighten to a single bundler thread and a 1 GB heap — for VPS hosts that cannot spare full CPU during the build (the closed PR #78131's ``build:light`` idea). """ return _env_flag(env if env is not None else dict(os.environ), "HERMES_WEB_BUILD_LIGHT")