readerboard 0.1.1__py3-none-any.whl

readerboard/services/alerts.py

@@ -0,0 +1,183 @@
+"""Taking the whole sign over, and giving it back.
+
+An alert is written to the sign's priority file, which by protocol suppresses
+every other file until it is released. Releasing means writing an empty priority
+file, at which point the sign resumes its run sequence by itself. Nothing has to
+rebuild the rotation afterwards.
+
+The release deadline is persisted. A service that restarted during an alert and
+forgot about it would leave the sign stuck showing that alert forever, with the
+rotation invisible behind it and no record of why.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime, timedelta
+
+from readerboard.protocol import constants as c
+from readerboard.protocol.markup import render
+from readerboard.protocol.tokens import MODE_BY_NAME, POSITION_BY_NAME
+from readerboard.sign.controller import SignController
+from readerboard.sign.state import AlertState, ServiceState, StateStore
+
+logger = logging.getLogger(__name__)
+
+
+class AlertTooLong(ValueError):
+    """The alert does not fit the sign's fixed size priority file."""
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class AlertService:
+    """Owns the priority file and the deadline for giving it back."""
+
+    def __init__(
+        self,
+        controller: SignController,
+        store: StateStore,
+        state: ServiceState,
+        *,
+        now: Callable[[], datetime] = _utcnow,
+        on_release: Callable[[], Awaitable[object]] | None = None,
+    ) -> None:
+        """Wire the alert service to the sign and to its restored state.
+
+        ``on_release`` runs after the sign has been handed back. The registry
+        uses it to apply a run sequence it held back while the alert was up; see
+        ``MessageRegistry._apply_run_sequence`` for why it holds one back.
+        """
+        self._controller = controller
+        self._store = store
+        self._state = state
+        self._now = now
+        self._on_release = on_release
+        self._lock = asyncio.Lock()
+
+    def set_release_hook(self, hook: Callable[[], Awaitable[object]]) -> None:
+        """Attach something to run after the sign is handed back."""
+        self._on_release = hook
+
+    @property
+    def active(self) -> AlertState | None:
+        """The alert currently holding the sign, if any."""
+        return self._state.alert
+
+    async def restore(self) -> None:
+        """Re-establish or clean up an alert that was running before a restart."""
+        alert = self._state.alert
+        if alert is None:
+            # The sign may still be holding an alert from before an unclean
+            # stop, and there is no way to ask it. Releasing costs one small
+            # write and guarantees the rotation is visible.
+            await self._controller.clear_priority()
+            return
+
+        if alert.expires_at is not None and alert.expires_at <= self._now():
+            logger.info("an alert was active before the restart but has since expired")
+            await self.release()
+            return
+
+        logger.info("restoring the alert that was active before the restart")
+        await self._write(alert)
+
+    async def reassert(self) -> bool:
+        """Write the active alert to the sign again, if there is one.
+
+        The registry's periodic refresh exists because the sign can be power
+        cycled behind a still-connected adapter, leaving it blank with nothing
+        to notice. That refresh puts the slots back, but an alert lives in the
+        priority file, which the registry does not touch. Without this, a sign
+        power cycled mid-alert would sit blank until the alert's deadline
+        passed, and an alert with no deadline would sit blank indefinitely.
+
+        Returns whether there was an alert to re-assert.
+        """
+        async with self._lock:
+            alert = self._state.alert
+            if alert is None:
+                return False
+            # Forced, because what is in doubt here is precisely whether the
+            # sign still holds what the controller believes it does. Left to
+            # suppression this would write nothing at all.
+            await self._write(alert, force=True)
+
+        return True
+
+    async def raise_alert(
+        self,
+        message: str,
+        *,
+        mode: str,
+        position: str,
+        ttl_seconds: float | None = None,
+        strict: bool = True,
+    ) -> AlertState:
+        """Take the sign over with an alert."""
+        body = render(message, strict=strict)
+        if len(body) > c.PRIORITY_FILE_CAPACITY:
+            raise AlertTooLong(
+                "the alert renders to %d bytes but the sign's priority file holds %d "
+                "and cannot be resized" % (len(body), c.PRIORITY_FILE_CAPACITY)
+            )
+
+        now = self._now()
+        alert = AlertState(
+            message=message,
+            mode=mode,
+            position=position,
+            started_at=now,
+            expires_at=now + timedelta(seconds=ttl_seconds) if ttl_seconds else None,
+        )
+
+        async with self._lock:
+            await self._write(alert)
+            self._state.alert = alert
+            self._store.save(self._state)
+
+        logger.info(
+            "alert raised%s",
+            " until %s" % alert.expires_at.isoformat() if alert.expires_at else " with no deadline",
+        )
+        return alert
+
+    async def release(self) -> bool:
+        """Give the sign back. Returns whether an alert was actually holding it."""
+        async with self._lock:
+            was_active = self._state.alert is not None
+            await self._controller.clear_priority()
+            self._state.alert = None
+            self._store.save(self._state)
+
+        if was_active:
+            logger.info("alert released, rotation resumes")
+
+        if self._on_release is not None:
+            await self._on_release()
+
+        return was_active
+
+    async def sweep(self) -> bool:
+        """Release the alert if its deadline has passed. Returns whether it did."""
+        alert = self._state.alert
+        if alert is None or alert.expires_at is None:
+            return False
+        if alert.expires_at > self._now():
+            return False
+
+        logger.info("alert reached its deadline")
+        await self.release()
+        return True
+
+    async def _write(self, alert: AlertState, *, force: bool = False) -> None:
+        await self._controller.write_priority(
+            render(alert.message, strict=False),
+            mode=MODE_BY_NAME[alert.mode].value,
+            position=POSITION_BY_NAME[alert.position].value,
+            force=force,
+        )

