"""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."
),
)