Source code for osprey_connectors.ipc._launch

"""Starting, stopping and listening to connector-host children.

Every supervisor of :mod:`osprey_connectors.ipc._host` children needs the same
four things — how the child is launched, what environment it is handed, how it
is put down, and how the requests still in flight on a child that was put down
learn why — and this module is where they are spelled once. Ending the process
itself is :mod:`osprey_connectors.process`'s, which spells it for every child a
supervisor owns; this module wraps it with what a connector-host child's proxy
needs around it. The controls MCP server's single-child manager and the
library's multi-target :class:`~osprey_connectors.ipc.ConnectorHostPool`
both use them.

Nothing here imports a control-system client library, and nothing here sets an
``EPICS_*`` variable: a supervisor is by definition a process that talks to the
control system only through its children.
"""

from __future__ import annotations

import asyncio
import os
from collections.abc import Mapping
from typing import TYPE_CHECKING

from osprey_connectors.dotenv import ENV_CHAIN_APPLIED_ENV
from osprey_connectors.ipc._host import EPICS_ENV_PREFIXES, START_MARKS_FD_ENV
from osprey_connectors.process import terminate

if TYPE_CHECKING:
    from osprey_connectors.ipc._proxy import ConnectorHostProxy

__all__ = [
    "CHILD_MODULE",
    "SETTLE_TIMEOUT_S",
    "AttributedReader",
    "host_env",
    "kill_host",
    "spawn_host",
    "stop_host",
]

#: The child is always this module, run with ``-m``. No arguments: everything
#: the child needs arrives on the wire, so nothing about a deployment shows up
#: in ``ps``.
CHILD_MODULE = "osprey_connectors.ipc._host"


[docs] def host_env() -> dict[str, str]: """The environment a child is launched with: :data:`os.environ`, minus EPICS. The child scrubs ``EPICS_CA_*``/``EPICS_PVA_*`` again on its own first line, and that is the scrub the design depends on. This one is the defense-in-depth half: an ambient gateway never reaches the process that could act on it, so no window exists between exec and scrub. The child is stamped with :data:`~osprey_connectors.dotenv.ENV_CHAIN_APPLIED_ENV`. Reading its config file would otherwise load the project ``.env`` from its working directory after the scrub, and an ``EPICS_*`` line there would put back what both scrubs took out. :data:`~osprey_connectors.ipc._host.START_MARKS_FD_ENV` is dropped too: a supervisor that is itself running under one never passes on a descriptor number that names something else in its child. """ env = { name: value for name, value in os.environ.items() if not name.startswith(EPICS_ENV_PREFIXES) and name != START_MARKS_FD_ENV } env[ENV_CHAIN_APPLIED_ENV] = "1" return env
[docs] async def spawn_host( python: str, env: Mapping[str, str], *, start_marks_fd: int | None = None ) -> asyncio.subprocess.Process: """Launch one connector-host child with its frame pipes attached. Args: python: The interpreter to run the child under. env: The child's environment, normally :func:`host_env`. start_marks_fd: The write end of a pipe the child writes its start marks to (see :mod:`osprey_connectors.ipc._host`), or ``None`` for a child that writes none. The child inherits the descriptor under the same number; the caller closes its own copy after the spawn. Returns: The ``asyncio.subprocess.Process``. stderr is inherited, so the child's diagnostics land wherever the supervisor's own do. Raises: OSError: The interpreter could not be executed. Callers wrap this in whatever their own failure type is. """ child_env = dict(env) pass_fds: tuple[int, ...] = () if start_marks_fd is not None: child_env[START_MARKS_FD_ENV] = str(start_marks_fd) pass_fds = (start_marks_fd,) return await asyncio.create_subprocess_exec( python, "-m", CHILD_MODULE, stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE, env=child_env, pass_fds=pass_fds, )
[docs] class AttributedReader: """A child's stdout, able to say why reading it stopped. The proxy fails every outstanding request with whatever ended its read stream. Left to itself that is an anonymous end-of-pipe, which tells an operator nothing about the decision that caused it — so the supervisor names the reason here before it kills the child, and the proxy's :class:`ConnectionError` carries it. """
[docs] def __init__(self, stream: asyncio.StreamReader) -> None: self._stream = stream self._reason: str | None = None
[docs] def retire(self, reason: str) -> None: """Name the reason the stream is about to end. Call before the kill.""" self._reason = reason
[docs] async def read(self, count: int) -> bytes: if self._reason is not None: raise ConnectionError(self._reason) chunk: bytes = await self._stream.read(count) # The usual path: the reader was already blocked here when the child was # retired, and the kill it was told about is what ends the read. if not chunk and self._reason is not None: raise ConnectionError(self._reason) return chunk
#: How long, after a child is killed, the proxy's reader gets to turn the dead #: pipe into failures on the calls that were in flight. SETTLE_TIMEOUT_S = 2.0
[docs] async def kill_host( process: asyncio.subprocess.Process, proxy: ConnectorHostProxy, reader: AttributedReader, *, reason: str | None, grace_s: float, ) -> None: """Put down a child that failed, and let its proxy settle. Never raises. Args: process: The child's ``asyncio.subprocess.Process``. proxy: The :class:`~osprey_connectors.ipc.ConnectorHostProxy` over its pipes. reader: The proxy's :class:`AttributedReader`. reason: Why the child is put down, named on the reader before the kill so every request in flight fails with it. ``None`` when the caller has already retired the reader. grace_s: How long the child gets to exit after SIGTERM before SIGKILL. """ if reason is not None: reader.retire(reason) await terminate(process, grace_s) await proxy.drain(SETTLE_TIMEOUT_S) await proxy.disconnect(ack_timeout=0.0)
[docs] async def stop_host( process: asyncio.subprocess.Process, proxy: ConnectorHostProxy, *, grace_s: float ) -> None: """Stop a healthy child in order: acknowledge, then make sure it is gone. Never raises. Args: process: The child's ``asyncio.subprocess.Process``. proxy: The :class:`~osprey_connectors.ipc.ConnectorHostProxy` over its pipes. grace_s: How long the child gets to exit after SIGTERM before SIGKILL. """ await proxy.disconnect() await terminate(process, grace_s)