"""
Abstract base class for control system connectors.
Provides protocol-agnostic interfaces for reading/writing process variables,
subscribing to changes, and retrieving metadata from various control systems.
"""
import asyncio
import functools
import inspect
import logging
import math
import numbers
import sys
import warnings
from abc import ABC, abstractmethod
from collections import Counter
from collections.abc import Awaitable, Callable, Coroutine, Iterator, Mapping, Sequence
from dataclasses import dataclass, field
from datetime import datetime
from enum import StrEnum
from os import PathLike
from pathlib import Path
from typing import TYPE_CHECKING, Any, Protocol, TypeAlias, TypeGuard
from osprey_connectors import posture_store, write_authorization
from osprey_connectors.control_system.write_door import open_door
from osprey_connectors.errors import RefusalReason
from osprey_connectors.posture_env import is_readonly_run
from osprey_connectors.posture_store import WriteVerdict
if TYPE_CHECKING:
from osprey_connectors.control_system._limits_validator import (
CurrentValueReader,
LimitsValidator,
)
from osprey_connectors.errors import ChannelLimitsViolationError
logger = logging.getLogger("osprey_connectors.control_system")
def _limit_bound(value: object) -> float | None:
"""One limit as a finite ``float``, or ``None`` for anything else.
Bools are excluded (``True`` is not a limit), as is every non-numeric value —
including a ``MagicMock`` standing in for a PV in tests — so a connector may
hand over whatever its transport reported without checking it first.
"""
if isinstance(value, bool) or not isinstance(value, numbers.Real):
return None
try:
bound = float(value)
except (TypeError, ValueError, OverflowError):
return None
return bound if math.isfinite(bound) else None
def normalise_limit_pair(low: object, high: object) -> tuple[float | None, float | None]:
"""Normalise one ``(low, high)`` limit pair the way :class:`ChannelMetadata` stores it.
Each bound that is missing, non-numeric or non-finite becomes ``None``. When
both survive and ``low >= high`` the pair describes no range — EPICS reports
an unset range as ``0``/``0`` — so both become ``None``. A pair with only one
valid bound keeps it. Idempotent.
"""
low_bound, high_bound = _limit_bound(low), _limit_bound(high)
if low_bound is not None and high_bound is not None and low_bound >= high_bound:
return None, None
return low_bound, high_bound
def _writable_flag(value: object) -> bool | None:
"""A reported write-access right as ``bool``, or ``None`` when not reported.
A client may report access rights as ``bool`` or ``0``/``1``; anything that
is not an integer (a ``MagicMock`` attribute, say) is "not reported".
"""
if isinstance(value, bool):
return value
if isinstance(value, numbers.Integral):
return bool(value)
return None
[docs]
@dataclass
class ChannelValue:
"""Value of a control system channel with metadata."""
value: Any
timestamp: datetime
metadata: ChannelMetadata = field(default_factory=ChannelMetadata)
[docs]
class WriteOutcome(StrEnum):
"""What became of one channel write — the single owned verdict.
The connector that performed the write is the only producer of this value;
every consumer (MCP tool, ``osprey.runtime``, the Bluesky bridge, the
connector-host IPC) reads it and none re-derives a verdict of its own.
* ``REFUSED`` — nothing was written; ``refusal_reason`` says why.
* ``FAILED`` — the value was sent and the control system did not take it.
* ``CONFIRMED`` — a re-read of the channel holds the value sent, in any
alarm state. Alarm state is reported, never raised on.
* ``MISMATCH`` — the re-read holds a different value (a clamped or rounded
setpoint is reported here, not tolerated).
* ``UNCONFIRMED`` — the value was sent, but not acknowledged in time or
the re-read itself failed, so what the channel holds is unknown.
* ``UNREQUESTED`` — ``confirm=False``: nothing was checked.
"""
REFUSED = "refused"
FAILED = "failed"
CONFIRMED = "confirmed"
MISMATCH = "mismatch"
UNCONFIRMED = "unconfirmed"
UNREQUESTED = "unrequested"
class _Vector(Protocol):
"""What :func:`values_match` compares positionally: a list, a tuple or an ndarray."""
def __len__(self) -> int: ...
def __getitem__(self, index: int, /) -> object: ...
def __iter__(self) -> Iterator[object]: ...
def _is_sequence(value: object) -> TypeGuard[_Vector]:
"""True when ``value`` is a vector rather than a scalar, for comparison.
Admits list, tuple and ndarray. Excluded, in order:
* str/bytes, which have a length but read back as one value;
* mappings and anything else without ``__getitem__``, because a vector is
compared by zipping the two sides positionally and a mapping iterates its
*keys* — two dicts with the same keys and different values would zip to a
match. Left as scalars, they compare by ``==``, which is what a mapping's
equality already means;
* 0-d numpy arrays (``ndim == 0``), which hold a single value and must
compare like the scalar they wrap.
"""
return (
not isinstance(value, str | bytes | Mapping)
and hasattr(value, "__len__")
and hasattr(value, "__getitem__")
and getattr(value, "ndim", 1) != 0
)
def _unwrap_length_one(value: object) -> object:
"""A length-1 sequence reduced to its element; anything else unchanged.
``[5.0]`` and ``5.0`` name the same reading: control systems differ on
whether a single-element channel reads back boxed, and that difference must
not decide an outcome.
"""
if _is_sequence(value) and len(value) == 1:
return value[0]
return value
def _scalars_match(sent: object, observed: object) -> bool:
"""Compare two scalars: floats by relative closeness, everything else by ``==``."""
if (
isinstance(sent, numbers.Real)
and isinstance(observed, numbers.Real)
and not isinstance(sent, bool)
and not isinstance(observed, bool)
):
return math.isclose(float(sent), float(observed), rel_tol=1e-6, abs_tol=0.0)
result = sent == observed
if isinstance(result, bool):
return result
# A numpy (or other array-like) elementwise comparison reduces to one verdict.
return bool(result.all()) if hasattr(result, "all") else bool(result)
[docs]
def values_match(sent: object, observed: object, *, enum_label: str | None = None) -> bool:
"""True when ``observed`` is the value ``sent`` — the one comparison rule.
Applied in order, and symmetric: swapping the arguments cannot change the
answer.
1. A string against a reported ``enum_label`` compares as text: an enum
channel written as ``"Open"`` reads back as its integer index, and the
label the connector resolved for that reading is what the text is
compared with. A connector that reports no ``enum_label`` (DOOCS) falls
through to the ordinary comparison.
2. A length-1 sequence is unwrapped to its element, on both sides.
3. After unwrapping, exactly one side a sequence is ``False``: a scalar is
not a vector. This is what stops a numpy broadcast
(``np.array([5.0, 5.0]) == 5.0`` reduced by ``.all()``) from
manufacturing a match.
4. Two sequences of unequal length are ``False``; equal lengths compare
elementwise.
5. Two real numbers (bools excluded) compare by ``math.isclose`` with
``rel_tol=1e-6`` — roughly eight float32 epsilons, so a legitimate
float32 store still matches — and ``abs_tol=0.0``, so nothing is close
to zero but zero. There is no configurable tolerance anywhere.
6. Anything else compares by ``==``.
7. Any exception means the two cannot be compared, which is not a match.
"""
try:
if enum_label is not None:
if isinstance(sent, str):
return sent == enum_label
if isinstance(observed, str):
return observed == enum_label
sent = _unwrap_length_one(sent)
observed = _unwrap_length_one(observed)
if _is_sequence(sent) and _is_sequence(observed):
if len(sent) != len(observed):
return False
return all(_scalars_match(a, b) for a, b in zip(sent, observed, strict=True))
if _is_sequence(sent) or _is_sequence(observed):
return False
return _scalars_match(sent, observed)
except Exception:
return False
def as_number(value: object) -> float | None:
"""``value`` as a float, or ``None`` when it is not a number.
A reading that is not a number — a string, an enum label, a waveform — has
no numeric form and is reported as ``None`` ("no numeric value"), never
coerced into one. A string that happens to parse as a number is still a
string here: what the channel holds is text, and inventing a number for it
is the fabrication this helper exists to prevent.
"""
if isinstance(value, bool) or not isinstance(value, numbers.Real):
return None
return float(value)
#: The outcomes whose result carries an ``error_message``: each has something
#: the operator has to be told.
_MESSAGE_OUTCOMES = frozenset({WriteOutcome.REFUSED, WriteOutcome.FAILED, WriteOutcome.UNCONFIRMED})
[docs]
@dataclass
class ChannelWriteResult:
"""What became of one channel write, and what the channel was seen to hold.
The control-system-agnostic result type returned by every connector.
:attr:`outcome` is the single owned verdict (see :class:`WriteOutcome`),
set by the connector that performed the write; no consumer re-derives one.
``error_message`` is set **if and only if** ``outcome`` is one of
``refused``, ``failed`` or ``unconfirmed`` — the three words that carry
something the operator has to be told. A ``mismatch`` needs no message:
both numbers are on the result already, in ``value_written`` and
``observed_value``. Construction enforces it: a result that breaks it
raises ``ValueError``.
``notes`` is display-only text ("observed 2.4, sent 2.5", "cannot be
compared"). No consumer reads it, and nothing classifies a write by
parsing it.
``refusal_reason`` is the :class:`~osprey_connectors.errors.RefusalReason`
that says why, and who, refused; it is set **if and only if** the outcome
is ``refused``. Construction enforces it too: a refused result with no
reason or an unknown one, or a reason on any other outcome, raises
``ValueError``. ``verdict_reason`` narrows a ``WRITES_DISABLED`` refusal
to the reason the write verdict gave, a member of
:data:`osprey_connectors.refusals.REASONS` — ``switch_off``,
``auth_exhausted``, ``auth_range`` and the rest — so a program can tell
them apart without parsing ``error_message``; it is ``None`` on every
other result. ``observed_value`` is whatever the confirming
re-read returned, in the type the channel holds — a number, a string, an
enum label, a waveform; :attr:`observed_number` narrows it to a float
where that makes sense.
Alarm state (``alarm_status``, ``alarm_severity``) is carried
protocol-agnostically — the alarm *name* as a string, the severity as an
int — and is information reported with the write, never a reason to raise.
``None`` means "not reported", which stays distinct from a reported
healthy value (``alarm_severity=0``). Mapping a protocol's raw codes to
those names is the connector's job, so this shared module imports no
control-system constants.
"""
channel_address: str # Channel that was written
value_written: Any # Value that was sent
outcome: WriteOutcome # The one verdict, set by the connector
# Set iff refused, enforced at construction
refusal_reason: RefusalReason | None = None
# Set iff refused, failed or unconfirmed, enforced at construction
error_message: str | None = None
observed_value: Any = None # What the confirming re-read returned
# Alarm name reported for the reading, e.g. "NO_ALARM"/"HIHI"; None if not reported
alarm_status: str | None = None
# Alarm severity: 0 healthy, higher is worse; None if not reported
alarm_severity: int | None = None
notes: str | None = None # Display-only detail
# The write verdict's reason, for a WRITES_DISABLED refusal that has one
verdict_reason: str | None = None
[docs]
def __post_init__(self) -> None:
"""Coerce ``outcome`` and ``refusal_reason`` to members, then check the shape.
A ``StrEnum`` crosses the connector-host IPC as the plain string JSON
encodes it to, and the codec rebuilds the dataclass by calling it with
the decoded fields — so what arrives here on the parent side is a
``str``. Coercing once, on construction, is what lets every consumer
compare against the members whichever side of the process boundary it
runs on.
Raises:
ValueError: ``refusal_reason`` is not a known reason, is missing on
a ``refused`` result or set on any other, or ``error_message``
is missing on a ``refused``, ``failed`` or ``unconfirmed``
result or set on any other.
"""
if not isinstance(self.outcome, WriteOutcome):
self.outcome = WriteOutcome(self.outcome)
if self.refusal_reason is not None and not isinstance(self.refusal_reason, RefusalReason):
try:
self.refusal_reason = RefusalReason(self.refusal_reason)
except ValueError:
raise ValueError(
f"Write result for '{self.channel_address}' (outcome {self.outcome}): "
f"refusal_reason {self.refusal_reason!r} is not a known refusal reason"
) from None
refused = self.outcome is WriteOutcome.REFUSED
if refused != (self.refusal_reason is not None):
expected = "a known refusal reason" if refused else "None"
raise ValueError(
f"Write result for '{self.channel_address}' (outcome {self.outcome}): "
f"refusal_reason must be {expected}, got {self.refusal_reason!r}"
)
if bool(self.error_message) != (self.outcome in _MESSAGE_OUTCOMES):
expected = "a message" if self.outcome in _MESSAGE_OUTCOMES else "None"
raise ValueError(
f"Write result for '{self.channel_address}' (outcome {self.outcome}): "
f"error_message must be {expected}, got {self.error_message!r}"
)
@property
def observed_number(self) -> float | None:
""":attr:`observed_value` as a float, or ``None`` when it is not a number."""
return as_number(self.observed_value)
#: Package path of the OSPREY MCP servers, as consecutive parts of the file
#: they are launched with (``python -m osprey.mcp_server.<server>`` sets
#: ``sys.argv[0]`` to that package's ``__main__.py``).
_MCP_SERVER_PACKAGE_PARTS = ("osprey", "mcp_server")
#: Set once by :func:`mark_long_lived_session`. A long-lived control session —
#: a panel backend that holds one connector for hours — runs no script either,
#: so a readonly refusal there is the deployment's, exactly as in an MCP server.
#: Process-global by design: the mark describes the process, not one connector.
_long_lived_session = False
[docs]
def mark_long_lived_session() -> None:
"""Record that this process holds a long-lived control session.
Called by :meth:`osprey.runtime.session.ControlSession.open`. From then on a
readonly refusal in this process uses the deployment-wide wording: the
process was started by the deployment, not submitted as one readonly
script, so "resubmit it with execution_mode='readwrite'" would send the
operator to a script that does not exist. Irreversible for the process.
"""
global _long_lived_session
_long_lived_session = True
def _reset_long_lived_session_for_tests() -> None:
"""Clear the :func:`mark_long_lived_session` mark. Tests only.
A test process opens many sessions; each test starts from an unmarked
process so the readonly wording does not depend on test order.
"""
global _long_lived_session
_long_lived_session = False
def _readonly_is_deployment_wide() -> bool:
"""Whether a readonly refusal here is the deployment's rather than one script's.
True in an OSPREY MCP server (:func:`_in_mcp_server_process`) and in a
process that holds a long-lived control session
(:func:`mark_long_lived_session`); everything else keeps the script wording.
"""
return _long_lived_session or _in_mcp_server_process()
def _in_mcp_server_process() -> bool:
"""True when this process is an OSPREY MCP server, not a script it ran.
This is the discriminator between the two remaining readonly stories, and
it deliberately does not look at the environment: it *cannot*. Both stories
speak through the same variable at the same value — the deployment-wide
read-only run stamps ``OSPREY_EXECUTION_MODE=readonly`` on the whole
deployment, and the python executor stamps the very same string on the
sandbox subprocess it builds for one readonly submission. So the value says
nothing about which one this is. What does differ is the process: an MCP
server runs the server package's ``__main__``, while the executor's sandbox
runs a script file it wrote for one submission. Answering True therefore
means "the deployment is read-only", and answering False means "this one
run was submitted readonly".
Answering **False** is the safe way to be wrong. It yields the older,
script-shaped message, which is what every readonly refusal said before
the deployment-wide run had its own wording; a launch shape this check does
not recognise therefore degrades to that text rather than to a message
telling an operator their whole deployment is read-only when it is not. The
refusal itself is identical either way — only the sentence telling the
operator where to go changes.
Neither story is the narrowing an operator makes from the
control-target chip in the header: that never lived in the environment at
all, and is read from the posture store further down this function's
caller.
"""
argv: object = getattr(sys, "argv", None)
if not isinstance(argv, Sequence) or not argv:
return False
launched = argv[0]
if not isinstance(launched, str | PathLike):
return False
try:
parts = Path(launched).parts
except (TypeError, ValueError):
return False
span = len(_MCP_SERVER_PACKAGE_PARTS)
return any(parts[i : i + span] == _MCP_SERVER_PACKAGE_PARTS for i in range(len(parts)))
#: What a refusal says in place of a phrase when the verdict itself allowed the
#: write and something else refused it: a subclass that overrides
#: :attr:`ControlSystemConnector._writes_enabled` and answers no. No reason of
#: the refusals contract applies, so none is claimed.
_OVERRIDE_REFUSAL = "Writes are refused by this connector's own write check."
#: The words a read-only run's refusal carries beside its phrase:
#: ``wrapper.READONLY_REFUSAL_MARKER``, which the executor's stderr matcher
#: looks for to name the runtime guard as the layer that refused. Kept out of
#: the phrase, which is a closed contract shared with the hooks.
_READONLY_MARKER = "readonly execution mode"
#: What a read-only refusal adds when the process is a script the executor ran
#: for one readonly submission rather than an MCP server of a read-only
#: deployment or a long-lived control session
#: (:func:`_readonly_is_deployment_wide`): that run alone can be resubmitted.
_READONLY_SCRIPT_REMEDY = (
"This script was submitted readonly; resubmit it with execution_mode='readwrite' "
"(human approval required) if the write is intended."
)
def _monitor_section() -> object:
"""The ``control_system`` section the reference monitor judges by.
Empty for a read-only run, which is answered before any config is read: it
refuses whatever the config says. A config that cannot be read arms
nothing — the section is then empty, which the tier answers ``never``.
"""
if is_readonly_run():
return {}
try:
from osprey_connectors.config import get_config_value
return get_config_value("control_system", {})
except (FileNotFoundError, RuntimeError):
return {}
def _monitor_verdict(control_target: str | None) -> "WriteVerdict":
"""The verdict the reference monitor decides one write (or batch) by.
:func:`osprey_connectors.posture_store.write_verdict` over this deployment's
``control_system`` section for *control_target*, the owner taken from the
ladder. An unstamped connector (*control_target* ``None``) resolves no
machine and is refused ``target_unknown`` unless an earlier term refuses
first. A read-only run is answered before any config is read: it refuses
whatever the config says. A config that cannot be read arms nothing — the
section is then empty, which the tier answers ``never``.
A process that names a program's write authorization
(:func:`~osprey_connectors.write_authorization.named_authorization`) is
answered by
:func:`~osprey_connectors.write_authorization.authorized_write_verdict`
instead: whether the authorization would let it write at all, channels
aside. That is the answer the gateway is chosen on; each write is judged
on its own channels and values by the write guard.
Never raises; reads the record at most once.
"""
return write_authorization.authorized_write_verdict(
_monitor_section(),
control_target,
authorization=write_authorization.named_authorization(),
owner=None,
)
def _verdict_refusal(
channel_address: str, value: object, verdict: "WriteVerdict"
) -> ChannelWriteResult:
"""The REFUSED result the monitor returns for a write *verdict* refused.
The operator's words are :func:`~osprey_connectors.refusals.refusal_text`
for the verdict's reason and machine kind — the same phrase the hooks
speak, ending with the ``[osprey-refusal: <reason>]`` trailer — after the
channel it concerns, with the verdict's own detail after the phrase. A
read-only run's refusal also carries :data:`_READONLY_MARKER`, and in a script
the executor ran for one readonly submission :data:`_READONLY_SCRIPT_REMEDY`
as well. A verdict that
allowed (an overriding subclass refused on its own) names no contract reason.
"""
from osprey_connectors.refusals import refusal_text
marker = ""
remedy = None
if verdict.reason == "readonly_run":
marker = f" ({_READONLY_MARKER})"
if not _readonly_is_deployment_wide():
# One script submitted readonly, not the deployment: the same
# refusal, and the one remedy that applies to it alone.
remedy = _READONLY_SCRIPT_REMEDY
if verdict.allowed or verdict.reason is None:
spoken = _OVERRIDE_REFUSAL
else:
try:
spoken = refusal_text(verdict.reason, verdict.kind, detail=remedy or verdict.detail)
except ValueError:
spoken = _OVERRIDE_REFUSAL
return ChannelWriteResult(
channel_address=channel_address,
value_written=value,
outcome=WriteOutcome.REFUSED,
refusal_reason=RefusalReason.WRITES_DISABLED,
error_message=f"Write to '{channel_address}' blocked{marker}: {spoken}",
verdict_reason=None if verdict.allowed else verdict.reason,
)
def _authorized_refusal(
connector: "ControlSystemConnector",
operations: Sequence[tuple[str, object]],
authorization: str,
) -> "WriteVerdict | None":
"""The verdict refusing one write call of a process that names an authorization.
``None`` means the call may go ahead and its step is spent. Otherwise the
refusing verdict, which :func:`_verdict_refusal` words; an allowed verdict
returned here is a subclass's own ``_writes_enabled`` answering no.
The order: a subclass that overrides ``_writes_enabled`` and answers no
refuses as it does for every process. A connector that cannot carry a
write over the gateway it selected (:meth:`ControlSystemConnector.
_write_route_open`) refuses ``switching`` when the authorization would
allow the call, its own reason when not, and spends nothing either way.
Otherwise :func:`~osprey_connectors.write_authorization.authorized_execution_verdict`
judges the whole call and, when it allows, spends its one step before
anything is put: a write the limits then refuse has still spent it.
"""
connector._last_verdict = None
if _overrides_writes_enabled(connector) and not connector._writes_enabled:
return connector._last_verdict or _monitor_verdict(connector._control_target)
section = _monitor_section()
target = connector._control_target
if not connector._write_route_open():
judged = write_authorization.authorized_execution_verdict(
section, target, operations, authorization=authorization
)
connector._last_verdict = judged
if not judged.allowed:
return judged
return posture_store.WriteVerdict(
allowed=False,
reason="switching",
target=judged.target,
kind=judged.kind,
authorization=authorization,
)
verdict = write_authorization.authorized_execution_verdict(
section, target, operations, authorization=authorization, spend=True
)
connector._last_verdict = verdict
return None if verdict.allowed else verdict
def _overrides_writes_enabled(connector: object) -> bool:
"""Whether *connector*'s class answers ``_writes_enabled`` with its own rule."""
return getattr(type(connector), "_writes_enabled", None) is not _BASE_WRITES_ENABLED
#: The outcomes a caller may proceed on: the channel was confirmed to hold the
#: value sent, or no confirmation was asked for. Deliberately an allowlist and
#: not a denylist — a :class:`WriteOutcome` member added after this line was
#: written raises rather than silently becoming proceed-able.
_PROCEEDABLE_OUTCOMES: frozenset[WriteOutcome] = frozenset(
{WriteOutcome.CONFIRMED, WriteOutcome.UNREQUESTED}
)
[docs]
def raise_for_write_result(result: ChannelWriteResult) -> ChannelWriteResult:
"""Enforce the reference monitor's denial contract on one write result.
The single place that decides whether a ``ChannelWriteResult`` counts as a
write the caller may proceed on. Every caller that must not proceed on an
unconfirmed write routes through here, so the refusal/failure distinction
cannot drift between the single-channel and multi-channel paths.
The verdict is read off :attr:`ChannelWriteResult.outcome` and nothing else.
The connector that performed the write already decided; re-deriving a verdict
here from a second field is what let a write to an unreadable channel report
itself as a success.
Args:
result: The result returned by a connector's ``write_channel``.
Returns:
The result unchanged, when the outcome is ``confirmed`` — whatever the
alarm severity, since alarm state is reported and never raised on — or
``unrequested``, where no confirmation was asked for.
Raises:
ChannelWriteBlockedError: The outcome is ``refused``: no value was
written. ``refusal_reason`` names why;
:meth:`ChannelWriteBlockedError.refuser` says who refused.
ChannelWriteFailedError: The value was sent and the write did not come
back confirmed — ``failed``, ``mismatch`` or ``unconfirmed``, each
raising under its own word. The exception carries the outcome, the
value sent and the value observed, so a ``mismatch`` message names
both numbers.
"""
from osprey_connectors.errors import ChannelWriteBlockedError, ChannelWriteFailedError
if result.outcome is WriteOutcome.REFUSED:
raise ChannelWriteBlockedError(
result.channel_address,
result.refusal_reason,
message=result.error_message,
verdict_reason=result.verdict_reason,
)
if result.outcome in _PROCEEDABLE_OUTCOMES:
return result
# Everything else is a write the caller must not proceed on. The reason code
# is the outcome word uppercased, so the reason a caller branches on and the
# outcome a consumer reads stay one vocabulary by construction rather than by
# a table that a new outcome could be left out of.
raise ChannelWriteFailedError(
result.channel_address,
result.outcome.upper(),
message=result.error_message,
outcome=result.outcome,
value_written=result.value_written,
observed_value=result.observed_value,
)
[docs]
def raise_for_write_results(results: Sequence[ChannelWriteResult]) -> Sequence[ChannelWriteResult]:
"""Enforce the denial contract on a batch's results.
:func:`raise_for_write_result` for each result in batch order, the writes
their batch only held back (``BATCH_REFUSED``) last: a batch stopped at its
checks raises for the write that was refused, wherever it stands.
Returns:
The results unchanged, when every one may be proceeded on.
"""
held_back = [r for r in results if r.refusal_reason == RefusalReason.BATCH_REFUSED]
for result in (*(r for r in results if r not in held_back), *held_back):
raise_for_write_result(result)
return results
def _limits_refusal(
channel_address: str, value: object, error: "ChannelLimitsViolationError"
) -> ChannelWriteResult:
"""The REFUSED result a batch answers for a write the limits refused.
One line per channel, the violation's type and reason, where a single
write raises the violation with its banner.
"""
kind = error.violation_type
reason = error.violation_reason
said = f"({kind}): {reason}" if kind and reason else f": {error}"
return ChannelWriteResult(
channel_address=channel_address,
value_written=value,
outcome=WriteOutcome.REFUSED,
refusal_reason=RefusalReason.LIMITS,
error_message=f"Write to '{channel_address}' refused by the limits {said}",
)
def _refused_batch(
named: Sequence[tuple[str, object]], refusals: Sequence[ChannelWriteResult | None]
) -> list[ChannelWriteResult]:
"""One result per write of a batch that was not sent because a write was refused."""
refused = [refusal for refusal in refusals if refusal is not None]
first = refused[0]
others = f" and {len(refused) - 1} more" if len(refused) > 1 else ""
why = (
f"the write to '{first.channel_address}' was refused "
f"({first.refusal_reason}){others}. No write of the batch was sent."
)
return [
refusal
if refusal is not None
else ChannelWriteResult(
channel_address=name,
value_written=value,
outcome=WriteOutcome.REFUSED,
refusal_reason=RefusalReason.BATCH_REFUSED,
error_message=f"Write to '{name}' not sent: {why}",
)
for (name, value), refusal in zip(named, refusals, strict=True)
]
def _repeated_refusal(channel_address: str, value: object, times: int) -> ChannelWriteResult:
"""The refusal of one write to a channel its batch names more than once."""
return ChannelWriteResult(
channel_address=channel_address,
value_written=value,
outcome=WriteOutcome.REFUSED,
refusal_reason=RefusalReason.VALIDATION_ERROR,
error_message=(
f"Write to '{channel_address}' refused: the batch names this channel more than "
f"once ({times} writes). A batch writes a channel once; send the later value "
"in a batch of its own."
),
)
def _batch_send_verdict(
channel_address: str, value: object, error: Exception
) -> ChannelWriteResult:
"""The result of one write of a batch whose send raised, or the raise itself.
A limits refusal at send time is a ``LIMITS`` refusal. A channel that
could not be reached or did not answer in time is ``unconfirmed``: the
others of the batch are not recalled, and what this one holds is unknown.
Any other error is the connector's own and is raised.
"""
from osprey_connectors.errors import ChannelLimitsViolationError, ChannelUnreachableError
if isinstance(error, ChannelLimitsViolationError):
return _limits_refusal(channel_address, value, error)
if isinstance(error, ChannelUnreachableError | TimeoutError):
return ChannelWriteResult(
channel_address=channel_address,
value_written=value,
outcome=WriteOutcome.UNCONFIRMED,
error_message=(
f"Write to '{channel_address}' could not be confirmed, "
f"its outcome is unknown: {error}"
),
)
raise error
@dataclass(frozen=True)
class _CheckNotMade:
"""A write whose limits check could not be made, so nothing was sent.
What a connector's validate-and-send worker hands back to the loop, which
builds the refusal (:meth:`ControlSystemConnector._validation_refusal`).
"""
error: Exception
@dataclass(frozen=True)
class _SendFailed:
"""A write the control system did not take: the send itself raised."""
error: Exception
#: What a validate-and-send worker answers: ``None`` when the value was sent.
_SendStep: TypeAlias = _CheckNotMade | _SendFailed | None
def _accepts_on_connection(subscribe: Callable[..., object]) -> bool:
"""Whether a ``subscribe()`` takes ``on_connection`` itself, by name or by ``**kwargs``."""
parameters = inspect.signature(subscribe).parameters.values()
return any(
parameter.name == "on_connection" or parameter.kind is inspect.Parameter.VAR_KEYWORD
for parameter in parameters
)
def _compat_subscribe_without_on_connection(
owner: type, subscribe: Callable[..., Awaitable[str]]
) -> Callable[..., Coroutine[object, object, str]]:
"""Give a ``subscribe()`` that predates ``on_connection`` the keyword. Deprecated.
A connector that reports no connection state of its own still shows one
fact about it: a value arrived, so the channel is up. The wrapper tells
``on_connection`` ``True`` before the first value and nothing after —
never ``False``, because such a connector never says a channel dropped.
Without ``on_connection`` the original runs untouched.
Wrapping ``owner`` emits one :class:`DeprecationWarning` naming it. This
compatibility wrapper is removed in osprey-connectors 2027.3.0; a connector's
``subscribe`` should take ``on_connection`` itself.
"""
warnings.warn(
f"{owner.__module__}.{owner.__qualname__}.subscribe does not take on_connection; "
"the base class wraps it for now, but the wrapper is deprecated and is removed "
"in osprey-connectors 2027.3.0. Add the on_connection keyword to subscribe().",
DeprecationWarning,
# this function, __init_subclass__, ABCMeta.__new__, the class statement
stacklevel=4,
)
@functools.wraps(subscribe)
async def _subscribe(
self: "ControlSystemConnector",
channel_address: str,
callback: Callable[["ChannelValue"], None],
*args: object,
on_connection: Callable[[bool], None] | None = None,
**kwargs: object,
) -> str:
if on_connection is None:
return await subscribe(self, channel_address, callback, *args, **kwargs)
connected = False
def _deliver(value: "ChannelValue") -> None:
nonlocal connected
if not connected:
connected = True
on_connection(True)
callback(value)
return await subscribe(self, channel_address, _deliver, *args, **kwargs)
# inspect.signature() reads __signature__ before following __wrapped__, so
# the wrapper reports the keyword it takes; mypy knows no such attribute.
signature = inspect.signature(subscribe)
_subscribe.__signature__ = signature.replace( # type: ignore[attr-defined]
parameters=[
*signature.parameters.values(),
inspect.Parameter("on_connection", inspect.Parameter.KEYWORD_ONLY, default=None),
]
)
return _subscribe
[docs]
class ControlSystemConnector(ABC):
"""
Abstract base class for control system connectors.
Implementations provide interfaces to different control systems
(EPICS, LabVIEW, Tango, the simulator, etc.) using a unified API.
Example:
>>> connector = await ConnectorFactory.create_control_system_connector()
>>> try:
>>> channel_value = await connector.read_channel('BEAM:CURRENT')
>>> print(f"Beam current: {channel_value.value} {channel_value.metadata.units}")
>>> finally:
>>> await connector.disconnect()
"""
_limits_validator: "LimitsValidator | None" = None # Initialized by subclasses in connect()
# The connector type this instance was built as. Stamped by
# ConnectorFactory.build_control_system_connector() between construction and
# connect(), so connect() can already read the posture
# (create_control_system_connector() is that build plus connect()). Stays
# None on an instance nobody built through the factory: no type, so no
# per-type block.
_connector_type: str | None = None
# The control target this instance was built for. Stamped by the same
# factory seam as _connector_type, from the target the *caller* named — the
# init payload's target, the sandbox's stamp, the deployment baseline, the
# bridge lane's own target. Stays None on an instance nobody built through
# the factory, and on a caller that has no target to name.
_control_target: str | None = None
# The wire this instance speaks, stamped by the same factory seam from the
# type and the serving leaf. Stays None on an instance nobody built through
# the factory.
_transport: str | None = None
@property
def transport(self) -> str | None:
"""The factory-stamped wire this instance speaks (``None`` off the factory)."""
return self._transport
# The verdict the last :attr:`_writes_enabled` evaluation reached, so the
# refusal it leads to is worded from the same answer without reading the
# record a second time — a switch flipped between two reads would otherwise
# produce a refusal for a cause the decision never saw. The write guard
# clears it before each evaluation, so a subclass that OVERRIDES
# ``_writes_enabled`` (and therefore never sets it) leaves it None and the
# refusal asks for a verdict itself.
_last_verdict: "WriteVerdict | None" = None
# A subclass's own ``write_channel`` before the guard wrapped it, set by
# ``__init_subclass__``: what an authorized batch writes each operation
# through once the whole call was judged and its step spent.
_unguarded_write_channel: Callable[..., Awaitable[ChannelWriteResult]]
@property
def _writes_enabled(self) -> bool:
"""Whether the write verdict allows a write to this connector's machine.
Decided by :func:`osprey_connectors.posture_store.write_verdict` for
:attr:`_control_target` (see :func:`_monitor_verdict`), re-read on every
call: a read-only run, the login's write tier, the target, the owner,
the login's switch for that machine and the launch pin, first refusal
wins. The switch is the live half: turning a machine on or off from the
chip lands on the very next write of a session already running, with no
respawn and no config edit.
An unstamped connector — one nobody built through the factory — names
no machine and is refused ``target_unknown``. Returns False rather than
raising on any failure.
The verdict is memoised on :attr:`_last_verdict` for the refusal the
write guard is about to build, so one write reads the record once; a
subclass overriding this property never sets it, and the refusal asks
for a verdict itself.
"""
verdict = _monitor_verdict(self._control_target)
self._last_verdict = verdict
return verdict.allowed
[docs]
def current_value_reader(self) -> "CurrentValueReader | None":
"""This connector's own way to read a channel's present value.
Handed to :meth:`LimitsValidator.validate` so the ``max_step`` check
measures the step over the client and the target the write itself is
bound for. The validator is shared by every connector and owns no
client; a connector that cannot read synchronously answers ``None``
here, and a ``max_step`` channel on it fails closed rather than being
measured over somebody else's protocol.
"""
return None
def _validation_refusal(
self, channel_address: str, value: Any, error: BaseException
) -> ChannelWriteResult:
"""The REFUSED result a non-limits validation error owes the caller.
Limits validation answers a write in one of two ways: a
:class:`ChannelLimitsViolationError`, which carries its own semantics
and propagates to the caller unchanged, or any other error — which
says the check could not be MADE. A check that could not be made is
not permission to write: a validator that never answered has not said
yes. So every connector turns that second case into this one REFUSED
result and sends nothing.
Spelled once, here, because the six-outcome contract is a promise
every connector makes with the same words
(``tests/connectors/test_cross_connector_parity.py``); four private
copies of it would be four chances to drift.
"""
logger.warning(
f"Validation error - refusing write (fail-closed): {channel_address}: {error}"
)
return ChannelWriteResult(
channel_address=channel_address,
value_written=value,
outcome=WriteOutcome.REFUSED,
refusal_reason=RefusalReason.VALIDATION_ERROR,
error_message=f"Write to '{channel_address}' refused: validation error: {error}",
)
[docs]
def __init_subclass__(cls, **kwargs):
"""Auto-wrap write methods with the write-verdict pre-check.
Any subclass that defines ``write_channel()`` or
``write_multiple_channels()`` gets them transparently wrapped.
The wrapper checks ``_writes_enabled`` before calling the original
method. When the verdict refuses, returns ``REFUSED`` results worded
by :func:`_verdict_refusal` — no exception is raised.
This fires before limits validation (intentional: fast-reject when
writes are disabled, avoiding unnecessary validation work).
Past that check the wrapper asks
:func:`~osprey_connectors.posture_store.session_hold_refusal`, kept out of
``_writes_enabled`` because that property also chooses the gateway: a held
session's write is refused here while its connection stays as it is.
A process that names a program's write authorization
(:func:`~osprey_connectors.write_authorization.named_authorization`) is
judged instead by
:func:`~osprey_connectors.write_authorization.authorized_execution_verdict`
on the call's channels and values, which spends the call's one step
before anything is put (:func:`_authorized_refusal`). A batch is the
base class's :meth:`write_multiple_channels` under an authorization,
a subclass's own batch included: judged whole and spent once, then each
operation written past the guard. A process naming none is judged
exactly as before.
Past both checks the original method runs inside
:func:`~osprey_connectors.control_system.write_door.open_door`, so the
raw-client guard attributes its put to a connector. A connector whose
writes are disabled never opens the door.
A ``subscribe()`` written before ``on_connection`` existed is wrapped
too (:func:`_compat_subscribe_without_on_connection`, deprecated), so every connector
takes the keyword and a facility's own connector keeps working.
"""
super().__init_subclass__(**kwargs)
original_subscribe = cls.__dict__.get("subscribe")
if original_subscribe is not None and not _accepts_on_connection(original_subscribe):
cls.subscribe = _compat_subscribe_without_on_connection(cls, original_subscribe) # type: ignore[method-assign] # wraps the subclass's own method
original_write: Callable[..., Awaitable[ChannelWriteResult]] | None = cls.__dict__.get(
"write_channel"
)
if original_write is not None:
@functools.wraps(original_write)
async def _guarded_write(
self: "ControlSystemConnector",
channel_address: str,
value: object,
*args: object,
**kwargs: object,
) -> ChannelWriteResult:
authorization = write_authorization.named_authorization()
if authorization is not None:
refused = _authorized_refusal(self, [(channel_address, value)], authorization)
if refused is not None:
return _verdict_refusal(channel_address, value, refused)
with open_door():
return await original_write(self, channel_address, value, *args, **kwargs)
self._last_verdict = None
if not self._writes_enabled:
verdict = self._last_verdict or _monitor_verdict(self._control_target)
return _verdict_refusal(channel_address, value, verdict)
held = posture_store.session_hold_refusal()
if held is not None:
return _verdict_refusal(channel_address, value, held)
with open_door():
return await original_write(self, channel_address, value, *args, **kwargs)
cls.write_channel = _guarded_write # type: ignore[method-assign] # wraps the subclass's own method
# The write past the guard, for an authorized batch that was judged
# and spent whole (:meth:`write_multiple_channels`).
cls._unguarded_write_channel = original_write
original_multi: Callable[..., Awaitable[list[ChannelWriteResult]]] | None = (
cls.__dict__.get("write_multiple_channels")
)
if original_multi is not None:
@functools.wraps(original_multi)
async def _guarded_multi(
self: "ControlSystemConnector",
operations: list[tuple[str, object]],
*args,
**kwargs,
) -> list[ChannelWriteResult]:
if write_authorization.named_authorization() is not None:
# Under an authorization a batch is the base class's: one
# step for the call, then each operation past the guard.
return await ControlSystemConnector.write_multiple_channels(
self, operations, *args, **kwargs
)
self._last_verdict = None
if not self._writes_enabled:
# One verdict for the batch, not one per operation: the
# whole batch was refused by one answer, and every result
# must tell the same story about why.
verdict = self._last_verdict or _monitor_verdict(self._control_target)
return [_verdict_refusal(addr, val, verdict) for addr, val in operations]
held = posture_store.session_hold_refusal()
if held is not None:
return [_verdict_refusal(addr, val, held) for addr, val in operations]
with open_door():
return await original_multi(self, operations, *args, **kwargs)
cls.write_multiple_channels = _guarded_multi # type: ignore[method-assign] # wraps the subclass's own method
def _write_route_open(self) -> bool:
"""Whether the route this connector selected at ``connect()`` can carry a write.
``True`` here; a connector that selects a gateway by the verdict at
connect time and refuses a write on the read gateway ``switching``
(EPICS) answers for itself. The write guard asks it before an
authorized write spends its step, so a write that could not go out
costs nothing.
"""
return True
def _resolve_confirm(self, channel_address: str) -> bool:
"""Whether a write to this channel must be confirmed by re-reading it.
The limits database is the single home of write policy: the channel's
own ``confirm``, else ``True``. A connector with no validator has limits
checking disabled and no policy to read, so it takes the fleet default
and confirms.
"""
if self._limits_validator is None:
return True
return bool(self._limits_validator.resolve_confirm(channel_address))
[docs]
@abstractmethod
async def connect(self, config: dict[str, Any]) -> None:
"""
Establish connection to control system.
Args:
config: Control system-specific configuration
Raises:
ConnectorUnavailableError: If connection cannot be established
"""
[docs]
@abstractmethod
async def disconnect(self) -> None:
"""Close connection to control system and cleanup resources."""
[docs]
@abstractmethod
async def read_channel(
self, channel_address: str, timeout: float | None = None
) -> ChannelValue:
"""
Read current value of a channel.
Args:
channel_address: Address/name of the channel
timeout: Optional timeout in seconds
Returns:
ChannelValue with current value, timestamp, and metadata
Raises:
ChannelUnreachableError: This channel cannot be reached or did not
answer in time; the connector stays in place
ConnectorUnavailableError: The connector's own transport is gone
TimeoutError: If operation times out
ValueError: If channel address is invalid
ChannelNotFoundError: The address is not a channel of the facility
(a connector that holds the facility's address set)
"""
[docs]
@abstractmethod
async def write_channel(
self,
channel_address: str,
value: Any,
timeout: float | None = None,
confirm: bool | None = None,
) -> ChannelWriteResult:
"""
Write a value to a channel, confirming it unless asked not to.
Args:
channel_address: Address/name of the channel
value: Value to write
timeout: Optional timeout in seconds
confirm: Whether to re-read the channel and compare, or ``None`` to
let the connector resolve the policy for this channel
Returns:
ChannelWriteResult carrying the outcome and what the channel was
seen to hold
Raises:
ChannelUnreachableError: This channel cannot be reached or did not
answer in time; the connector stays in place
ConnectorUnavailableError: The connector's own transport is gone
TimeoutError: If operation times out
ValueError: If value is invalid for this channel
PermissionError: If write access is not allowed
Outcomes:
The connector sets exactly one :class:`WriteOutcome` on the result,
and no consumer re-derives a verdict of its own:
- ``refused`` — nothing was written; ``refusal_reason`` says why.
- ``failed`` — the value was sent and the control system did not
take it.
- ``confirmed`` — a fresh re-read holds the value sent, in any alarm
state. Alarm state is reported with the write, never raised on.
- ``mismatch`` — the re-read holds a different value. A clamped or
rounded setpoint is reported here, not tolerated.
- ``unconfirmed`` — the value was sent, but not acknowledged in
time or the re-read itself failed, so what the channel holds is
unknown.
- ``unrequested`` — ``confirm=False``: nothing was checked.
The comparison is :func:`values_match`, one rule shared by every
connector; there is no configurable tolerance anywhere.
Omission sentinel:
``confirm=None`` means "no opinion" — it is NOT ``False``. A caller
with no opinion leaves the keyword off entirely; the connector then
resolves the policy for this specific channel through
:meth:`_resolve_confirm`: the channel's own ``confirm`` entry in the
limits database, else ``True``. The limits database is the single
home of write policy.
An explicit ``confirm=False`` is an answer and must travel as one, so
every guard on the omission is ``if confirm is not None`` and never
``if confirm:`` — the truth test would silently turn a declined
confirmation back into "resolve it" and confirm anyway.
Two-layer safety model:
**Per-write mechanical safety** lives INSIDE the connector and is applied
per individual channel write: the ``writes_enabled`` gate, limits
validation (min/max/step/writable), and the fail-closed validation path.
This is complete mediation at the write primitive — every write passes
through it.
**Per-intent human authorization** is a SEPARATE layer at the tool
boundary: the PreToolUse approval hook (and, for scans, the promote token)
gate the *intent* to write, once per intent — not once per channel write.
The two are orthogonal and complementary: the connector cannot be talked
out of a mechanical refusal, and the approval layer cannot substitute for
that refusal.
"""
[docs]
async def write_channel_checked(
self, channel_address: str, value: Any, **kwargs: Any
) -> ChannelWriteResult:
"""Await write_channel and enforce the reference monitor's denial contract.
``refused`` (policy/limits/validation) -> raises ChannelWriteBlockedError.
``failed`` / ``mismatch`` / ``unconfirmed`` -> raises ChannelWriteFailedError.
Connection failures and timeouts propagate unchanged.
``confirmed`` or ``unrequested`` -> returns the ChannelWriteResult.
A scan device setter wraps this so any raise aborts the RunEngine, while a
confirmed write returns and the scan proceeds; ``osprey.runtime.write_channel``
routes through it for the same reason. Extra keyword arguments (``confirm``,
``timeout``) pass straight through to write_channel. The result inspection
itself lives in :func:`raise_for_write_result`, which the multi-channel paths
share.
"""
from osprey_connectors.errors import (
ChannelLimitsViolationError,
ChannelWriteBlockedError,
)
try:
result = await self.write_channel(channel_address, value, **kwargs)
except ChannelLimitsViolationError as exc:
# A limits refusal is a REFUSAL — normalize it into the unified denial type
# so consumers key on one refusal signal. Connection failures and
# timeouts are not caught here, so they propagate unchanged.
raise ChannelWriteBlockedError(channel_address, "LIMITS", message=str(exc)) from exc
return raise_for_write_result(result)
async def _read_concurrently(
self, channel_addresses: list[str], timeout: float | None
) -> dict[str, ChannelValue]:
"""Read channels concurrently, omitting failed reads and re-raising cancellations."""
results = await asyncio.gather(
*(self.read_channel(address, timeout) for address in channel_addresses),
return_exceptions=True,
)
values: dict[str, ChannelValue] = {}
for address, result in zip(channel_addresses, results, strict=True):
if isinstance(result, Exception):
continue
if isinstance(result, BaseException):
raise result
values[address] = result
return values
[docs]
@abstractmethod
async def read_multiple_channels(
self, channel_addresses: list[str], timeout: float | None = None
) -> dict[str, ChannelValue]:
"""
Read multiple channels efficiently (can be optimized per control system).
Args:
channel_addresses: List of channel addresses to read
timeout: Optional timeout in seconds
Returns:
Dictionary mapping channel address to ChannelValue
(May exclude channels that failed to read)
"""
[docs]
async def write_multiple_channels(
self,
operations: list[tuple[str, Any]],
timeout: float | None = None,
confirm: bool | None = None,
) -> list[ChannelWriteResult]:
"""
Write several channels as one batch: every write checked, then every write sent.
What a batch means, on every connector:
1. **The checks are all-or-nothing.** Every write passes every check a
single :meth:`write_channel` makes before it sends: the write
verdict, the connector's own refusals and the limits, ``max_step``
included. The channels a step
is measured on are read together, once, before anything is sent. If
one write is refused there, **no write of the batch is sent**, and every
channel gets a ``refused`` result: a refused write its own reason,
each other write ``BATCH_REFUSED`` naming a refused one.
2. **Past the checks every write is sent and verified on its own.** One
result per channel, with the outcome a single write would report. A
write that fails, mismatches or stays unconfirmed does not recall
the others, which may already hold their values. The batch has
failed unless every result may be proceeded on
(:func:`raise_for_write_result`).
The promise covers what is known before the send. A refusal the control
system gives only at the send (a connector with no
:meth:`_write_precheck`, a value the target coerces or a read-only
channel it rejects) can come after earlier writes of the batch went
out; each result still says what happened to its own channel.
A batch names a channel once. One that names a channel more than once
is refused whole: a later write to it could only be checked against an
earlier one that may never land.
The write verdict is asked again right before the send, so a switch
turned off, a hold or a stop that arrives while the batch is checked
refuses every write not yet sent.
A batch never raises ``ChannelLimitsViolationError``: a limits refusal
is a ``refused`` result with reason ``LIMITS``. A channel whose send
raised ``ChannelUnreachableError`` or timed out is ``unconfirmed``. An
error of the connector itself (``ConnectorUnavailableError``) is
raised, and the batch's outcome is then unknown.
This method is the batch on every connector. A connector changes how a
batch is checked or sent through :meth:`_write_precheck`,
:meth:`_current_values` and :meth:`_send_batch`, not by overriding it.
A refusal a connector makes only inside its own :meth:`write_channel`
is not known before the send: it belongs in :meth:`_write_precheck`.
Args:
operations: List of (channel_address, value) tuples
timeout: Optional timeout in seconds, given to each write
confirm: Whether every channel in the batch is confirmed, or ``None``
to let each channel resolve its own policy
Returns:
List of ChannelWriteResult in the same order as operations
Note:
An omitted ``confirm`` is not resolved here: each channel resolves
its own policy from the limits database, as :meth:`write_channel`
documents. An explicit ``confirm``, ``False`` as much as ``True``,
reaches every channel unchanged.
In a process that names a program's write authorization the whole
call is judged and its one step spent before anything is checked
or sent; a batch the limits then refuse has still spent it.
"""
batch: list[tuple[str, object]] = list(operations)
authorization = write_authorization.named_authorization()
refused: WriteVerdict | None
if authorization is not None:
refused = _authorized_refusal(self, batch, authorization)
else:
# Every write is judged, as a single write is, before any is sent.
# The first refusal answers for the batch: every result of a
# refused batch tells the same story about why.
refused = None
for _ in batch:
self._last_verdict = None
if not self._writes_enabled:
refused = self._last_verdict or _monitor_verdict(self._control_target)
else:
refused = posture_store.session_hold_refusal()
if refused is not None:
break
if refused is not None:
return [_verdict_refusal(address, value, refused) for address, value in batch]
if not batch:
return []
with open_door():
named, refusals = await self._check_batch(batch)
if any(refusal is not None for refusal in refusals):
return _refused_batch(named, refusals)
return await self._send_batch(named, timeout, confirm)
def _write_precheck(
self,
channel_address: str,
value: Any, # noqa: ARG002 - a connector's refusal carries the value
) -> tuple[str, ChannelWriteResult | None]:
"""One write's name, and the refusal this connector answers before the limits.
The checks :meth:`write_channel` makes without touching the control
system, ahead of limits validation. The name is the one the limits,
the send and the result use for the channel.
"""
return channel_address, None
async def _current_values(self, channel_addresses: list[str]) -> dict[str, Any] | None:
"""What the named channels hold now, for a batch's ``max_step`` checks.
``None`` when the connector has no reader, and the step checks then
fail closed. A channel that could not be read maps to the exception
its read raised, or to ``None``. The default reads through
:meth:`current_value_reader` in one worker thread for the whole batch.
"""
reader = self.current_value_reader()
if reader is None:
return None
def read_all() -> dict[str, object]:
held: dict[str, object] = {}
for address in channel_addresses:
try:
held[address] = reader(address)
except Exception as exc:
held[address] = exc
return held
return await asyncio.to_thread(read_all)
async def _check_batch(
self, batch: Sequence[tuple[str, object]]
) -> tuple[list[tuple[str, object]], list[ChannelWriteResult | None]]:
"""Check every write of a batch; nothing is sent.
Returns the writes under the names :meth:`_write_precheck` gave them,
and one entry per write: its refusal, or ``None`` when it passed.
"""
from osprey_connectors.errors import ChannelLimitsViolationError
named: list[tuple[str, object]] = []
refusals: list[ChannelWriteResult | None] = []
for address, value in batch:
name, refusal = self._write_precheck(address, value)
named.append((name, value))
refusals.append(refusal)
times = Counter(name for name, _ in named)
for index, (name, value) in enumerate(named):
if times[name] > 1 and refusals[index] is None:
refusals[index] = _repeated_refusal(name, value, times[name])
validator = self._limits_validator
if not validator:
return named, refusals
def measured(name: str) -> bool:
try:
return bool(validator.measures_step(name))
except Exception:
return True # cannot tell: read it
stepped = [
name
for (name, _), refusal in zip(named, refusals, strict=True)
if refusal is None and measured(name)
]
held: Mapping[str, object] | None = await self._current_values(stepped) if stepped else {}
def read_current(name: str) -> object:
current = held.get(name) if held is not None else None
if isinstance(current, BaseException):
raise current
return current
reader = None if held is None else read_current
for index, (name, value) in enumerate(named):
if refusals[index] is not None:
continue
try:
validator.validate(name, value, read_current=reader)
except ChannelLimitsViolationError as exc:
refusals[index] = _limits_refusal(name, value, exc)
except Exception as exc:
# The check could not be made, which is not permission to write.
refusals[index] = self._validation_refusal(name, value, exc)
return named, refusals
def _send_refusal(self, batch: Sequence[tuple[str, object]]) -> "WriteVerdict | None":
"""The verdict refusing what a checked batch has not sent yet, or ``None``.
The batch was judged before its checks, and the checks take time: a
switch turned off, a hold or a stop since then must not be outrun by
the send. This asks again what the write guard asks of a single write.
In a process that names an authorization the call is judged again
without spending; ``auth_exhausted`` alone is no refusal here, since
the step this batch spent may have been the last.
"""
authorization = write_authorization.named_authorization()
self._last_verdict = None
if authorization is None:
if not self._writes_enabled:
return self._last_verdict or _monitor_verdict(self._control_target)
return posture_store.session_hold_refusal()
if _overrides_writes_enabled(self) and not self._writes_enabled:
return self._last_verdict or _monitor_verdict(self._control_target)
verdict = write_authorization.authorized_execution_verdict(
_monitor_section(), self._control_target, batch, authorization=authorization
)
return None if verdict.allowed or verdict.reason == "auth_exhausted" else verdict
async def _send_batch(
self,
batch: list[tuple[str, Any]],
timeout: float | None,
confirm: bool | None,
) -> list[ChannelWriteResult]:
"""Send a batch that passed every check: one result per write, in order.
The default sends one write after the other through the connector's
own :meth:`write_channel`, past the guard that already judged the
batch, and asks :meth:`_send_refusal` before each: once it refuses,
every write not yet sent is refused by that verdict. A connector whose
control system takes concurrent puts sends them together, and asks
once, immediately before the puts start.
"""
kwargs: dict[str, float | bool | None] = {"timeout": timeout}
if confirm is not None:
kwargs["confirm"] = confirm
write = type(self)._unguarded_write_channel
results: list[ChannelWriteResult] = []
for index, (address, value) in enumerate(batch):
refused = self._send_refusal(batch)
if refused is not None:
results.extend(_verdict_refusal(*held, refused) for held in batch[index:])
break
try:
results.append(await write(self, address, value, **kwargs))
except Exception as exc:
results.append(_batch_send_verdict(address, value, exc))
return results
[docs]
@abstractmethod
async def subscribe(
self,
channel_address: str,
callback: Callable[[ChannelValue], None],
*,
on_connection: Callable[[bool], None] | None = None,
) -> str:
"""
Subscribe to channel changes.
Args:
channel_address: Address/name of the channel
callback: Function called when value changes (receives ChannelValue)
on_connection: Optional function told the channel's connection state:
``True`` when it connects (before the first value of that
connection), ``False`` when it drops. A channel that never
connects reports nothing. Called on the event loop, like
``callback``. Connectors whose control system reports no
connection state (DOOCS, Tango) accept and ignore it. A
subclass whose ``subscribe`` does not take it is told ``True``
before its first value by the base class instead.
Returns:
Subscription ID for later unsubscribe
"""
[docs]
@abstractmethod
async def unsubscribe(self, subscription_id: str) -> None:
"""
Cancel subscription to channel changes.
Args:
subscription_id: Subscription ID returned by subscribe()
"""
[docs]
async def wait_stale(self) -> None:
"""
Raise :class:`~osprey_connectors.errors.ConnectorUnavailableError` once this connector's transport has gone stale.
Stale means the control system serves a channel again while this
process's client library still holds it down and will not notice on its
own; only a new connector in a new process cures it. That is a lost
connector, so it is raised as the lost-connector root, and the
supervisor that owns the connector's lifetime replaces it as it would
after any :class:`~osprey_connectors.errors.ConnectorUnavailableError`
(:mod:`osprey_connectors.recovery`). It never returns normally. A
connector that can tell (EPICS with a name server) overrides this
method.
This default serves every connector where staleness cannot occur or
cannot be told (DOOCS, Tango, ...): it waits for ever. A caller that is
shutting down cancels it.
An overriding connector counts only channels that connected in this
process, so in the successor of a stale process a channel that never
comes back cannot drive a respawn loop.
"""
await asyncio.get_running_loop().create_future()
[docs]
def channel_key(self, address: str) -> str:
"""The one name every spelling of a channel's address shares on this control system.
A caller that must treat two addresses as one channel (a session
admitting one write per channel at a time) compares these keys; the
read or write itself still goes to the address as given. Pure and
synchronous. This default strips surrounding whitespace; a connector
whose protocol spells one channel several ways (EPICS: ``ca://X``,
``X.VAL`` and ``X``) overrides it.
"""
return address.strip()
[docs]
@abstractmethod
async def validate_channel(self, channel_address: str) -> bool:
"""
Check if channel exists and is accessible.
Args:
channel_address: Address/name of the channel
Returns:
True if channel is valid and accessible
"""
#: The base class's own ``_writes_enabled``, which a subclass may override.
_BASE_WRITES_ENABLED: object = ControlSystemConnector.__dict__["_writes_enabled"]