| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151 |
- """s6 leg of the one-gateway-per-host convergence, shared by container boot and in-process migration.
- Inside the official image every profile has an s6 slot (``/run/hermes-service/gateway-<profile>``). The
- container's boot (``hermes_cli/container_boot.py``) registers every NAMED slot down and lets the
- root slot inherit their autostart intent; ``hermes gateway migrate --multiplex`` (and the hook
- ``hermes update`` runs) must be able to do the same thing to a slot that is UP, from inside the
- running container, without a container restart. Both paths decide "which named intents fold into
- the root slot" through :func:`fold_named_slot_intent` so they can never disagree.
- """
- from __future__ import annotations
- import logging
- import os
- from dataclasses import dataclass
- from pathlib import Path
- from typing import Iterable, Optional, Sequence
- logger = logging.getLogger(__name__)
- #: Only this desired state autostarts; everything else (startup_failed, starting, stopped, missing)
- #: waits for the operator — no crash-loop of a broken gateway across ``docker restart``.
- AUTOSTART_STATES = frozenset({"running"})
- @dataclass(frozen=True)
- class FoldDecision:
- #: Named profiles whose autostart intent the root slot takes over.
- folded: tuple[str, ...]
- #: Whether the root slot must be up after the fold.
- root_should_start: bool
- def fold_named_slot_intent(default_prior_state: Optional[str],
- named_states: Iterable[tuple[str, Optional[str]]]) -> FoldDecision:
- """The ONE rule for folding per-profile s6 slots into the root slot.
- A named slot is never booted from its own intent (a started named slot IS a second gateway on
- this host); its ``running`` intent moves to the root slot, which is the process that serves it.
- Without the fold an image only ever driven as ``hermes -p coder gateway start`` came up with
- ZERO gateways: no root state, every named slot registered down, every action "registered".
- """
- folded = tuple(sorted(name for name, prior in named_states if prior in AUTOSTART_STATES))
- return FoldDecision(folded=folded,
- root_should_start=default_prior_state in AUTOSTART_STATES or bool(folded))
- def named_slot_name(profile: str) -> str:
- from hermes_cli.service_manager import S6_SERVICE_PREFIX
- return f"{S6_SERVICE_PREFIX}{profile}"
- def running_named_slots(profiles: Sequence[str], manager=None) -> list[str]:
- """Named profiles whose s6 slot is UP right now — the only s6 state that is a second gateway.
- A registered-down slot (what boot leaves behind) is a start target for ``hermes -p X gateway
- start``, not a running gateway, and must never veto the multiplex default.
- """
- manager = manager or _manager()
- up: list[str] = []
- for profile in profiles:
- if profile == "default":
- continue
- try:
- if manager.is_running(named_slot_name(profile)):
- up.append(profile)
- except Exception: # an unprobeable slot is not a running gateway
- logger.debug("could not probe s6 slot for %s", profile, exc_info=True)
- return up
- def slot_is_up(profile: str, manager=None) -> bool:
- return bool(running_named_slots([profile], manager))
- def park_named_slot(profile: str, manager=None) -> None:
- """Stop a named profile's slot and write its ``down`` file so a supervisor restart does not
- revive it (``s6-svc -d`` alone is undone by the next ``s6-svscanctl -a``/container restart)."""
- manager = manager or _manager()
- slot = named_slot_name(profile)
- if manager.is_running(slot):
- manager.stop(slot)
- _wait_down(manager.scandir / slot)
- _set_down_marker(manager.scandir / slot, down=True)
- def _set_down_marker(service_dir: Path, *, down: bool) -> None:
- """Create or remove a slot's ``down`` file without following symlinks.
- Slots live in the hermes-owned scandir, so a root caller must not ``touch`` through a ``down``
- (or slot) symlink planted there. The slot is opened O_NOFOLLOW and ``down`` is handled
- relative to that fd. An existing marker that resolves is left untouched; a dangling ``down``
- symlink (which s6 would not honour) is replaced by a regular file.
- """
- from hermes_cli.service_manager import _root_hermes_account
- slot_fd = os.open(service_dir, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
- try:
- if not down:
- try:
- os.unlink("down", dir_fd=slot_fd) # unlink never follows a symlink
- except FileNotFoundError:
- pass
- return
- flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW
- try:
- fd = os.open("down", flags, 0o644, dir_fd=slot_fd)
- except FileExistsError:
- try:
- os.stat("down", dir_fd=slot_fd) # s6 follows the marker, so a resolvable one parks
- return
- except FileNotFoundError:
- pass
- # A dangling symlink does not park the slot: replace the link itself, never its target.
- os.unlink("down", dir_fd=slot_fd)
- fd = os.open("down", flags, 0o644, dir_fd=slot_fd)
- try:
- account = _root_hermes_account()
- if account is not None:
- os.fchown(fd, account.pw_uid, account.pw_gid)
- finally:
- os.close(fd)
- finally:
- os.close(slot_fd)
- def _wait_down(service_dir: Path, timeout_ms: int = 15000) -> None:
- from hermes_cli.service_manager import S6ServiceManager
- try:
- # As root, s6-svwait would create its subscription FIFO through a hermes-owned event/.
- S6ServiceManager._s6("s6-svwait", "-d", "-t", str(timeout_ms), str(service_dir),
- timeout=timeout_ms / 1000 + 5)
- except Exception:
- logger.debug("s6-svwait failed for %s", service_dir, exc_info=True)
- def bring_root_slot_up(manager=None) -> str:
- """Start (or restart, so it re-reads its config) the root slot; returns a one-line description."""
- manager = manager or _manager()
- slot = named_slot_name("default")
- _set_down_marker(manager.scandir / slot, down=False)
- if manager.is_running(slot):
- manager.restart(slot)
- return "restarted the root gateway slot (s6)"
- manager.start(slot)
- return "started the root gateway slot (s6)"
- def _manager():
- from hermes_cli.service_manager import S6ServiceManager
- return S6ServiceManager()
|