Files
BearHuddleston e94a35ca6c fix(webapp): serve a desktop bundle's prebuilt renderer as shipped
`hermes webapp` and the Desktop's Web Access Start reuse a renderer only
when scripts/build/freshness.mjs certifies it, and a bundle's sealed
payload ships no scripts/. Even with the Webapp planted they took the
build lock in the install root (Permission denied inside WindowsApps; a
lock file written into the signed macOS app) and then tried to build
from sources the payload does not have.

A bundled payload (install stamp payload "bundled") now serves its
planted dist-webapp as it is, like the Nix package's HERMES_WEBAPP_DIST:
no freshness check, no lock, no build, and --force-build says it cannot
be rebuilt. The Termux .deb stamps payload "runtime" and is unchanged.
2026-11-12 14:16:57 -06:00

151 lines
6.6 KiB
Python

"""Build and launch plumbing for the browser-hosted Desktop workspace.
The browser surface shares Hermes' hardened dashboard server. This module owns
only the separate renderer artifact and the one-way handoff into that server;
it never creates a second HTTP/WebSocket stack. The renderer is compiled by the
shared product builders (``apps/desktop/scripts/build-webapp.mjs``), whose
receipt inside ``dist-webapp`` decides freshness.
"""
from __future__ import annotations
from contextlib import contextmanager
import os
from pathlib import Path
import subprocess
# Serialize renderer publication with Dashboard builds in this checkout.
_LOCK_NAME = ".web_ui_build.lock"
_LOCK_WAIT_SECONDS = 30 * 60
# Written into the bundle when `hermes update` could not rebuild it, so the gateways serving it report
# the Webapp unavailable instead of serving it against the updated backend. Publishing a build
# replaces the whole folder, and the receipt's output hash covers this file, so a marked bundle is
# never reused as current.
STALE_MARKER = ".hermes-stale"
# A packaged bundle (the Nix package), like HERMES_WEB_DIST for the dashboard: the packager
# builds it, so Hermes serves it as it is and never builds or marks it.
DIST_ENV = "HERMES_WEBAPP_DIST"
class WebappBuildError(RuntimeError):
"""The browser-hosted Desktop renderer could not be prepared."""
def packaged_webapp_dist() -> Path | None:
"""The bundle :data:`DIST_ENV` names, or None when Hermes builds its own."""
value = os.environ.get(DIST_ENV)
return Path(value).expanduser() if value else None
def webapp_dist_dir(project_root: Path) -> Path:
return packaged_webapp_dist() or project_root / "apps" / "desktop" / "dist-webapp"
def mark_webapp_stale(project_root: Path) -> bool:
"""Mark the built bundle in *project_root* out of date, after a rebuild that failed. False when
no bundle is built: nothing serves one, and the build output folder stays the builder's. Also
False for a packaged bundle, which is the packager's."""
dist = webapp_dist_dir(project_root)
if packaged_webapp_dist() is not None or not (dist / "index.html").is_file():
return False
(dist / STALE_MARKER).write_text("hermes update could not rebuild this bundle\n", encoding="utf-8")
return True
def webapp_bundle_stale(dist: Path) -> bool:
"""Whether the bundle in *dist* is marked out of date (:func:`mark_webapp_stale`)."""
return (Path(dist) / STALE_MARKER).is_file()
def _clear_stale_mark(dist: Path) -> None:
try:
(dist / STALE_MARKER).unlink(missing_ok=True)
except OSError as exc:
raise WebappBuildError(f"Could not mark the Webapp renderer at {dist} current: {exc}") from exc
@contextmanager
def _exclusive_build_lock(path: Path):
"""Cross-platform exclusive lock for one renderer generation."""
from pm.filesystem import lock_fd, unlock_fd
try:
path.parent.mkdir(parents=True, exist_ok=True)
handle = path.open("a+b")
except OSError as exc:
raise WebappBuildError(f"Could not open Webapp build lock {path}: {exc}") from exc
try:
try:
if not lock_fd(handle.fileno(), wait=False):
print("→ Another Hermes Webapp build is running; waiting for it...")
if not lock_fd(handle.fileno(), wait=True, timeout=_LOCK_WAIT_SECONDS):
raise WebappBuildError(f"Timed out waiting for another Webapp build ({path})")
except OSError as exc:
raise WebappBuildError(f"Could not lock Webapp build {path}: {exc}") from exc
yield
finally:
unlock_fd(handle.fileno())
handle.close()
def prepare_webapp_renderer(
project_root: Path,
*,
force: bool = False,
skip_build: bool = False,
explicit: bool = False,
) -> Path:
"""Return a verified browser renderer, serializing concurrent builds.
``explicit`` (a requested build) may install dependencies even when lazy
installs are disabled, like ``hermes desktop --build-only``.
"""
from hermes_cli.source_build import build_source_webapp, source_build_env, source_product_current
from hermes_cli.steward import is_bundled_payload
project_root = project_root.resolve()
dist = webapp_dist_dir(project_root)
if packaged_webapp_dist() is not None:
# The packager built it into a read-only store; there is nothing here to rebuild.
if not (dist / "index.html").is_file():
raise WebappBuildError(f"{DIST_ENV} is set but no Webapp renderer exists at {dist}")
if force:
raise WebappBuildError(f"The Webapp renderer at {dist} comes from {DIST_ENV} and cannot be rebuilt here")
print(f"→ Using Hermes Webapp renderer from {DIST_ENV}: {dist}")
return dist
if is_bundled_payload(project_root):
# A desktop app's sealed payload ships the renderer prebuilt, without the sources or scripts to build it.
if not (dist / "index.html").is_file():
raise WebappBuildError(f"This desktop app ships no Webapp renderer at {dist}")
if force:
raise WebappBuildError(f"The Webapp renderer at {dist} ships with the desktop app and cannot be rebuilt")
print(f"→ Using the desktop app's Webapp renderer: {dist}")
return dist
if skip_build:
# Reuse takes no build lock, like `hermes dashboard --skip-build`: the
# lock lives in the install root, which a read-only install cannot write.
if not (dist / "index.html").is_file():
raise WebappBuildError(
f"--skip-build was passed but no Webapp renderer exists at {dist}"
)
print(f"→ Reusing Hermes Webapp renderer at {dist} (--skip-build)")
return dist
# A current, unmarked bundle needs no lock either, so a read-only install
# (the Docker image) reuses the one baked at build time.
if not force and not webapp_bundle_stale(dist) and source_product_current(project_root, "webapp", dist):
print(f"✓ Hermes Webapp renderer is up to date: {dist}")
return dist
with _exclusive_build_lock(project_root / _LOCK_NAME):
if not force and source_product_current(project_root, "webapp", dist):
_clear_stale_mark(dist)
print(f"✓ Hermes Webapp renderer is up to date: {dist}")
return dist
try:
build_source_webapp(project_root, env=source_build_env(explicit=explicit), explicit=explicit)
except (OSError, subprocess.SubprocessError, RuntimeError) as exc:
raise WebappBuildError(f"Browser-hosted Desktop build failed: {exc}") from exc
_clear_stale_mark(dist)
print(f"✓ Hermes Webapp renderer built: {dist}")
return dist