yjdZddlmZddlZddlmZddlmZmZm Z edZ ej dZ dZ d/d Ze GddeZd0dZd1dZGddZGddeZGddeZGddeZd2dZedZdZd3d Zd4d"Zd#Zd$Zd$Zd5d&ZGd'd(eZ Gd)d*e Z!Gd+d,e Z"Gd-d.Z#dS)6u=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. ) annotationsN)Path)LiteralProtocolruntime_checkable)systemdlaunchdwindowss6nonez^[a-z0-9][a-z0-9_-]*$namestrreturnNonec|stdt|tkr(tdt|dtdt|std|dS)aARaise 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``. zprofile name must not be emptyzprofile name too long (z > )z1profile name must match [a-z0-9][a-z0-9_-]*, got N) ValueErrorlen_MAX_PROFILE_LEN_VALID_PROFILE_REmatch)rs @/home/ragecks/.hermes/hermes-agent/hermes_cli/service_manager.pyvalidate_profile_namer!s ;9::: 4yy### Gc$ii G G4D G G G     " "4 ( (  H H H     cfeZdZUdZded<ddZdd Zdd Zdd Zdd Z dddddZ ddZ ddZ dS)ServiceManageruAbstract 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. ServiceManagerKindkindrrrrcdSNselfrs rstartzServiceManager.startDrcdSr!r"r#s rstopzServiceManager.stopEr&rcdSr!r"r#s rrestartzServiceManager.restartFr&rboolcdSr!r"r#s r is_runningzServiceManager.is_runningGr&rcdSr!r"r$s rsupports_runtime_registrationz,ServiceManager.supports_runtime_registrationJr&rNT extra_env start_nowprofiler2dict[str, str] | Noner3cdSr!r"r$r4r2r3s rregister_profile_gatewayz'ServiceManager.register_profile_gatewayKs srcdSr!r"r$r4s runregister_profile_gatewayz)ServiceManager.unregister_profile_gatewayRr&r list[str]cdSr!r"r/s rlist_profile_gatewaysz$ServiceManager.list_profile_gatewaysSr&rrrrrrrrr+rr+r4rr2r5r3r+rrr4rrrrr<) __name__ __module__ __qualname____doc____annotations__r%r(r*r-r0r8r;r>r"rrrr5s,+++****----00009888 ,0 DCCC555555rrrcddlm}m}m}t rdS|rdS|rdS|rdSdS)uDetect which service manager is available in this environment. Returns: "s6" — s6-svscan is PID 1 (s6-overlay image; Docker, Podman, or a Fly Firecracker microVM) "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``). ris_macos is_windowssupports_systemd_servicesr r r rr )hermes_cli.gatewayrLrMrN _s6_runningrKs rdetect_service_managerrQVs&}}tz||yxzzy  ""y 6rr+c tdd}n#t$rYdSwxYw|dkrdStdS)uTrue 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``). z /proc/1/commutf-8encodingFz s6-svscanz/run/s6/basedir)r read_textstripOSErroris_dir)comms rrPrPs0N##--w-??EEGG uu {u ! " " ) ) + ++s58 AAc:eZdZdZddZdddddZddZddZdS)_RegistrationUnsupportedMixinz@Mixin for host backends that don't support runtime registration.rr+cdS)NFr"r/s rr0z;_RegistrationUnsupportedMixin.supports_runtime_registrationsurNTr1r4rr2r5r3rcJtt|jd)NzO does not support runtime profile gateway registration (container-only feature)NotImplementedErrortyperEr7s rr8z6_RegistrationUnsupportedMixin.register_profile_gateways1"Dzz" < < <   rcJtt|jd)NzQ does not support runtime profile gateway unregistration (container-only feature)r_r:s rr;z8_RegistrationUnsupportedMixin.unregister_profile_gateways/!Dzz" > > >   rr<cgSr!r"r/s rr>z3_RegistrationUnsupportedMixin.list_profile_gatewayss rrArBrCrD)rErFrGrHr0r8r;r>r"rrr\r\s|JJ,0           rr\cBeZdZUdZdZded<dd Zdd Zdd Zdd Z dS)SystemdServiceManagera 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). rrrrrrrc&ddlm}|dS)Nr) systemd_start)rOrg)r$rrgs rr%zSystemdServiceManager.start#444444 rc&ddlm}|dS)Nr) systemd_stop)rOrj)r$rrjs rr(zSystemdServiceManager.stop#333333 rc&ddlm}|dS)Nr)systemd_restart)rOrm)r$rrms rr*zSystemdServiceManager.restart(666666rr+c,ddlm}|\}}|S)Nr)_probe_systemd_service_running)rOrp)r$rrp_runnings rr-z SystemdServiceManager.is_runnings+EEEEEE3355 7rNr?r@ rErFrGrHrrIr%r(r*r-r"rrreres )D((((rrecBeZdZUdZdZded<dd Zdd Zdd Zdd Z dS)LaunchdServiceManagerzFThin wrapper around the ``launchd_*`` functions in hermes_cli.gateway.r rrrrrrc&ddlm}|dS)Nr) launchd_start)rOrw)r$rrws rr%zLaunchdServiceManager.startrhrc&ddlm}|dS)Nr) launchd_stop)rOry)r$rrys rr(zLaunchdServiceManager.stoprkrc&ddlm}|dS)Nr)launchd_restart)rOr{)r$rr{s rr*zLaunchdServiceManager.restartrnrr+c"ddlm}|S)Nr)_probe_launchd_service_running)rOr})r$rr}s rr-z LaunchdServiceManager.is_runnings#EEEEEE--///rNr?r@rsr"rrrurus}PP(D((((000000rrucVeZdZUdZdZded<dddddddZddZddZddZ ddZ dS)WindowsServiceManageruThin 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. r rrFNforcer3start_on_loginelevated_handoffrr+r3 bool | NonerrrrcDddlm}|||||dS)Nrgateway_windowsr) hermes_clirinstall)r$rr3rrrs rrzWindowsServiceManager.install sI /.....)-      rrrc:ddlm}|dSNrr)rrr%r$rrs rr%zWindowsServiceManager.starts,......rc:ddlm}|dSr)rrr(rs rr(zWindowsServiceManager.stops,......rc:ddlm}|dSr)rrr*rs rr*zWindowsServiceManager.restart#s,......!!!!!rctddlm}ddlm}|sdSt |S)Nrr)find_gateway_pidsF)rrrOr is_installedr+)r$rrrs rr-z WindowsServiceManager.is_running'sW......888888++-- 5%%''(((r) rr+r3rrrrr+rrr?r@) rErFrGrHrrIrr%r(r*r-r"rrrrs   )D(((( !%&*!&           """"))))))rrct}|dkrtS|dkrtS|dkrtS|dkrt St d)zReturn the ServiceManager instance for the current environment. Raises: RuntimeError: when no supported backend is available. rr r r z%no supported service manager detected)rQrerurS6ServiceManager RuntimeError)rs rget_service_managerr/sx " # #D y$&&& y$&&& y$&&& t||!!! > ? ??rz /run/servicegateway-rcFddl}|tr|ttdn|}t |t |jdd}|jj dkr |jj}n|}|dkr|n|dz |z S)aResolve ``gateway-`` to its persistent profile directory. s6 lifecycle commands may be invoked from any active profile, including ``gateway stop --all``. Do not write the caller's HERMES_HOME blindly; derive the shared profile root from the current HERMES_HOME and map the service suffix to either the root default profile or ``/profiles/``. rN HERMES_HOMEz /opt/dataprofilesdefault) os startswithS6_SERVICE_PREFIXrrrenvirongetparentr)rrr4 hermes_homeroots r _profile_dir_for_gateway_servicerRsIII/3?P/Q/Q[d3())**++W[G'"""rz~~m[AABBK*,,!(i''44TJ->-HHr desired_statecddl}ddl}t|}|dz } |sdS |r)||dni}t |tsi}n#t|j f$ri}YnwxYw||d<t||d<| |j dz}| ||d d zd||dS#t$rYdSwxYw) aPersist durable s6 gateway intent next to runtime status. ``gateway_state`` remains the volatile runtime field written by the gateway process. ``desired_state`` records the operator's start/stop intent so container-boot reconciliation can restore the correct s6 want-up/want-down state after pod recreation even if the previous runtime state was transient (draining, startup_failed, etc.). The write is best-effort: a failed persistence attempt must not prevent immediate s6 lifecycle control. rNzgateway_state.jsonrSrTr updated_at.tmp),:) separators )jsontimerexistsloadsrV isinstancedictrXJSONDecodeErrorint with_suffixsuffix write_textdumpsreplace)rrrr profile_dir state_filedatatmps r_write_gateway_desired_statergssKKKKKK2488K33J!!##  F ISIZIZI\I\d4::j22G2DDEEEbdDdD)) -.   DDD  -_ --\$$Z%6%?@@ tzz$:z>>EPWXXX J s6D1AB D1 B"D1!B""B D11 D?>D?z/commandi'svc_dircddldfd }||d z d |d z }||d ||d z d |dz }|s^|d|d |t t n#t$rYnwxYw|dz }|r||d z d |d z }||d ||d z d |dz }|sb|d|d |t t dS#t$rYdSwxYwdSdS)u 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: ``/event`` and ``/supervise``, both with mode ``0700``. It also ``mkfifo``s ``/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 (``_); 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. rNpathrmoderrrc|rdS|dd|| |tt dS#t $rYdSwxYw)NF)parentsexist_ok)rmkdirchmodchown _HERMES_UID _HERMES_GIDPermissionError)rrrs r _mkdir_ownedz._seed_supervise_skeleton.._mkdir_owneds ;;==  F 55 111 4  HHT; 4 4 4 4 4    DD  s!A(( A65A6eventi supervisecontrolilog)rrrrrr) rrmkfiforrrrrrY)rrrrlog_dir log_supervise log_controlrs @r_seed_supervise_skeletonrsHIII       L7"F++++%ILE"""LW$f---)#G >>   '5!!! e  HHWk; 7 7 7 7    D oG~~  Ww&///+-  ]E*** ]W,f555#i/ !!##  IIk5 ) ) )   e $ $ $ k;?????"         s$!B"" B/.B/?!E"" E0/E0c*eZdZdZddd fd ZxZS) S6Errora 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. Nservicemessagerr str | NonerrcXt|||_dSr!)super__init__r)r$rr __class__s rrzS6Error.__init__+s& !!! r)rrrrrrrErFrGrHr __classcell__rs@rrr#sW?Crrc$eZdZdZdfd ZxZS)GatewayNotRegisteredErroraMRaised 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-`` service-dir name) so callers can phrase a user-facing message like "no such gateway 'typo'". r4rrrcp||_td|d|dd|dS)Nzno such gateway z*: register it with `hermes profile create z9` first, or pass an existing profile name via `-p `rr)r4rr)r$r4rs rrz"GatewayNotRegisteredError.__init__9se   7w 7 7&- 7 7 7)w((      rrCrrs@rrr0sG          rrc$eZdZdZd fd ZxZS) S6CommandErroruRaised 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. rraction returncoderstderrrrc||_||_||_d|d|d|d}|r|d|z }t ||dS)Nzs6-svc z on z failed (rc=rz: r)rrrrWrr)r$rrrrrrs rrzS6CommandError.__init__Ks $ Ff F F' F F F F F  <<>> - ,FLLNN,, ,G '22222r) rrrrrrrrrrrrs@rrrCsG 3 3 3 3 3 3 3 3 3 3rrceZdZUdZdZded<efd(d Zd)d Zd*d Z e d+dZ e d,dZ e d*dZ d-dZd.dZd/dZd.dZd.dZd0dZd1dZdd d!d2d$Zd3d%Zd4d'ZdS)5rzPer-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. r rrscandirrrrc||_dSr!)r)r$rs rrzS6ServiceManager.__init__cs  rr4rcFt||jt|z Sr!)rrrr:s r _service_dirzS6ServiceManager._service_dirhs)g&&&|!2=G====rct|Sr!)rr:s r _service_namezS6ServiceManager._service_namels#.W...rr2dict[str, str]c ddl}gd}t|D]3\}}|d|d||4|d|dkrd}nd ||d }|d ||d |d |d zS)u> 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. Resets ``HOME`` to ``/opt/data`` before the privilege drop so with-contenv's root HOME does not leak into the unprivileged gateway process. 3. Activates the bundled venv. 4. Drops to the hermes user and exec's ``hermes -p 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 binds the port resolved by ``gateway/config.py`` from the profile's own environment — ``API_SERVER_PORT`` (or ``platforms.api_server.extra.port`` in that profile's ``config.yaml``), defaulting to 8642. There is no ``[gateway] port`` key and no Python-side allocator: because each supervised profile gateway loads its own ``HERMES_HOME``, two profiles that both leave the port unset will both try to bind 8642 — give each profile a distinct ``API_SERVER_PORT`` in its ``.env``. Previously this method took a ``port`` parameter that was passed in but never substituted into the rendered script (carried 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. rN)z#!/command/with-contenv shz# shellcheck shell=shzset -ezexport HOME=/opt/dataz cd /opt/dataz . /opt/hermes/.venv/bin/activatezexport =z#export HERMES_S6_SUPERVISED_CHILD=1rzhermes gateway run --replacez hermes -p z gateway run --replacez[ "$(id -u)" = 0 ] || exec zexec s6-setuidgid hermes r)shlexsorteditemsappendquotejoin)r4r2rlineskv gateway_cmds r_render_run_scriptz#S6ServiceManager._render_run_scriptos Z     9??,,-- 9 9DAq LL7177u{{1~~77 8 8 8 8  :;;; i  8KKSu{{7';';SSSK  @;@@AAA >>>???yy$&&rc$ddlm}|}d|d|dS)uyGenerate the finish script for a profile-gateway s6 service. When the gateway exits with EX_CONFIG (78) — a fatal configuration error such as a token collision or no messaging platforms — we tell s6-supervise to stop restarting by exiting 125 (permanent failure). Any other exit code lets s6 restart normally. See #51228. r)GATEWAY_FATAL_CONFIG_EXIT_CODEz^#!/command/with-contenv sh # shellcheck shell=sh # $1 = exit code from the run script. # Exit uB (EX_CONFIG) = fatal config error — don't restart. if [ "$1" = "z" ]; then exit 125 fi exit 0 )gateway.restartr)rcodes r_render_finish_scriptz&S6ServiceManager._render_finish_scriptsI CBBBBB-   !     rc@ddl}||}d|dS)uGenerate the log/run script for a profile-gateway service. OQ8-C: persist to ``${HERMES_HOME}/logs/gateways//``. 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. Output routing — the script is two action directives, applied per line, in order: 1. ``1`` (forward to stdout) — propagates the line up the s6-supervise pipeline to /init's stdout, which is the container's stdout, which is ``docker logs``. Without this, supervised stdout would be terminated inside s6-log and never reach the container's log stream; users would have to ``docker exec`` and ``tail`` the file just to see startup banners. (Python's ``logging`` module defaults to stderr, which s6-supervise leaves unfiltered — so warnings/errors already reach docker logs. This change is specifically about the rich-console banner output and other plain stdout writes.) 2. ``T `` — also write a timestamped copy to the rotated log directory (``current`` + archived ``@*.s`` files). This is what ``hermes logs`` reads and what persists across container restarts via the volume mount. ``T`` is non-sticky: it only prefixes lines for the next action directive. We deliberately put ``T`` between ``1`` and the log dir (not before ``1``) so: * ``docker logs`` shows raw lines — Python's logging formatter has its own timestamps, and ``docker logs --timestamps`` adds a third layer when desired. No double-stamping in the most common reading path. * The persisted file gets s6-log's own ISO 8601 timestamp so even output that lacked a Python-logger timestamp (rich banners, third-party libs' raw prints) is correlatable in ``current``. rNzs#!/command/with-contenv sh # shellcheck shell=sh : "${HERMES_HOME:=/opt/data}" log_dir="$HERMES_HOME/logs/gateways/a$" if [ "$(id -u)" = 0 ]; then s6-setuidgid hermes mkdir -p "$log_dir" s6-setuidgid hermes rm -f "$log_dir/lock" else mkdir -p "$log_dir" rm -f "$log_dir/lock" fi [ "$(id -u)" = 0 ] || exec s6-log 1 n10 s1000000 T "$log_dir" exec s6-setuidgid hermes s6-log 1 n10 s1000000 T "$log_dir" )rr)r4rprofs r_render_log_runz S6ServiceManager._render_log_runsAV  {{7## M48 M M M r action_flag action_labelrc ddl}|j|z }|sG|tr|t tdn|}t | |td|t|gdddddddS#|j $r%}t|||j |j pd |d}~wwxYw) ugShared lifecycle dispatch for start / stop / restart. Translates the two failure modes operators care about into named errors: * ``GatewayNotRegisteredError`` — the service directory at ``//`` 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. rN/s6-svcTrSr)checkcapture_outputtextrUerrorstimeout)rrrr) subprocessrrYrrrrrun _S6_BIN_DIRrCalledProcessErrorrrr)r$r r rr service_dirr4excs r_run_svczS6ServiceManager._run_svc's!( lT) !!## 5 ??#455S*++,,--  ,G44 4  NN(((+s;7G7GH4dWU^hi      ,    #>z'R     s+4B!! C+ C  CcT|dd|t|ddS)a$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.). z-ur%rrNrrr#s rr%zS6ServiceManager.startUs0 dGT***$T955555r int | NonecLddl} |tdt|j|z gddddd}n#t |jf$rYdSwxYw|jdkrdStj d |j }|r"t| d ndS) aReturn the PID of the supervised gateway process, or None. Parses ``s6-svstat`` output (``up (pid NNNN) ...``). Used to mark an operator-initiated stop with the planned-stop marker so the gateway's shutdown handler classifies the incoming SIGTERM as intentional rather than an unexpected kill (issue #42675). Best-effort: any parse/exec failure returns None. rN /s6-svstatTrSrr rrrUrrz \(pid (\d+)\)) rrrrrrXSubprocessErrorrresearchstdoutrgroup)r$rrresultms r_supervised_pidz S6ServiceManager._supervised_pid`s  ^^+++S1D-E-EF#$\]$FF34   44    ! !4 I& 6 6"#-s1771::-s:AAAc||}|# ddlm}||n#t$rYnwxYw|dd|t |ddS)uBring down a registered service (``s6-svc -d``). Writes a planned-stop marker naming the supervised gateway PID BEFORE sending the down command, so the gateway's shutdown handler recognises this SIGTERM as an operator-initiated stop and persists ``gateway_state=stopped`` (respecting the explicit intent). Without the marker, an intentional ``hermes gateway stop`` is indistinguishable from the container/s6 SIGTERM sent on ``docker restart``; the latter must NOT persist ``stopped`` or container_boot refuses to auto-start on the next boot (#42675). The marker write is best-effort — a failure only means the stop is treated as signal-initiated, which is the safe fallback. Raises: GatewayNotRegisteredError: no service directory for ``name``. S6CommandError: s6-svc exited non-zero for any other reason. Nr)write_planned_stop_marker-dr(stopped)r)gateway.statusr+ Exceptionrr)r$rpidr+s rr(zS6ServiceManager.stopws$""4(( ? DDDDDD))#....     dFD)))$T955555s + 88cT|dd|t|ddS)zRestart a registered service (``s6-svc -t`` = SIGTERM). Raises: GatewayNotRegisteredError: no service directory for ``name``. S6CommandError: s6-svc exited non-zero for any other reason. -tr*rrNrr#s rr*zS6ServiceManager.restarts0 dIt,,,$T955555rr+cddl}|tdt|j|z gddddd}|jdkod |jvS) z1True iff ``s6-svstat`` reports the service as up.rNrTrSrr r zup )rrrrrrr%)r$rrr's rr-zS6ServiceManager.is_runningsn ' ' 'T\D-@)A)A BdWYXY    A%@%6=*@@rcdS)NTr"r/s rr0z.S6ServiceManager.supports_runtime_registrationstrNTr1r5r3cddl}ddl}||}|rt d|d||d|jzdz}|r||d|d  |d z d d | ||pi}|dz } | |d | d|dz } | | d | d|dz } | | dz } | | |d | dt||s|dz ||n&#t"$r||dwxYw|t&ddt)|jgddd dd} | jdkr5||dt/d| jp| jdS)a^Create the s6 service directory for a profile gateway. Triggers ``s6-svscanctl -a`` so s6-svscan picks the new directory up immediately. When *start_now* is ``True`` (the default) the service starts immediately; when ``False`` a ``down`` marker file is written so s6-supervise leaves the service stopped until the user explicitly runs ``hermes -p gateway start``. Raises: ValueError: if the profile name is invalid or the service directory already exists. RuntimeError: if ``s6-svscanctl`` fails. rNzprofile gateway z already registered at .rT ignore_errors)rrazlongrun rSrTrrfinishrdown /s6-svscanctlz-arr r zs6-svscanctl failed: )shutilrrrr with_namerrmtreerrrrrrrtouchrenamer/rrrrrrrr%)r$r4r2r3r<rrtmp_dir run_scriptrun_path finish_path log_subdirlog_runr's rr8z)S6ServiceManager.register_profile_gateways(  ##G,, >>   N7NNWNN *##C',$6$?@@ >>   7 MM'M 6 6 6 d ###&  v  ) )+ ) H H H00)/rJJJH    W  = = = NN5 ! ! !!H,K  " "4#=#=#?#?' " R R R   e $ $ $!5J       5(G   t33G<)r$r4r<rrrs rr;z+S6ServiceManager.unregister_profile_gatewaysR   ##G,,~~  F  $ $ $dCLL 9dWYXY     ' ' 'tWc'll KdWYXZ      * * *E3t|3D3D EdWYXY     3  gT 22222rr<c|jsgSg}|jD]}|jdr|s2|jt sR||jtt d|S)zReturn 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. r6N) rriterdirrrrYrrr)r$rentrys rr>z&S6ServiceManager.list_profile_gatewaysTs |""$$ I \))++ A AEz$$S)) <<>> :(():;;  OOEJs+<'='='>'>? @ @ @ @r)rrrr)r4rrr)r4rrr)r4rr2rrr)rr)r rr rrrrrr?)rrrrr@rArBrCrD)rErFrGrHrrIS6_DYNAMIC_SCANDIRrrr staticmethodrrrrr%r)r(r*r-r0r8r;r>r"rrrrYs $D####'9 >>>>////V'V'V'\V'p   \ .B B B \B L,,,,\ 6 6 6 6.....6666:6666AAAA,0 ffffffP>3>3>3>3@rrr?)rrrA)rr)rrrr)rrrrrr)rrrr)$rH __future__rr#pathlibrtypingrrrrcompilerrrrrQrPr\rerurrrNrrrrrrrrrrrrr"rrrTs #""""" 7777777777JK BJ788    (66666X666@((((V,,,,\898000009000,/)/)/)/)/)9/)/)/)d@@@@>T.))IIII*\   @@@@F     l           &33333W333,LLLLLLLLLLr