readerboard/services/clock.py

@@ -0,0 +1,111 @@
+"""Keeping the sign's clock right.
+
+The sign has its own battery-backed clock and it drifts. It also loses the time
+when it loses power for long enough, and a sign showing ``<time>`` with a wrong
+clock is worse than one showing nothing, because it looks fine.
+
+So the clock is set on startup, once an hour, and on every reconnect. The
+reconnect trigger is the one that earns its keep: a scheduled sync alone leaves
+a sign that came back at ten past the hour wrong until the next sync, and the
+link returning is the closest signal available to "the sign may just have been
+power cycled".
+
+``now`` is injected rather than mocked, so the tests can be about what gets sent
+at a given time rather than about patching the clock out from under the code.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import Callable
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+from readerboard.protocol import frames
+from readerboard.sign.controller import SignController
+from readerboard.transport.base import TransportError
+
+logger = logging.getLogger(__name__)
+
+
+def _local_now() -> datetime:
+    return datetime.now().astimezone()
+
+
+def sign_day_of_week(moment: datetime) -> int:
+    """Convert a datetime to the sign's day numbering, 1 for Sunday to 7 for Saturday."""
+    # isoweekday is 1 for Monday through 7 for Sunday, so this rotates Sunday
+    # to the front.
+    return (moment.isoweekday() % 7) + 1
+
+
+class ClockService:
+    """Sets the sign's clock on a schedule and whenever the link comes back."""
+
+    def __init__(
+        self,
+        controller: SignController,
+        *,
+        interval_seconds: float = 3600.0,
+        timezone: str | None = None,
+        now: Callable[[], datetime] = _local_now,
+    ) -> None:
+        """Configure the sync. Nothing is sent until :meth:`sync` or :meth:`start`."""
+        self._controller = controller
+        self._interval = interval_seconds
+        self._zone = ZoneInfo(timezone) if timezone else None
+        self._now = now
+        self._task: asyncio.Task[None] | None = None
+        self._stopping = asyncio.Event()
+
+        self.last_sync_at: datetime | None = None
+
+    def current_time(self) -> datetime:
+        """Return the time the sign should be told, in the configured zone."""
+        moment = self._now()
+        return moment.astimezone(self._zone) if self._zone else moment
+
+    async def sync(self) -> datetime:
+        """Set the sign's clock and day of week. Returns the time it was told."""
+        moment = self.current_time()
+        await self._controller.send_special(frames.set_time(moment.hour, moment.minute))
+        await self._controller.send_special(frames.set_day_of_week(sign_day_of_week(moment)))
+        self.last_sync_at = moment
+        logger.info("sign clock set to %s", moment.strftime("%Y-%m-%d %H:%M %Z").strip())
+        return moment
+
+    async def start(self) -> None:
+        """Begin syncing on a schedule."""
+        self._task = asyncio.create_task(self._loop())
+
+    async def stop(self) -> None:
+        """Stop syncing."""
+        self._stopping.set()
+        task = self._task
+        self._task = None
+        if task is not None:
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+
+    async def sync_quietly(self) -> None:
+        """Sync, logging rather than raising if the sign is unreachable.
+
+        This is what the reconnect hook and the periodic loop use. A clock sync
+        that fails is worth a log line, not a crashed background task.
+        """
+        try:
+            await self.sync()
+        except (TransportError, OSError) as err:
+            logger.warning("could not set the sign's clock: %s", err)
+
+    async def _loop(self) -> None:
+        while not self._stopping.is_set():
+            try:
+                await asyncio.wait_for(self._stopping.wait(), timeout=self._interval)
+            except TimeoutError:
+                await self.sync_quietly()
+            else:
+                return

