readerboard 0.1.1__py3-none-any.whl

readerboard/sign/layout.py

@@ -0,0 +1,112 @@
+"""Deciding which sign file each message lives in.
+
+The sign stores up to 26 TEXT files, labelled ``A`` through ``Z``, plus the
+priority file ``0``. This service allocates a fixed pool of those TEXT files
+once and then hands them out to registered messages, one file each.
+
+The pool is fixed rather than grown on demand for one reason: allocating files
+erases the sign. Growing the pool when a fourth source turned up would blank the
+other three, so the size is a configuration decision made up front and the
+service simply refuses a message once the pool is full.
+"""
+
+from __future__ import annotations
+
+from readerboard.protocol import constants as c
+from readerboard.protocol.frames import FileAllocation
+from readerboard.sign.state import AppliedLayout
+
+
+class LayoutFull(RuntimeError):
+    """Every file in the pool is already spoken for."""
+
+
+class Layout:
+    """The pool of sign files, and who currently holds each one."""
+
+    def __init__(self, slot_count: int, slot_capacity: int) -> None:
+        """Describe a pool of ``slot_count`` files of ``slot_capacity`` bytes each."""
+        if not 1 <= slot_count <= len(c.TEXT_FILE_LABELS):
+            raise ValueError(
+                "slot_count must be between 1 and %d, got %d"
+                % (len(c.TEXT_FILE_LABELS), slot_count)
+            )
+        self.slot_count = slot_count
+        self.slot_capacity = slot_capacity
+        self.labels: tuple[bytes, ...] = c.TEXT_FILE_LABELS[:slot_count]
+        self._assigned: dict[str, bytes] = {}
+
+    # == the memory configuration ==========================================
+
+    def allocations(self) -> list[FileAllocation]:
+        """Return the memory configuration entries for the whole pool."""
+        return [FileAllocation(label, self.slot_capacity) for label in self.labels]
+
+    def as_applied(self) -> AppliedLayout:
+        """Return this layout in the form the state file records."""
+        return AppliedLayout(
+            slot_count=self.slot_count,
+            slot_capacity=self.slot_capacity,
+            labels=[label.decode("ascii") for label in self.labels],
+        )
+
+    def needs_reconfiguration(self, applied: AppliedLayout | None) -> bool:
+        """Whether the sign has to be reallocated, which will erase it."""
+        if applied is None:
+            return True
+        return not applied.matches(self.slot_count, self.slot_capacity)
+
+    # == handing files out ==================================================
+
+    def assign(self, key: str) -> bytes:
+        """Return the file this key uses, claiming a free one if it has none.
+
+        Raises :class:`LayoutFull` when the pool is exhausted, which the API
+        turns into a 409 rather than quietly dropping somebody's message.
+        """
+        existing = self._assigned.get(key)
+        if existing is not None:
+            return existing
+
+        taken = set(self._assigned.values())
+        for label in self.labels:
+            if label not in taken:
+                self._assigned[key] = label
+                return label
+
+        raise LayoutFull(
+            "all %d message slots are in use. Remove one, or raise slot_count and "
+            "restart, which reallocates the sign and clears it." % self.slot_count
+        )
+
+    def release(self, key: str) -> bytes | None:
+        """Give a key's file back to the pool, returning the file it held."""
+        return self._assigned.pop(key, None)
+
+    def label_for(self, key: str) -> bytes | None:
+        """Return the file this key holds, or None if it holds none."""
+        return self._assigned.get(key)
+
+    def restore(self, key: str, label: bytes) -> None:
+        """Re-establish an assignment read back from the state file.
+
+        A pool that shrank between runs can leave a key pointing at a file that
+        no longer exists. That key is dropped rather than silently moved, since
+        moving it would mean writing to a file the sign has not allocated.
+        """
+        if label not in self.labels:
+            raise ValueError(
+                "file %r is outside the pool A to %s"
+                % (label.decode("ascii"), self.labels[-1].decode("ascii"))
+            )
+        self._assigned[key] = label
+
+    @property
+    def assignments(self) -> dict[str, bytes]:
+        """A copy of the current key to file mapping."""
+        return dict(self._assigned)
+
+    @property
+    def free_count(self) -> int:
+        """How many files in the pool are unclaimed."""
+        return self.slot_count - len(self._assigned)

readerboard/sign/state.py

