Source code for osprey_connectors.ipc._verification

"""What a connector-host child should connect to, and whether it did.

Two pure questions every supervisor of :mod:`osprey_connectors.ipc._host`
children asks, answered once for all of them — the controls MCP server's target
switch and the library's multi-target
:class:`~osprey_connectors.ipc.ConnectorHostPool` alike:

**Derivation** (:func:`derive_endpoints`) restates
``EPICSConnector.connect()``'s gateway selection *positively*, from config
alone: for a target, the connector type it resolves to, the endpoint each
configured gateway role would produce, and the role this run will actually
select given the target's write posture and the run mode.

**Verification** (:func:`verify_host_report`, and :func:`verify_child_report`
for the gateway case) compares a child's post-connect report against that
derivation: not "nothing looked wrong" but "the child configured exactly this
host, this port, this mode, for exactly the role the derivation selected". A
mismatch names the field, the expected value and the value received.

**Collision with the live machine** (:func:`live_collision`) is the one
eligibility question both supervisors ask from derivation alone: an endpoint a
target that is never the real machine selects must not be one ``live`` derives.

Nothing here imports a control-system client library.
"""

from __future__ import annotations

from collections.abc import Mapping
from dataclasses import dataclass
from typing import SupportsIndex, SupportsInt

from osprey_connectors.config import config_flag
from osprey_connectors.control_system._gateway_role import (
    ROLE_READ_ONLY,
    ROLE_WRITE_ACCESS,
    _selected_role,
    readonly_gateway_refusal,
)
from osprey_connectors.posture_env import is_readonly_run
from osprey_connectors.types import (
    STANDIN_TYPES,
    TARGET_LIVE,
    TRANSPORT_IN_PROCESS,
    VIRTUAL_ACCELERATOR,
    connector_transport,
    resolve_target,
    tier_allows,
)

__all__ = [
    "config_section",
    "subsection",
    "DEFAULT_CA_PORT",
    "DEFAULT_PVA_PORT",
    "GATEWAYS_MISSING",
    "GATEWAYS_NONE_DECLARED",
    "GATEWAYS_ROWS",
    "MODE_ADDR_LIST",
    "MODE_NAME_SERVER",
    "NEVER_LIVE_TYPES",
    "ROLE_PVA",
    "ROLE_READ_ONLY",
    "ROLE_WRITE_ACCESS",
    "Endpoint",
    "LiveCollision",
    "TargetDerivation",
    "Verification",
    "connector_block",
    "declared_gateways",
    "derive_endpoints",
    "live_collision",
    "readonly_gateway_refusal",
    "same_endpoint",
    "verify_child_report",
    "verify_host_report",
]

# -- Gateway roles and the environment modes they produce -------------------

ROLE_PVA = "pva"

#: ``use_name_server: true`` — EPICS_CA_NAME_SERVERS / EPICS_PVA_NAME_SERVERS.
MODE_NAME_SERVER = "name_server"
#: ``use_name_server: false`` — EPICS_CA_ADDR_LIST / EPICS_PVA_ADDR_LIST.
MODE_ADDR_LIST = "addr_list"

#: The ports ``EPICSConnector.connect()`` falls back to when a gateway names
#: none. The virtual accelerator never reaches the CA default: its unset ports
#: are filled from ``services.virtual_accelerator.port`` first. The PVA default
#: applies to name servers only (TCP); an address-list entry that names no port
#: is passed to p4p without one, so its row carries ``None``.
DEFAULT_CA_PORT = 5064
DEFAULT_PVA_PORT = 5075

#: How a connector block spells its ``gateways`` table, as
#: :func:`declared_gateways` reads it: an explicit ``gateways: []`` (nothing to
#: probe), no table anybody filled in, or rows.
GATEWAYS_NONE_DECLARED = "none_declared"
GATEWAYS_MISSING = "missing"
GATEWAYS_ROWS = "rows"


