web_build_limits.py 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140
  1. """Web UI build resource caps (issue #63338).
  2. ``npm run build`` in ``web/`` runs the TypeScript solution builder plus Vite 8's
  3. Rust-native bundler (Rolldown). On small hosts (2–4 vCPU VPS, ~4–10 GB RAM) that
  4. combination saturates every CPU (200%+ ``top`` readings) and can OOM the box or
  5. freeze SSH sessions for the ~20 s build window. Rolldown does not expose a JS-level
  6. worker/thread option, but its native binding parallelizes with rayon, which honours
  7. ``RAYON_NUM_THREADS`` — and V8's heap is capped via ``--max-old-space-size``.
  8. The defaults are deliberately conservative: bounded to half the available cores so
  9. one build can never monopolize a small host, and a heap ceiling sized from the
  10. container/cgroup limit (75% of it, same shape as the TUI launcher's sizing) so a
  11. constrained container gets a graceful V8 allocation failure instead of a silent
  12. cgroup OOM kill.
  13. User overrides always win: an explicit ``NODE_OPTIONS`` ``--max-old-space-size`` or
  14. ``RAYON_NUM_THREADS`` in the environment is left untouched, and
  15. ``HERMES_WEB_BUILD_MAX_OLD_SPACE_SIZE`` / ``HERMES_WEB_BUILD_THREADS`` allow
  16. tailoring without code changes.
  17. """
  18. from __future__ import annotations
  19. import os
  20. # Never let the heap ceiling drop below this on constrained-but-usable hosts:
  21. # below ~1 GB V8 spends the build GC-thrashing instead of making progress.
  22. _MIN_WEB_BUILD_HEAP_MB = 1024
  23. # Ceiling even on huge machines; the dashboard bundle is small and a larger cap
  24. # only inflates the resident set (and OOM risk on shared VPS hosts).
  25. _MAX_WEB_BUILD_HEAP_MB = 4096
  26. # Likewise for parallelism: rolldown caps its own JS-plugin workers at 8, and
  27. # beyond ~half-a-dozen threads the small dashboard graph doesn't speed up.
  28. _MAX_WEB_BUILD_THREADS = 8
  29. _TRUTHY = {"1", "true", "yes", "on"}
  30. def _cgroup_memory_limit_mb() -> int | None:
  31. """Return the cgroup memory limit in MB, or None when unconstrained."""
  32. limit = None
  33. for path in (
  34. "/sys/fs/cgroup/memory.max", # cgroup v2
  35. "/sys/fs/cgroup/memory/memory.limit_in_bytes", # cgroup v1
  36. ):
  37. try:
  38. with open(path, "r", encoding="utf-8-sig") as f:
  39. raw = f.read().strip()
  40. except OSError:
  41. continue
  42. if raw == "max":
  43. return None
  44. try:
  45. value = int(raw)
  46. except ValueError:
  47. continue
  48. if value <= 0 or value >= (1 << 50): # the v1 "unlimited" sentinel
  49. return None
  50. limit = value
  51. break
  52. if limit is None:
  53. return None
  54. return limit // (1024 * 1024)
  55. def _available_cores() -> int:
  56. try:
  57. return max(1, len(os.sched_getaffinity(0))) # type: ignore[attr-defined]
  58. except AttributeError:
  59. return max(1, os.cpu_count() or 1)
  60. def _bounded_threads() -> int:
  61. """Half the cores, clamped to [1, _MAX_WEB_BUILD_THREADS]."""
  62. return max(1, min(_MAX_WEB_BUILD_THREADS, _available_cores() // 2 or 1))
  63. def _bounded_heap_mb() -> int:
  64. """Heap ceiling from the cgroup limit, clamped to [_MIN, _MAX]."""
  65. limit_mb = _cgroup_memory_limit_mb()
  66. if not limit_mb:
  67. return _MAX_WEB_BUILD_HEAP_MB
  68. return max(_MIN_WEB_BUILD_HEAP_MB, min(_MAX_WEB_BUILD_HEAP_MB, int(limit_mb * 0.75)))
  69. def _env_flag(env: dict[str, str], name: str) -> bool:
  70. return str(env.get(name, "")).strip().lower() in _TRUTHY
  71. def web_build_limits(env: dict[str, str] | None = None) -> dict[str, str]:
  72. """Return a copy of *env* bounding the web dashboard build's CPU and heap (#63338).
  73. Never overrides the user: an existing ``NODE_OPTIONS`` containing
  74. ``--max-old-space-size`` or an existing ``RAYON_NUM_THREADS`` is preserved.
  75. ``HERMES_WEB_BUILD_LIGHT=1`` tightens the caps (1 thread, 1 GB heap) for hosts
  76. that cannot spare full CPU during the build.
  77. """
  78. env = dict(env if env is not None else os.environ)
  79. light = light_build_requested(env)
  80. # --- V8 heap cap ---------------------------------------------------------
  81. tokens = env.get("NODE_OPTIONS", "").split()
  82. if not any(t.startswith("--max-old-space-size=") for t in tokens):
  83. explicit = (env.get("HERMES_WEB_BUILD_MAX_OLD_SPACE_SIZE") or "").strip()
  84. try:
  85. heap_mb = int(explicit) if explicit else (
  86. _MIN_WEB_BUILD_HEAP_MB if light else _bounded_heap_mb()
  87. )
  88. except ValueError:
  89. heap_mb = _MIN_WEB_BUILD_HEAP_MB if light else _bounded_heap_mb()
  90. heap_mb = max(_MIN_WEB_BUILD_HEAP_MB, heap_mb)
  91. tokens.append(f"--max-old-space-size={heap_mb}")
  92. env["NODE_OPTIONS"] = " ".join(t for t in tokens if t).strip()
  93. # --- Native bundler parallelism cap -------------------------------------
  94. if not env.get("RAYON_NUM_THREADS"):
  95. explicit = (env.get("HERMES_WEB_BUILD_THREADS") or "").strip()
  96. try:
  97. threads = int(explicit) if explicit else (1 if light else _bounded_threads())
  98. except ValueError:
  99. threads = 1 if light else _bounded_threads()
  100. env["RAYON_NUM_THREADS"] = str(max(1, threads))
  101. return env
  102. def apply_web_build_limits(env: dict[str, str]) -> dict[str, str]:
  103. """Apply :func:`web_build_limits` into *env* (in place) and return it."""
  104. env.update(web_build_limits(env))
  105. return env
  106. def light_build_requested(env: dict[str, str] | None = None) -> bool:
  107. """True when the caller asked for the minimal-footprint web build.
  108. ``HERMES_WEB_BUILD_LIGHT=1``: caps tighten to a single bundler thread and a
  109. 1 GB heap — for VPS hosts that cannot spare full CPU during the build
  110. (the closed PR #78131's ``build:light`` idea).
  111. """
  112. return _env_flag(env if env is not None else dict(os.environ), "HERMES_WEB_BUILD_LIGHT")