@@ -0,0 +1,171 @@
+"""What the service remembers across a restart.
+
+Three things have to survive: which messages are registered and where on the
+sign each one lives, whether an alert is currently holding the display, and
+which memory configuration was last applied.
+
+The last of those matters more than it looks. Writing a memory configuration
+erases every file on the sign, so the service must be able to tell "the pool I
+want is the pool that is already there" from "the pool changed", and only
+reconfigure in the second case. Without this record, every restart would wipe
+the sign.
+
+Writes are atomic. A half-written state file after a power cut would strand the
+sign, and a Pi losing power is exactly the event this service is expected to
+recover from.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+from datetime import datetime
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+STATE_VERSION = 1
+
+
+class SlotState(BaseModel):
+    """One registered message."""
+
+    key: str
+    label: str
+    message: str
+    mode: str
+    position: str
+    order: int = 0
+    source: str | None = None
+    expires_at: datetime | None = None
+    updated_at: datetime
+
+
+class AlertState(BaseModel):
+    """An alert holding the priority file."""
+
+    message: str
+    mode: str
+    position: str
+    started_at: datetime
+    expires_at: datetime | None = None
+
+
+class AppliedLayout(BaseModel):
+    """The memory configuration currently believed to be on the sign."""
+
+    slot_count: int
+    slot_capacity: int
+    labels: list[str]
+
+    def matches(self, slot_count: int, slot_capacity: int) -> bool:
+        """Whether this layout is already what the given settings ask for."""
+        return self.slot_count == slot_count and self.slot_capacity == slot_capacity
+
+
+class ServiceState(BaseModel):
+    """Everything persisted, in one document."""
+
+    version: int = STATE_VERSION
+    slots: dict[str, SlotState] = Field(default_factory=dict)
+    alert: AlertState | None = None
+    layout: AppliedLayout | None = None
+
+
+class StateStore:
+    """Loads and saves :class:`ServiceState` as JSON, atomically."""
+
+    def __init__(self, path: Path) -> None:
+        """Point the store at a file. The file need not exist yet."""
+        self.path = path
+        self._last_written: str | None = None
+        self.writes = 0
+        self.skipped = 0
+
+    def load(self) -> ServiceState:
+        """Read the state, returning a fresh one if there is nothing usable to read.
+
+        A corrupt or unreadable state file is a bad reason to refuse to start.
+        The sign can be repopulated by its sources; refusing to boot cannot be
+        fixed without someone logging in. So it is logged loudly and set aside.
+        """
+        if not self.path.exists():
+            logger.info("no state file at %s; starting empty", self.path)
+            return ServiceState()
+
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as err:
+            logger.error("could not read state from %s (%s); starting empty", self.path, err)
+            return ServiceState()
+
+        version = raw.get("version")
+        if version != STATE_VERSION:
+            logger.error(
+                "state at %s is version %r, not %d; starting empty",
+                self.path,
+                version,
+                STATE_VERSION,
+            )
+            return ServiceState()
+
+        try:
+            state = ServiceState.model_validate(raw)
+        except ValueError as err:
+            logger.error("state at %s did not validate (%s); starting empty", self.path, err)
+            return ServiceState()
+
+        logger.info(
+            "restored %d slot(s)%s from %s",
+            len(state.slots),
+            " and an active alert" if state.alert else "",
+            self.path,
+        )
+        return state
+
+    def save(self, state: ServiceState) -> None:
+        """Write the state out, replacing the old file in one step.
+
+        A save whose content is identical to the last one written is skipped.
+        This runs on a Raspberry Pi with an SD card underneath it, and the
+        service saves on every operation whether or not the operation changed
+        anything: sweeps that expire nothing, restores, releases with no alert
+        to release.
+
+        An upsert that genuinely re-sends the same temperature is not one of
+        those, because ``updated_at`` moves. That is deliberate. Knowing when a
+        source last wrote is how a dead automation becomes visible, and it is
+        worth one small write per message to keep.
+        """
+        payload = state.model_dump_json(indent=2)
+        if payload == self._last_written and self.path.exists():
+            self.skipped += 1
+            return
+
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+        handle = tempfile.NamedTemporaryFile(  # noqa: SIM115 - closed, then renamed
+            mode="w",
+            encoding="utf-8",
+            dir=self.path.parent,
+            prefix=self.path.name + ".",
+            suffix=".tmp",
+            delete=False,
+        )
+        temporary = Path(handle.name)
+        try:
+            with handle:
+                handle.write(payload)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary, self.path)
+        except OSError:
+            temporary.unlink(missing_ok=True)
+            raise
+
+        self._last_written = payload
+        self.writes += 1

readerboard/transport/__init__.py

@@ -0,0 +1 @@
+"""Ways of getting bytes to the sign."""

readerboard/transport/base.py

@@ -0,0 +1,53 @@
+"""What the rest of the service is allowed to assume about the link to the sign."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+class TransportError(RuntimeError):
+    """The bytes did not reach the sign.
+
+    This is the one failure the ``/v2`` API turns into a 503. Reporting it any
+    other way, in particular as a 200 with an error string in the body, makes a
+    dead serial link indistinguishable from success to anything that reads the
+    status code.
+    """
+
+
+@runtime_checkable
+class Transport(Protocol):
+    """A one-way byte pipe to the sign.
+
+    Implementations are synchronous and are expected to block. The controller
+    runs them on a worker thread, so nothing here needs to know about asyncio.
+    """
+
+    @property
+    def is_open(self) -> bool:
+        """Whether the link is currently up."""
+        ...
+
+    @property
+    def description(self) -> str:
+        """A short human readable name for the link, safe to put in a log line."""
+        ...
+
+    def ensure_open(self) -> None:
+        """Open the link if it is down.
+
+        Raises :class:`TransportError` if it cannot be opened, including when a
+        backoff window means it is not yet worth trying.
+        """
+        ...
+
+    def write(self, data: bytes) -> None:
+        """Send one complete transmission.
+
+        Raises :class:`TransportError` if it could not be sent.
+        """
+        ...
+
+    def close(self) -> None:
+        """Close the link. Closing an already closed link does nothing."""
+        ...