[docs] @dataclass(frozen=True) class Endpoint: """Where one gateway role points, and how the child will say so to EPICS.""" host: str #: The ``port`` the gateway block carries, as written (or the default the #: derivation filled in): usually an ``int``, but whatever the config holds. port: object mode: str
[docs] def as_dict(self) -> dict[str, object]: return {"host": self.host, "port": self.port, "mode": self.mode}
[docs] @dataclass(frozen=True) class TargetDerivation: """What a connector-host child *will* do for a target, derived from config. ``endpoints`` carries one row per configured role: ``read_only`` and ``write_access`` when the gateways table has them, plus ``pva`` when the block configures PVA routing *and* a PVA gateway — the same conjunction ``connect()`` requires before it touches a PVA environment variable. ``selected_role`` is the row the child will actually configure the process with: EPICS keeps one process-wide context, so exactly one gateway is used. ``transport`` is the wire the child's connector will speak (:func:`~osprey_connectors.types.connector_transport`), so a child that built the other venue of the simulator is refused by what it echoes. ``gateways_declared`` is :func:`declared_gateways` of the block: only an explicit empty ``gateways: []`` is :data:`GATEWAYS_NONE_DECLARED`, the facility saying this target has nothing to probe. A missing table is not that statement — a forgotten table must never read as a direct connection — so it is :data:`GATEWAYS_MISSING`. The simulator served in process reads no block, and keeps the default. """ target: str connector_type: str endpoints: dict[str, Endpoint] selected_role: str transport: str | None gateways_declared: str = GATEWAYS_MISSING @property def declares_no_endpoints(self) -> bool: """Whether the block spells ``gateways: []``, and so has nothing to probe.""" return self.gateways_declared == GATEWAYS_NONE_DECLARED
[docs] def selected_endpoint(self) -> Endpoint | None: """The row the child will configure, or ``None`` when config has none.""" return self.endpoints.get(self.selected_role)
[docs] @dataclass(frozen=True) class Verification: """Whether the child came up where the derivation said it would.""" ok: bool field: str | None = None expected: object = None got: object = None detail: str = ""
[docs] def as_dict(self) -> dict[str, object]: return { "ok": self.ok, "field": self.field, "expected": self.expected, "got": self.got, "detail": self.detail, }
[docs] def config_section(config: object, name: str) -> dict[str, object]: """One top-level section of a rendered config, or an empty mapping. Nested sections only, the way ``MCPServerConfig`` and ``ConfigBuilder`` read this file: a top-level dotted line in ``config.yml`` configures nothing. """ if not isinstance(config, dict): return {} value = config.get(name) return value if isinstance(value, dict) else {}
[docs] def subsection(section: Mapping[str, object], name: str) -> dict[str, object]: """One nested section of *section*, or an empty mapping when it is absent or not one.""" value = section.get(name) return value if isinstance(value, dict) else {}
[docs] def connector_block(config: object, connector_type: str) -> object: """The ``control_system.connector.<type>`` block, as written.""" return subsection(config_section(config, "control_system"), "connector").get(connector_type)
def _mode(gateway: Mapping[str, object], key: str) -> str: name_server = config_flag(gateway.get("use_name_server"), key=f"{key}.use_name_server") return MODE_NAME_SERVER if name_server else MODE_ADDR_LIST def _row(gateway: object, default_port: int | None, key: str) -> Endpoint | None: """One endpoint row, or ``None`` for a gateway ``connect()`` would ignore. ``connect()`` guards its environment derivation with ``if gateway_config:``, so a missing, non-mapping or empty gateway configures nothing at all — and a role that configures nothing is not a role this deployment can select. """ if not isinstance(gateway, dict) or not gateway: return None return Endpoint( host=gateway.get("address", ""), port=gateway.get("port", default_port), mode=_mode(gateway, key), ) def _pva_globs(block: Mapping[str, object]) -> list[str]: """The PVA routing globs, normalized exactly as ``connect()`` normalizes.""" pva_channels = block.get("pva_channels") or [] if isinstance(pva_channels, str): pva_channels = [pva_channels] if not isinstance(pva_channels, list | tuple): return [] return [str(pattern).strip() for pattern in pva_channels if str(pattern).strip()]
[docs] def derive_endpoints( config: object, target: str, *, writes_enabled: bool | None = None, readonly_run: bool | None = None, config_path: str | None = None, ) -> TargetDerivation: """Derive the per-role endpoints and selected role for *target*. Args: config: The full rendered config mapping (``config.yml`` as loaded). target: The control target, ``'live'`` or ``'va'``. writes_enabled: Whether writes are armed for *target*. Defaults to the deployment's write tier — :func:`~osprey_connectors.types.tier_allows` over the ``control_system`` section, which is what the connector's write verdict reads — never the per-type ``writes_enabled`` key on its own; injectable so a caller (or a test) can derive the endpoints of a posture other than the configured one. readonly_run: Whether this is a readonly executor run. Defaults to :func:`~osprey_connectors.posture_env.is_readonly_run`. config_path: The project config an unset virtual-accelerator gateway port is filled from — the file the child reads, so the port derived here is the port it connects to. ``None`` reads ``CONFIG_FILE``, else ``./config.yml``. Returns: The derivation, whose ``endpoints`` may be empty when the deployment has no gateways for this target — an eligibility question, not an error, so the derivation still answers "which role would be selected". Raises: ValueError: Propagated from :func:`~osprey_connectors.types.resolve_target` when the target is unknown, or is ``live`` on a deployment that has never named its real machine, and from :func:`~osprey_connectors.config.config_flag` when a ``use_name_server`` spells neither true nor false. :func:`~osprey.mcp_server.control_system.target_eligibility.evaluate_eligibility` is where that becomes a reason rather than an exception. """ control_system = config_section(config, "control_system") connector_type = resolve_target(control_system, target) transport = connector_transport(control_system, connector_type) if transport == TRANSPORT_IN_PROCESS: # The simulator served inside the child dials nothing, so there is no # block to read endpoints from and no gateway role to select. return TargetDerivation( target=target, connector_type=connector_type, endpoints={}, selected_role=ROLE_READ_ONLY, transport=transport, ) if writes_enabled is None: writes_enabled = tier_allows(control_system) if readonly_run is None: readonly_run = is_readonly_run() raw_block = connector_block(config, connector_type) block = raw_block if isinstance(raw_block, dict) else {} # The virtual accelerator served from its container is a service this # project deploys, so an unset gateway port follows # services.virtual_accelerator.port. Filled through the # connector's own helper rather than restated, so the roster cannot name a # port the child will not use. if connector_type == VIRTUAL_ACCELERATOR: # Imported here: the connector module is only needed for this one # type, and the derivation should not load a connector to answer for # every other one. from osprey_connectors.control_system._va_connector import fill_gateway_ports block = fill_gateway_ports(block, config_path) block_key = f"control_system.connector.{connector_type}" gateways = subsection(block, "gateways") endpoints: dict[str, Endpoint] = {} for role in (ROLE_READ_ONLY, ROLE_WRITE_ACCESS): row = _row(gateways.get(role), DEFAULT_CA_PORT, f"{block_key}.gateways.{role}") if row is not None: endpoints[role] = row # PVA is derived only under the same conjunction connect() requires: routing # globs AND a gateway. Globs without a gateway import p4p but touch no PVA # environment variable, so there is no endpoint to report. if _pva_globs(block): pva_gateway = block.get("pva_gateway") # connect() appends no port to an address list unless one is set; the # TCP default applies to name servers only. pva_key = f"{block_key}.pva_gateway" name_server = ( isinstance(pva_gateway, dict) and _mode(pva_gateway, pva_key) == MODE_NAME_SERVER ) pva_row = _row(pva_gateway, DEFAULT_PVA_PORT if name_server else None, pva_key) if pva_row is not None: endpoints[ROLE_PVA] = pva_row return TargetDerivation( target=target, connector_type=connector_type, endpoints=endpoints, selected_role=_selected_role( gateways, writes_enabled=bool(writes_enabled), readonly_run=bool(readonly_run) ), transport=transport, gateways_declared=declared_gateways(block), )
[docs] def declared_gateways(block: object) -> str: """How a connector *block* spells its ``gateways`` table: the one reader of that fact. Only the explicit empty list is :data:`GATEWAYS_NONE_DECLARED`. A block that is not a mapping, or whose table is missing, ``null``, ``{}`` or anything but a non-empty mapping, is :data:`GATEWAYS_MISSING` — a table nobody filled in, never "nothing to probe". A non-empty mapping is :data:`GATEWAYS_ROWS`. """ if not isinstance(block, dict): return GATEWAYS_MISSING if block.get("gateways") == []: return GATEWAYS_NONE_DECLARED return GATEWAYS_ROWS if subsection(block, "gateways") else GATEWAYS_MISSING
# --------------------------------------------------------------------------- # Verification # --------------------------------------------------------------------------- def _as_int(value: object) -> int: """``int(value)`` for whatever ``int`` converts; ``TypeError`` for anything else.""" if isinstance(value, str | bytes | SupportsInt | SupportsIndex): return int(value) raise TypeError(f"{type(value).__name__!r} is not a number") def _ports_equal(expected: object, got: object) -> bool: """Whether two ports name the same port. ``connect()`` interpolates the port into a string environment value, so a child may report ``'5064'`` where the config carries ``5064``. Compared numerically when both are integral and textually otherwise, so a genuinely different port never compares equal. """ try: return _as_int(expected) == _as_int(got) except (TypeError, ValueError): return str(expected) == str(got) def _host_key(host: object) -> str: """*host* as two rows must both spell it to name the same machine. Stripped and case-folded, and nothing more: no name is resolved, and no two spellings of one address — ``localhost`` and ``127.0.0.1``, say — are folded together. A compose service name that resolves only inside its own network is a host this process may be unable to resolve at all, and a comparison that needed to would answer differently on every machine. """ return str(host).strip().lower() if host is not None else "" def same_endpoint(first: Endpoint, second: Endpoint) -> bool: """Whether two derived rows name the same address and port, as written. The CA/PVA *mode* is deliberately not compared: a name server and an address-list entry on one host and port reach the same server. Ports are compared as verification compares them (``'5064'`` is ``5064``); hosts as :func:`_host_key` spells them, so two different spellings of one machine are not caught here. """ return _host_key(first.host) == _host_key(second.host) and _ports_equal(first.port, second.port) #: Types that are never the facility's own machine, so an endpoint one of them #: selects must never be an endpoint ``live`` derives. NEVER_LIVE_TYPES = frozenset({VIRTUAL_ACCELERATOR, *STANDIN_TYPES})
[docs] @dataclass(frozen=True) class LiveCollision: """A live gateway that a never-live target's selected endpoint lands on. ``selected`` and ``live`` name the same endpoint, each as its own block spells it; ``role`` and ``connector_type`` locate ``live`` in the config. """ selected: Endpoint live: Endpoint role: str connector_type: str
[docs] def live_collision( config: object, derivation: TargetDerivation, *, config_path: str | None = None ) -> LiveCollision | None: """The live gateway *derivation*'s selected endpoint lands on, or ``None``. Only a target whose type is in :data:`NEVER_LIVE_TYPES` is asked: its reads and writes must not reach an endpoint ``live`` derives from the same config, read-only or write-access alike, or they reach the real machine under a soft label. Addresses are compared as written (:func:`same_endpoint`), never resolved, so this is the negative half only — whatever the target is, it is not the machine. A deployment with no live machine has nothing to collide with. Args: config: The rendered config mapping *derivation* was derived from. derivation: The target being judged, from :func:`derive_endpoints`. config_path: See :func:`derive_endpoints`; pass the one *derivation* used. """ selected = derivation.selected_endpoint() if selected is None or derivation.connector_type not in NEVER_LIVE_TYPES: return None try: live = derive_endpoints( config, TARGET_LIVE, writes_enabled=False, readonly_run=True, config_path=config_path ) except ValueError: return None for role in (ROLE_READ_ONLY, ROLE_WRITE_ACCESS): row = live.endpoints.get(role) if row is not None and same_endpoint(selected, row): return LiveCollision( selected=selected, live=row, role=role, connector_type=live.connector_type ) return None
def verify_child_report(derivation: TargetDerivation, report: Mapping[str, object]) -> Verification: """Assert a child came up exactly where the derivation said it would. Positive and role-aware: every field of the selected role's endpoint is compared, and the child must also say it configured EPICS at all — a child that connected without a gateway leaves ``_epics_configured`` false and has silently inherited whatever CA environment the process already carried. Args: derivation: The derivation for the target being switched to, from :func:`derive_endpoints`. report: The child's post-connect report: ``selected_role``, ``mode``, ``host``, ``port`` and ``_epics_configured``. Returns: A passing :class:`Verification`, or a failing one naming the field, the expected value and the value the child reported. The switch aborts on a failure and leaves the previous target active. """ if not report.get("_epics_configured"): return Verification( False, "_epics_configured", True, report.get("_epics_configured"), "The child reports it never configured an EPICS gateway, so its " "environment is whatever the process already carried rather than this " "target's.", ) expected_role = derivation.selected_role got_role = report.get("selected_role") if got_role != expected_role: return Verification( False, "selected_role", expected_role, got_role, f"The child selected the {got_role!r} gateway where target " f"{derivation.target!r} derives {expected_role!r}.", ) endpoint = derivation.selected_endpoint() if endpoint is None: return Verification( False, "endpoints", f"a derived {expected_role!r} endpoint", None, f"Target {derivation.target!r} has no derived {expected_role!r} endpoint " "to compare the child against; it should never have been switched to.", ) for field_name, expected in (("mode", endpoint.mode), ("host", endpoint.host)): got = report.get(field_name) if got != expected: return Verification( False, field_name, expected, got, f"The child's {field_name} is {got!r} where target " f"{derivation.target!r} derives {expected!r} for its " f"{expected_role!r} gateway.", ) if not _ports_equal(endpoint.port, report.get("port")): return Verification( False, "port", endpoint.port, report.get("port"), f"The child's port is {report.get('port')!r} where target " f"{derivation.target!r} derives {endpoint.port!r} for its " f"{expected_role!r} gateway.", ) return Verification( True, detail=( f"The child is on target {derivation.target!r} via its {expected_role!r} " f"gateway at {endpoint.host}:{endpoint.port} ({endpoint.mode})." ), ) def _verify_posture( derivation: TargetDerivation, report: Mapping[str, object], *, readonly_run: bool, writes_enabled: bool | None, ) -> Verification | None: """The identity and posture failure in *report*, or ``None`` when there is none. The child echoes the target it was sent, so only the type it resolved that target to can differ — a child from another build of the package. Posture is checked for every connector type: the endpoint check sees it only through the gateway role, which a connector with no gateways, or with a ``read_only`` row alone, never varies. """ got_type = report.get("connector_type") if got_type != derivation.connector_type: return Verification( False, "connector_type", derivation.connector_type, got_type, f"The child reports connector type {got_type!r} where target " f"{derivation.target!r} derives {derivation.connector_type!r}.", ) got_transport = report.get("transport") if got_transport != derivation.transport: return Verification( False, "transport", derivation.transport, got_transport, f"The child for target {derivation.target!r} reports transport " f"{got_transport!r} where {derivation.transport!r} was derived.", ) if readonly_run: got_readonly = report.get("readonly_run") if got_readonly is not True: return Verification( False, "readonly_run", True, got_readonly, f"The child for target {derivation.target!r} was asked to run readonly " "but reports it is not in a readonly run.", ) return None if writes_enabled is None: return None got_writes = report.get("writes_enabled") if (got_writes is True) != writes_enabled: return Verification( False, "writes_enabled", writes_enabled, got_writes, f"The child for target {derivation.target!r} reports writes " f"{'armed' if got_writes is True else 'off'} where this process derives them " f"{'armed' if writes_enabled else 'off'}.", ) return None
[docs] def verify_host_report( derivation: TargetDerivation, report: Mapping[str, object], *, readonly_run: bool | None = None, writes_enabled: bool | None = None, ) -> Verification: """Assert the child came up where the derivation said it would. Given the posture the derivation was taken under (*readonly_run*, *writes_enabled*), the report is first held to it: its ``connector_type`` and its ``transport`` must be the derived ones, and then a readonly run requires the report's ``readonly_run`` to be ``True`` while any other run requires its ``writes_enabled`` to equal *writes_enabled*. With neither given, only the endpoint check below runs. :func:`verify_child_report` answers this for every target whose config names a gateway. A deployment can also select a connector that talks to no gateway at all — the simulator served in process is one, and it is the fail-safe default — and for that one the derivation has no endpoint and the child reports none. Nothing is verified there because there is no endpoint to get wrong, but the *symmetry* is: a child that configured Channel Access where the config derived nothing has inherited an environment from somewhere, and that is a mismatch as serious as any other. The unverified branch is entered only when the derivation has **no endpoint rows at all**. A target with rows whose *selected* role is missing — a write-only gateway table on a deployment that selects ``read_only``, say — is a gateway deployment with a hole in it, not a gatewayless one: its child connects to a real control system over whatever default broadcast address it finds, and that is precisely the unpinned-CA case verification exists to catch. It goes to :func:`verify_child_report`, which refuses it either for reporting no gateway or for having no derived endpoint to compare against. Args: derivation: The derivation for the target, from :func:`derive_endpoints`. report: The child's post-connect report. readonly_run: Whether the derivation was taken for a readonly run. writes_enabled: Whether the derivation was taken with writes armed. Returns: A passing :class:`Verification`, or a failing one naming the field (``connector_type``, ``transport``, ``readonly_run``, ``writes_enabled`` or an endpoint field), the expected value and the value the child reported. """ if readonly_run is not None or writes_enabled is not None: refusal = _verify_posture( derivation, report, readonly_run=bool(readonly_run), writes_enabled=writes_enabled ) if refusal is not None: return refusal if derivation.endpoints: return verify_child_report(derivation, report) if report.get("_epics_configured") or report.get("mode") or report.get("host"): return Verification( False, "_epics_configured", False, report.get("_epics_configured"), f"Target {derivation.target!r} derives no gateway on this deployment, but the " f"child reports it configured {report.get('mode')!r} routing to " f"{report.get('host')!r} — an endpoint this config never described.", ) if derivation.declares_no_endpoints: return Verification( True, detail=( f"Target {derivation.target!r} declares no endpoints (`gateways: []`), " "so there is no gateway to check the child against, and it configured none." ), ) return Verification( True, detail=( f"Target {derivation.target!r} derives no gateway (connector type " f"{derivation.connector_type!r}) and the child configured none." ), )