Merge pull request #31760 from NousResearch/hermes/hermes-bf5898da
feat(docker)!: s6-overlay container supervision (salvage of #30136)
This commit is contained in:
Ben Barclay
@@ -658,7 +658,8 @@ DEFAULT_CONFIG = {
|
||||
# are owned by your host user instead of root, which avoids needing
|
||||
# `sudo chown` after container runs. Default off to preserve behavior
|
||||
# for images whose entrypoints expect to start as root (e.g. the
|
||||
# bundled Hermes image, which drops to the `hermes` user via gosu).
|
||||
# bundled Hermes image, which drops to the `hermes` user via
|
||||
# s6-setuidgid inside each supervised service).
|
||||
# When on, SETUID/SETGID caps are omitted from the container since
|
||||
# no privilege drop is needed.
|
||||
"docker_run_as_host_user": False,
|
||||
|
||||
@@ -0,0 +1,325 @@
|
||||
"""Container-boot reconciliation of per-profile gateway s6 services.
|
||||
|
||||
Service directories under /run/service/ live on **tmpfs** and are wiped
|
||||
on every container restart. Profile directories under
|
||||
``$HERMES_HOME/profiles/<name>/`` live on the persistent VOLUME, and
|
||||
each one records its gateway's last state in ``gateway_state.json``.
|
||||
This module bridges the two: on every container boot, walk the
|
||||
persistent profiles, recreate the s6 service slots, and auto-start
|
||||
only those whose last recorded state was ``running``.
|
||||
|
||||
Wired into the image as /etc/cont-init.d/02-reconcile-profiles by the
|
||||
Dockerfile (Phase 4 Task 4.0). Runs as root after 01-hermes-setup
|
||||
(the stage2 hook) has chowned the volume and seeded $HERMES_HOME, but
|
||||
before s6-rc starts user services.
|
||||
|
||||
Without this module, every ``docker restart`` would silently wipe
|
||||
every per-profile gateway, even though the user's profiles still
|
||||
exist on disk.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Literal
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
# Only this prior state triggers automatic restart. Everything else
|
||||
# (startup_failed, starting, stopped, missing) registers the slot in
|
||||
# the down state and waits for explicit user action — this avoids the
|
||||
# crash-loop where a broken gateway keeps being restarted across
|
||||
# `docker restart` cycles.
|
||||
_AUTOSTART_STATES = frozenset({"running"})
|
||||
|
||||
# Stale runtime files we sweep before recreating service slots. These
|
||||
# all hold container-namespaced state (PIDs, process tables) that's
|
||||
# garbage post-restart — a numerically-equal PID in the new container
|
||||
# is a different process. See the Risk Register in the plan.
|
||||
_STALE_RUNTIME_FILES = ("gateway.pid", "processes.json")
|
||||
|
||||
ReconcileActionLabel = Literal["started", "registered", "skipped"]
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ReconcileAction:
|
||||
"""One profile's outcome from a single reconciliation pass."""
|
||||
profile: str
|
||||
prior_state: str | None
|
||||
action: ReconcileActionLabel
|
||||
|
||||
|
||||
def reconcile_profile_gateways(
|
||||
*,
|
||||
hermes_home: Path,
|
||||
scandir: Path,
|
||||
dry_run: bool = False,
|
||||
) -> list[ReconcileAction]:
|
||||
"""Recreate s6 service registrations for every persistent profile.
|
||||
|
||||
Always registers a ``gateway-default`` slot for the root profile
|
||||
(the implicit profile that lives at the top of ``$HERMES_HOME``,
|
||||
not under ``profiles/``). The dispatcher in ``hermes_cli.gateway``
|
||||
maps an empty profile suffix to ``gateway-default``, so this slot
|
||||
is what ``hermes gateway start`` (no ``-p``) targets. Without it,
|
||||
bare ``hermes gateway start`` inside the container would land on
|
||||
``s6-svc -u /run/service/gateway-default`` → uncaught
|
||||
``CalledProcessError`` → traceback to the user (PR #30136 review).
|
||||
|
||||
The default slot's prior state is read from
|
||||
``$HERMES_HOME/gateway_state.json`` (sibling to the profile root,
|
||||
not under ``profiles/``); stale runtime files there are swept the
|
||||
same way as for named profiles.
|
||||
|
||||
Args:
|
||||
hermes_home: The container's HERMES_HOME (typically /opt/data).
|
||||
Profiles live under ``<hermes_home>/profiles/<name>/``;
|
||||
the default profile lives at ``<hermes_home>`` itself.
|
||||
scandir: The s6 dynamic scandir (typically /run/service). Service
|
||||
directories are created at ``<scandir>/gateway-<profile>/``.
|
||||
dry_run: When True, walk and return the action list without
|
||||
touching the filesystem. For tests and `--dry-run` debug.
|
||||
|
||||
Returns:
|
||||
One :class:`ReconcileAction` per profile, in this order:
|
||||
``default`` first, then named profiles in directory order.
|
||||
"""
|
||||
actions: list[ReconcileAction] = []
|
||||
|
||||
# Default profile — always register, even if nothing has ever
|
||||
# populated the root profile dir. The slot exists so
|
||||
# ``hermes gateway start`` (no ``-p``) has somewhere to land;
|
||||
# auto-up only when the prior state was "running" (same rule as
|
||||
# named profiles).
|
||||
default_prior_state = _read_prior_state(hermes_home)
|
||||
default_should_start = default_prior_state in _AUTOSTART_STATES
|
||||
if not dry_run:
|
||||
_cleanup_stale_runtime_files(hermes_home)
|
||||
_register_service(scandir, "default", start=default_should_start)
|
||||
actions.append(ReconcileAction(
|
||||
profile="default",
|
||||
prior_state=default_prior_state,
|
||||
action="started" if default_should_start else "registered",
|
||||
))
|
||||
|
||||
profiles_root = hermes_home / "profiles"
|
||||
if profiles_root.is_dir():
|
||||
for entry in sorted(profiles_root.iterdir()):
|
||||
if not entry.is_dir():
|
||||
continue
|
||||
# SOUL.md is always seeded by `hermes profile create` (config.yaml
|
||||
# is not — that comes later via `hermes setup`). Use it as the
|
||||
# "real profile" marker so stray dirs (backups, manual mkdir)
|
||||
# aren't picked up.
|
||||
if not (entry / "SOUL.md").exists():
|
||||
continue
|
||||
# The "default" service name is reserved for the root
|
||||
# profile (above) — if a user has somehow created a
|
||||
# ``profiles/default/`` directory, skip it to avoid the
|
||||
# slot collision. Their gateway would still be reachable
|
||||
# via ``hermes -p default-named gateway start`` if they
|
||||
# rename the directory; we don't try to disambiguate here.
|
||||
if entry.name == "default":
|
||||
log.warning(
|
||||
"profiles/default/ exists — skipping to avoid colliding "
|
||||
"with the reserved root-profile s6 slot",
|
||||
)
|
||||
continue
|
||||
|
||||
prior_state = _read_prior_state(entry)
|
||||
should_start = prior_state in _AUTOSTART_STATES
|
||||
|
||||
if not dry_run:
|
||||
_cleanup_stale_runtime_files(entry)
|
||||
_register_service(scandir, entry.name, start=should_start)
|
||||
|
||||
actions.append(ReconcileAction(
|
||||
profile=entry.name,
|
||||
prior_state=prior_state,
|
||||
action="started" if should_start else "registered",
|
||||
))
|
||||
|
||||
if not dry_run:
|
||||
_write_reconcile_log(hermes_home, actions)
|
||||
return actions
|
||||
|
||||
|
||||
def _read_prior_state(profile_dir: Path) -> str | None:
|
||||
"""Read gateway_state.json's ``gateway_state`` field, or None if
|
||||
missing or unparseable. Unparseable counts as "no prior state" so
|
||||
we don't bork the whole reconciliation on a corrupt file."""
|
||||
state_file = profile_dir / "gateway_state.json"
|
||||
if not state_file.exists():
|
||||
return None
|
||||
try:
|
||||
return json.loads(state_file.read_text()).get("gateway_state")
|
||||
except (OSError, json.JSONDecodeError):
|
||||
log.warning(
|
||||
"could not read %s; treating as no prior state", state_file,
|
||||
)
|
||||
return None
|
||||
|
||||
|
||||
def _cleanup_stale_runtime_files(profile_dir: Path) -> None:
|
||||
"""Remove gateway.pid and processes.json — they reference PIDs in
|
||||
the dead container's process namespace and would otherwise confuse
|
||||
the newly-started gateway's process-mismatch checks."""
|
||||
for name in _STALE_RUNTIME_FILES:
|
||||
(profile_dir / name).unlink(missing_ok=True)
|
||||
|
||||
|
||||
def _register_service(scandir: Path, profile: str, *, start: bool) -> None:
|
||||
"""Recreate the s6 service slot for one profile.
|
||||
|
||||
Mirrors the rendering in :func:`S6ServiceManager.register_profile_gateway`,
|
||||
but here we control the start state directly via the ``down`` marker
|
||||
file (s6-svscan honors it on rescan). Cannot use the manager
|
||||
directly because the cont-init.d phase runs as root before
|
||||
s6-svscan starts scanning the dynamic scandir — the manager's
|
||||
``s6-svscanctl -a`` call would fail with no control socket.
|
||||
|
||||
Atomicity: build the new layout in a sibling temp directory and
|
||||
rename it into place via :meth:`Path.replace`. This matches
|
||||
:meth:`S6ServiceManager.register_profile_gateway` (PR #30136
|
||||
review item O4) — even though cont-init.d runs before s6-svscan
|
||||
starts scanning, an atomic publication keeps the contract uniform
|
||||
between the two registration paths and protects against a
|
||||
half-populated dir if the script is interrupted mid-write.
|
||||
"""
|
||||
import shutil
|
||||
|
||||
from hermes_cli.service_manager import (
|
||||
S6ServiceManager,
|
||||
_seed_supervise_skeleton,
|
||||
validate_profile_name,
|
||||
)
|
||||
|
||||
validate_profile_name(profile)
|
||||
service_dir = scandir / f"gateway-{profile}"
|
||||
tmp_dir = service_dir.with_name(service_dir.name + ".tmp")
|
||||
|
||||
# Wipe any leftover tmp from a previous interrupted run.
|
||||
if tmp_dir.exists():
|
||||
shutil.rmtree(tmp_dir, ignore_errors=True)
|
||||
tmp_dir.mkdir(parents=True)
|
||||
|
||||
try:
|
||||
(tmp_dir / "type").write_text("longrun\n")
|
||||
|
||||
# Reuse the manager's run-script rendering — single source of
|
||||
# truth so register_profile_gateway and reconcile_profile_gateways
|
||||
# stay consistent. extra_env is empty here; users who need
|
||||
# per-profile env can set it via the profile's config.yaml
|
||||
# (which the gateway itself loads).
|
||||
run = tmp_dir / "run"
|
||||
run.write_text(S6ServiceManager._render_run_script(profile, extra_env={}))
|
||||
run.chmod(0o755)
|
||||
|
||||
# Persistent log rotation (OQ8-C).
|
||||
log_subdir = tmp_dir / "log"
|
||||
log_subdir.mkdir()
|
||||
log_run = log_subdir / "run"
|
||||
log_run.write_text(S6ServiceManager._render_log_run(profile))
|
||||
log_run.chmod(0o755)
|
||||
|
||||
# The presence of a `down` file tells s6-supervise to NOT
|
||||
# start the service when s6-svscan picks it up. User brings
|
||||
# it up explicitly with `hermes -p <profile> gateway start`
|
||||
# (which routes through the Phase 4
|
||||
# _dispatch_via_service_manager_if_s6 helper to `s6-svc -u`).
|
||||
if not start:
|
||||
(tmp_dir / "down").touch()
|
||||
|
||||
# Pre-create the supervise/ skeleton with hermes ownership
|
||||
# BEFORE we publish the slot. Mirrors the same pre-creation
|
||||
# step in S6ServiceManager.register_profile_gateway — when
|
||||
# s6-svscan picks the published slot up, the s6-supervise it
|
||||
# spawns will EEXIST our dirs/FIFOs and inherit hermes
|
||||
# ownership, so runtime s6-svc / s6-svstat / s6-svwait calls
|
||||
# (all dispatched as the hermes user) won't hit EACCES. See
|
||||
# ``_seed_supervise_skeleton`` in service_manager.py for the
|
||||
# full rationale.
|
||||
_seed_supervise_skeleton(tmp_dir)
|
||||
|
||||
# Publish atomically. Path.replace handles the existing-target
|
||||
# case the same way os.rename does on POSIX: the target is
|
||||
# silently replaced, so a previous reconcile pass's slot is
|
||||
# cleanly overwritten in one operation.
|
||||
if service_dir.exists():
|
||||
shutil.rmtree(service_dir)
|
||||
tmp_dir.replace(service_dir)
|
||||
except Exception:
|
||||
shutil.rmtree(tmp_dir, ignore_errors=True)
|
||||
raise
|
||||
|
||||
|
||||
def _write_reconcile_log(
|
||||
hermes_home: Path, actions: list[ReconcileAction],
|
||||
) -> None:
|
||||
"""Append one line per profile to $HERMES_HOME/logs/container-boot.log.
|
||||
|
||||
Operators inspect this to debug "why didn't my profile come back
|
||||
up". Keeping a separate log file (vs. mixing into agent.log) lets
|
||||
troubleshooters grep for "profile=foo" without wading through
|
||||
unrelated activity.
|
||||
|
||||
Size-bounded: when the file exceeds ``_LOG_ROTATE_BYTES``
|
||||
(defaults to 256 KiB ≈ 3000 reconcile lines), the current file
|
||||
is renamed to ``container-boot.log.1`` (replacing any previous
|
||||
rotation) before the new entries are appended. This gives long-
|
||||
lived containers a soft cap of ~512 KiB across the two files
|
||||
without pulling in logrotate or s6-log machinery just for this
|
||||
one append-only file (PR #30136 review item O3).
|
||||
"""
|
||||
import time
|
||||
log_dir = hermes_home / "logs"
|
||||
log_dir.mkdir(parents=True, exist_ok=True)
|
||||
log_path = log_dir / "container-boot.log"
|
||||
|
||||
# Rotate before opening to append, so the new entries always land
|
||||
# in a fresh file when we crossed the threshold last time.
|
||||
try:
|
||||
if log_path.exists() and log_path.stat().st_size >= _LOG_ROTATE_BYTES:
|
||||
log_path.replace(log_dir / "container-boot.log.1")
|
||||
except OSError as exc:
|
||||
# Rotation failure is non-fatal — keep appending to the
|
||||
# existing file rather than losing the entry entirely.
|
||||
log.warning("could not rotate %s: %s", log_path, exc)
|
||||
|
||||
ts = time.strftime("%Y-%m-%dT%H:%M:%S%z")
|
||||
with log_path.open("a", encoding="utf-8") as f:
|
||||
for a in actions:
|
||||
f.write(
|
||||
f"{ts} profile={a.profile} prior_state={a.prior_state} "
|
||||
f"action={a.action}\n"
|
||||
)
|
||||
|
||||
|
||||
# 256 KiB soft cap on container-boot.log; rotated to .1 when crossed.
|
||||
# At ~80 B per reconcile-action line this is ~3000 lines, or about a
|
||||
# year of daily reboots on a 5-profile container. Two files = ~512 KiB
|
||||
# worst case. Tuned for visibility (small enough to grep / cat without
|
||||
# scrolling forever) more than space (the persistent volume has GB).
|
||||
_LOG_ROTATE_BYTES = 256 * 1024
|
||||
|
||||
|
||||
def main() -> int:
|
||||
"""Entry point invoked from /etc/cont-init.d/02-reconcile-profiles."""
|
||||
hermes_home = Path(os.environ.get("HERMES_HOME", "/opt/data"))
|
||||
scandir = Path(os.environ.get("S6_PROFILE_GATEWAY_SCANDIR", "/run/service"))
|
||||
actions = reconcile_profile_gateways(
|
||||
hermes_home=hermes_home, scandir=scandir,
|
||||
)
|
||||
for a in actions:
|
||||
print(
|
||||
f"reconcile: profile={a.profile} "
|
||||
f"prior_state={a.prior_state} action={a.action}"
|
||||
)
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
+85
-1
@@ -207,14 +207,69 @@ def _fail_and_issue(text: str, detail: str, fix: str, issues: list[str]) -> None
|
||||
issues.append(fix)
|
||||
|
||||
|
||||
def _check_s6_supervision(issues: list[str]) -> None:
|
||||
"""Inside a container under our s6 /init, surface what s6 sees.
|
||||
|
||||
Runs as a counterpart to :func:`_check_gateway_service_linger` for
|
||||
the systemd-on-host case. No-op everywhere except in the s6
|
||||
container so host runs aren't cluttered with irrelevant output.
|
||||
|
||||
Reports:
|
||||
- Whether the main-hermes and dashboard static services are up
|
||||
- How many per-profile gateway slots are registered (via
|
||||
``S6ServiceManager.list_profile_gateways()``) and how many are
|
||||
currently supervised as ``up``
|
||||
"""
|
||||
try:
|
||||
from hermes_cli.service_manager import (
|
||||
S6ServiceManager,
|
||||
detect_service_manager,
|
||||
)
|
||||
except Exception:
|
||||
return
|
||||
|
||||
if detect_service_manager() != "s6":
|
||||
return
|
||||
|
||||
_section("s6 Supervision")
|
||||
|
||||
mgr = S6ServiceManager()
|
||||
|
||||
# Static services. They live under /run/service/ via s6-rc symlinks,
|
||||
# so the same s6-svstat probe works.
|
||||
for static in ("main-hermes", "dashboard"):
|
||||
if mgr.is_running(static):
|
||||
check_ok(f"{static}: up")
|
||||
else:
|
||||
check_info(f"{static}: down (expected if not enabled via env)")
|
||||
|
||||
profiles = mgr.list_profile_gateways()
|
||||
if not profiles:
|
||||
check_info("No per-profile gateways registered yet — create one with `hermes profile create <name>`")
|
||||
return
|
||||
|
||||
up_count = sum(1 for p in profiles if mgr.is_running(f"gateway-{p}"))
|
||||
check_ok(
|
||||
f"Per-profile gateways: {up_count}/{len(profiles)} supervised up"
|
||||
+ (f" ({', '.join(sorted(profiles))})" if len(profiles) <= 8 else "")
|
||||
)
|
||||
|
||||
|
||||
def _check_gateway_service_linger(issues: list[str]) -> None:
|
||||
"""Warn when a systemd user gateway service will stop after logout."""
|
||||
"""Warn when a systemd user gateway service will stop after logout.
|
||||
|
||||
Skipped inside a container running under s6 — the linger concept
|
||||
(user-systemd surviving SSH logout) doesn't apply there, and the
|
||||
s6 supervision state is surfaced separately by
|
||||
``_check_s6_supervision``.
|
||||
"""
|
||||
try:
|
||||
from hermes_cli.gateway import (
|
||||
get_systemd_linger_status,
|
||||
get_systemd_unit_path,
|
||||
is_linux,
|
||||
)
|
||||
from hermes_cli.service_manager import detect_service_manager
|
||||
except Exception as e:
|
||||
check_warn("Gateway service linger", f"(could not import gateway helpers: {e})")
|
||||
return
|
||||
@@ -222,6 +277,12 @@ def _check_gateway_service_linger(issues: list[str]) -> None:
|
||||
if not is_linux():
|
||||
return
|
||||
|
||||
# Inside a container under our s6 /init, _check_s6_supervision
|
||||
# reports the live supervision state; the linger warning would be
|
||||
# confusing here (no systemd, no logout, no "lingering" concept).
|
||||
if detect_service_manager() == "s6":
|
||||
return
|
||||
|
||||
unit_path = get_systemd_unit_path()
|
||||
if not unit_path.exists():
|
||||
return
|
||||
@@ -984,6 +1045,7 @@ def run_doctor(args):
|
||||
pass
|
||||
|
||||
_check_gateway_service_linger(issues)
|
||||
_check_s6_supervision(issues)
|
||||
|
||||
if sys.platform != "win32":
|
||||
_section("Command Installation")
|
||||
@@ -1076,6 +1138,26 @@ def run_doctor(args):
|
||||
|
||||
# Docker (optional)
|
||||
terminal_env = os.getenv("TERMINAL_ENV", "local")
|
||||
try:
|
||||
from hermes_constants import is_container as _is_container
|
||||
running_in_container = _is_container()
|
||||
except Exception:
|
||||
running_in_container = False
|
||||
|
||||
if running_in_container:
|
||||
# Inside our container the Docker terminal backend is not
|
||||
# configured by default (Docker-in-Docker isn't set up); the
|
||||
# local backend is the intended one. Skip the noisy "docker
|
||||
# not found" warning. If the user has explicitly chosen
|
||||
# TERMINAL_ENV=docker inside the container they likely mounted
|
||||
# /var/run/docker.sock, so fall through to the normal check.
|
||||
if terminal_env != "docker":
|
||||
check_info(
|
||||
"Running inside a container — using local terminal backend "
|
||||
"(docker-in-docker is not configured by default)"
|
||||
)
|
||||
# Skip to next section; Docker isn't relevant here.
|
||||
terminal_env = "local"
|
||||
if terminal_env == "docker":
|
||||
if _safe_which("docker"):
|
||||
# Check if docker daemon is running
|
||||
@@ -1098,6 +1180,8 @@ def run_doctor(args):
|
||||
check_ok("docker", "(optional)")
|
||||
elif _is_termux():
|
||||
check_info("Docker backend is not available inside Termux (expected on Android)")
|
||||
elif running_in_container:
|
||||
pass # already explained above
|
||||
else:
|
||||
check_warn("docker not found", "(optional)")
|
||||
|
||||
|
||||
+179
-1
@@ -981,6 +981,18 @@ def get_gateway_runtime_snapshot(system: bool = False) -> GatewayRuntimeSnapshot
|
||||
from hermes_constants import is_container
|
||||
|
||||
if is_linux() and is_container():
|
||||
# Phase 4: report s6 supervision when running under our /init.
|
||||
# Other container runtimes (or containers built before Phase 2)
|
||||
# still get the original "docker (foreground)" label.
|
||||
try:
|
||||
from hermes_cli.service_manager import detect_service_manager
|
||||
if detect_service_manager() == "s6":
|
||||
return GatewayRuntimeSnapshot(
|
||||
manager="s6 (container supervisor)",
|
||||
gateway_pids=gateway_pids,
|
||||
)
|
||||
except Exception:
|
||||
pass # Fall through to the legacy label on any detection error.
|
||||
return GatewayRuntimeSnapshot(
|
||||
manager="docker (foreground)",
|
||||
gateway_pids=gateway_pids,
|
||||
@@ -1202,7 +1214,17 @@ def _systemd_operational(system: bool = False) -> bool:
|
||||
|
||||
|
||||
def _container_systemd_operational() -> bool:
|
||||
"""Return True when a container exposes working user or system systemd."""
|
||||
"""Return True when a container exposes working user or system systemd.
|
||||
|
||||
This is NOT our Hermes Docker image — that one runs s6-overlay as
|
||||
PID 1 (since Phase 2 of the s6-overlay supervision plan) and is
|
||||
detected via ``service_manager.detect_service_manager() == "s6"``.
|
||||
This function handles the "container managed by something else"
|
||||
case: systemd-nspawn, certain k8s pods, containers built FROM
|
||||
systemd-bearing distros where the user has wired systemd as their
|
||||
init. In those environments systemctl behaves identically to the
|
||||
host case, so we fall through to the normal systemd code paths.
|
||||
"""
|
||||
if _systemd_operational(system=False):
|
||||
return True
|
||||
if _systemd_operational(system=True):
|
||||
@@ -5005,6 +5027,108 @@ def gateway_setup():
|
||||
# Main Command Handler
|
||||
# =============================================================================
|
||||
|
||||
def _dispatch_via_service_manager_if_s6(
|
||||
action: str, profile: str | None = None,
|
||||
) -> bool:
|
||||
"""If we're in a container with s6, dispatch gateway lifecycle via s6.
|
||||
|
||||
Returns True iff dispatched (caller should ``return``); False
|
||||
otherwise — caller continues with the host-side code path.
|
||||
|
||||
``action`` is one of ``start`` / ``stop`` / ``restart``. The
|
||||
profile defaults to the current one (resolved via ``_profile_arg``).
|
||||
The s6 service slot was created either by the Phase 4 profile-create
|
||||
hook or by the container-boot reconciler (cont-init.d/02-…). If it
|
||||
doesn't exist or s6 returns an error, the named errors from
|
||||
:mod:`hermes_cli.service_manager` are caught and surfaced as
|
||||
actionable CLI messages (no raw ``CalledProcessError`` traceback).
|
||||
"""
|
||||
from hermes_cli.service_manager import (
|
||||
GatewayNotRegisteredError,
|
||||
S6CommandError,
|
||||
detect_service_manager,
|
||||
get_service_manager,
|
||||
)
|
||||
|
||||
if detect_service_manager() != "s6":
|
||||
return False
|
||||
if profile is None:
|
||||
# _profile_suffix() returns the bare profile name for
|
||||
# HERMES_HOME=<root>/profiles/<name>, "" for the default root,
|
||||
# or a hash for unrelated paths. Map "" → "default" so the
|
||||
# default-profile gateway is reachable as gateway-default.
|
||||
profile = _profile_suffix() or "default"
|
||||
mgr = get_service_manager()
|
||||
service_name = f"gateway-{profile}"
|
||||
try:
|
||||
if action == "start":
|
||||
mgr.start(service_name)
|
||||
elif action == "stop":
|
||||
mgr.stop(service_name)
|
||||
elif action == "restart":
|
||||
mgr.restart(service_name)
|
||||
else:
|
||||
return False
|
||||
except GatewayNotRegisteredError as exc:
|
||||
print(f"✗ {exc}")
|
||||
sys.exit(1)
|
||||
except S6CommandError as exc:
|
||||
print(f"✗ {exc}")
|
||||
sys.exit(1)
|
||||
return True
|
||||
|
||||
|
||||
def _dispatch_all_via_service_manager_if_s6(action: str) -> bool:
|
||||
"""Inside a container with s6, dispatch ``--all`` lifecycle to every
|
||||
registered profile gateway.
|
||||
|
||||
Returns True iff dispatched (caller should ``return``); False
|
||||
otherwise — caller continues with the host-side code path.
|
||||
|
||||
Without this, ``hermes gateway stop --all`` and ``... restart --all``
|
||||
fall through to ``kill_gateway_processes(all_profiles=True)``, which
|
||||
just ``pkill``s every gateway process. s6-supervise observes the
|
||||
crash and restarts each one ~1s later — so ``--all`` ends up
|
||||
*kicking* every gateway instead of *stopping* it. By iterating
|
||||
``list_profile_gateways()`` and sending the lifecycle command
|
||||
through the service manager we get the intended semantics (s6's
|
||||
``want up``/``want down`` flips correctly so supervise stays down
|
||||
after a stop).
|
||||
|
||||
``action`` is one of ``stop`` / ``restart`` (``start --all`` isn't
|
||||
a supported CLI surface).
|
||||
"""
|
||||
from hermes_cli.service_manager import (
|
||||
detect_service_manager,
|
||||
get_service_manager,
|
||||
)
|
||||
|
||||
if detect_service_manager() != "s6":
|
||||
return False
|
||||
if action not in ("stop", "restart"):
|
||||
return False
|
||||
mgr = get_service_manager()
|
||||
profiles = mgr.list_profile_gateways()
|
||||
if not profiles:
|
||||
print("✗ No profile gateways registered under s6")
|
||||
return True
|
||||
fn = mgr.stop if action == "stop" else mgr.restart
|
||||
errors: list[tuple[str, Exception]] = []
|
||||
for profile in profiles:
|
||||
service_name = f"gateway-{profile}"
|
||||
try:
|
||||
fn(service_name)
|
||||
except Exception as exc: # noqa: BLE001 — report and continue
|
||||
errors.append((profile, exc))
|
||||
succeeded = len(profiles) - len(errors)
|
||||
verb = "stopped" if action == "stop" else "restarted"
|
||||
if succeeded:
|
||||
print(f"✓ {verb.capitalize()} {succeeded} profile gateway(s) under s6")
|
||||
for profile, exc in errors:
|
||||
print(f"✗ Could not {action} gateway-{profile}: {exc}")
|
||||
return True
|
||||
|
||||
|
||||
def gateway_command(args):
|
||||
"""Handle gateway subcommands."""
|
||||
try:
|
||||
@@ -5089,6 +5213,21 @@ def _gateway_command_inner(args):
|
||||
print(" nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 & # background")
|
||||
sys.exit(1)
|
||||
elif is_container():
|
||||
# Phase 4: inside a container with s6 the gateway service is
|
||||
# auto-registered when the profile is created (and reconciled
|
||||
# at every container boot). `install` is therefore informational.
|
||||
from hermes_cli.service_manager import detect_service_manager
|
||||
if detect_service_manager() == "s6":
|
||||
print("Per-profile gateways are auto-registered when you create a profile.")
|
||||
print()
|
||||
print(" hermes profile create <name> # creates the s6 service slot")
|
||||
print(" hermes -p <name> gateway start # bring it up via s6")
|
||||
print(" hermes status # see currently-supervised gateways")
|
||||
return
|
||||
# Fallback for pre-s6 containers or other container runtimes
|
||||
# we haven't taught about supervision (Podman without our
|
||||
# /init, k8s plain runs, etc.) — the historical guidance still
|
||||
# applies.
|
||||
print("Service installation is not needed inside a Docker container.")
|
||||
print("The container runtime is your service manager — use Docker restart policies instead:")
|
||||
print()
|
||||
@@ -5119,6 +5258,13 @@ def _gateway_command_inner(args):
|
||||
from hermes_cli import gateway_windows
|
||||
gateway_windows.uninstall()
|
||||
elif is_container():
|
||||
from hermes_cli.service_manager import detect_service_manager
|
||||
if detect_service_manager() == "s6":
|
||||
print("Per-profile gateways are auto-unregistered when you delete the profile.")
|
||||
print()
|
||||
print(" hermes profile delete <name> # tears down the s6 service slot")
|
||||
print(" hermes -p <name> gateway stop # stop without deleting the profile")
|
||||
return
|
||||
print("Service uninstall is not applicable inside a Docker container.")
|
||||
print("To stop the gateway, stop or remove the container:")
|
||||
print()
|
||||
@@ -5133,6 +5279,14 @@ def _gateway_command_inner(args):
|
||||
system = getattr(args, 'system', False)
|
||||
start_all = getattr(args, 'all', False)
|
||||
|
||||
# Phase 4: inside a container with s6, dispatch via the service
|
||||
# manager instead of falling through to systemd/launchd/windows.
|
||||
# `--all` isn't meaningful here (each profile has its own service
|
||||
# slot — start them individually via `hermes -p <name> gateway
|
||||
# start`), so just bring up the current profile's slot.
|
||||
if not start_all and _dispatch_via_service_manager_if_s6("start"):
|
||||
return
|
||||
|
||||
if start_all:
|
||||
# Kill all stale gateway processes across all profiles before starting
|
||||
killed = kill_gateway_processes(all_profiles=True)
|
||||
@@ -5162,6 +5316,11 @@ def _gateway_command_inner(args):
|
||||
print("To enable systemd: add systemd=true to /etc/wsl.conf and run 'wsl --shutdown' from PowerShell.")
|
||||
sys.exit(1)
|
||||
elif is_container():
|
||||
# Reached only when s6 ISN'T running (the early dispatch
|
||||
# above handles the s6 case). Pre-s6 containers or other
|
||||
# container runtimes that don't ship our /init get the
|
||||
# historical guidance: the gateway is the container's main
|
||||
# process, so use docker lifecycle commands.
|
||||
print("Service start is not applicable inside a Docker container.")
|
||||
print("The gateway runs as the container's main process.")
|
||||
print()
|
||||
@@ -5178,6 +5337,15 @@ def _gateway_command_inner(args):
|
||||
stop_all = getattr(args, 'all', False)
|
||||
system = getattr(args, 'system', False)
|
||||
|
||||
# Phase 4: inside a container with s6, dispatch via the service
|
||||
# manager. ``--all`` iterates every registered profile gateway
|
||||
# through s6 (otherwise it would fall through to ``pkill``,
|
||||
# which s6-supervise observes as a crash and immediately restarts).
|
||||
if stop_all and _dispatch_all_via_service_manager_if_s6("stop"):
|
||||
return
|
||||
if not stop_all and _dispatch_via_service_manager_if_s6("stop"):
|
||||
return
|
||||
|
||||
if stop_all:
|
||||
# --all: kill every gateway process on the machine
|
||||
service_available = False
|
||||
@@ -5247,6 +5415,16 @@ def _gateway_command_inner(args):
|
||||
restart_all = getattr(args, 'all', False)
|
||||
service_configured = False
|
||||
|
||||
# Phase 4: inside a container with s6, dispatch via the service
|
||||
# manager (s6-svc -t restarts the supervised process). ``--all``
|
||||
# iterates every registered profile gateway through s6; without
|
||||
# this it would fall through to ``pkill``, which s6-supervise
|
||||
# would observe as a crash and immediately restart anyway.
|
||||
if restart_all and _dispatch_all_via_service_manager_if_s6("restart"):
|
||||
return
|
||||
if not restart_all and _dispatch_via_service_manager_if_s6("restart"):
|
||||
return
|
||||
|
||||
if restart_all:
|
||||
# --all: stop every gateway process across all profiles, then start fresh
|
||||
service_stopped = False
|
||||
|
||||
@@ -777,6 +777,14 @@ def create_profile(
|
||||
except Exception:
|
||||
pass # non-fatal — user can describe later with `hermes profile describe`
|
||||
|
||||
# Phase 4: when running inside a container under s6, register the
|
||||
# new profile's gateway as a runtime s6 service so
|
||||
# `hermes -p <profile> gateway start` can supervise it via
|
||||
# `s6-svc -u` instead of spawning a bare process. On host (systemd
|
||||
# / launchd / windows) this is a no-op — the existing per-profile
|
||||
# unit-generation paths handle gateway lifecycle.
|
||||
_maybe_register_gateway_service(canon)
|
||||
|
||||
return profile_dir
|
||||
|
||||
|
||||
@@ -893,6 +901,10 @@ def delete_profile(name: str, yes: bool = False) -> Path:
|
||||
|
||||
# 1. Disable service (prevents auto-restart)
|
||||
_cleanup_gateway_service(canon, profile_dir)
|
||||
# 1b. Phase 4: unregister the s6 service slot (container path).
|
||||
# On host this is a no-op; on container it removes
|
||||
# /run/service/gateway-<profile>/ so s6-supervise drops it.
|
||||
_maybe_unregister_gateway_service(canon)
|
||||
|
||||
# 2. Stop running gateway
|
||||
if gw_running:
|
||||
@@ -965,6 +977,87 @@ def delete_profile(name: str, yes: bool = False) -> Path:
|
||||
return profile_dir
|
||||
|
||||
|
||||
def _maybe_register_gateway_service(profile_name: str) -> None:
|
||||
"""Register a profile's gateway with s6 inside the container.
|
||||
|
||||
No-op on host (systemd/launchd/windows) — those backends raise
|
||||
``NotImplementedError`` on ``register_profile_gateway`` and the
|
||||
existing per-profile unit-generation paths handle lifecycle.
|
||||
|
||||
Best-effort: any error (no backend detected, s6 not yet ready,
|
||||
etc.) is logged and swallowed so profile creation doesn't fail
|
||||
because the s6 supervision tree is in a weird state. The user
|
||||
can re-register manually later via the gateway start command,
|
||||
which goes through the same dispatch path.
|
||||
|
||||
Port selection is governed by the profile's ``config.yaml``
|
||||
(``[gateway] port = …``) — there is no Python-side allocator
|
||||
(PR #30136 review item I5 retired the SHA-256-derived range
|
||||
[9200, 9800) because it was dead code through the entire stack).
|
||||
|
||||
Host short-circuit: check ``detect_service_manager()`` first and
|
||||
return immediately if it isn't ``"s6"``. This keeps host
|
||||
(systemd/launchd/windows) profile creation completely silent —
|
||||
no ``get_service_manager()`` call, no exception path, no chance
|
||||
of the ``⚠ Could not register s6 gateway service`` warning ever
|
||||
rendering on a non-container machine. The earlier
|
||||
``supports_runtime_registration()`` check still catches the case
|
||||
where detection somehow returns ``"s6"`` but the backend isn't
|
||||
actually the S6 one.
|
||||
"""
|
||||
try:
|
||||
from hermes_cli.service_manager import detect_service_manager
|
||||
if detect_service_manager() != "s6":
|
||||
return # host path — silent, no registration needed
|
||||
from hermes_cli.service_manager import get_service_manager
|
||||
mgr = get_service_manager()
|
||||
except RuntimeError:
|
||||
return # no backend on this host — nothing to do
|
||||
except Exception:
|
||||
# Defensive: detect_service_manager failed for some other
|
||||
# reason. Stay silent on host rather than printing a confusing
|
||||
# s6 warning to users who have never touched the container.
|
||||
return
|
||||
if not mgr.supports_runtime_registration():
|
||||
return # host backend; no-op
|
||||
try:
|
||||
mgr.register_profile_gateway(profile_name)
|
||||
except ValueError:
|
||||
# Already registered (e.g. the container-boot reconciler ran
|
||||
# first and brought up a stale slot). That's fine.
|
||||
pass
|
||||
except Exception as exc:
|
||||
# Don't fail profile create over a supervision-tree hiccup.
|
||||
print(f"⚠ Could not register s6 gateway service: {exc}")
|
||||
|
||||
|
||||
def _maybe_unregister_gateway_service(profile_name: str) -> None:
|
||||
"""Tear down a profile's s6 gateway service inside the container.
|
||||
|
||||
No-op on host. Idempotent: absent services are silently skipped
|
||||
by ``unregister_profile_gateway``.
|
||||
|
||||
Same host short-circuit as :func:`_maybe_register_gateway_service`
|
||||
— see that docstring.
|
||||
"""
|
||||
try:
|
||||
from hermes_cli.service_manager import detect_service_manager
|
||||
if detect_service_manager() != "s6":
|
||||
return # host path — silent
|
||||
from hermes_cli.service_manager import get_service_manager
|
||||
mgr = get_service_manager()
|
||||
except RuntimeError:
|
||||
return
|
||||
except Exception:
|
||||
return
|
||||
if not mgr.supports_runtime_registration():
|
||||
return
|
||||
try:
|
||||
mgr.unregister_profile_gateway(profile_name)
|
||||
except Exception as exc:
|
||||
print(f"⚠ Could not unregister s6 gateway service: {exc}")
|
||||
|
||||
|
||||
def _cleanup_gateway_service(name: str, profile_dir: Path) -> None:
|
||||
"""Disable and remove systemd/launchd service for a profile."""
|
||||
import platform as _platform
|
||||
|
||||
@@ -0,0 +1,886 @@
|
||||
"""Abstract service manager interface.
|
||||
|
||||
Wraps the existing systemd (Linux host), launchd (macOS host), Windows
|
||||
Scheduled Task (native Windows host), and s6 (container) backends behind
|
||||
a common Protocol. Only the s6 backend supports runtime registration
|
||||
(for per-profile gateways) — host backends raise NotImplementedError
|
||||
from those methods, and callers MUST check supports_runtime_registration()
|
||||
before invoking them.
|
||||
|
||||
Host-side call sites (setup wizard, uninstall, status) continue to use
|
||||
the existing module-level functions in hermes_cli.gateway and
|
||||
hermes_cli.gateway_windows directly. This protocol is a thin facade
|
||||
used by new code that needs to be backend-agnostic — specifically the
|
||||
profile create/delete hooks (Phase 4) and the s6 dispatch path in
|
||||
``hermes gateway start/stop/restart`` when running inside a container.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import Literal, Protocol, runtime_checkable
|
||||
|
||||
ServiceManagerKind = Literal["systemd", "launchd", "windows", "s6", "none"]
|
||||
|
||||
# Profile name → service directory mapping. Profile names must be safe
|
||||
# as filesystem directory names because the s6 backend creates a service
|
||||
# directory at ``<scandir>/gateway-<profile>/``. We reject anything that
|
||||
# could traverse paths, span filesystems, or break s6's own naming rules.
|
||||
_VALID_PROFILE_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
|
||||
_MAX_PROFILE_LEN = 251 # s6-svscan default name_max
|
||||
|
||||
|
||||
def validate_profile_name(name: str) -> None:
|
||||
"""Raise ValueError if ``name`` is not usable as a profile name.
|
||||
|
||||
Profile names are used as s6 service directory names, so they must
|
||||
match a conservative subset of filesystem-safe characters. Reject
|
||||
empty strings, uppercase, paths-traversal sequences, and anything
|
||||
longer than s6's default ``name_max``.
|
||||
"""
|
||||
if not name:
|
||||
raise ValueError("profile name must not be empty")
|
||||
if len(name) > _MAX_PROFILE_LEN:
|
||||
raise ValueError(
|
||||
f"profile name too long ({len(name)} > {_MAX_PROFILE_LEN})"
|
||||
)
|
||||
if not _VALID_PROFILE_RE.match(name):
|
||||
raise ValueError(
|
||||
f"profile name must match [a-z0-9][a-z0-9_-]*, got {name!r}"
|
||||
)
|
||||
|
||||
|
||||
@runtime_checkable
|
||||
class ServiceManager(Protocol):
|
||||
"""Abstract interface for init-system-specific service operations.
|
||||
|
||||
Lifecycle methods (start / stop / restart / is_running) are
|
||||
implemented by every backend. Runtime registration
|
||||
(register_profile_gateway / unregister_profile_gateway /
|
||||
list_profile_gateways) is implemented only by the s6 backend —
|
||||
callers MUST check ``supports_runtime_registration()`` before
|
||||
invoking the registration methods.
|
||||
"""
|
||||
|
||||
kind: ServiceManagerKind
|
||||
|
||||
# Lifecycle of a pre-declared service.
|
||||
def start(self, name: str) -> None: ...
|
||||
def stop(self, name: str) -> None: ...
|
||||
def restart(self, name: str) -> None: ...
|
||||
def is_running(self, name: str) -> bool: ...
|
||||
|
||||
# Runtime registration (s6 only).
|
||||
def supports_runtime_registration(self) -> bool: ...
|
||||
def register_profile_gateway(
|
||||
self,
|
||||
profile: str,
|
||||
*,
|
||||
extra_env: dict[str, str] | None = None,
|
||||
) -> None: ...
|
||||
def unregister_profile_gateway(self, profile: str) -> None: ...
|
||||
def list_profile_gateways(self) -> list[str]: ...
|
||||
|
||||
|
||||
def detect_service_manager() -> ServiceManagerKind:
|
||||
"""Detect which service manager is available in this environment.
|
||||
|
||||
Returns:
|
||||
"s6" — inside a container when /init is s6-svscan (Phase 2+)
|
||||
"windows" — native Windows host
|
||||
"launchd" — macOS host
|
||||
"systemd" — Linux host with a working user/system bus
|
||||
"none" — anything else (Termux, sandbox shells, etc.)
|
||||
|
||||
This function does NOT replace ``supports_systemd_services()`` —
|
||||
host call sites continue to use that. It exists for new backend-
|
||||
agnostic code (profile create/delete hooks, the s6 dispatch path
|
||||
in ``hermes gateway start/stop/restart``).
|
||||
"""
|
||||
# Imports deferred so importing this module doesn't drag in the
|
||||
# whole gateway dependency graph for callers that only need the
|
||||
# Protocol type or validate_profile_name().
|
||||
from hermes_constants import is_container
|
||||
from hermes_cli.gateway import (
|
||||
is_macos,
|
||||
is_windows,
|
||||
supports_systemd_services,
|
||||
)
|
||||
|
||||
if is_container() and _s6_running():
|
||||
return "s6"
|
||||
if is_windows():
|
||||
return "windows"
|
||||
if is_macos():
|
||||
return "launchd"
|
||||
if supports_systemd_services():
|
||||
return "systemd"
|
||||
return "none"
|
||||
|
||||
|
||||
def _s6_running() -> bool:
|
||||
"""True when s6-svscan is running as PID 1 in this container.
|
||||
|
||||
Detection has to work for **both** root and the unprivileged hermes
|
||||
user (UID 10000). The obvious probe — ``Path('/proc/1/exe').resolve()``
|
||||
— only works as root: for any other UID, the symlink at
|
||||
``/proc/1/exe`` is unreadable and ``resolve()`` silently returns the
|
||||
path unchanged, so the resolved name is the literal ``"exe"`` and
|
||||
detection always fails. Since every Hermes runtime call inside the
|
||||
container drops to hermes via ``s6-setuidgid``, that silent failure
|
||||
made the entire service-manager runtime-registration path inert in
|
||||
production (PR #30136 review).
|
||||
|
||||
Probe instead via:
|
||||
* ``/proc/1/comm`` — world-readable, contains the process comm
|
||||
(``s6-svscan`` when s6-overlay is PID 1).
|
||||
* ``/run/s6/basedir`` — s6-overlay-specific directory created by
|
||||
stage1. World-readable. More specific than ``/run/s6`` (which
|
||||
other tools occasionally create).
|
||||
|
||||
Both signals are required; either alone could false-positive
|
||||
(e.g. a container with the s6 binaries installed but a different
|
||||
init, or an unrelated process named ``s6-svscan``).
|
||||
"""
|
||||
try:
|
||||
comm = Path("/proc/1/comm").read_text(encoding="utf-8").strip()
|
||||
except OSError:
|
||||
return False
|
||||
if comm != "s6-svscan":
|
||||
return False
|
||||
return Path("/run/s6/basedir").is_dir()
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Backend wrappers
|
||||
#
|
||||
# These adapters are thin facades over the existing module-level functions
|
||||
# in ``hermes_cli.gateway`` (systemd/launchd) and ``hermes_cli.gateway_windows``
|
||||
# (Windows Scheduled Tasks). The protocol's ``name`` parameter is currently
|
||||
# unused for host backends — they operate on whichever profile is currently
|
||||
# active (set via the ``hermes -p <profile>`` flag before the call). This
|
||||
# matches existing host-side semantics; the parameter shape is designed
|
||||
# for s6 where each profile maps to a distinct service directory.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class _RegistrationUnsupportedMixin:
|
||||
"""Mixin for host backends that don't support runtime registration."""
|
||||
|
||||
def supports_runtime_registration(self) -> bool:
|
||||
return False
|
||||
|
||||
def register_profile_gateway(
|
||||
self,
|
||||
profile: str,
|
||||
*,
|
||||
extra_env: dict[str, str] | None = None,
|
||||
) -> None:
|
||||
raise NotImplementedError(
|
||||
f"{type(self).__name__} does not support runtime profile "
|
||||
"gateway registration (container-only feature)"
|
||||
)
|
||||
|
||||
def unregister_profile_gateway(self, profile: str) -> None:
|
||||
raise NotImplementedError(
|
||||
f"{type(self).__name__} does not support runtime profile "
|
||||
"gateway unregistration (container-only feature)"
|
||||
)
|
||||
|
||||
def list_profile_gateways(self) -> list[str]:
|
||||
return []
|
||||
|
||||
|
||||
class SystemdServiceManager(_RegistrationUnsupportedMixin):
|
||||
"""Thin wrapper around the ``systemd_*`` functions in hermes_cli.gateway.
|
||||
|
||||
Existing host call sites continue to use those functions directly;
|
||||
this wrapper exists for new code that needs to be backend-agnostic
|
||||
(the Phase 4 profile create/delete hooks).
|
||||
"""
|
||||
|
||||
kind: ServiceManagerKind = "systemd"
|
||||
|
||||
def start(self, name: str) -> None:
|
||||
from hermes_cli.gateway import systemd_start
|
||||
systemd_start()
|
||||
|
||||
def stop(self, name: str) -> None:
|
||||
from hermes_cli.gateway import systemd_stop
|
||||
systemd_stop()
|
||||
|
||||
def restart(self, name: str) -> None:
|
||||
from hermes_cli.gateway import systemd_restart
|
||||
systemd_restart()
|
||||
|
||||
def is_running(self, name: str) -> bool:
|
||||
from hermes_cli.gateway import _probe_systemd_service_running
|
||||
_, running = _probe_systemd_service_running()
|
||||
return running
|
||||
|
||||
|
||||
class LaunchdServiceManager(_RegistrationUnsupportedMixin):
|
||||
"""Thin wrapper around the ``launchd_*`` functions in hermes_cli.gateway."""
|
||||
|
||||
kind: ServiceManagerKind = "launchd"
|
||||
|
||||
def start(self, name: str) -> None:
|
||||
from hermes_cli.gateway import launchd_start
|
||||
launchd_start()
|
||||
|
||||
def stop(self, name: str) -> None:
|
||||
from hermes_cli.gateway import launchd_stop
|
||||
launchd_stop()
|
||||
|
||||
def restart(self, name: str) -> None:
|
||||
from hermes_cli.gateway import launchd_restart
|
||||
launchd_restart()
|
||||
|
||||
def is_running(self, name: str) -> bool:
|
||||
from hermes_cli.gateway import _probe_launchd_service_running
|
||||
return _probe_launchd_service_running()
|
||||
|
||||
|
||||
class WindowsServiceManager(_RegistrationUnsupportedMixin):
|
||||
"""Thin wrapper around ``hermes_cli.gateway_windows`` (Scheduled Task /
|
||||
Startup-folder fallback).
|
||||
|
||||
The native Windows backend uses a Scheduled Task rather than a true
|
||||
init-system service, but for protocol purposes the lifecycle is the
|
||||
same: start / stop / restart / is_running. ``install`` accepts a
|
||||
handful of Windows-specific kwargs (start_now, start_on_login,
|
||||
elevated_handoff) that are passed straight through — non-Windows
|
||||
callers should never invoke ``install`` on this wrapper.
|
||||
"""
|
||||
|
||||
kind: ServiceManagerKind = "windows"
|
||||
|
||||
def install(
|
||||
self,
|
||||
*,
|
||||
force: bool = False,
|
||||
start_now: bool | None = None,
|
||||
start_on_login: bool | None = None,
|
||||
elevated_handoff: bool = False,
|
||||
) -> None:
|
||||
from hermes_cli import gateway_windows
|
||||
gateway_windows.install(
|
||||
force=force,
|
||||
start_now=start_now,
|
||||
start_on_login=start_on_login,
|
||||
elevated_handoff=elevated_handoff,
|
||||
)
|
||||
|
||||
def start(self, name: str) -> None:
|
||||
from hermes_cli import gateway_windows
|
||||
gateway_windows.start()
|
||||
|
||||
def stop(self, name: str) -> None:
|
||||
from hermes_cli import gateway_windows
|
||||
gateway_windows.stop()
|
||||
|
||||
def restart(self, name: str) -> None:
|
||||
from hermes_cli import gateway_windows
|
||||
gateway_windows.restart()
|
||||
|
||||
def is_running(self, name: str) -> bool:
|
||||
from hermes_cli import gateway_windows
|
||||
from hermes_cli.gateway import find_gateway_pids
|
||||
if not gateway_windows.is_installed():
|
||||
return False
|
||||
return bool(find_gateway_pids())
|
||||
|
||||
|
||||
def get_service_manager() -> ServiceManager:
|
||||
"""Return the ServiceManager instance for the current environment.
|
||||
|
||||
Raises:
|
||||
RuntimeError: when no supported backend is available.
|
||||
"""
|
||||
kind = detect_service_manager()
|
||||
if kind == "systemd":
|
||||
return SystemdServiceManager()
|
||||
if kind == "launchd":
|
||||
return LaunchdServiceManager()
|
||||
if kind == "windows":
|
||||
return WindowsServiceManager()
|
||||
if kind == "s6":
|
||||
return S6ServiceManager()
|
||||
raise RuntimeError("no supported service manager detected")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# S6ServiceManager (container-only)
|
||||
#
|
||||
# Per-profile gateways are registered dynamically when `hermes profile create`
|
||||
# runs inside the container (Phase 4). Static services (main-hermes, dashboard)
|
||||
# live in /etc/s6-overlay/s6-rc.d/ and are NOT managed by this class — they're
|
||||
# part of the image, not runtime-created.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
# s6-overlay's dynamic scandir for runtime-registered services. Lives on
|
||||
# tmpfs and is the directory s6-svscan watches. Writes here trigger
|
||||
# automatic supervision on the next rescan.
|
||||
S6_DYNAMIC_SCANDIR = Path("/run/service")
|
||||
S6_SERVICE_PREFIX = "gateway-"
|
||||
|
||||
# s6-overlay installs its binaries under /command/ and only adds that
|
||||
# directory to PATH for processes started under the supervision tree
|
||||
# (services started by s6-svscan, cont-init.d scripts, etc.). Code
|
||||
# that runs via `docker exec` or any other out-of-tree entry point —
|
||||
# notably our Phase 4 profile create/delete hooks — inherits the
|
||||
# container's base PATH which does NOT include /command/.
|
||||
#
|
||||
# Rather than asking every caller to fix up its environment, the
|
||||
# S6ServiceManager calls s6-* binaries by absolute path via this
|
||||
# constant. We don't use `/usr/bin/s6-…` symlinks because the
|
||||
# s6-overlay-symlinks-noarch tarball only links a subset, and we
|
||||
# want every s6 invocation to be guaranteed-findable.
|
||||
_S6_BIN_DIR = "/command"
|
||||
|
||||
|
||||
# UID/GID of the in-image ``hermes`` user. Hardcoded to match what
|
||||
# ``stage2-hook.sh`` enforces (the runtime invariant — see also
|
||||
# tests/docker/test_uid_remap.py). The container starts s6-supervise
|
||||
# under root and immediately drops to this UID via ``s6-setuidgid``.
|
||||
_HERMES_UID = 10000
|
||||
_HERMES_GID = 10000
|
||||
|
||||
|
||||
def _seed_supervise_skeleton(svc_dir: Path) -> None:
|
||||
"""Pre-create the ``supervise/`` and top-level ``event/`` skeleton
|
||||
inside a service directory, owned by the hermes user.
|
||||
|
||||
Why this exists
|
||||
---------------
|
||||
When s6-supervise spawns a service it tries to ``mkdir`` two
|
||||
directories: ``<svc>/event`` and ``<svc>/supervise``, both with mode
|
||||
``0700``. It also ``mkfifo``s ``<svc>/supervise/control`` with mode
|
||||
``0600``. Because s6-supervise runs as PID 1's effective UID (root)
|
||||
these dirs end up root-owned mode 0700, and an unprivileged client
|
||||
(the ``hermes`` user — UID 10000 — running every Hermes runtime
|
||||
operation via ``s6-setuidgid``) gets ``EACCES`` on any ``s6-svc``,
|
||||
``s6-svstat``, or ``s6-svwait`` invocation against the slot.
|
||||
|
||||
The PR #30136 review surfaced this as a real product gap: the
|
||||
entire S6ServiceManager lifecycle (``register/start/stop/unregister
|
||||
_profile_gateway``) was inert in production because every operation
|
||||
is dispatched as the hermes user.
|
||||
|
||||
Why this works
|
||||
--------------
|
||||
Reading s6's source (src/supervision/s6-supervise.c::trymkdir +
|
||||
control_init): the ``mkdir`` and ``mkfifo`` calls both treat
|
||||
``EEXIST`` as success. If the directory is already present, the
|
||||
chown/chmod fix-up that would normally make event/ ``03730
|
||||
root:root`` is **skipped** entirely — s6-supervise just opens the
|
||||
pre-existing FIFOs and proceeds. So if we lay the skeleton down
|
||||
with hermes ownership before triggering ``s6-svscanctl -a``,
|
||||
s6-supervise inherits our layout and never touches it.
|
||||
|
||||
Layout produced
|
||||
---------------
|
||||
``svc_dir/`` hermes:hermes, 0755 (parent must already exist)
|
||||
``svc_dir/event/`` hermes:hermes, 03730 (setgid + g+rwx + sticky)
|
||||
``svc_dir/supervise/`` hermes:hermes, 0755
|
||||
``svc_dir/supervise/event/`` hermes:hermes, 03730
|
||||
``svc_dir/supervise/control`` hermes:hermes, 0660 (FIFO)
|
||||
|
||||
The ``death_tally``, ``lock``, and ``status`` regular files end up
|
||||
written by s6-supervise itself (as root), but those land mode 0644 —
|
||||
world-readable — and ``s6-svstat`` only needs read access, so the
|
||||
hermes user reads them fine.
|
||||
|
||||
If ``svc_dir/log/`` is present (the canonical s6 logger pattern —
|
||||
one s6-supervise instance per service, plus a second for its
|
||||
logger), the same skeleton is seeded under ``log/`` as well:
|
||||
``log/event/``, ``log/supervise/``, ``log/supervise/event/``,
|
||||
``log/supervise/control``. Without this, unregister teardown
|
||||
would EACCES on the logger's supervise dir even after the parent
|
||||
slot's supervise/ was hermes-owned.
|
||||
|
||||
Idempotency
|
||||
-----------
|
||||
Safe to call against a directory where the skeleton already exists.
|
||||
Existing entries are left untouched (the helper doesn't try to
|
||||
re-chown / re-chmod live FIFOs that s6-supervise may have already
|
||||
opened).
|
||||
|
||||
Reference
|
||||
---------
|
||||
Discussed at length on the skarnet `skaware` mailing list in 2020
|
||||
(`<http://skarnet.org/lists/skaware/1424.html>`_); see also
|
||||
just-containers/s6-overlay#130. The pre-creation pattern was
|
||||
historically called out as forward-compatibility-fragile, but the
|
||||
EEXIST handling in s6-supervise has been stable since 2015 — it's
|
||||
the same pattern ``s6-svperms`` and ``fix-attrs.d`` rely on.
|
||||
"""
|
||||
import os
|
||||
|
||||
def _mkdir_owned(path: Path, mode: int) -> None:
|
||||
if path.exists():
|
||||
return
|
||||
path.mkdir(parents=False, exist_ok=False)
|
||||
path.chmod(mode)
|
||||
try:
|
||||
os.chown(path, _HERMES_UID, _HERMES_GID)
|
||||
except PermissionError:
|
||||
# Running as the hermes user already — directory is hermes-
|
||||
# owned by default. The chown is a no-op in that case, so
|
||||
# swallowing this keeps both root and unprivileged callers
|
||||
# on one code path.
|
||||
pass
|
||||
|
||||
# Top-level event/ dir (this is the s6-svlisten1 event-subscription
|
||||
# dir at the service root, distinct from supervise/event/).
|
||||
_mkdir_owned(svc_dir / "event", 0o3730)
|
||||
|
||||
# supervise/ dir + its inner event/ dir.
|
||||
supervise = svc_dir / "supervise"
|
||||
_mkdir_owned(supervise, 0o755)
|
||||
_mkdir_owned(supervise / "event", 0o3730)
|
||||
|
||||
# supervise/control FIFO. Same EEXIST-safe pattern: if it's already
|
||||
# there (s6-supervise has already started against this slot), leave
|
||||
# it alone. The explicit chmod after mkfifo is required because
|
||||
# mkfifo honors the process umask, which can strip group-write
|
||||
# (e.g. the default 0022 on most dev hosts → 0o660 becomes 0o640).
|
||||
# The container runs with umask 0 inside s6-overlay's stage2, but
|
||||
# being defensive here keeps the helper consistent under any
|
||||
# invocation context.
|
||||
control = supervise / "control"
|
||||
if not control.exists():
|
||||
os.mkfifo(control, 0o660)
|
||||
control.chmod(0o660)
|
||||
try:
|
||||
os.chown(control, _HERMES_UID, _HERMES_GID)
|
||||
except PermissionError:
|
||||
pass
|
||||
|
||||
# If a log/ subdir is present (the canonical s6 logger pattern —
|
||||
# see servicedir(7)), it gets its own s6-supervise instance and
|
||||
# needs the same skeleton. Without this, unregister teardown
|
||||
# would EACCES on the logger's root-owned supervise/ dir even
|
||||
# when the parent slot's supervise/ is hermes-owned.
|
||||
log_dir = svc_dir / "log"
|
||||
if log_dir.is_dir():
|
||||
_mkdir_owned(log_dir / "event", 0o3730)
|
||||
log_supervise = log_dir / "supervise"
|
||||
_mkdir_owned(log_supervise, 0o755)
|
||||
_mkdir_owned(log_supervise / "event", 0o3730)
|
||||
log_control = log_supervise / "control"
|
||||
if not log_control.exists():
|
||||
os.mkfifo(log_control, 0o660)
|
||||
log_control.chmod(0o660)
|
||||
try:
|
||||
os.chown(log_control, _HERMES_UID, _HERMES_GID)
|
||||
except PermissionError:
|
||||
pass
|
||||
|
||||
|
||||
class S6Error(RuntimeError):
|
||||
"""Base error for S6ServiceManager lifecycle failures.
|
||||
|
||||
Concrete subclasses carry the slot name (and, where useful, the
|
||||
underlying subprocess output) so the CLI can render an actionable
|
||||
message instead of leaking a raw ``CalledProcessError`` traceback.
|
||||
"""
|
||||
|
||||
def __init__(self, message: str, *, service: str | None = None) -> None:
|
||||
super().__init__(message)
|
||||
self.service = service
|
||||
|
||||
|
||||
class GatewayNotRegisteredError(S6Error):
|
||||
"""Raised when a lifecycle method targets a slot that doesn't exist.
|
||||
|
||||
Most commonly: ``hermes -p typo gateway start`` when no profile
|
||||
``typo`` exists. Carries the unprefixed profile name (not the
|
||||
full ``gateway-<profile>`` service-dir name) so callers can phrase
|
||||
a user-facing message like "no such gateway 'typo'".
|
||||
"""
|
||||
|
||||
def __init__(self, profile: str) -> None:
|
||||
self.profile = profile
|
||||
super().__init__(
|
||||
f"no such gateway {profile!r}: register it with "
|
||||
f"`hermes profile create {profile}` first, or pass "
|
||||
"an existing profile name via `-p <name>`",
|
||||
service=f"gateway-{profile}",
|
||||
)
|
||||
|
||||
|
||||
class S6CommandError(S6Error):
|
||||
"""Raised when an s6 command fails for a reason other than a
|
||||
missing slot — e.g. permission denied on the supervise control
|
||||
FIFO, or s6-svc returning a non-zero exit for an unexpected
|
||||
reason. Carries the stderr from the failing command so callers
|
||||
can surface it.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self, *, service: str, action: str, returncode: int, stderr: str,
|
||||
) -> None:
|
||||
self.action = action
|
||||
self.returncode = returncode
|
||||
self.stderr = stderr
|
||||
message = (
|
||||
f"s6-svc {action} on {service!r} failed (rc={returncode})"
|
||||
)
|
||||
if stderr.strip():
|
||||
message += f": {stderr.strip()}"
|
||||
super().__init__(message, service=service)
|
||||
|
||||
|
||||
class S6ServiceManager:
|
||||
"""Per-profile gateway supervision via s6-overlay.
|
||||
|
||||
Only handles runtime-registered services under
|
||||
``S6_DYNAMIC_SCANDIR``. Static services (main-hermes, dashboard)
|
||||
are managed by s6-rc at image-build time and are out of scope.
|
||||
"""
|
||||
|
||||
kind: ServiceManagerKind = "s6"
|
||||
|
||||
def __init__(self, scandir: Path = S6_DYNAMIC_SCANDIR) -> None:
|
||||
self.scandir = scandir
|
||||
|
||||
# -- internal helpers --------------------------------------------------
|
||||
|
||||
def _service_dir(self, profile: str) -> Path:
|
||||
validate_profile_name(profile)
|
||||
return self.scandir / f"{S6_SERVICE_PREFIX}{profile}"
|
||||
|
||||
def _service_name(self, profile: str) -> str:
|
||||
return f"{S6_SERVICE_PREFIX}{profile}"
|
||||
|
||||
@staticmethod
|
||||
def _render_run_script(
|
||||
profile: str,
|
||||
extra_env: dict[str, str],
|
||||
) -> str:
|
||||
"""Generate the run script for a profile-gateway s6 service.
|
||||
|
||||
The script:
|
||||
1. Sources HERMES_HOME (and any extra env) via with-contenv —
|
||||
so e.g. ``-e HERMES_HOME=/data/hermes`` is honored at run
|
||||
time, not Python-substituted at registration time (OQ8-C).
|
||||
2. Activates the bundled venv.
|
||||
3. Drops to the hermes user and exec's
|
||||
``hermes -p <profile> gateway run`` (or just ``hermes
|
||||
gateway run`` for the default profile — see below).
|
||||
|
||||
Special case: ``profile == "default"`` emits ``hermes gateway
|
||||
run`` with **no** ``-p`` flag. This is the sentinel for "the
|
||||
root HERMES_HOME profile" (the implicit profile that exists at
|
||||
the top of $HERMES_HOME, not under profiles/). It must be
|
||||
spelled this way because ``_profile_suffix()`` returns the
|
||||
empty string for the root profile, and the dispatcher in
|
||||
``hermes_cli.gateway`` maps that empty string to the
|
||||
``gateway-default`` service slot. Passing ``-p default`` here
|
||||
would instead look up ``$HERMES_HOME/profiles/default/`` — a
|
||||
completely different (and almost always nonexistent) profile.
|
||||
|
||||
Port selection: the gateway picks its bind port from the
|
||||
profile's ``config.yaml`` (``[gateway] port = ...``) — that
|
||||
is the single source of truth. Previously this method took a
|
||||
``port`` parameter that was passed in but never substituted
|
||||
into the rendered script (it was carried in for "API parity"
|
||||
with a deterministic SHA-256 allocator in
|
||||
``hermes_cli.profiles._allocate_gateway_port``). PR #30136
|
||||
review item I5 retired both the allocator and the parameter
|
||||
because they were dead code through the entire stack.
|
||||
"""
|
||||
import shlex
|
||||
lines = [
|
||||
"#!/command/with-contenv sh",
|
||||
"# shellcheck shell=sh",
|
||||
"set -e",
|
||||
"cd /opt/data",
|
||||
". /opt/hermes/.venv/bin/activate",
|
||||
]
|
||||
for k, v in sorted(extra_env.items()):
|
||||
lines.append(f"export {k}={shlex.quote(v)}")
|
||||
if profile == "default":
|
||||
lines.append("exec s6-setuidgid hermes hermes gateway run")
|
||||
else:
|
||||
lines.append(
|
||||
f"exec s6-setuidgid hermes hermes -p {shlex.quote(profile)} gateway run"
|
||||
)
|
||||
return "\n".join(lines) + "\n"
|
||||
|
||||
@staticmethod
|
||||
def _render_log_run(profile: str) -> str:
|
||||
"""Generate the log/run script for a profile-gateway service.
|
||||
|
||||
OQ8-C: persist to ``${HERMES_HOME}/logs/gateways/<profile>/``.
|
||||
CRITICAL: the HERMES_HOME path is sourced from the runtime env
|
||||
via with-contenv — NOT Python-substituted at registration time
|
||||
— so a container started with ``-e HERMES_HOME=/data/hermes``
|
||||
gets its logs under /data/hermes/logs/..., not the build-time
|
||||
default.
|
||||
"""
|
||||
import shlex
|
||||
prof = shlex.quote(profile)
|
||||
return (
|
||||
f"#!/command/with-contenv sh\n"
|
||||
f"# shellcheck shell=sh\n"
|
||||
f': "${{HERMES_HOME:=/opt/data}}"\n'
|
||||
f'log_dir="$HERMES_HOME/logs/gateways/{prof}"\n'
|
||||
f'mkdir -p "$log_dir"\n'
|
||||
f'chown -R hermes:hermes "$log_dir" 2>/dev/null || true\n'
|
||||
f'exec s6-setuidgid hermes s6-log n10 s1000000 T "$log_dir"\n'
|
||||
)
|
||||
|
||||
# -- lifecycle ---------------------------------------------------------
|
||||
|
||||
def _run_svc(self, action_flag: str, action_label: str, name: str) -> None:
|
||||
"""Shared lifecycle dispatch for start / stop / restart.
|
||||
|
||||
Translates the two failure modes operators care about into
|
||||
named errors:
|
||||
|
||||
* ``GatewayNotRegisteredError`` — the service directory at
|
||||
``<scandir>/<name>/`` doesn't exist. ``s6-svc`` would
|
||||
exit non-zero with a fairly opaque message; we pre-empt
|
||||
it with a clear "no such gateway 'X'" tied to the profile
|
||||
name (without the ``gateway-`` prefix).
|
||||
* ``S6CommandError`` — anything else (EACCES on the
|
||||
supervise control FIFO, timeout, etc.). Carries the
|
||||
subprocess return code and stderr so callers can render
|
||||
them inline.
|
||||
|
||||
``action_flag`` is the ``s6-svc`` flag (``-u`` / ``-d`` /
|
||||
``-t``); ``action_label`` is the human verb (``start`` /
|
||||
``stop`` / ``restart``) used in error messages.
|
||||
"""
|
||||
import subprocess
|
||||
|
||||
service_dir = self.scandir / name
|
||||
if not service_dir.is_dir():
|
||||
# Strip the gateway- prefix back off so the message
|
||||
# matches what the user typed on the CLI (``-p <profile>``).
|
||||
profile = (
|
||||
name[len(S6_SERVICE_PREFIX):]
|
||||
if name.startswith(S6_SERVICE_PREFIX)
|
||||
else name
|
||||
)
|
||||
raise GatewayNotRegisteredError(profile)
|
||||
|
||||
try:
|
||||
subprocess.run(
|
||||
[f"{_S6_BIN_DIR}/s6-svc", action_flag, str(service_dir)],
|
||||
check=True, capture_output=True, text=True, timeout=5,
|
||||
)
|
||||
except subprocess.CalledProcessError as exc:
|
||||
raise S6CommandError(
|
||||
service=name,
|
||||
action=action_label,
|
||||
returncode=exc.returncode,
|
||||
stderr=exc.stderr or "",
|
||||
) from exc
|
||||
|
||||
def start(self, name: str) -> None:
|
||||
"""Bring up a registered service (``s6-svc -u``).
|
||||
|
||||
Raises:
|
||||
GatewayNotRegisteredError: no service directory for ``name``.
|
||||
S6CommandError: s6-svc exited non-zero for any other reason
|
||||
(permission denied on the supervise FIFO, timeout, etc.).
|
||||
"""
|
||||
self._run_svc("-u", "start", name)
|
||||
|
||||
def stop(self, name: str) -> None:
|
||||
"""Bring down a registered service (``s6-svc -d``).
|
||||
|
||||
Raises:
|
||||
GatewayNotRegisteredError: no service directory for ``name``.
|
||||
S6CommandError: s6-svc exited non-zero for any other reason.
|
||||
"""
|
||||
self._run_svc("-d", "stop", name)
|
||||
|
||||
def restart(self, name: str) -> None:
|
||||
"""Restart a registered service (``s6-svc -t`` = SIGTERM).
|
||||
|
||||
Raises:
|
||||
GatewayNotRegisteredError: no service directory for ``name``.
|
||||
S6CommandError: s6-svc exited non-zero for any other reason.
|
||||
"""
|
||||
self._run_svc("-t", "restart", name)
|
||||
|
||||
def is_running(self, name: str) -> bool:
|
||||
"""True iff ``s6-svstat`` reports the service as up."""
|
||||
import subprocess
|
||||
result = subprocess.run(
|
||||
[f"{_S6_BIN_DIR}/s6-svstat", str(self.scandir / name)],
|
||||
capture_output=True, text=True, timeout=5,
|
||||
)
|
||||
return result.returncode == 0 and "up " in result.stdout
|
||||
|
||||
# -- runtime registration ---------------------------------------------
|
||||
|
||||
def supports_runtime_registration(self) -> bool:
|
||||
return True
|
||||
|
||||
def register_profile_gateway(
|
||||
self,
|
||||
profile: str,
|
||||
*,
|
||||
extra_env: dict[str, str] | None = None,
|
||||
) -> None:
|
||||
"""Create the s6 service directory for a profile gateway.
|
||||
|
||||
Triggers ``s6-svscanctl -a`` so s6-svscan picks the new directory
|
||||
up immediately. The service is created in the *up* state — to
|
||||
register without auto-starting, follow up with ``stop(profile)``
|
||||
(or pass the start flag via the future ``start_now=False`` arg,
|
||||
which the Phase 4 reconciliation path uses via a ``down``
|
||||
marker file written directly).
|
||||
|
||||
Raises:
|
||||
ValueError: if the profile name is invalid or the service
|
||||
directory already exists.
|
||||
RuntimeError: if ``s6-svscanctl`` fails.
|
||||
"""
|
||||
import shutil
|
||||
import subprocess
|
||||
|
||||
svc_dir = self._service_dir(profile)
|
||||
if svc_dir.exists():
|
||||
raise ValueError(
|
||||
f"profile gateway {profile!r} already registered at {svc_dir}"
|
||||
)
|
||||
|
||||
# Build the service directory atomically: write to a sibling
|
||||
# temp dir, then rename. Avoids s6-svscan observing a half-
|
||||
# populated directory on a fast rescan.
|
||||
tmp_dir = svc_dir.with_name(svc_dir.name + ".tmp")
|
||||
if tmp_dir.exists():
|
||||
shutil.rmtree(tmp_dir, ignore_errors=True)
|
||||
tmp_dir.mkdir(parents=True)
|
||||
|
||||
try:
|
||||
(tmp_dir / "type").write_text("longrun\n")
|
||||
|
||||
run_script = self._render_run_script(profile, extra_env or {})
|
||||
run_path = tmp_dir / "run"
|
||||
run_path.write_text(run_script)
|
||||
run_path.chmod(0o755)
|
||||
|
||||
# Persistent log rotation (OQ8-C).
|
||||
log_subdir = tmp_dir / "log"
|
||||
log_subdir.mkdir()
|
||||
log_run = log_subdir / "run"
|
||||
log_run.write_text(self._render_log_run(profile))
|
||||
log_run.chmod(0o755)
|
||||
|
||||
# Pre-create the supervise/ skeleton with hermes ownership
|
||||
# BEFORE we publish the slot. s6-supervise will EEXIST our
|
||||
# dirs/FIFOs and inherit the ownership, so the runtime
|
||||
# s6-svc / s6-svstat / s6-svwait calls (all dispatched as
|
||||
# the hermes user) won't hit EACCES on root-owned 0700
|
||||
# dirs. See ``_seed_supervise_skeleton`` for the full
|
||||
# rationale.
|
||||
_seed_supervise_skeleton(tmp_dir)
|
||||
|
||||
tmp_dir.rename(svc_dir)
|
||||
except Exception:
|
||||
shutil.rmtree(tmp_dir, ignore_errors=True)
|
||||
raise
|
||||
|
||||
# Trigger rescan so s6-svscan picks up the new service.
|
||||
result = subprocess.run(
|
||||
[f"{_S6_BIN_DIR}/s6-svscanctl", "-a", str(self.scandir)],
|
||||
capture_output=True, text=True, timeout=5,
|
||||
)
|
||||
if result.returncode != 0:
|
||||
# Clean up: rescan failed, leave the directory in place would
|
||||
# be confusing (no supervisor watching it).
|
||||
shutil.rmtree(svc_dir, ignore_errors=True)
|
||||
raise RuntimeError(
|
||||
f"s6-svscanctl failed: {result.stderr or result.stdout}"
|
||||
)
|
||||
|
||||
def unregister_profile_gateway(self, profile: str) -> None:
|
||||
"""Stop the profile gateway service and remove its directory.
|
||||
|
||||
Idempotent: absent services are a no-op. Best-effort stop +
|
||||
wait-for-down before removal so the running gateway process
|
||||
gets a chance to shut down cleanly before its service dir
|
||||
disappears.
|
||||
|
||||
Teardown ordering matters: ``s6-svscanctl -an`` is fired
|
||||
**before** ``rmtree`` so s6-svscan reaps the supervise child
|
||||
process (releasing its handle on ``supervise/lock`` and the
|
||||
regular files inside the supervise dir), giving us a clean
|
||||
directory to remove. Without the reap-first ordering, the
|
||||
rmtree races s6-supervise on a set of root-owned files inside
|
||||
the supervise dir and the dir is left half-removed.
|
||||
"""
|
||||
import shutil
|
||||
import subprocess
|
||||
import time
|
||||
|
||||
svc_dir = self._service_dir(profile)
|
||||
if not svc_dir.exists():
|
||||
return
|
||||
|
||||
# Stop the service (best effort — service may already be down).
|
||||
subprocess.run(
|
||||
[f"{_S6_BIN_DIR}/s6-svc", "-d", str(svc_dir)],
|
||||
capture_output=True, text=True, timeout=5,
|
||||
check=False,
|
||||
)
|
||||
# Wait for it to actually go down (up to 10s).
|
||||
subprocess.run(
|
||||
[f"{_S6_BIN_DIR}/s6-svwait", "-D", "-t", "10000", str(svc_dir)],
|
||||
capture_output=True, text=True, timeout=15,
|
||||
check=False,
|
||||
)
|
||||
|
||||
# Reap the supervise child FIRST: -n tells s6-svscan to drop
|
||||
# any supervise processes whose service dir is gone (which
|
||||
# includes any service dir we're about to remove). This
|
||||
# releases the file handles s6-supervise holds against the
|
||||
# supervise/lock + supervise/status + supervise/death_tally
|
||||
# files inside the slot, so the upcoming rmtree doesn't race.
|
||||
subprocess.run(
|
||||
[f"{_S6_BIN_DIR}/s6-svscanctl", "-an", str(self.scandir)],
|
||||
capture_output=True, text=True, timeout=5,
|
||||
check=False,
|
||||
)
|
||||
# Give s6-svscan a moment to reap. There's no synchronous
|
||||
# "scan completed" handshake — the -a/-n trigger just sets a
|
||||
# flag s6-svscan reads on its next loop iteration. 200ms is
|
||||
# comfortably above the loop's resolution but well under any
|
||||
# user-perceived latency.
|
||||
time.sleep(0.2)
|
||||
|
||||
# Now the supervise dir's files are no longer held open by a
|
||||
# live s6-supervise, so rmtree can remove them. Files inside
|
||||
# supervise/ are root-owned (death_tally, lock, status, written
|
||||
# by s6-supervise itself) — but the parent supervise/ directory
|
||||
# is hermes-owned (see ``_seed_supervise_skeleton``), and on
|
||||
# POSIX you only need write+execute on the parent to remove
|
||||
# contained files regardless of file ownership.
|
||||
shutil.rmtree(svc_dir, ignore_errors=True)
|
||||
|
||||
def list_profile_gateways(self) -> list[str]:
|
||||
"""Return the profile names of all currently-registered gateway services.
|
||||
|
||||
Filters the scandir to entries that match the ``gateway-`` prefix.
|
||||
Other services (e.g. ``s6-linux-init-shutdownd``) are ignored.
|
||||
"""
|
||||
if not self.scandir.exists():
|
||||
return []
|
||||
profiles: list[str] = []
|
||||
for entry in self.scandir.iterdir():
|
||||
if entry.name.startswith("."):
|
||||
continue
|
||||
if not entry.is_dir():
|
||||
continue
|
||||
if not entry.name.startswith(S6_SERVICE_PREFIX):
|
||||
continue
|
||||
profiles.append(entry.name[len(S6_SERVICE_PREFIX):])
|
||||
return profiles
|
||||
Reference in New Issue
Block a user