raccoon_transport.contract_check

Startup check of the transport contract. Semantics: contract/CHECK_SPEC.md.

Every component runs startup_check() once when it starts. The result goes to a status file (never over the transport, which may be the thing that is broken) and, for mismatch and bundle-fehler, the component refuses to start. The Pi server reads the status files with aggregate().

Attributes

EXIT_CODE
OK
MISMATCH
DEV_WARNING
BUNDLE_ERROR
SKIPPED

Exceptions

ContractError

The transport contract of this component does not match the bundle.

Classes

ComponentCheck	The result of a check that belongs to the component, not to the transport.
CheckResult

Functions

is_refusing(→ bool)	Everything except ok, dev-warnung and skipped refuses, including the results that a
check(→ CheckResult)	Run the decision of the spec. Reads one file, writes nothing.
status_dir(→ pathlib.Path)
write_status(→ Optional[pathlib.Path])	Write <component>.json atomically. Returns None (and logs) on failure.
startup_check(→ CheckResult)	Check, record, log. Raises ContractError if the component must refuse.
exit_if_refused(→ None)	For long-running services: exit with the reserved code.
read_statuses(→ list[dict[str, Any]])	All status files with an active flag. Unreadable files are reported, not hidden.
aggregate(→ dict[str, Any])	What GET /contract of the Pi server returns.
refusal_message(→ Optional[str])	Text for rejecting a run, or None when the run may start.

Module Contents

raccoon_transport.contract_check.EXIT_CODE = 78

raccoon_transport.contract_check.OK = 'ok'

raccoon_transport.contract_check.MISMATCH = 'mismatch'

raccoon_transport.contract_check.DEV_WARNING = 'dev-warnung'

raccoon_transport.contract_check.BUNDLE_ERROR = 'bundle-fehler'

raccoon_transport.contract_check.SKIPPED = 'skipped'

raccoon_transport.contract_check.is_refusing(result: str | None) → bool

Everything except ok, dev-warnung and skipped refuses, including the results that a component’s own check defines (for example the component version check).

exception raccoon_transport.contract_check.ContractError(result: CheckResult)

Bases: RuntimeError

The transport contract of this component does not match the bundle.

result

class raccoon_transport.contract_check.ComponentCheck

The result of a check that belongs to the component, not to the transport.

A component runs its own check (for example “is my version the one in the bundle?”) and hands the result to check() / startup_check(). The transport knows nothing about what it checks: result is ok, dev-warnung or any name that refuses (version-mismatch, …), and message is shown as it is. It is merged after the transport’s own checks (a transport failure always wins) and recorded in the status file.

name: str

result: str

message: str

reason: str | None = None

expected: str | None = None

class raccoon_transport.contract_check.CheckResult

component: str

component_version: str

own_hash: str

own_transport_version: str

expected_hash: str | None

expected_transport_version: str | None

bundle: str | None

result: str

reason: str | None

message: str

bundle_file: str = '/etc/raccoon-bundle.json'

component_check: ComponentCheck | None = None

property refuse: bool

raccoon_transport.contract_check.check(component: str, component_version: str, *, component_check: ComponentCheck | None = None, own_hash: str | None = None, own_version: str | None = None, bundle_file: str | None = None, device_marker: str | None = None, force: bool | None = None) → CheckResult

Run the decision of the spec. Reads one file, writes nothing.

raccoon_transport.contract_check.status_dir(override: str | None = None) → pathlib.Path

raccoon_transport.contract_check.write_status(result: CheckResult, *, persistent: bool, directory: str | None = None) → pathlib.Path | None

Write <component>.json atomically. Returns None (and logs) on failure.

raccoon_transport.contract_check.startup_check(component: str, component_version: str, *, persistent: bool, enforce: bool = True, status_directory: str | None = None, **kwargs: Any) → CheckResult

Check, record, log. Raises ContractError if the component must refuse.

raccoon_transport.contract_check.exit_if_refused(result: CheckResult) → None

For long-running services: exit with the reserved code.

raccoon_transport.contract_check.read_statuses(directory: str | None = None) → list[dict[str, Any]]

All status files with an active flag. Unreadable files are reported, not hidden.

raccoon_transport.contract_check.aggregate(*, bundle_file: str | None = None, directory: str | None = None, device_marker: str | None = None, force: bool | None = None) → dict[str, Any]

What GET /contract of the Pi server returns.

Off a Raccoon device (laptop, simulation, tests) there is nothing to enforce: the result is ok with on_device false.

raccoon_transport.contract_check.refusal_message(summary: dict[str, Any]) → str | None

Text for rejecting a run, or None when the run may start.