"""Which control targets the deployment's archive serves, decided in one place.
A deployment carries **one** ``archiver:`` block, and a session can be pointed
at up to three machines — the facility's own (``live``), the virtual
accelerator (``va``) and the stand-in soft IOC (``standin``). The block holds
the past of some of them and not others. :func:`archive_targets` says which,
so that a reader offering history on a target can ask whether the store it
would open is that target's own, and answer "no archive" when it is not —
never another machine's past under the selected machine's name.
Every archiver belongs to one of two classes, and the class decides:
* ``mongodb_archiver`` is **the deployment's own store**. On a deployment that
built a virtual accelerator it serves ``va``, whatever machine its sessions
start on and whether or not a stand-in was built beside it; on one that built
no simulator it serves nothing.
* Every other archiver except the mock is **the facility's archive** (the
EPICS archiver appliance, MYA, DOOCS, or a type this table does not know)
and serves ``live`` and ``standin`` when its block names an address, nothing
when it does not.
* The mock, or no block at all, serves nothing.
**The facility's archive belongs to the facility's machine, and the stand-in
rehearses that machine.** It is not something a deployment stands up for its
simulation; it holds the real machine's past, and that past is the one a
stand-in session is shown, because what the stand-in rehearses is the
procedure against the real machine's history. It needs an address to count: a
block that cannot be dialled is not a deployment saying it has an archive. The
address is read per type (:data:`_ADDRESS_SETTINGS`): the appliance's ``url``;
MYA and DOOCS find their server without a setting (the client library's
configured ``myquery_server``, the facility's name service), so their block
always names one.
**The mongodb store belongs to the virtual accelerator.** The deployment seeds
it with the simulator's synthesized history and the recorder samples the
simulator into it (``osprey.services.archiver_recorder``); the stand-in is
never recorded there and its offsets are never seeded there. So the store is
the ``va`` target's exactly when the deployment built a simulator — read
through :func:`osprey_connectors.simulator.virtual_accelerator_port`, the
build's own statement that it stood one up — and no other target's ever.
``control_system.type`` is not consulted: it names the machine a session
starts on, and a deployment baselined on its stand-in or on the facility's
machine still seeds and records the simulator it built.
Nothing is the honest answer for the mock, which synthesizes and has no past,
and for a block the connector factory would refuse — both settings spellings
at once, or a settings value that is not a mapping — which serves no archive,
so it claims none.
Pure: the answer is a function of the mapping alone. No environment variable,
no file and no control-context record is consulted, which is what lets a
supervisor call it at every restart and get the deployment's answer rather than
the calling process's.
"""
from __future__ import annotations
from collections.abc import Mapping
from types import MappingProxyType
from osprey_connectors.simulator import virtual_accelerator_port
from osprey_connectors.types import (
DOOCS_ARCHIVER,
EPICS_ARCHIVER,
MOCK_ARCHIVER,
MONGODB_ARCHIVER,
MYA_ARCHIVER,
TARGET_LIVE,
TARGET_STANDIN,
TARGET_VA,
resolve_archiver_settings,
resolve_archiver_type,
)
#: The top-level config section selecting and configuring the archiver.
_ARCHIVER_SECTION_KEY = "archiver"
#: The archiver types that are the deployment's own store. Every other type
#: except the mock is the facility's archive.
_STORE_ARCHIVERS: frozenset[str] = frozenset({MONGODB_ARCHIVER})
#: The setting under which a facility archive names where it is, per type.
#: ``None``: the connector finds its server without one (MYA through the client
#: library's configured ``myquery_server``, DOOCS through the facility's name
#: service), so its block always names an address. A type not listed names it
#: under :data:`_DEFAULT_ADDRESS_SETTING`.
_ADDRESS_SETTINGS: Mapping[str, str | None] = MappingProxyType(
{EPICS_ARCHIVER: "url", MYA_ARCHIVER: None, DOOCS_ARCHIVER: None}
)
#: The address setting of a facility archive :data:`_ADDRESS_SETTINGS` does not list.
_DEFAULT_ADDRESS_SETTING = "url"
#: The targets the facility's archive serves: the real machine and the
#: stand-in that rehearses it.
APPLIANCE_TARGETS: frozenset[str] = frozenset({TARGET_LIVE, TARGET_STANDIN})
#: The targets the deployment's own store serves: the virtual accelerator.
_STORE_TARGETS: frozenset[str] = frozenset({TARGET_VA})
#: No archive for any target.
_NO_TARGETS: frozenset[str] = frozenset()
__all__ = [
"APPLIANCE_TARGETS",
"archive_targets",
"archive_withheld",
]
[docs]
def archive_targets(config: Mapping[str, object]) -> frozenset[str]:
"""The control targets whose history this deployment's ``archiver`` block holds.
Args:
config: The full config mapping, as loaded from ``config.yml`` — not the
``archiver:`` section, because the answer for the mongodb store
turns on whether the deployment built a simulator, which the
section alone does not carry.
Returns:
The targets per the module table — :data:`APPLIANCE_TARGETS`,
:data:`_STORE_TARGETS` or :data:`_NO_TARGETS`. A target absent from the
set has no archive: a caller holding it has nothing to offer, never a
default to fall back on.
"""
section = config.get(_ARCHIVER_SECTION_KEY) if isinstance(config, Mapping) else None
archiver_type = resolve_archiver_type(section)
if archiver_type == MOCK_ARCHIVER:
return _NO_TARGETS
try:
settings = resolve_archiver_settings(section)
except ValueError:
# The factory refuses this block with the same error, so no connector
# is ever built from it and there is no store to attribute.
return _NO_TARGETS
if archiver_type in _STORE_ARCHIVERS:
return _STORE_TARGETS if virtual_accelerator_port(config) is not None else _NO_TARGETS
return APPLIANCE_TARGETS if _names_an_address(archiver_type, settings) else _NO_TARGETS
[docs]
def archive_withheld(config: Mapping[str, object], target: str) -> bool:
"""Whether a session on *target* must be told it has no archive.
The agent's reader of the one ``archiver:`` block asks this before it
opens the connector, and the answer is the table's: an attributed block
whose targets do not include *target* is another machine's past, and is
withheld. The mock is not withheld here; whether it is an honest pairing is
the archiver pairing's question, asked at build and at the target switch.
Args:
config: The full config mapping, as loaded from ``config.yml``.
target: The control target the session is on.
Returns:
``True`` when the block is not the mock and does not serve *target*.
"""
section = config.get(_ARCHIVER_SECTION_KEY) if isinstance(config, Mapping) else None
if resolve_archiver_type(section) == MOCK_ARCHIVER:
return False
return target not in archive_targets(config)
def _names_an_address(archiver_type: str, settings: Mapping[str, object]) -> bool:
"""Whether a facility archive's *settings* state where it is.
A non-blank string under the type's :data:`_ADDRESS_SETTINGS` entry, or
always for a type whose connector finds its server without one. The
connector's own reader decides whether the address is well formed; this
only establishes that the deployment said one.
"""
key = _ADDRESS_SETTINGS.get(archiver_type, _DEFAULT_ADDRESS_SETTING)
if key is None:
return True
address = settings.get(key)
return isinstance(address, str) and bool(address.strip())