"""Connector type constants, and the fallbacks a factory applies to them.
Single source of truth for built-in connector type name strings.
Custom connectors use dotted module paths (e.g., 'mypackage.SiteConnector')
and don't need constants here.
The resolvers at the bottom are here rather than in
:mod:`osprey_connectors.factory` so that a guard deciding what a deployment
*will build* can share them with the factory that builds it. A guard which
re-implements "what does this config select" is a guard that can disagree with
the answer, and the disagreement is a bypass rather than a discrepancy — see
:mod:`osprey_connectors.honesty`.
:func:`resolve_archiver_settings` is the same arrangement for the other half of
an archiver selection: which block its ``connect()`` is handed. The build
refuses what it would refuse, from the same helpers.
:func:`resolve_target` extends that to the run-time question "which machine is
this session pointed at". It is the same shape of answer for the same reason:
several holders follow a control target — the connector-host process, its child,
an executor sandbox — and a holder that translates ``live`` into a connector type
privately can route a tool call somewhere the roster never claimed. A target
names a *machine*, and there are three of them: the facility's own control
system (``live``), the virtual accelerator (``va``), and the live stand-in
(``standin``) — a soft IOC a deployment runs for itself, which is a third
machine with a connector block of its own rather than a mode of the first. That
is what keeps ``live`` meaning the machine the facility authored on a deployment
that runs the stand-in beside it. The target is an *argument* here, never
something this module reads from the environment: an environment-reading
override would make the honesty predicate describe a deployment the process is
no longer running.
:func:`tier_writes` answers "how far may this deployment write" from the one tier key,
``control_system.writes``, for the same reason. The lint that reads the config,
the profile card that tells an operator what they hold, and the connector that
would perform the write all have to agree about the answer. Two readings of one
posture is one of them being wrong about a machine somebody can move.
:class:`LimitsPosture` is the same story for limits checking, which is likewise
per connector type: a deployment may run its simulator ``optional`` while its
live machine runs ``exclusive``. It carries the resolved posture together
with the config key that answered it, so a refusal names the line an operator
would have to edit rather than one some per-type block overrides.
Where the write tier reads an unusable value as ``never`` and is done, the
limits family cannot: "no limits checking configured" is itself a permissive
answer, so a leaf written as something no reader can turn into a boolean is
reported as a block that failed to state it rather than as a block that stated
nothing. Such a posture answers neither leaf, and a caller that must act blocks
every write instead of waving them through unchecked.
"""
import json
import logging
import os
from collections.abc import Callable, Mapping
from dataclasses import dataclass
from typing import Final, Literal, TypeGuard
__all__ = [
"CLI_CONTROL_SYSTEM_TYPES",
"CONTROL_TARGETS",
"ControlTarget",
"DEFAULT_VA_PORT",
"DOOCS",
"DOOCS_ARCHIVER",
"EPICS",
"EPICS_ARCHIVER",
"INVENTED_HISTORY_TYPES",
"IN_PROCESS",
"LIMITS_CHECKING_LEAF",
"LIMITS_LEAVES",
"LIMITS_MODES",
"LIMITS_MODE_EXCLUSIVE",
"LIMITS_MODE_OPTIONAL",
"LIVE_STANDIN",
"LimitsPosture",
"MOCK_ARCHIVER",
"MONGODB_ARCHIVER",
"MYA_ARCHIVER",
"RETIRED_CONTROL_SYSTEM_TYPES",
"SERVED",
"SERVING_KEY",
"SERVING_LEAF",
"SERVING_MODES",
"SET_CONTROL_SYSTEM_TYPES",
"SIMULATED_TYPES",
"STANDIN_TYPES",
"TANGO",
"TARGET_LIVE",
"TARGET_STANDIN",
"TARGET_VA",
"TIER_WORDS",
"TierWord",
"TRANSPORT_CA",
"TRANSPORT_IN_PROCESS",
"UNSET_TYPE_WARNING",
"VIRTUAL_ACCELERATOR",
"WRITES_KEY",
"archiver_settings_errors",
"archiver_settings_key",
"baseline_target",
"configured_targets",
"connector_transport",
"incomplete_limits_blocks",
"is_simulated",
"limits_database_required",
"machine_kind",
"most_restrictive_limits_posture",
"published_machine_kind",
"resolve_archiver_settings",
"resolve_archiver_type",
"resolve_control_system_type",
"resolve_serving",
"resolve_target",
"retired_type_message",
"speaks_channel_access",
"switch_capable",
"talks_to_network",
"target_configured",
"target_limits_posture",
"tier_allows",
"tier_limits_database_targets",
"tier_writes",
"type_limits_posture",
]
logger = logging.getLogger("osprey_connectors.types")
#: Config shapes the second-real-block warning has already been said about, so
#: a resolver asked on every roster render says it once. Keyed by the shape
#: itself — a deployment has one, and a test that edits a config gets a fresh
#: line for the shape it edited to.
_SECOND_REAL_BLOCK_WARNED: set[tuple[str, tuple[str, ...]]] = set()
# -- Control system connector types (have implementations) --
EPICS = "epics"
VIRTUAL_ACCELERATOR = "virtual_accelerator"
DOOCS = "doocs"
TANGO = "tango"
#: The live stand-in: a facility-shaped soft IOC a deployment runs for itself.
#: A connector type of its own — served by the EPICS connector, but keyed apart
#: from ``epics`` so that the facility's authored ``epics`` block stays the one
#: thing ``live`` can mean, and the stand-in gets its own
#: ``control_system.connector.live_standin`` block to be configured from.
LIVE_STANDIN = "live_standin"
#: Channel Access port the shipped Virtual Accelerator soft-IOC serves on. It is
#: here rather than only in the VA connector because the deployment layer fills
#: the same default when it dials the VA, and it must not import a concrete
#: connector (and the EPICS client stack behind it) to learn one integer.
DEFAULT_VA_PORT = 5064
# -- Where the simulator runs --
#: The leaf under ``control_system.connector.virtual_accelerator`` that says
#: where the simulator runs: ``served`` from its container over Channel Access,
#: or ``in_process`` inside the process that asks, with no network at all.
SERVING_LEAF = "serving"
SERVED = "served"
IN_PROCESS = "in_process"
SERVING_MODES = (SERVED, IN_PROCESS)
SERVING_KEY = f"control_system.connector.{VIRTUAL_ACCELERATOR}.{SERVING_LEAF}"
# -- Transports: the wire a connector speaks --
TRANSPORT_IN_PROCESS = "in_process"
TRANSPORT_CA = "ca"
_TRANSPORT_DOOCS = "doocs"
_TRANSPORT_TANGO = "tango"
#: The wire each built-in type speaks when it is served over a network. There
#: is no PVAccess row: the EPICS-family connectors carry PVAccess channels beside
#: Channel Access, behind the same gateway gate, so ``ca`` covers both. A
#: connector that speaks only PVAccess adds its own row.
_TRANSPORTS = {
EPICS: TRANSPORT_CA,
VIRTUAL_ACCELERATOR: TRANSPORT_CA,
LIVE_STANDIN: TRANSPORT_CA,
DOOCS: _TRANSPORT_DOOCS,
TANGO: _TRANSPORT_TANGO,
}
# -- Retired type names --
#: Type names no deployment may state any more, each with the type that now
#: means it. A table rather than a missing registration, so that every site
#: refusing one says what to write instead.
RETIRED_CONTROL_SYSTEM_TYPES = {"mock": VIRTUAL_ACCELERATOR}
#: What a factory says when it builds from a section that states no type.
UNSET_TYPE_WARNING = (
f"control_system.type is not set; defaulting to '{VIRTUAL_ACCELERATOR}' "
"served in process (no network). Set control_system.type explicitly to "
"select a connector."
)
# -- Archiver connector types --
MOCK_ARCHIVER = "mock_archiver"
EPICS_ARCHIVER = "epics_archiver"
MONGODB_ARCHIVER = "mongodb_archiver"
DOOCS_ARCHIVER = "doocs_archiver"
MYA_ARCHIVER = "mya_archiver"
# -- CLI choice lists (only types with implementations) --
CLI_CONTROL_SYSTEM_TYPES = [EPICS, VIRTUAL_ACCELERATOR, DOOCS, TANGO]
_CLI_ARCHIVER_TYPES = [
MOCK_ARCHIVER,
EPICS_ARCHIVER,
MONGODB_ARCHIVER,
DOOCS_ARCHIVER,
MYA_ARCHIVER,
]
#: Settable, not initable. A deployment may be pointed at its stand-in once it
#: has one — ``osprey set connector=live_standin`` is how a session starts on
#: the soft IOC — but ``osprey init`` never offers it: a fresh project has no
#: stand-in to point at, so a project that began on one would name a machine
#: that does not exist. Hence one list for what the ``connector:`` shorthand
#: accepts and another, narrower one for what ``init`` will materialize.
SET_CONTROL_SYSTEM_TYPES = [*CLI_CONTROL_SYSTEM_TYPES, LIVE_STANDIN]
# -- Control targets --
# What a *deployment* can be pointed at, as opposed to what a *config* selects.
# Deliberately three names and not one per connector type: a target names a
# machine (the facility's own, the virtual accelerator, the stand-in soft IOC),
# and which connector type reaches that machine is this module's job to answer,
# not the caller's.
ControlTarget = Literal["live", "va", "standin"]
TARGET_LIVE: Final = "live"
TARGET_VA: Final = "va"
TARGET_STANDIN: Final = "standin"
CONTROL_TARGETS: list[ControlTarget] = [TARGET_LIVE, TARGET_VA, TARGET_STANDIN]
#: The topology those three names bound, spelled once and quoted by every
#: answer that runs into it. One deployment describes one real machine: the
#: target vocabulary has a single name for it, and the connector table is keyed
#: by connector type, so a second machine on the same protocol cannot be written
#: down at all. That is a product shape rather than an oversight — a complex
#: whose sessions must reach two real machines runs one deployment per machine,
#: which is also what keeps a session's posture, limits and archive about one
#: machine each. Said here so a deployer meets it in the error and in the how-to
#: rather than in the silence of a configured block nothing ever offers.
_ONE_REAL_MACHINE = (
"A deployment names one real machine — exactly one connector block that is "
"neither simulated nor the stand-in — and 'live' is that machine. A complex "
"with two real machines runs one deployment per machine."
)
# -- Write posture --
#: The login tier's write ceiling, dotted as a caller spells it for
#: ``get_config_value``: ``"never"``, ``"asked"`` or ``"allowed"``, the furthest
#: position a login may pick. Target-blind — a tier that allows writes allows
#: them for every machine, and which machine is actually written is the
#: session's switch to decide, not the tier's. Read by :func:`tier_writes`; when
#: the key is absent the tier is ``never``.
WRITES_KEY = "control_system.writes"
#: :data:`WRITES_KEY`'s leaf inside the ``control_system:`` section.
_WRITES_LEAF = "writes"
#: The two values of :data:`WRITES_KEY` that arm anything, and the refusing word.
_TIER_ALLOWED: Literal["allowed"] = "allowed"
_TIER_ASKED: Literal["asked"] = "asked"
_TIER_NEVER: Literal["never"] = "never"
#: One tier word, as a type: a member of :data:`TIER_WORDS`.
TierWord = Literal["never", "asked", "allowed"]
#: The three tier words, narrowest first: every answer :func:`tier_writes` gives.
TIER_WORDS: tuple[Literal["never"], Literal["asked"], Literal["allowed"]] = (
_TIER_NEVER,
_TIER_ASKED,
_TIER_ALLOWED,
)
#: Types that serve a machine nobody has to be careful around. They are the
#: reason ``live`` cannot simply be "whatever the config selects": a deployment
#: whose baseline is one of these has not yet said what its real machine is.
SIMULATED_TYPES = (VIRTUAL_ACCELERATOR,)
[docs]
def is_simulated(connector_type: str) -> bool:
"""Whether a connector type serves the simulator rather than a machine.
A type predicate: the simulator answers True whether it is served or runs
in process. It never says whether a connector dials a network; that is
:func:`speaks_channel_access` and :func:`talks_to_network`.
"""
return connector_type in SIMULATED_TYPES
#: Types that serve the live stand-in. Reachable only through the ``standin``
#: target: a stand-in is a machine in its own right, so it is never a candidate
#: for a deployment's ``live`` one — not as the baseline the derivation starts
#: from, and not as a block it falls back to. A deployment running the stand-in
#: beside its facility's own block still has exactly one real machine.
STANDIN_TYPES = (LIVE_STANDIN,)
#: Types whose history is invented rather than recorded, so pairing one with a
#: synthesizing archiver leaves nothing that ever tells a reader the data is
#: made up. Both are machines a deployment stands up for itself, and neither has
#: an archive of its own — see :mod:`osprey_connectors.honesty`.
INVENTED_HISTORY_TYPES = (VIRTUAL_ACCELERATOR, LIVE_STANDIN)
#: The target each self-standing machine's type is the baseline of. A type
#: absent from this table describes the facility's own machine, hence ``live``.
_BASELINE_TARGETS: dict[str, ControlTarget] = {
VIRTUAL_ACCELERATOR: TARGET_VA,
LIVE_STANDIN: TARGET_STANDIN,
}
def _resolve_type(section: object, fallback: str) -> str:
"""The connector type a factory builds from a config section.
A section that is missing, is not a mapping, or carries no usable ``type``
resolves to *fallback* — the factory's documented fail-closed default, which
it announces with a ``… is not set; defaulting to …`` warning. For a control
system that default is the simulator in process, which dials nothing; the
transport (:func:`connector_transport`), never the type, says whether a
connector dials a network. Empty and
``None`` count as absent (YAML gives ``None`` for a bare ``type:``); any
other value is returned as written, so a typo reaches the factory's
"Unknown … type" error rather than being quietly rounded to something.
"""
value = section.get("type") if isinstance(section, dict) else None
return str(value) if value else fallback
[docs]
def resolve_archiver_type(section: object) -> str:
"""The archiver an ``archiver:`` config section actually selects.
Absent means the mock: a config that says nothing about its archiver is a
config that gets the synthesizing one, which is the fact the honesty rule is
really about.
"""
return _resolve_type(section, MOCK_ARCHIVER)
[docs]
def resolve_control_system_type(section: object) -> str:
"""The control system a ``control_system:`` config section actually selects.
A section that states no type selects the simulator, and
:func:`resolve_serving` runs it in process, so it dials nothing. The
transport (:func:`connector_transport`), never the type, says whether a
connector dials a network.
"""
return _resolve_type(section, VIRTUAL_ACCELERATOR)
def _states_type(section: object) -> TypeGuard[dict[object, object]]:
return isinstance(section, dict) and bool(section.get("type"))
[docs]
def resolve_serving(section: object) -> str:
"""Where the simulator a ``control_system:`` section selects runs.
A section that states no type is the fail-safe default, the simulator in
process, and the leaf is not read: a section that names nothing must dial
nothing. A stated ``virtual_accelerator`` answers
:data:`SERVING_KEY`, else :data:`SERVED`. Any other stated type is
:data:`SERVED`: only the simulator has an in-process venue.
Raises:
ValueError: when the leaf holds a value outside :data:`SERVING_MODES`.
"""
if not _states_type(section):
return IN_PROCESS
if resolve_control_system_type(section) != VIRTUAL_ACCELERATOR:
return SERVED
connector = section.get("connector")
block: object = connector.get(VIRTUAL_ACCELERATOR) if isinstance(connector, dict) else None
value: object = block.get(SERVING_LEAF) if isinstance(block, dict) else None
if value is None:
return SERVED
if value not in SERVING_MODES:
raise ValueError(f"{SERVING_KEY} is {value!r}; it is {SERVED!r} or {IN_PROCESS!r}.")
return str(value)
[docs]
def connector_transport(section: object, connector_type: str | None = None) -> str | None:
"""The wire a connector built from *section* speaks.
Computed once, here, from the type and the serving leaf, so every check that
asks "does this speak Channel Access" or "does this dial a network" reads
one derived fact and never the type word. *connector_type* defaults to
:func:`resolve_control_system_type` of *section*; a caller building for a
target passes the type the target resolves to.
Returns:
:data:`TRANSPORT_IN_PROCESS` for the simulator served in process, the
type's :data:`_TRANSPORTS` row otherwise, and ``None`` for a type with
no row (a dotted custom connector).
Raises:
ValueError: when the serving leaf holds an unknown value.
"""
if connector_type is None:
connector_type = resolve_control_system_type(section)
if connector_type == VIRTUAL_ACCELERATOR and resolve_serving(section) == IN_PROCESS:
return TRANSPORT_IN_PROCESS
return _TRANSPORTS.get(connector_type)
[docs]
def speaks_channel_access(section: object, connector_type: str | None = None) -> bool:
"""Whether a connector built from *section* speaks real Channel Access.
The facility's own EPICS machine, the simulator served from its container,
or the live stand-in soft IOC. The queue worker builds its devices over
Channel Access, so these are the connectors plans can execute against today
and every other one browses. That is a property of the worker's device
layer, not of the plan stack: a facility whose machine speaks another
protocol executes plans once a device layer for it exists, and its
transport joins this one — this is not a statement that no other protocol
can ever run plans.
"""
return connector_transport(section, connector_type) == TRANSPORT_CA
[docs]
def talks_to_network(section: object, connector_type: str | None = None) -> bool:
"""Whether a connector built from *section* dials anything at all.
False only for the simulator served in process. A transport this module has
no row for (a dotted custom connector) answers True: what it dials is not
known, so it is not assumed to dial nothing.
"""
return connector_transport(section, connector_type) != TRANSPORT_IN_PROCESS
[docs]
def retired_type_message(value: str) -> str:
"""The one sentence every site refusing a retired type name quotes."""
replacement = RETIRED_CONTROL_SYSTEM_TYPES.get(value, VIRTUAL_ACCELERATOR)
return (
f"`{value}` is retired: the simulator in process is `control_system.type: "
f"{replacement}` with `{SERVING_KEY}: {IN_PROCESS}` (`osprey set "
f"connector={replacement} config.{SERVING_KEY}={IN_PROCESS}`), then "
"rebuild with `osprey build`."
)
#: The one block under ``archiver:`` a connector's settings are read from,
#: whichever route selected the connector. It has no dot in it, so a profile's
#: ``archiver.settings.<leaf>`` renders to exactly the block the factory reads.
_ARCHIVER_SETTINGS_LEAF = "settings"
#: Keys of the ``archiver:`` section that are not a connector's settings block:
#: the selector, the settings block itself, and archiver_read's point budget.
_ARCHIVER_SECTION_LEAVES = ("type", _ARCHIVER_SETTINGS_LEAF, "auto_bin_points")
def _own_name_block(connector_type: str) -> str | None:
"""The older spelling of a short-named archiver's settings, or ``None``.
A built-in, or a connector registered under a short name, may still keep
its settings in a block carrying its own name (``archiver.epics_archiver``).
A dotted module path has no such block: a profile splits keys on every dot,
so a block keyed by one could never have been written from ``config:``.
"""
return None if "." in connector_type else connector_type
def _archiver_settings_homes(section: object) -> list[tuple[str, object]]:
"""Every block in *section* that configures the selected archiver, in order."""
if not isinstance(section, dict):
return []
homes: list[tuple[str, object]] = []
if _ARCHIVER_SETTINGS_LEAF in section:
homes.append((_ARCHIVER_SETTINGS_LEAF, section[_ARCHIVER_SETTINGS_LEAF]))
own = _own_name_block(resolve_archiver_type(section))
if own is not None and own != _ARCHIVER_SETTINGS_LEAF and own in section:
homes.append((own, section[own]))
return homes
def _two_homes(own: str) -> str:
return (
f"`archiver.settings` and `archiver.{own}` both configure {own}; keep one "
f"— `archiver.settings` is the spelling for every archiver"
)
def _not_a_block(key: str, value: object) -> str:
return (
f"`archiver.{key}` is {value!r}, not a block; it holds the selected "
f"archiver's settings as a mapping"
)
[docs]
def archiver_settings_key(section: object) -> str:
"""The dotted key of the block that configures *section*'s archiver.
``archiver.<type>`` when a short-named archiver is configured by its own-name
block alone, else ``archiver.settings`` — so a message about a setting names
the line an operator actually wrote.
"""
homes = _archiver_settings_homes(section)
home = homes[0][0] if len(homes) == 1 else _ARCHIVER_SETTINGS_LEAF
return f"archiver.{home}"
[docs]
def resolve_archiver_settings(section: object) -> dict[str, object]:
"""The settings block the selected archiver's ``connect()`` is handed.
``archiver.settings`` for every archiver; for a short-named one, its own-name
block when ``settings`` is absent. Absent, or a bare ``settings:``, is ``{}``.
Raises:
ValueError: when both spellings are present, or the block is not a
mapping. :func:`archiver_settings_errors` refuses the same configs
at build time, with the same words.
"""
homes = _archiver_settings_homes(section)
if len(homes) > 1:
raise ValueError(_two_homes(homes[1][0]))
if not homes or homes[0][1] is None:
return {}
key, value = homes[0]
if not isinstance(value, dict):
raise ValueError(_not_a_block(key, value))
return dict(value)
[docs]
def archiver_settings_errors(section: object) -> list[str]:
"""Every block under a rendered ``archiver:`` section that no archiver reads, named.
A lint, like :func:`incomplete_limits_blocks`, and read by the build over the
config a deployment runs. It reports, in section order: each mapping under a
key no reader takes (anything but :data:`_ARCHIVER_SECTION_LEAVES`, a built-in
archiver's name, or the selected type's own name when it has no dot); then
the two refusals :func:`resolve_archiver_settings` raises, in its words. A
scalar is not a block and is not reported. Never raises.
"""
if not isinstance(section, dict):
return []
selected = resolve_archiver_type(section)
own = _own_name_block(selected)
known = {*_ARCHIVER_SECTION_LEAVES, *_CLI_ARCHIVER_TYPES, *([own] if own else [])}
errors = [
f"`{key}:` under `archiver:` is a block no archiver reads; the selected "
f"archiver, {selected}, takes its settings from `archiver.settings`"
for key, value in section.items()
if isinstance(value, dict) and key not in known
]
homes = _archiver_settings_homes(section)
if len(homes) > 1:
errors.append(_two_homes(homes[1][0]))
errors.extend(
_not_a_block(key, value)
for key, value in homes
if value is not None and not isinstance(value, dict)
)
return errors
[docs]
def resolve_target(section: object, target: object) -> str:
"""The connector type a session *target* selects, in a given deployment.
The returned type is also the key of the block the factory reads its
settings from — ``control_system.connector.<type>`` — so one string answers
both "what do I build" and "where are its gateways".
``va`` and ``standin`` are the same answer everywhere: ``va`` is the
deployment's simulator, and the stand-in is the soft IOC the deployment runs
for itself, configured from the block that carries its name. The factory
serves ``va`` in the venue ``connector.virtual_accelerator.serving`` names,
and only a deployment whose own type is ``virtual_accelerator`` may serve it
in process; the type this function answers is the same in either venue.
``live`` is deployment-specific and is the half that can refuse:
- When the section's own type is a real control system, that is the live
machine, and it is returned as written — including a value this module
does not recognize, which reaches the factory's "Unknown … type" error
exactly as :func:`resolve_control_system_type` already lets it. A second
non-simulated block beside it is not a second target: no name reaches it
(:data:`_ONE_REAL_MACHINE`), so it is warned about rather than skipped in
silence.
- When the section's own type is simulated or is a stand-in (or absent,
which resolves to the simulator in process), the deployment has not named
its real machine there, so the live type is taken from the connector
table: exactly one block that is neither simulated nor a stand-in means
the deployment has said which machine it means. None, or more than one, raises. The stand-in
is skipped on both sides of that derivation, so standing it up beside a
facility's ``epics`` block never makes ``live`` ambiguous and never
answers it with the stand-in.
Nothing is inferred from the absence of evidence. A deployment that has
never been told about its real machine gets an error naming what it would
have to configure, because the alternative — resolving ``live`` to the one
connector type that talks to hardware because it is the usual one — is a
tool call arriving at a real machine on the strength of a guess.
Args:
section: The ``control_system:`` config section, in the same shape
:func:`resolve_control_system_type` takes.
target: The control target, one of :data:`CONTROL_TARGETS`. An argument,
never read from the environment, and never defaulted.
Returns:
The connector type, which doubles as the connector sub-block key.
Raises:
ValueError: If *target* is not a known target (including ``None`` and
blank), or if it is ``live`` on a deployment with no single
derivable live control system.
"""
if target == TARGET_VA:
return VIRTUAL_ACCELERATOR
if target == TARGET_STANDIN:
return LIVE_STANDIN
if target == TARGET_LIVE:
return _live_type(section)
raise ValueError(
f"Unknown control target {target!r}. Valid targets are "
f"{TARGET_LIVE!r}, {TARGET_VA!r} and {TARGET_STANDIN!r}, spelled "
f"exactly. {_ONE_REAL_MACHINE} A control target is always stated, never "
"defaulted — there is no target a caller gets by saying nothing, "
"because the one it would get could be the real machine."
)
[docs]
def baseline_target(section: object) -> ControlTarget:
"""The target a deployment's own ``control_system:`` section selects.
``va`` for the simulator, in whichever venue its leaf names (a section
that states no type is the simulator in process, so it is on ``va``),
``standin`` for the live stand-in, and ``live`` for every real control
system.
Beside :func:`resolve_control_system_type` rather than restated by each
holder, because "which target am I on when nobody has switched" is asked by
the supervisor, the switch predicate below, and every baseline-pinned reader
— and three answers to it is three ways for one deployment to be described.
"""
return _BASELINE_TARGETS.get(resolve_control_system_type(section), TARGET_LIVE)
[docs]
def switch_capable(section: object) -> bool:
"""Whether a deployment gives a session more than one target to be pointed at.
The predicate itself, in the module that already owns "which connector type
does a target mean here". Two layers ask the question and must never answer
it differently: the controls server decides from it whether its tools are
served by a connector-host child, and the build decides from it whether the
agent's frozen safety rule describes a switchable machine at all. A build
that promises a switch the runtime will not perform is worse than one that
never mentions it.
One rule: a deployment is switch-capable when its section resolves and
**at least two targets are configured** (:func:`configured_targets`, the
same resolve-and-read-the-block enumeration every roster walks; the
baseline is always one of them).
Which two is not this predicate's business: a facility rehearsing on a
stand-in beside its simulator, with no live machine authored yet, has
exactly the two-machine world the switch exists for — demanding the
``live``/``va`` pair specifically would lock that deployment's posture
toggles for want of a machine it never claimed to have.
Deliberately *not* checked: ``probe_channel``, the gateways table, the
operator acknowledgment. Those decide whether a target may be switched *to*
— a per-switch question answered with a reason the operator is told. This is
the coarser question of whether the deployment is in the multi-target world.
Args:
section: The ``control_system:`` config section, in the same shape
:func:`resolve_control_system_type` takes. Callers holding a whole
rendered config pass ``config.get("control_system")``.
Returns:
``True`` when the section resolves and configures at least two
targets. Never raises: a section that is not a mapping or does not
resolve is not capable.
"""
if not isinstance(section, dict):
return False
try:
return len(configured_targets(section)) >= 2
except ValueError:
return False
[docs]
def tier_writes(section: object) -> Literal["never", "asked", "allowed"]:
"""The write ceiling this deployment's login tier sets: ``never``, ``asked`` or ``allowed``.
:data:`WRITES_KEY` decides when the section carries it, and then only the
literal strings ``"asked"`` and ``"allowed"`` arm, matched exactly; ``"never"``,
any other string (the switch's retired ``"on"`` among them), ``True``, ``None``
and every other value answer ``never``. When the key is absent the tier is
``never``: the retired arming leaves are not read at run time, so a render
built before the tier key existed writes nowhere until it is rebuilt (the
build's normalizer writes the key into every render).
Target-blind by design: a tier that allows writes allows them for every
machine. The tier is a ceiling, not a selection — the session's switch picks
the machine.
Never raises. A section that is not a mapping answers ``never``.
"""
value = section.get(_WRITES_LEAF) if isinstance(section, dict) else None
if isinstance(value, str):
if value == _TIER_ASKED:
return _TIER_ASKED
if value == _TIER_ALLOWED:
return _TIER_ALLOWED
return _TIER_NEVER
[docs]
def tier_allows(section: object) -> bool:
"""Whether the tier arms anything: :func:`tier_writes` is not ``never``. Never raises.
This reads the ceiling only: ``asked`` and ``allowed`` both answer true, so
whether a write prompts is not decided here.
"""
return tier_writes(section) != _TIER_NEVER
#: What kind of machine each control target names by its name alone, for the
#: words a refusal uses about it. ``standin`` is ``real`` here: a name cannot
#: tell this deployment's stand-in container from a ``standin`` target pointed at
#: anything else, so only the published report (:func:`published_machine_kind`)
#: may call it the rehearsal machine.
_MACHINE_KINDS: dict[str, Literal["real", "rehearsal", "simulator"]] = {
TARGET_LIVE: "real",
TARGET_STANDIN: "real",
TARGET_VA: "simulator",
}
#: The kind a published report may claim for ``standin``. Anything else it says
#: about that target, or nothing at all, reads as the real machine.
_REHEARSAL: Literal["rehearsal"] = "rehearsal"
#: The report key the controls server publishes each target's kind under.
_MACHINE_KIND_KEY = "machine_kind"
[docs]
def machine_kind(
section: object, target: object
) -> Literal["real", "rehearsal", "simulator"] | None:
"""The kind of machine *target* names by its name: ``real`` or ``simulator``.
``live`` and ``standin`` are the real machine, ``va`` the simulator. The
name never answers ``rehearsal``: whether a ``standin`` target really is
this deployment's stand-in is an endpoint fact only the controls server's
report states, read by :func:`published_machine_kind`. ``None`` when
:func:`resolve_target` cannot resolve the target in this deployment — an
unknown target, or ``live`` on a deployment that never named its real
machine. Never raises.
"""
try:
resolve_target(section, target)
except ValueError:
return None
# A target that resolved is one of the three names, so a string.
return _MACHINE_KINDS.get(target) if isinstance(target, str) else None
def _published_targets(directory: str) -> dict[str, object]:
"""Per-target metadata from the first live controls server's report, or ``{}``.
The hook twin's ``_published_targets`` restated: report files in name order,
the PID taken from the file name, a dead server's report skipped (never
deleted), and the first live report carrying a non-empty ``targets``
mapping is the answer. Never raises.
"""
# Imported here: control_context imports this module.
from osprey_connectors import control_context
prefix = control_context.REPORT_FILE_PREFIX
suffix = control_context.REPORT_FILE_SUFFIX
try:
names = sorted(
n for n in os.listdir(directory) if n.startswith(prefix) and n.endswith(suffix)
)
except (OSError, TypeError, ValueError):
return {}
for name in names:
try:
pid = int(name[len(prefix) : -len(suffix)])
except ValueError:
continue
if not control_context.is_process_alive(pid):
continue
try:
with open(os.path.join(directory, name), encoding="utf-8") as handle:
report: object = json.load(handle)
except (OSError, ValueError):
continue
if not isinstance(report, dict):
continue
targets = report.get("targets")
if isinstance(targets, dict) and targets:
return targets
return {}
[docs]
def published_machine_kind(
target: object, *, state_dir: str | os.PathLike[str] | None = None
) -> Literal["real", "rehearsal", "simulator"]:
"""The kind of machine *target* is, as this deployment's controls server publishes it.
The one source every surface reads (C-KIND). ``standin`` is ``rehearsal``
only when the first live server's report — in the hook twin's order, dead
servers' reports ignored — says so for it; no live report, no key, or any
other value reads ``real``, the cautious words. So a process that sees no
report (an executor sandbox, a bluesky or dispatch container, a deployment
with no server running) names a ``standin`` the real machine. Every other
target answers from the name table: ``va`` is the simulator, ``live`` and
anything unknown the real machine — a report can never make them a
rehearsal.
Args:
target: The control target.
state_dir: The directory holding the servers' reports; ``None`` reads
:func:`osprey_connectors.posture_store.state_dir`.
Returns:
``real``, ``rehearsal`` or ``simulator``. Never raises.
"""
if target != TARGET_STANDIN:
return _MACHINE_KINDS.get(target, "real") if isinstance(target, str) else "real"
try:
if state_dir is None:
# Imported here: posture_store imports this module.
from osprey_connectors import posture_store
state_dir = posture_store.state_dir()
if not isinstance(state_dir, str | os.PathLike):
# Only a path names a report directory; ``None`` names none.
return "real"
meta = _published_targets(os.fspath(state_dir)).get(TARGET_STANDIN)
except Exception: # the kind is a word an operator reads; it must not raise
logger.debug("Could not read the published machine kind", exc_info=True)
return "real"
if isinstance(meta, dict) and meta.get(_MACHINE_KIND_KEY) == _REHEARSAL:
return _REHEARSAL
return "real"
# -- Limits posture --
# Limits checking is per connector type for the same reason write posture is: a
# deployment with a live machine beside a virtual accelerator has one posture
# per machine, not one per deployment. The block overrides *whole* — a per-type
# block states both leaves and then answers alone — so the value below carries
# the two leaves together with the key that answered them.
#: The limits block's own name, both deployment-wide
#: (``control_system.limits_checking``) and inside one connector block
#: (``control_system.connector.<type>.limits_checking``). One name because it is
#: one block at two scopes, the per-type one overriding the other whole.
LIMITS_CHECKING_LEAF = "limits_checking"
#: The leaves a limits block has to state to answer at all. ``database_path`` is
#: deliberately not among them: the deployment mounts one limits database, so a
#: per-type block that omits the path is complete rather than incomplete.
LIMITS_LEAVES = ("enabled", "mode")
#: The two limits modes. ``exclusive``: the limits database is the complete
#: list of writable channels, and a channel with no record is refused.
#: ``optional``: a channel with a record is checked against it, and a channel
#: with no record is written with no limits.
LIMITS_MODE_EXCLUSIVE = "exclusive"
LIMITS_MODE_OPTIONAL = "optional"
LIMITS_MODES = (LIMITS_MODE_EXCLUSIVE, LIMITS_MODE_OPTIONAL)
#: Every leaf the deployment-wide ``limits_checking`` block defines: the posture
#: pair plus the database path, which is deployment-wide only. A per-type block
#: defines :data:`LIMITS_LEAVES` alone. A block carrying any other leaf is
#: refused by :func:`incomplete_limits_blocks`, so a misspelt or retired leaf
#: cannot sit in a config looking like a posture nobody reads.
_LIMITS_BLOCK_LEAVES = (*LIMITS_LEAVES, "database_path")
[docs]
@dataclass(frozen=True)
class LimitsPosture:
"""A resolved limits posture, together with the config key that answered it.
The value and its key travel as one because a refusal has to send an
operator to the line they can actually edit. A deployment that set
``mode: optional`` for its simulator alone has two keys in play,
and a refusal naming the deployment-wide one would have the operator flip a
line the per-type block overrides — a change that does nothing, on a
posture they did not mean to touch. Resolving the value without carrying
its key back is what makes that mistake available, so this type does not
offer the value on its own.
Both leaves are tri-state. ``None`` is "no block said", which is not the
same as a block stating a value: silence is what a deployment that never
configured limits checking has, and every write path treats it as no
permission rather than as a decision. Only :data:`LIMITS_LEAVES` are
carried; the limits database path stays deployment-wide.
Attributes:
enabled: Whether limits checking is on, or ``None`` when unstated.
mode: One of :data:`LIMITS_MODES`, or ``None`` when unstated. Write
paths write a channel with no record only on ``optional``.
connector_type: The connector type whose block answered, or ``None``
when the deployment-wide block did. It selects the key spelling and
nothing else.
incomplete: The :data:`LIMITS_LEAVES` the answering block failed to
state, in :data:`LIMITS_LEAVES` order — a leaf a per-type block
omitted, or a leaf either block wrote as something no reader can
use. Empty for a well-formed block. A non-empty value
means the posture answered nothing — both leaves are ``None`` —
and a reader that must act builds a failsafe rather than guessing
which half of the block was meant. The one posture not read from a
single block, :func:`most_restrictive_limits_posture`'s fold, may
carry definite leaves beside a non-empty tuple; readers check this
field first for exactly that reason.
"""
enabled: bool | None
mode: str | None
connector_type: str | None
incomplete: tuple[str, ...] = ()
[docs]
def key(self, leaf: str) -> str:
"""The config key this posture's *leaf* was read from.
``control_system.connector.<type>.limits_checking.<leaf>`` when a
connector block answered, and ``control_system.limits_checking.<leaf>``
when the deployment-wide block did. A custom connector's dotted module
path (``'mypackage.SiteConnector'``) is one key and is interpolated
whole, never split on its dots.
A posture holding no type at all — the deployment-wide answer, and the
fallback a target that resolves to no type gets — spells the
deployment-wide key, which is where such a posture was read from
anyway.
Args:
leaf: One of :data:`LIMITS_LEAVES`.
Returns:
The dotted key, as a caller spells it for ``get_config_value`` and
as a refusal names it to an operator.
"""
if not self.connector_type:
return f"control_system.{LIMITS_CHECKING_LEAF}.{leaf}"
return f"control_system.connector.{self.connector_type}.{LIMITS_CHECKING_LEAF}.{leaf}"
@property
def block_key(self) -> str:
"""The dotted key of the whole ``limits_checking`` block, without a leaf.
What a refusal names when the block itself is the problem — it is not a
mapping, or it failed to state leaves an operator now has to go and
write. Spelled off :meth:`key` rather than rebuilt, so a refusal about a
block and a refusal about one of its leaves cannot disagree about where
the block is.
"""
return self.key(LIMITS_LEAVES[0]).rsplit(".", 1)[0]
@property
def strict(self) -> bool:
"""Whether this posture refuses everything the limits database does not list.
Limits checking on *and* the mode explicitly ``exclusive`` — the only
definition of "strict" in the codebase, so the target roster and the
docs cannot drift into two readings of one word.
Explicit on both leaves: ``None`` is a deployment that never stated a
posture, and a deployment that stated nothing has refused nothing.
Counting silence as strict would advertise a guarantee no config line
backs, on exactly the deployments least likely to have checked.
"""
return self.enabled is True and self.mode == LIMITS_MODE_EXCLUSIVE
[docs]
def type_limits_posture(section: object, connector_type: str | None) -> LimitsPosture:
"""The limits posture one connector *type* runs under.
``control_system.connector.<type>.limits_checking`` when that block is
there, and ``control_system.limits_checking`` when it is not, where
*connector_type* is one key. A custom connector's dotted module path
(``'mypackage.SiteConnector'``) names a single block, never a path through
several, so the type is looked up whole and never split on its dots.
The per-type block overrides **whole**, and that is the rule the rest of the
family is built on:
- **Absent** — no connector table, no block for this type, a connector
block that is not a mapping, or one carrying no ``limits_checking`` key
at all — inherits the deployment-wide block, both leaves tri-state. That
is the compatibility story: a deployment that says nothing per type keeps
the posture it had when the deployment-wide block was the only posture
there was.
- **Present but not a mapping** — ``limits_checking: 'true'``, a list, a
bare ``limits_checking:`` — is a block written and unreadable, not an
absent one, so it answers nothing with both leaves incomplete. Inheriting
there would hand the deployment-wide posture to a type whose own block
says something nobody can read, which is the one case where inheritance
would be a guess rather than compatibility.
- **Present and complete** answers alone. Not one leaf is borrowed from the
deployment-wide block, because a facility that wrote a block under its
live machine has described *that* machine, and a global relaxation meant
for a simulator must not complete it into permission on hardware.
- **Present and failing to state a leaf** answers *nothing*: both leaves
``None``, and :attr:`LimitsPosture.incomplete` names what it failed to
state. Half a block is a config the build and ``osprey validate`` refuse
outright; a hand-edited or older render can still carry one, and then a
reader that must act builds a failsafe — blocking every write — rather
than guessing which half was meant.
A block fails to state a leaf in two ways, and only the first is particular
to per-type blocks. A per-type block may **omit** one, which the
deployment-wide block may do freely because it inherits nothing. Either
block may **write one unreadably** — the ``None`` YAML gives a bare
``enabled:``, the quoted ``'true'``, a ``1``, an unexpanded
``'${LIMITS_ON}'`` — and that is a failure in both scopes. It has to be:
an unreadable leaf read as merely unset would leave ``enabled`` meaning
"this deployment configured no limits checking", so a deployment that wrote
``enabled: 'true'`` to switch checking *on* would have its writes go
unchecked. Reported as unstated, it costs a config edit; read as unset, it
would cost the guarantee the line was written to provide. Both readings are
the build refusal's too (:func:`incomplete_limits_blocks`), so a config the
build accepts and one the runtime enforces cannot come apart.
Keyed by type rather than by control target because a connector, the
factory that builds it, an IPC child all know which connector type they are and never which target
selected it. :func:`target_limits_posture` is this same answer for the
holders that carry a target instead.
Args:
section: The ``control_system:`` config section, in the same shape
:func:`resolve_control_system_type` takes.
connector_type: A connector type name, as
:func:`resolve_control_system_type` and :func:`resolve_target`
return it — which is also its connector sub-block key. ``None``
(or an empty name) asks the deployment-wide question, which is what
a caller holding no type at all has always asked.
Returns:
The resolved :class:`LimitsPosture`, carrying the type whose block
answered — or ``None`` for the deployment-wide block, which is the key
such a posture was read from anyway. Never raises: a section or a
connector table that is not a mapping is a deployment that has said
nothing, and a deployment that has said nothing states no posture — a
``limits_checking`` value that is present but not a mapping is instead
an unreadable block, incomplete on both leaves.
"""
if connector_type:
connector = section.get("connector") if isinstance(section, dict) else None
block = connector.get(connector_type) if isinstance(connector, dict) else None
if isinstance(block, dict) and LIMITS_CHECKING_LEAF in block:
limits = block[LIMITS_CHECKING_LEAF]
if not isinstance(limits, dict):
return LimitsPosture(None, None, connector_type, LIMITS_LEAVES)
return _block_limits_posture(limits, connector_type, whole=True)
return _global_limits_posture(section)
[docs]
def target_limits_posture(section: object, target: object) -> LimitsPosture:
"""The limits posture one session *target* runs under.
:func:`type_limits_posture` for the type that target resolves to, so a
holder following the control target and the connector that knows only its
own type read one posture and not two. The roster row, the stdlib hook, the
executor and the tool layer all arrive here; the connector, the factory and
the IPC child arrive at :func:`type_limits_posture` — and a deployment that
described one machine must not answer them differently.
A target that does not resolve answers the deployment-wide block instead.
Two shapes reach that branch and both mean the same thing: there is no
per-type block to consult because there is no type. An unknown target names
nothing. ``live`` on a deployment baselined on the simulator in process with
no real machine authored names a machine the config never described, which
:func:`resolve_target` refuses to guess.
Such a deployment has only ever had the one deployment-wide block, and
keeping it is parity rather than a fallback: a target this deployment never
configured still has the one block every such deployment had. Refusing here
would instead take the posture away from every deployment that never had a
second target.
Args:
section: The ``control_system:`` config section, in the same shape
:func:`resolve_control_system_type` takes.
target: The control target, one of :data:`CONTROL_TARGETS`.
Returns:
The resolved :class:`LimitsPosture` for that target, carrying the type
whose block answered — or ``None`` for the deployment-wide block, which
is both what an unresolvable target gets and what a resolvable one gets
when its type wrote no block. Never raises.
"""
try:
connector_type = resolve_target(section, target)
except ValueError:
return _global_limits_posture(section)
return type_limits_posture(section, connector_type)
[docs]
def most_restrictive_limits_posture(section: object) -> LimitsPosture:
"""The limits posture that holds across every target a session here can select.
What a caller with no target of its own has to assume. The stdlib hook is
the one that needs it: when the deployment's control target cannot be read —
no state written yet, an unreadable state directory, a target that resolves
to nothing — it still has to decide about a write, and the machine it is
deciding about is any of the reachable ones.
The reachable set is every
:func:`configured_targets` when the deployment renders the switch
(:func:`switch_capable`), and otherwise the single connector
``control_system.type`` builds, read by *type* through
:func:`type_limits_posture`. Reading the baseline by type rather than by
target is what keeps a deployment without the switch from folding a
second block's relaxation into an answer no session here could ever reach;
and walking the configured targets rather than
:data:`CONTROL_TARGETS` keeps :func:`target_limits_posture`'s
unresolvable-target fallback from voting for a machine nobody stood up.
The two leaves fold in opposite directions, each toward the answer that
costs a config edit rather than a machine:
- ``enabled`` is ``True`` when *any* reachable posture has it ``True``.
Limits checking being on somewhere is a constraint that may apply to the
write in hand.
- ``mode`` is ``optional`` only when *every* reachable posture is
``optional``. Permission to write a channel the limits database does not
list holds only where every machine grants it, so one ``exclusive``
target — or one that states nothing, ``None`` and an incomplete block
alike counting as not-``optional`` — makes the answer ``exclusive``.
Incompleteness travels with them, as the union of every reachable
posture's :attr:`LimitsPosture.incomplete` in :data:`LIMITS_LEAVES` order.
One reachable machine whose block cannot be read makes the fold incomplete,
and a reader that must act therefore builds the blocking failsafe. Dropping
it would be the worst failure available here: the ``enabled`` fold sends an
incomplete posture's ``None`` to ``False``, which reads as "checking off" — and a validator built from *that* is no validator at
all, so the caller with the least information about which machine it is
touching would be the one waved through. This is the fail-closed direction
:func:`LimitsValidator.from_config_most_restrictive`'s callers are promised.
The result is derived rather than read, which is why both leaves come back
definite where a single block's would be tri-state, and why the posture
carries no connector type: no per-type line answers for a union, and naming
one would send an operator to edit a machine rather than the answer. The
deployment-wide keys :meth:`LimitsPosture.key` then spells are the honest
ones — they are the lines that decide every target that wrote no block.
Args:
section: The ``control_system:`` config section, in the same shape
:func:`resolve_control_system_type` takes.
Returns:
The folded :class:`LimitsPosture`, always carrying ``None`` for its
connector type, and incomplete when any reachable posture is. Never
raises and never folds an empty set:
:func:`configured_targets` always holds the baseline, and a deployment
that says nothing still has one target.
"""
if switch_capable(section):
postures = [
target_limits_posture(section, target) for target in configured_targets(section)
]
else:
postures = [type_limits_posture(section, resolve_control_system_type(section))]
return LimitsPosture(
enabled=any(posture.enabled is True for posture in postures),
mode=(
LIMITS_MODE_OPTIONAL
if all(posture.mode == LIMITS_MODE_OPTIONAL for posture in postures)
else LIMITS_MODE_EXCLUSIVE
),
connector_type=None,
incomplete=tuple(
leaf
for leaf in LIMITS_LEAVES
if any(leaf in posture.incomplete for posture in postures)
),
)
[docs]
def limits_database_required(posture: LimitsPosture, *, path_configured: bool) -> bool:
"""Whether a target with this limits posture needs a limits database.
The one answer every caller gives before it demands the file — the
connector's validator, the compose mount, the build check, a service start
and the bridge's startup gate — so none of them can refuse a deployment
another one runs.
A database is required when limits checking is on and either the mode is
not ``optional`` or a path is configured. ``optional`` with no path is a
deployment that legitimately keeps no limits file: every channel is
unlisted, and an unlisted channel is written with no limits, so there is
no file whose absence could matter. An unstated mode counts as not
optional, because silence is no permission to skip the database. A path
that is configured is always required, so a configured file that fails to
load stays a refusal everywhere rather than quietly checking nothing.
Args:
posture: The resolved posture of the target being asked about.
path_configured: Whether the caller's own config names a limits
database path (the live lookup at runtime, the rendered config at
render and build time).
Returns:
``True`` when a limits database must exist and load.
"""
return posture.enabled is True and (posture.mode != LIMITS_MODE_OPTIONAL or path_configured)
[docs]
def tier_limits_database_targets(section: object, *, path_configured: bool) -> list[str]:
"""The targets the login tier lets write whose limits posture needs a database.
The tier is a ceiling, not a selection: a render whose :func:`tier_writes`
answers ``asked`` or ``allowed`` lets a session write to every :func:`configured_targets`,
so every one of them whose resolved :func:`target_limits_posture` makes
:func:`limits_database_required` true — limits checking on, and a mode
other than ``optional`` or a path configured — needs the channel-limits
database to exist and load. A ``never`` render writes nowhere and so arms
none. This is the one list a deployment-level caller reads before it
demands the file (the compose mount, the build check), so none of them can
refuse a deployment another one runs; a caller that serves one lane or one
type asks :func:`limits_database_required` for that posture directly.
The write half is deployment-wide and the limits half is per target, so
both are read off the same machine by construction. ``incomplete`` is not
read here: a half-written block builds a blocking failsafe at every write
surface, and a caller that refuses it names the leaves itself
(:attr:`LimitsPosture.incomplete`).
Args:
section: The ``control_system:`` config section.
path_configured: Whether the config names a limits database path; the
path is deployment-wide, so one answer serves every target.
Returns:
The qualifying targets in :func:`configured_targets` order; empty for a
``never`` render. Never raises.
"""
if not tier_allows(section):
return []
return [
target
for target in configured_targets(section)
if limits_database_required(
target_limits_posture(section, target), path_configured=path_configured
)
]
[docs]
def incomplete_limits_blocks(section: object) -> list[str]:
"""Every half-written per-type limits block in a rendered section, named.
A per-type ``limits_checking`` block overrides whole, so a block that states
one leaf states no posture at all: :func:`type_limits_posture` answers
``None`` twice for it and a write path that must act builds a failsafe. The
build and ``osprey validate`` refuse such a config outright rather than ship
a deployment whose limits posture silently stopped working, and this is what
they read to do it — the rendered config itself, so a spelling the profile
layer could not classify is still caught before it reaches a machine.
A lint and not a posture: it answers about a section rather than about a
target, and each line it emits names the key an operator has to fix. It
reports exactly what :func:`type_limits_posture` reads as a block that
failed to state a leaf — the two share :func:`_unstated_limits_leaves`, so
a config the build accepts and one the runtime enforces cannot come apart —
which is the two failures a block can have:
- A **per-type** block that omits a leaf. The deployment-wide block is not
reported for an omission: it inherits nothing, so a leaf it never carried
is the tri-state's ``None`` and the shape every deployment predating
per-type blocks has.
- **Either** block writing a leaf as something no reader can use — for
``enabled`` a quoted ``'true'``, a ``1``, a bare ``enabled:``, an
unexpanded ``'${LIMITS_ON}'``; for ``mode`` anything but one of
:data:`LIMITS_MODES`. Environment expansion yields strings, so
this is what a deployment gets when it wires a limits leaf to a variable
nothing set. It blocks every write at runtime, which is the safe
direction but a poor way to find out; refusing the build is where that
config is cheap to fix.
- **Either** ``limits_checking`` being present but not a mapping at all,
which gets one line naming the block and quoting what was found there
instead of a line per leaf: there are no leaves to name.
- The deployment-wide block carrying a leaf outside
:data:`_LIMITS_BLOCK_LEAVES`, or a per-type block one outside
:data:`LIMITS_LEAVES`. No reader consults such a leaf, so the posture
its author meant by it is not the one the deployment runs.
Args:
section: The ``control_system:`` config section, in the same shape
:func:`resolve_control_system_type` takes — the *rendered* one, as
the build produced it, since that is the config a deployment runs.
Returns:
One line per unstated leaf and per undefined one: the deployment-wide
block first, then the connector blocks in the order the section carries
them, leaves in :data:`LIMITS_LEAVES` order and undefined leaves sorted
after them, so one refusal lists everything an operator has to fix. Empty for a section whose blocks are complete, absent, or
not blocks at all. Never raises: a lint that crashed on a malformed
config would fail a build without saying what is wrong with it.
"""
if not isinstance(section, dict):
return []
connector = section.get("connector")
blocks: list[tuple[str | None, object, bool]] = []
if LIMITS_CHECKING_LEAF in section:
blocks.append((None, section[LIMITS_CHECKING_LEAF], False))
if isinstance(connector, dict):
blocks.extend(
(connector_type, block[LIMITS_CHECKING_LEAF], True)
for connector_type, block in connector.items()
if isinstance(block, dict) and LIMITS_CHECKING_LEAF in block
)
errors: list[str] = []
for connector_type, block, whole in blocks:
# The posture this block would answer with, built for its keys alone —
# so the line naming the block and the lines naming its leaves are
# spelled by one thing.
posture = LimitsPosture(None, None, connector_type)
if not isinstance(block, dict):
errors.append(
f"{posture.block_key} is {block!r}, not a block; a limits "
f"block is a mapping stating {LIMITS_LEAVES[0]} and {LIMITS_LEAVES[1]}"
)
continue
for leaf, written in _unstated_limits_leaves(block, whole=whole):
if written:
errors.append(
f"{posture.key(leaf)} is {block[leaf]!r}, not {_LEAF_VALUES[leaf]}; "
"a limits leaf that cannot be read states no posture and blocks "
"every write as a failsafe"
)
else:
errors.append(
f"{posture.key(leaf)} is missing; a per-type limits block must state "
f"both {LIMITS_LEAVES[0]} and {LIMITS_LEAVES[1]}"
)
defined = LIMITS_LEAVES if whole else _LIMITS_BLOCK_LEAVES
errors.extend(
f"{posture.key(leaf)} is not a limits leaf; a limits block states "
f"{LIMITS_LEAVES[0]} and {LIMITS_CHECKING_LEAF}.{LIMITS_LEAVES[1]}: "
f"{' | '.join(LIMITS_MODES)}"
for leaf in sorted(str(key) for key in block if key not in defined)
)
return errors
def _global_limits_posture(section: object) -> LimitsPosture:
"""The deployment-wide posture, ``control_system.limits_checking``.
A leaf this block does not carry is the tri-state and not a malformed
block: silence here is the shape every deployment predating per-type blocks
has, and only a per-type block, which overrides whole, has to state both
leaves to answer at all. A leaf it *does* carry but spells as something
no reader can use is unreadable in either block alike — see
:func:`_unstated_limits_leaves` — and so is the whole block when
``limits_checking`` is present but is not a mapping, which is incomplete on
both leaves rather than the silence of a deployment that wrote none.
"""
if not isinstance(section, dict) or LIMITS_CHECKING_LEAF not in section:
return _block_limits_posture({}, None, whole=False)
block = section[LIMITS_CHECKING_LEAF]
if not isinstance(block, dict):
return LimitsPosture(None, None, None, LIMITS_LEAVES)
return _block_limits_posture(block, None, whole=False)
def _unstated_limits_leaves(block: Mapping[str, object], *, whole: bool) -> list[tuple[str, bool]]:
"""The leaves a limits block fails to state, and whether each was written.
One classifier for both scopes and both readers — the posture resolvers and
the build's render check — because "which leaves did this block fail to
state" decided twice is a config the build accepts and the runtime refuses,
or worse the other way round.
Two ways a block fails to state a leaf, and they are told apart by the
boolean each entry carries:
- **Absent** (``False``), which is a failure only under *whole*: a per-type
block overrides the deployment-wide pair entire, so it has to state both
leaves to answer at all. The deployment-wide block is read with
``whole=False``, where an absent leaf is simply the tri-state's ``None``.
- **Written but unreadable** (``True``) — for ``enabled`` a quoted
``'true'``, a ``1``, a bare ``enabled:``, an unexpanded
``'${LIMITS_ON}'`` that no environment resolved; for ``mode`` anything
but one of :data:`LIMITS_MODES` — which is a failure in *either* scope. This is the leaf that
cannot be allowed to read as a plain unset: unset ``enabled`` means "no
limits checking configured", so a deployment that wrote
``enabled: 'true'`` meaning to switch checking *on* would have every
write waved through unchecked. Reporting it unstated instead makes the
posture incomplete, and an incomplete posture blocks. The config edit is
one line; the alternative is unchecked writes on a machine somebody
believed was guarded.
Args:
block: A ``limits_checking`` mapping, deployment-wide or per type.
whole: Whether an absent leaf is a failure, which it is exactly when
the block overrides another one entire.
Returns:
``(leaf, was_written)`` in :data:`LIMITS_LEAVES` order, empty for a
block that states everything it has to.
"""
unstated: list[tuple[str, bool]] = []
for leaf in LIMITS_LEAVES:
if leaf not in block:
if whole:
unstated.append((leaf, False))
elif _LEAF_READERS[leaf](block[leaf]) is None:
unstated.append((leaf, True))
return unstated
def _block_limits_posture(
block: Mapping[str, object], connector_type: str | None, *, whole: bool
) -> LimitsPosture:
"""One ``limits_checking`` mapping read into a posture.
A block that fails to state any leaf answers *nothing* — both leaves
``None``, with :attr:`LimitsPosture.incomplete` naming what it failed to
state. Half an answer is not available: neither leaf of a block written
with the other one unreadable can be trusted to mean what a reader would do
with it, and a caller that must act builds a failsafe from ``incomplete``
rather than guessing.
"""
unstated = _unstated_limits_leaves(block, whole=whole)
if unstated:
return LimitsPosture(None, None, connector_type, tuple(leaf for leaf, _ in unstated))
enabled_leaf, mode_leaf = LIMITS_LEAVES
return LimitsPosture(
enabled=_limits_leaf(block.get(enabled_leaf)),
mode=_limits_mode(block.get(mode_leaf)),
connector_type=connector_type,
)
def _limits_leaf(value: object) -> bool | None:
"""One limits leaf as a literal boolean, or ``None`` for anything else.
The literal booleans and nothing else are readable. A quoted ``'true'``, a
``1``, a bare ``enabled:`` — values no write tier reads as an arming
either — are not.
Unlike write posture, ``None`` here is not itself the safe answer, which is
why no caller reads this directly: an unset ``enabled`` means "this
deployment configured no limits checking", so a leaf written unreadably and
reported as merely unset would turn an attempt to switch checking *on* into
writes that are never checked at all. :func:`_unstated_limits_leaves` is
what the resolvers use, and it separates a leaf nobody wrote from a leaf
nobody can read.
"""
if value is True:
return True
if value is False:
return False
return None
def _limits_mode(value: object) -> str | None:
"""The ``mode`` leaf as one of :data:`LIMITS_MODES`, or ``None`` for anything else.
The two spellings and nothing else are readable: a boolean, a different
case, a bare ``mode:`` each state no mode, and a block that states no mode
is one :func:`_unstated_limits_leaves` reports rather than one a reader
guesses at.
"""
if isinstance(value, str) and value in LIMITS_MODES:
return value
return None
#: How each of :data:`LIMITS_LEAVES` is read, and what a refusal says a
#: readable value looks like.
_LEAF_READERS: dict[str, Callable[[object], bool | str | None]] = {
LIMITS_LEAVES[0]: _limits_leaf,
LIMITS_LEAVES[1]: _limits_mode,
}
_LEAF_VALUES = {
LIMITS_LEAVES[0]: "a literal true or false",
LIMITS_LEAVES[1]: " or ".join(LIMITS_MODES),
}
def _real_blocks(section: object, never_live: tuple[str, ...]) -> list[str]:
"""The connector blocks that could describe a real machine, sorted."""
connector = section.get("connector") if isinstance(section, dict) else None
if not isinstance(connector, dict):
return []
return sorted(key for key in connector if isinstance(key, str) and key not in never_live)
def _report_second_real_block(section: object, baseline: str, never_live: tuple[str, ...]) -> None:
"""Say so when a config describes a real machine no target can reach.
A deployment whose own type is its real machine never consults the connector
table for ``live``, so a second non-simulated block is not ambiguous here —
it is unreachable, and quietly so: no control target resolves to it, and the
roster it never appears in looks exactly like a roster for a deployment that
configured one machine. Nothing else in the stack will ever mention it, so
the resolver that skipped it is where a deployer has to hear about it.
Once per config shape, not once per call: this resolver answers every roster
render, and a line repeated at that rate is a line nobody reads.
"""
others = [name for name in _real_blocks(section, never_live) if name != baseline]
if not others:
return
seen = (baseline, tuple(others))
if seen in _SECOND_REAL_BLOCK_WARNED:
return
_SECOND_REAL_BLOCK_WARNED.add(seen)
logger.warning(
"'control_system.connector' carries %s beside this deployment's own %r block, "
"and no control target reaches %s. %s",
", ".join(repr(name) for name in others),
baseline,
"them" if len(others) > 1 else "it",
_ONE_REAL_MACHINE,
)
def _live_type(section: object) -> str:
"""The control system type that reaches this deployment's real machine.
Neither a simulated type nor a stand-in one can be that machine, and the
exclusion holds on both sides of the derivation — the baseline it starts
from, and the candidate blocks it falls back to. A stand-in is a machine the
deployment stands up itself; counting it would either answer ``live`` with
the stand-in, or make ``live`` ambiguous on exactly the deployments that run
the stand-in beside the block naming their facility's own machine.
Either way the answer is one machine — :data:`_ONE_REAL_MACHINE` — and both
ways of missing it are said out loud: a baseline that cannot derive one
raises, and a baseline that *is* one, beside a second real block no target
can reach, is warned about.
"""
never_live = SIMULATED_TYPES + STANDIN_TYPES
baseline = resolve_control_system_type(section)
if baseline not in never_live:
_report_second_real_block(section, baseline, never_live)
return baseline
candidates = _real_blocks(section, never_live)
if len(candidates) == 1:
return candidates[0]
found = ", ".join(repr(name) for name in candidates) if candidates else "none"
raise ValueError(
f"Target {TARGET_LIVE!r} has no control system on this deployment: "
f"'control_system.type' resolves to {baseline!r}, which is simulated, "
f"and the live blocks under 'control_system.connector' are: {found}. "
f"{_ONE_REAL_MACHINE} Configure exactly one such block (an {EPICS!r} or "
f"{DOOCS!r} block, say). It is not inferred, so that no session reaches "
"a real machine this config never described."
)