readerboard 0.1.1__py3-none-any.whl

readerboard/__init__.py

@@ -0,0 +1,10 @@
+"""An HTTP service that drives a BetaBrite Classic sign over the Alpha protocol.
+
+The version here and the one in pyproject.toml are checked against each other,
+and against the release tag, before anything is published. See
+.github/workflows/release.yml.
+"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.1"

readerboard/__main__.py

@@ -0,0 +1,57 @@
+"""Run the service.
+
+This is what the systemd unit invokes and what ``readerboard`` on the command
+line runs. It exists so the unit does not have to know a uvicorn invocation, and
+so the host and port come from the same configuration as everything else.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+import uvicorn
+
+from readerboard import __version__, logging_setup
+from readerboard.config import Settings
+
+
+def main() -> int:
+    """Start the HTTP server."""
+    parser = argparse.ArgumentParser(
+        prog="readerboard",
+        description=(
+            "Serve the readerboard API, which drives a BetaBrite Classic sign. "
+            "Settings come from the config file "
+            "(/etc/readerboard/config.toml unless READERBOARD_CONFIG_FILE says otherwise) "
+            "and from environment variables prefixed READERBOARD_."
+        ),
+    )
+    parser.add_argument("--version", action="version", version="readerboard %s" % __version__)
+    parser.add_argument("--host", help="override the configured listen address")
+    parser.add_argument("--port", type=int, help="override the configured port")
+    parser.add_argument(
+        "--print-config",
+        action="store_true",
+        help="show the settings in force, with the API key redacted, and exit",
+    )
+    args = parser.parse_args()
+
+    settings = Settings()
+    logging_setup.configure(settings.log_level, settings.log_file)
+
+    if args.print_config:
+        for key, value in sorted(settings.redacted().items()):
+            print("%-32s %s" % (key, value))
+        return 0
+
+    uvicorn.run(
+        "readerboard.api.app:app",
+        host=args.host or settings.host,
+        port=args.port or settings.port,
+        log_config=None,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

readerboard/api/__init__.py

@@ -0,0 +1 @@
+"""The HTTP surface."""

readerboard/api/app.py

@@ -0,0 +1,262 @@
+"""Building the application and wiring its parts together.
+
+Startup order matters. The transport is opened first, then the memory
+configuration is settled, then the slots and any alert are put back, and only
+then does anything start on a timer. Getting that wrong would mean writing
+messages to files the sign has not allocated.
+
+Nothing here fails to start because the sign is unreachable. A service that
+refused to boot with the sign unplugged would need someone to notice and restart
+it once the sign came back, which is precisely the situation it exists to
+survive.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import AsyncIterator, Awaitable, Callable
+
+from fastapi import FastAPI, Request, status
+from fastapi.responses import JSONResponse
+
+from readerboard import __version__, logging_setup
+from readerboard.api import routes_simple, routes_v2
+from readerboard.api.deps import get_alerts, get_clock, get_controller, get_registry
+from readerboard.api.models import HealthResponse, LinkHealth
+from readerboard.config import Settings
+from readerboard.protocol.frames import ProtocolError
+from readerboard.protocol.markup import MarkupError
+from readerboard.services import commands
+from readerboard.services.alerts import AlertService, AlertTooLong
+from readerboard.services.clock import ClockService
+from readerboard.services.registry import (
+    MessageRegistry,
+    MessageTooLong,
+    UnknownSlot,
+)
+from readerboard.sign.controller import SignController
+from readerboard.sign.layout import Layout, LayoutFull
+from readerboard.sign.state import StateStore
+from readerboard.transport.base import Transport, TransportError
+from readerboard.transport.serial_link import SerialTransport
+
+logger = logging.getLogger(__name__)
+
+DESCRIPTION = """
+Drives a BetaBrite Classic sign over the Alpha protocol, either through a serial
+cable or through an Ethernet to RS-232 adapter.
+
+Several sources can share the sign at once. Each registers a named **slot**, and
+the sign rotates through the registered slots by itself. An **alert** takes the
+whole display over until it is released, then the rotation resumes.
+
+Every write needs an `X-API-Key` header. `GET /health` does not.
+
+The `/Write` and `/Enumerations` paths are a smaller surface for clients that
+would rather not read status codes: every response there is a 200 with the
+outcome in the body.
+"""
+
+
+def build_transport(settings: Settings) -> Transport:
+    """Create the link to the sign described by the settings."""
+    return SerialTransport(
+        settings.serial_url,
+        baud_rate=settings.baud_rate,
+        timeout=settings.serial_timeout,
+        backoff_initial=settings.backoff_initial,
+        backoff_max=settings.backoff_max,
+    )
+
+
+async def _refresh_loop(app: FastAPI, interval: float) -> None:
+    """Push everything to the sign again, periodically.
+
+    See ``MessageRegistry.refresh`` for why blind re-pushing is the only thing
+    that repairs a sign power cycled behind a still-connected adapter.
+    """
+    registry: MessageRegistry = app.state.registry
+    alerts: AlertService = app.state.alerts
+
+    while True:
+        await asyncio.sleep(interval)
+        try:
+            await registry.refresh()
+            # The 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 stay blank until the alert's
+            # deadline, and an alert with no deadline would stay blank for good.
+            await alerts.reassert()
+        except TransportError as err:
+            logger.debug("periodic refresh skipped, sign unreachable: %s", err)
+        except Exception:
+            logger.exception("the periodic refresh failed")
+
+
+async def _sweep_loop(app: FastAPI, interval: float) -> None:
+    """Expire slots and alerts whose deadlines have passed."""
+    registry: MessageRegistry = app.state.registry
+    alerts: AlertService = app.state.alerts
+
+    while True:
+        await asyncio.sleep(interval)
+        try:
+            await alerts.sweep()
+            await registry.sweep()
+        except TransportError as err:
+            logger.warning("could not apply expiries: %s", err)
+        except Exception:
+            # A sweep that raises must not take the loop down with it, or
+            # nothing would ever expire again.
+            logger.exception("the expiry sweep failed")
+
+
+def create_app(settings: Settings | None = None, transport: Transport | None = None) -> FastAPI:
+    """Build the application.
+
+    ``transport`` is for tests, which supply a capturing one. In the service it
+    is left unset and built from the settings.
+    """
+    settings = settings or Settings()
+
+    @contextlib.asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        logging_setup.configure(settings.log_level, settings.log_file)
+        logger.info("readerboard %s starting; sign at %s", __version__, settings.serial_url)
+
+        link = transport if transport is not None else build_transport(settings)
+        controller = SignController(link, inter_packet_delay=settings.inter_packet_delay)
+        store = StateStore(settings.state_path)
+        state = store.load()
+        layout = Layout(settings.slot_count, settings.slot_capacity)
+        alerts = AlertService(controller, store, state)
+        registry = MessageRegistry(
+            controller, layout, store, state, alert_active=lambda: alerts.active is not None
+        )
+        # An alert holding the sign makes the registry hold back run sequence
+        # writes; releasing it is what lets them through.
+        alerts.set_release_hook(registry.flush_deferred)
+        clock = ClockService(
+            controller,
+            interval_seconds=settings.clock_sync_interval_seconds,
+            timezone=settings.timezone,
+        )
+
+        app.state.settings = settings
+        app.state.controller = controller
+        app.state.registry = registry
+        app.state.alerts = alerts
+        app.state.clock = clock
+
+        await controller.start()
+
+        # The sign may be unreachable, and that is not a reason to refuse to
+        # start. What is put back below happens again on the next reconnect.
+        try:
+            await registry.restore()
+            await alerts.restore()
+            if settings.clock_sync_enabled:
+                await clock.sync_quietly()
+        except TransportError as err:
+            logger.warning("could not restore the sign's contents yet: %s", err)
+
+        # Only now, so that opening the link above does not fire hooks that
+        # duplicate the work just done. Registering them earlier meant every
+        # startup set the clock twice and sent a run sequence for an empty
+        # registry before the pool had even been allocated.
+        if settings.clock_sync_enabled:
+            controller.on_reconnect(clock.sync_quietly)
+        # A link that just came back may be in front of a sign that was power
+        # cycled, so nothing the controller believes about its contents holds.
+        controller.on_reconnect(registry.refresh)
+
+        if settings.clock_sync_enabled:
+            await clock.start()
+        sweeper = asyncio.create_task(_sweep_loop(app, settings.registry_sweep_seconds))
+        refresher = asyncio.create_task(
+            _refresh_loop(app, settings.refresh_interval_seconds)
+        )
+
+        try:
+            yield
+        finally:
+            for task in (sweeper, refresher):
+                task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await task
+            if settings.clock_sync_enabled:
+                await clock.stop()
+            await controller.stop()
+            logger.info("readerboard stopped")
+
+    app = FastAPI(
+        title="readerboard",
+        description=DESCRIPTION,
+        version=__version__,
+        lifespan=lifespan,
+    )
+    app.state.settings = settings
+
+    _install_error_handlers(app)
+    app.include_router(routes_v2.router)
+    app.include_router(routes_simple.router)
+
+    @app.get("/health", tags=["Health"], summary="Is the service talking to the sign")
+    async def health(request: Request) -> HealthResponse:
+        """Report the state of the link, the slots, and the clock.
+
+        Deliberately unauthenticated, so that a monitor can watch the sign
+        without holding a key that could write to it.
+        """
+        controller = get_controller(request)
+        registry = get_registry(request)
+        alerts = get_alerts(request)
+        clock = get_clock(request)
+
+        used, total = registry.occupancy
+        return HealthResponse(
+            status="ok" if controller.is_connected else "degraded",
+            version=__version__,
+            link=LinkHealth(
+                url=controller.link_description,
+                connected=controller.is_connected,
+                last_write_at=controller.last_write_at,
+                last_error=controller.last_error,
+                writes=controller.writes,
+                suppressed_writes=controller.suppressed,
+            ),
+            slots_used=used,
+            slots_total=total,
+            sign_in_sync=registry.in_sync,
+            alert_active=alerts.active is not None,
+            clock_last_synced_at=clock.last_sync_at,
+        )
+
+    return app
+
+
+def _install_error_handlers(app: FastAPI) -> None:
+    """Turn the service's own exceptions into the status codes they mean."""
+
+    def handler(code: int) -> Callable[[Request, Exception], Awaitable[JSONResponse]]:
+        async def handle(_: Request, exc: Exception) -> JSONResponse:
+            if code >= 500:
+                logger.warning("request failed: %s", exc)
+            return JSONResponse(status_code=code, content={"detail": str(exc)})
+
+        return handle
+
+    app.add_exception_handler(MarkupError, handler(status.HTTP_400_BAD_REQUEST))
+    app.add_exception_handler(ProtocolError, handler(status.HTTP_400_BAD_REQUEST))
+    app.add_exception_handler(MessageTooLong, handler(status.HTTP_400_BAD_REQUEST))
+    app.add_exception_handler(AlertTooLong, handler(status.HTTP_400_BAD_REQUEST))
+    app.add_exception_handler(commands.UnknownCommand, handler(status.HTTP_400_BAD_REQUEST))
+    app.add_exception_handler(commands.BadParameter, handler(status.HTTP_400_BAD_REQUEST))
+    app.add_exception_handler(UnknownSlot, handler(status.HTTP_404_NOT_FOUND))
+    app.add_exception_handler(LayoutFull, handler(status.HTTP_409_CONFLICT))
+    app.add_exception_handler(TransportError, handler(status.HTTP_503_SERVICE_UNAVAILABLE))
+
+
+app = create_app()

readerboard/api/deps.py

@@ -0,0 +1,93 @@
+"""Getting at the running service's parts from inside a request, and the API key.
+
+Everything the service owns is built once during startup and hung on
+``app.state``. These accessors are what routes depend on, so a route never
+reaches into application state directly and tests can build the pieces
+themselves.
+"""
+
+from __future__ import annotations
+
+import hmac
+from typing import Annotated
+
+from fastapi import Depends, Header, HTTPException, Request, status
+
+from readerboard.config import Settings
+from readerboard.services.alerts import AlertService
+from readerboard.services.clock import ClockService
+from readerboard.services.registry import MessageRegistry
+from readerboard.sign.controller import SignController
+
+API_KEY_HEADER = "X-API-Key"
+
+
+def get_settings(request: Request) -> Settings:
+    """Return the service's configuration."""
+    settings: Settings = request.app.state.settings
+    return settings
+
+
+def get_controller(request: Request) -> SignController:
+    """Return the single writer that owns the sign."""
+    controller: SignController = request.app.state.controller
+    return controller
+
+
+def get_registry(request: Request) -> MessageRegistry:
+    """Return the registered messages."""
+    registry: MessageRegistry = request.app.state.registry
+    return registry
+
+
+def get_alerts(request: Request) -> AlertService:
+    """Return the alert service."""
+    alerts: AlertService = request.app.state.alerts
+    return alerts
+
+
+def get_clock(request: Request) -> ClockService:
+    """Return the clock sync."""
+    clock: ClockService = request.app.state.clock
+    return clock
+
+
+def require_api_key(
+    request: Request,
+    x_api_key: Annotated[str | None, Header(alias=API_KEY_HEADER)] = None,
+) -> None:
+    """Reject a write that does not carry the configured API key.
+
+    Compared with :func:`hmac.compare_digest` so that a wrong key cannot be
+    narrowed down by timing. The key itself is never logged or echoed, here or
+    anywhere else.
+
+    This is the one place the simple endpoints are allowed to break their
+    "always 200" rule. A caller without the key is not a caller whose request
+    failed; it is a caller the service will not talk to.
+    """
+    expected: str = request.app.state.settings.api_key.get_secret_value()
+
+    if not expected:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=(
+                "no API key is configured, so every write is refused. Set api_key in "
+                "the config file or READERBOARD_API_KEY in the environment."
+            ),
+        )
+
+    if x_api_key is None or not hmac.compare_digest(x_api_key, expected):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="a valid %s header is required" % API_KEY_HEADER,
+            headers={"WWW-Authenticate": API_KEY_HEADER},
+        )
+
+
+SettingsDep = Annotated[Settings, Depends(get_settings)]
+ControllerDep = Annotated[SignController, Depends(get_controller)]
+RegistryDep = Annotated[MessageRegistry, Depends(get_registry)]
+AlertsDep = Annotated[AlertService, Depends(get_alerts)]
+ClockDep = Annotated[ClockService, Depends(get_clock)]
+RequireApiKey = Depends(require_api_key)

