gateway_multiplex_s6.py 6.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151
  1. """s6 leg of the one-gateway-per-host convergence, shared by container boot and in-process migration.
  2. Inside the official image every profile has an s6 slot (``/run/hermes-service/gateway-<profile>``). The
  3. container's boot (``hermes_cli/container_boot.py``) registers every NAMED slot down and lets the
  4. root slot inherit their autostart intent; ``hermes gateway migrate --multiplex`` (and the hook
  5. ``hermes update`` runs) must be able to do the same thing to a slot that is UP, from inside the
  6. running container, without a container restart. Both paths decide "which named intents fold into
  7. the root slot" through :func:`fold_named_slot_intent` so they can never disagree.
  8. """
  9. from __future__ import annotations
  10. import logging
  11. import os
  12. from dataclasses import dataclass
  13. from pathlib import Path
  14. from typing import Iterable, Optional, Sequence
  15. logger = logging.getLogger(__name__)
  16. #: Only this desired state autostarts; everything else (startup_failed, starting, stopped, missing)
  17. #: waits for the operator — no crash-loop of a broken gateway across ``docker restart``.
  18. AUTOSTART_STATES = frozenset({"running"})
  19. @dataclass(frozen=True)
  20. class FoldDecision:
  21. #: Named profiles whose autostart intent the root slot takes over.
  22. folded: tuple[str, ...]
  23. #: Whether the root slot must be up after the fold.
  24. root_should_start: bool
  25. def fold_named_slot_intent(default_prior_state: Optional[str],
  26. named_states: Iterable[tuple[str, Optional[str]]]) -> FoldDecision:
  27. """The ONE rule for folding per-profile s6 slots into the root slot.
  28. A named slot is never booted from its own intent (a started named slot IS a second gateway on
  29. this host); its ``running`` intent moves to the root slot, which is the process that serves it.
  30. Without the fold an image only ever driven as ``hermes -p coder gateway start`` came up with
  31. ZERO gateways: no root state, every named slot registered down, every action "registered".
  32. """
  33. folded = tuple(sorted(name for name, prior in named_states if prior in AUTOSTART_STATES))
  34. return FoldDecision(folded=folded,
  35. root_should_start=default_prior_state in AUTOSTART_STATES or bool(folded))
  36. def named_slot_name(profile: str) -> str:
  37. from hermes_cli.service_manager import S6_SERVICE_PREFIX
  38. return f"{S6_SERVICE_PREFIX}{profile}"
  39. def running_named_slots(profiles: Sequence[str], manager=None) -> list[str]:
  40. """Named profiles whose s6 slot is UP right now — the only s6 state that is a second gateway.
  41. A registered-down slot (what boot leaves behind) is a start target for ``hermes -p X gateway
  42. start``, not a running gateway, and must never veto the multiplex default.
  43. """
  44. manager = manager or _manager()
  45. up: list[str] = []
  46. for profile in profiles:
  47. if profile == "default":
  48. continue
  49. try:
  50. if manager.is_running(named_slot_name(profile)):
  51. up.append(profile)
  52. except Exception: # an unprobeable slot is not a running gateway
  53. logger.debug("could not probe s6 slot for %s", profile, exc_info=True)
  54. return up
  55. def slot_is_up(profile: str, manager=None) -> bool:
  56. return bool(running_named_slots([profile], manager))
  57. def park_named_slot(profile: str, manager=None) -> None:
  58. """Stop a named profile's slot and write its ``down`` file so a supervisor restart does not
  59. revive it (``s6-svc -d`` alone is undone by the next ``s6-svscanctl -a``/container restart)."""
  60. manager = manager or _manager()
  61. slot = named_slot_name(profile)
  62. if manager.is_running(slot):
  63. manager.stop(slot)
  64. _wait_down(manager.scandir / slot)
  65. _set_down_marker(manager.scandir / slot, down=True)
  66. def _set_down_marker(service_dir: Path, *, down: bool) -> None:
  67. """Create or remove a slot's ``down`` file without following symlinks.
  68. Slots live in the hermes-owned scandir, so a root caller must not ``touch`` through a ``down``
  69. (or slot) symlink planted there. The slot is opened O_NOFOLLOW and ``down`` is handled
  70. relative to that fd. An existing marker that resolves is left untouched; a dangling ``down``
  71. symlink (which s6 would not honour) is replaced by a regular file.
  72. """
  73. from hermes_cli.service_manager import _root_hermes_account
  74. slot_fd = os.open(service_dir, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
  75. try:
  76. if not down:
  77. try:
  78. os.unlink("down", dir_fd=slot_fd) # unlink never follows a symlink
  79. except FileNotFoundError:
  80. pass
  81. return
  82. flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW
  83. try:
  84. fd = os.open("down", flags, 0o644, dir_fd=slot_fd)
  85. except FileExistsError:
  86. try:
  87. os.stat("down", dir_fd=slot_fd) # s6 follows the marker, so a resolvable one parks
  88. return
  89. except FileNotFoundError:
  90. pass
  91. # A dangling symlink does not park the slot: replace the link itself, never its target.
  92. os.unlink("down", dir_fd=slot_fd)
  93. fd = os.open("down", flags, 0o644, dir_fd=slot_fd)
  94. try:
  95. account = _root_hermes_account()
  96. if account is not None:
  97. os.fchown(fd, account.pw_uid, account.pw_gid)
  98. finally:
  99. os.close(fd)
  100. finally:
  101. os.close(slot_fd)
  102. def _wait_down(service_dir: Path, timeout_ms: int = 15000) -> None:
  103. from hermes_cli.service_manager import S6ServiceManager
  104. try:
  105. # As root, s6-svwait would create its subscription FIFO through a hermes-owned event/.
  106. S6ServiceManager._s6("s6-svwait", "-d", "-t", str(timeout_ms), str(service_dir),
  107. timeout=timeout_ms / 1000 + 5)
  108. except Exception:
  109. logger.debug("s6-svwait failed for %s", service_dir, exc_info=True)
  110. def bring_root_slot_up(manager=None) -> str:
  111. """Start (or restart, so it re-reads its config) the root slot; returns a one-line description."""
  112. manager = manager or _manager()
  113. slot = named_slot_name("default")
  114. _set_down_marker(manager.scandir / slot, down=False)
  115. if manager.is_running(slot):
  116. manager.restart(slot)
  117. return "restarted the root gateway slot (s6)"
  118. manager.start(slot)
  119. return "started the root gateway slot (s6)"
  120. def _manager():
  121. from hermes_cli.service_manager import S6ServiceManager
  122. return S6ServiceManager()