readerboard/transport/fake.py

@@ -0,0 +1,84 @@
+"""A transport that keeps the packets instead of sending them.
+
+This is what the tests assert against. It is not a mock of the serial link so
+much as a sign that writes everything down: tests read ``packets`` to see
+exactly what would have gone down the wire, which is the same thing the golden
+byte tests in ``tests/test_frames.py`` check the builders produce.
+
+It can also be told to fail, which is how the reconnect and error paths get
+exercised without unplugging anything.
+"""
+
+from __future__ import annotations
+
+from readerboard.transport.base import TransportError
+
+
+class FakeTransport:
+    """An in-memory transport that records every packet written to it."""
+
+    def __init__(self, *, fail_with: str | None = None, open_fails_with: str | None = None) -> None:
+        """Create a transport. Pass a reason to make writes or opens fail."""
+        self.packets: list[bytes] = []
+        self.fail_with = fail_with
+        self.open_fails_with = open_fails_with
+        self.open_count = 0
+        self.close_count = 0
+        self.write_count = 0
+        self._is_open = False
+
+    @property
+    def is_open(self) -> bool:
+        """Whether the link is currently up."""
+        return self._is_open
+
+    @property
+    def description(self) -> str:
+        """A short name for the link, safe to log."""
+        return "fake://"
+
+    @property
+    def last_error(self) -> str | None:
+        """Why the link last failed, or None."""
+        return self.open_fails_with or self.fail_with
+
+    def seconds_until_retry(self) -> float:
+        """How long until a reconnect would be attempted. The fake never waits."""
+        return 0.0
+
+    def ensure_open(self) -> None:
+        """Open the link if it is down."""
+        if self._is_open:
+            return
+        if self.open_fails_with is not None:
+            raise TransportError(self.open_fails_with)
+        self._is_open = True
+        self.open_count += 1
+
+    def write(self, data: bytes) -> None:
+        """Record one transmission, or fail if the fake was told to."""
+        self.ensure_open()
+        if self.fail_with is not None:
+            self._is_open = False
+            raise TransportError(self.fail_with)
+        self.write_count += 1
+        self.packets.append(data)
+
+    def close(self) -> None:
+        """Close the link."""
+        if self._is_open:
+            self.close_count += 1
+        self._is_open = False
+
+    # == helpers for tests ==================================================
+
+    @property
+    def last_packet(self) -> bytes:
+        """The most recent packet written, for the common single-write assertion."""
+        if not self.packets:
+            raise AssertionError("nothing has been written to this transport")
+        return self.packets[-1]
+
+    def clear(self) -> None:
+        """Forget every recorded packet, leaving the counters alone."""
+        self.packets.clear()

readerboard/transport/serial_link.py