readerboard/api/models.py

@@ -0,0 +1,266 @@
+"""Request and response shapes.
+
+The ``Simple*`` models are the shapes the ``/Write`` and ``/Enumerations``
+endpoints use, where every response is a 200 carrying the outcome in the body.
+The rest belong to ``/v2``, which reports through status codes instead.
+
+Every ``description`` here ends up in the OpenAPI page, so it is documentation
+in the same sense the README is, and it rots the same way.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from readerboard.protocol.tokens import COMMAND_BY_NAME, MODE_BY_NAME, POSITION_BY_NAME
+from readerboard.sign.state import AlertState, SlotState
+
+SlotKey = Annotated[
+    str,
+    Field(
+        min_length=1,
+        max_length=64,
+        pattern=r"^[A-Za-z0-9._-]+$",
+        description="the name of the slot, chosen by whoever owns it",
+    ),
+]
+
+
+def _normalise_mode(value: str) -> str:
+    upper = value.strip().upper()
+    if upper not in MODE_BY_NAME:
+        raise ValueError(
+            "unknown display mode %r; see GET /v2/enumerations/display-modes" % value
+        )
+    return upper
+
+
+def _normalise_position(value: str) -> str:
+    upper = value.strip().upper()
+    if upper not in POSITION_BY_NAME:
+        raise ValueError(
+            "unknown text position %r; see GET /v2/enumerations/text-positions" % value
+        )
+    return upper
+
+
+class MessageRequest(BaseModel):
+    """A message registered into a slot."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    message: str = Field(
+        max_length=4096,
+        description="the message, including markup tokens such as <red> and <degree>",
+    )
+    display_mode: str = Field(default="HOLD", description="how the sign presents the message")
+    position: str = Field(default="MIDDLE", description="where the text sits vertically")
+    order: int = Field(
+        default=0,
+        description="lower numbers play earlier in the rotation; ties break on the slot name",
+    )
+    ttl_seconds: float | None = Field(
+        default=None,
+        gt=0,
+        description="drop the message this many seconds from now; omit to keep it until replaced",
+    )
+    source: str | None = Field(
+        default=None,
+        max_length=128,
+        description="who registered this, recorded so the slot list is readable",
+    )
+
+    _check_mode = field_validator("display_mode")(_normalise_mode)
+    _check_position = field_validator("position")(_normalise_position)
+
+
+class SlotResponse(BaseModel):
+    """A registered slot."""
+
+    key: str
+    label: str = Field(description="the sign file this slot occupies, A through Z")
+    message: str
+    display_mode: str
+    position: str
+    order: int
+    source: str | None
+    expires_at: datetime | None
+    updated_at: datetime
+
+    @classmethod
+    def of(cls, slot: SlotState) -> SlotResponse:
+        """Render a stored slot as the API's view of it."""
+        return cls(
+            key=slot.key,
+            label=slot.label,
+            message=slot.message,
+            display_mode=slot.mode,
+            position=slot.position,
+            order=slot.order,
+            source=slot.source,
+            expires_at=slot.expires_at,
+            updated_at=slot.updated_at,
+        )
+
+
+class AlertRequest(BaseModel):
+    """A message that takes the whole sign over until it is released."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    message: str = Field(
+        max_length=4096,
+        description=(
+            "the alert text. The sign's priority file holds 125 bytes once markup has "
+            "been rendered, and cannot be resized"
+        ),
+    )
+    display_mode: str = Field(default="HOLD", description="how the sign presents the alert")
+    position: str = Field(default="MIDDLE", description="where the text sits vertically")
+    ttl_seconds: float | None = Field(
+        default=None,
+        gt=0,
+        description=(
+            "release the sign this many seconds from now. Omit and the alert holds the "
+            "sign until something releases it explicitly"
+        ),
+    )
+
+    _check_mode = field_validator("display_mode")(_normalise_mode)
+    _check_position = field_validator("position")(_normalise_position)
+
+
+class AlertResponse(BaseModel):
+    """The alert currently holding the sign."""
+
+    message: str
+    display_mode: str
+    position: str
+    started_at: datetime
+    expires_at: datetime | None
+
+    @classmethod
+    def of(cls, alert: AlertState) -> AlertResponse:
+        """Render a stored alert as the API's view of it."""
+        return cls(
+            message=alert.message,
+            display_mode=alert.mode,
+            position=alert.position,
+            started_at=alert.started_at,
+            expires_at=alert.expires_at,
+        )
+
+
+class ControlCommandRequest(BaseModel):
+    """A command aimed at the sign itself rather than at a message."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    command: str = Field(description="one of %s" % ", ".join(sorted(COMMAND_BY_NAME)))
+    parameter: str = Field(default="", description="the command's parameter, if it takes one")
+
+
+class ClockResponse(BaseModel):
+    """The result of setting the sign's clock."""
+
+    synced_at: datetime = Field(description="the time the sign was told, in its configured zone")
+
+
+class LinkHealth(BaseModel):
+    """The state of the link to the sign."""
+
+    url: str = Field(description="the configured pyserial URL")
+    connected: bool
+    last_write_at: datetime | None
+    last_error: str | None
+    writes: int
+    suppressed_writes: int = Field(
+        description="writes skipped because the sign already held those exact bytes"
+    )
+
+
+class HealthResponse(BaseModel):
+    """What the service knows about itself. Requires no API key."""
+
+    status: str = Field(description="'ok' when the sign is reachable, otherwise 'degraded'")
+    version: str
+    link: LinkHealth
+    slots_used: int
+    slots_total: int
+    sign_in_sync: bool = Field(
+        description=(
+            "false when a registered message has been accepted but not yet written to "
+            "the sign, which is what a write during an outage looks like"
+        )
+    )
+    alert_active: bool
+    clock_last_synced_at: datetime | None
+
+
+class TokenInfo(BaseModel):
+    """One entry in an enumeration."""
+
+    name: str
+    description: str
+
+
+# ===========================================================================
+# The simple API's shapes. Every response is a 200 with the outcome in the body.
+# ===========================================================================
+
+
+class SimpleMessageRequest(BaseModel):
+    """The body POST /Write/Message has always accepted."""
+
+    display_mode: str = Field(description="the display mode to use when showing the message")
+    message: str = Field(
+        description="the message, including markup tokens, to display on the sign"
+    )
+
+
+class SimpleCommandRequest(BaseModel):
+    """The body POST /Write/ControlCommand has always accepted."""
+
+    command: str = Field(description="the control command to send to the sign")
+    parameter: str = Field(default="", description="a parameter for the command")
+
+
+class SimpleResult(BaseModel):
+    """The body the old endpoints have always returned, whatever happened."""
+
+    result: str = Field(description="OK or ERROR")
+    result_message: str = Field(description="text description of the command result")
+
+    @classmethod
+    def ok(cls, message: str) -> SimpleResult:
+        """Build a success, in the old shape."""
+        return cls(result="OK", result_message=message)
+
+    @classmethod
+    def error(cls, message: str) -> SimpleResult:
+        """Build a failure, in the old shape and still with a 200 status."""
+        return cls(result="ERROR", result_message=message)
+
+
+class SimpleDisplayMode(BaseModel):
+    """One entry of GET /Enumerations/DisplayModes."""
+
+    display_mode: str
+    description: str
+
+
+class SimpleControlCommand(BaseModel):
+    """One entry of GET /Enumerations/ControlCommands."""
+
+    control_command: str
+    description: str
+
+
+class SimpleToken(BaseModel):
+    """One entry of GET /Enumerations/MarkupTokens."""
+
+    token_text: str
+    description: str