readerboard/services/commands.py

@@ -0,0 +1,83 @@
+"""Turning a named control command and its parameter into a payload.
+
+These are the commands that act on the sign itself rather than on a message:
+setting its clock, its day of week, and how it renders the time.
+
+The set is deliberately closed. Anything reaching the sign from here is one of
+these three, none of which touches the memory configuration or the run time
+table, so a caller cannot use this route to disturb the file layout the service
+believes it has.
+
+Note the day of week numbering, which is easy to get wrong: the protocol defines
+1 for Sunday through 7 for Saturday, not 0 through 6.
+"""
+
+from __future__ import annotations
+
+from readerboard.protocol import frames
+from readerboard.protocol.tokens import COMMAND_BY_NAME
+
+
+class UnknownCommand(ValueError):
+    """No control command by that name exists."""
+
+
+class BadParameter(ValueError):
+    """The parameter is not valid for the command it was given to."""
+
+
+def build(name: str, parameter: str) -> bytes:
+    """Build the payload for a named control command.
+
+    ``name`` is matched case insensitively.
+    """
+    command = name.strip().upper()
+    if command not in COMMAND_BY_NAME:
+        raise UnknownCommand(
+            "unrecognized control command %r; the available commands are %s"
+            % (name, ", ".join(sorted(COMMAND_BY_NAME)))
+        )
+
+    if command == "SET_TIME":
+        return _set_time(parameter)
+    if command == "SET_DAY_OF_WEEK":
+        return _set_day_of_week(parameter)
+    if command == "SET_TIME_FORMAT":
+        return _set_time_format(parameter)
+
+    raise UnknownCommand("control command %r has no handler" % command)  # pragma: no cover
+
+
+def _set_time(parameter: str) -> bytes:
+    value = parameter.strip()
+    if len(value) != 4 or not value.isdigit():
+        raise BadParameter(
+            "SET_TIME takes the time as four digits, HHMM on a 24 hour clock, got %r"
+            % parameter
+        )
+    try:
+        return frames.set_time(int(value[:2]), int(value[2:]))
+    except frames.ProtocolError as err:
+        raise BadParameter(str(err)) from err
+
+
+def _set_day_of_week(parameter: str) -> bytes:
+    value = parameter.strip()
+    if len(value) != 1 or not value.isdigit():
+        raise BadParameter(
+            "SET_DAY_OF_WEEK takes a single digit, 1 for Sunday through 7 for Saturday, "
+            "got %r" % parameter
+        )
+    try:
+        return frames.set_day_of_week(int(value))
+    except frames.ProtocolError as err:
+        raise BadParameter(str(err)) from err
+
+
+def _set_time_format(parameter: str) -> bytes:
+    value = parameter.strip().upper()
+    if value not in {"S", "M"}:
+        raise BadParameter(
+            "SET_TIME_FORMAT takes 'S' for standard or 'M' for military, got %r" % parameter
+        )
+    return frames.set_time_format(military=value == "M")