@@ -0,0 +1,159 @@
+"""The real link to the sign, over a serial port or over the network.
+
+``serial.serial_for_url`` accepts both ``socket://192.168.2.51:4001`` for an
+Ethernet to RS-232 adapter and ``/dev/ttyUSB0`` for a cable plugged straight
+in, so one configuration value covers both ways of reaching the sign. It also
+accepts ``loop://``, which is what the tests use to exercise this module rather
+than a stand-in for it.
+
+The link is opened once and held, not opened and closed around every write. The
+old implementation did the latter, and paid for it with a two second sleep on
+every request and a race whenever two callers arrived together.
+
+Reconnection is deliberately passive. When the link is down, ``ensure_open``
+refuses to try again until a backoff window has passed, and ``write`` fails
+immediately rather than blocking a request behind a device that is not there.
+Something has to drive the retries; that is the controller's reconnect loop.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from collections.abc import Callable
+
+import serial
+
+from readerboard.transport.base import TransportError
+
+logger = logging.getLogger(__name__)
+
+
+class SerialTransport:
+    """A held-open pyserial link with capped exponential backoff on failure."""
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        baud_rate: int = 9600,
+        timeout: float = 10.0,
+        backoff_initial: float = 1.0,
+        backoff_max: float = 60.0,
+        monotonic: Callable[[], float] = time.monotonic,
+    ) -> None:
+        """Configure the link. Nothing is opened until :meth:`ensure_open`."""
+        self._url = url
+        self._baud_rate = baud_rate
+        self._timeout = timeout
+        self._backoff_initial = backoff_initial
+        self._backoff_max = backoff_max
+        self._monotonic = monotonic
+
+        self._port: serial.Serial | None = None
+        self._lock = threading.Lock()
+        self._failures = 0
+        self._retry_after = 0.0
+        self._last_error: str | None = None
+
+    @property
+    def is_open(self) -> bool:
+        """Whether the link is currently up."""
+        port = self._port
+        return port is not None and bool(port.is_open)
+
+    @property
+    def description(self) -> str:
+        """A short name for the link, safe to log."""
+        return self._url
+
+    @property
+    def last_error(self) -> str | None:
+        """Why the link last failed, or None if it has not failed since it opened."""
+        return self._last_error
+
+    def seconds_until_retry(self) -> float:
+        """How long until :meth:`ensure_open` will try again. Zero means now."""
+        if self.is_open:
+            return 0.0
+        return max(0.0, self._retry_after - self._monotonic())
+
+    def ensure_open(self) -> None:
+        """Open the link if it is down, honouring the backoff window."""
+        with self._lock:
+            self._ensure_open_locked()
+
+    def write(self, data: bytes) -> None:
+        """Send one complete transmission, opening the link first if needed."""
+        with self._lock:
+            self._ensure_open_locked()
+            port = self._port
+            assert port is not None  # _ensure_open_locked guarantees this
+            try:
+                port.write(data)
+                port.flush()
+            except (serial.SerialException, OSError) as err:
+                self._record_failure(err)
+                self._close_locked()
+                raise TransportError("write to %s failed: %s" % (self._url, err)) from err
+
+    def close(self) -> None:
+        """Close the link. Closing an already closed link does nothing."""
+        with self._lock:
+            self._close_locked()
+
+    # == internals ==========================================================
+
+    def _ensure_open_locked(self) -> None:
+        if self.is_open:
+            return
+
+        waiting = max(0.0, self._retry_after - self._monotonic())
+        if waiting > 0:
+            raise TransportError(
+                "link to %s is down (%s); next attempt in %.1fs"
+                % (self._url, self._last_error or "reason unknown", waiting)
+            )
+
+        try:
+            self._port = serial.serial_for_url(
+                self._url, baudrate=self._baud_rate, timeout=self._timeout
+            )
+        except (serial.SerialException, OSError, ValueError) as err:
+            self._record_failure(err)
+            self._port = None
+            raise TransportError("could not open %s: %s" % (self._url, err)) from err
+
+        if self._failures:
+            logger.info("link to %s is back after %d failed attempts", self._url, self._failures)
+        else:
+            logger.info("link to %s is open", self._url)
+        self._failures = 0
+        self._retry_after = 0.0
+        self._last_error = None
+
+    def _record_failure(self, err: Exception) -> None:
+        self._failures += 1
+        self._last_error = str(err)
+        delay = min(self._backoff_max, self._backoff_initial * (2 ** (self._failures - 1)))
+        self._retry_after = self._monotonic() + delay
+        logger.warning(
+            "link to %s failed (attempt %d): %s; backing off %.1fs",
+            self._url,
+            self._failures,
+            err,
+            delay,
+        )
+
+    def _close_locked(self) -> None:
+        port = self._port
+        self._port = None
+        if port is None:
+            return
+        try:
+            port.close()
+        except Exception:
+            # A port that will not close cleanly is still a port we are done
+            # with, and there is nothing useful for a caller to do about it.
+            logger.debug("ignoring error while closing %s", self._url, exc_info=True)