readerboard 0.2.0__tar.gz → 0.3.0__tar.gz

{readerboard-0.2.0/readerboard.egg-info → readerboard-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.2.0
-Summary: An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, scheduling and clock sync
+Version: 0.3.0
+Summary: An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, expiring messages and clock sync
 Author: mjaksn
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/mjaksn/readerboard
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Home Automation
 Classifier: Topic :: System :: Hardware
 Classifier: Typing :: Typed
@@ -72,8 +73,9 @@ until it is released, after which the rotation resumes.
 - **It survives restarts and outages.** The registered messages are persisted, and a
   write that arrives while the sign is unreachable is accepted and delivered when the
   link returns.
-- **Errors are errors.** A dead serial link is a 503, not an HTTP 200 with the word
-  ERROR in the body.
+- **Errors are errors.** A dead serial link is a 503 and a message the sign cannot
+  render is a 400, each with the reason in the body. Nothing here reports a failure
+  under a 200.
 
 ## Requirements
 
@@ -181,7 +183,7 @@ Swagger UI at `/docs`, the **Authorize** button puts it in once for the whole pa
 Register a message:
 
 ```
-curl -X PUT http://localhost:5001/v2/messages/temperature \
+curl -X PUT http://localhost:5001/messages/temperature \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<green>18.4<degree> <red><time>", "display_mode": "HOLD"}'
 ```
@@ -189,7 +191,7 @@ curl -X PUT http://localhost:5001/v2/messages/temperature \
 Register a second one and the sign rotates between them:
 
 ```
-curl -X PUT http://localhost:5001/v2/messages/doorbell \
+curl -X PUT http://localhost:5001/messages/doorbell \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<amber>Someone at the door", "ttl_seconds": 300}'
 ```
@@ -197,46 +199,25 @@ curl -X PUT http://localhost:5001/v2/messages/doorbell \
 Take the sign over for thirty seconds:
 
 ```
-curl -X POST http://localhost:5001/v2/alerts \
+curl -X POST http://localhost:5001/alerts \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<red><flash_on>SMOKE ALARM", "ttl_seconds": 30}'
 ```
 
-The full API, including every markup token and display mode, is at `/docs`.
+The full API is at `/docs`. Every markup token, display mode, text position and
+control command is listed by the `/enumerations` reads there, which answer at
+request time rather than being frozen into the description.
 
 ### Writing messages
 
 A message is plain text plus tokens written as `<name>`: `<green>18.4<degree>` is a
-colour change, a number, and a degree symbol. `GET /v2/enumerations/markup-tokens` lists
+colour change, a number, and a degree symbol. `GET /enumerations/markup-tokens` lists
 them all.
 
 Text is encoded against the sign's own character table rather than as UTF-8, so `café`
-displays correctly. A character the sign cannot render is rejected with a 400 on `/v2`,
-and replaced with `?` on the simpler endpoints described below.
-
-## A simpler set of endpoints
-
-Alongside `/v2` there is a smaller surface: `POST /Write/Message`,
-`POST /Write/ControlCommand`, and the `/Enumerations` reads.
-
-These follow one convention that `/v2` does not. **Every response is HTTP 200**, with the
-outcome in the body:
-
-```json
-{"result": "OK", "result_message": "Message displayed on sign"}
-```
-
-That suits a client which finds branching on status codes awkward, such as a Home
-Assistant `rest_command` or a shell one-liner in a cron job. The exceptions are the
-requests that never reach the endpoint at all: a missing or wrong API key is a 401, a
-service with no API key configured is a 503, and a body that is not the shape the endpoint
-declares gets FastAPI's own 422. A caller the service will not talk to, and a body it
-cannot read, are not the same as a request that failed.
-
-`POST /Write/Message` writes to one reserved slot, named `default`. It deliberately does
-not touch the sign's **priority** file, which by protocol suppresses every other message on
-the sign. Written to an ordinary slot it looks identical while it is the only message
-registered, and it shares the sign the moment anything else registers.
+displays correctly. A character the sign cannot render is rejected with a 400, as is an
+unknown token: a write is told what the sign would have made of it rather than being
+shown something it did not ask for.
 
 ## Configuration
 
@@ -321,35 +302,31 @@ claim. Read it before changing anything in `readerboard/protocol/`.
 `scripts/protocol_spike.py` settles the few questions the document cannot answer about
 this particular sign. It is destructive and refuses to run without `--confirm-erase`.
 
-`tools/signsim/` is a PySide6 stand-in for the sign, described above. Its own tests
-are collected by the `pytest` run here and need no Qt installed; the application does,
-and it is pinned separately so that nothing the service installs ever pulls Qt in.
+`tools/signsim/` is the sign simulator, a PySide6 stand-in for the sign, described
+above. `tools/apiclient/` is the client, a PySide6 application for calling the API by
+hand: every endpoint, responses shown as text rather than JSON, and a vocabulary it
+loads from the service rather than one compiled into it. The tests of both are
+collected by the `pytest` run here and need no Qt installed; the applications do, and
+each is pinned separately so that nothing the service installs ever pulls Qt in.
 
-`scripts/run_with_simulator.py` starts the service and the simulator together. Both
-editors have it as a launch configuration, "API and sign simulator" in
-`.vscode/launch.json` and "API and simulator" in `.idea/runConfigurations/`, along with
-configurations for each half on its own.
+`scripts/run_with_simulator.py` starts the service and the simulator together, and
+with `--with-client` the client as well, so the whole loop comes up from one command.
+Both editors carry it as a launch configuration under the same name, "readerboard and
+the sign simulator", in `.vscode/launch.json` and in `.idea/runConfigurations/`, beside
+configurations for running the pieces separately. Both carry the three way one as
+"readerboard, the sign simulator and the client" as well.
 
 ## Licence
 
 MIT. See [LICENSE](https://github.com/mjaksn/readerboard/blob/main/LICENSE).
 
-One caveat, recorded because it is easy to miss.
-`readerboard/protocol/constants.py` is vendored from
-[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), and that
-repository carries no license file. No license is not the same as a permissive one: it
-means no copying permission has been granted at all. That module is therefore the one
-part of this project whose provenance is not cleanly MIT.
-
-In practice it is a table of byte values dictated by the protocol rather than authored
-expression, and `docs/protocol-notes.md` now cites the protocol document directly, so the
-table can be regenerated from the primary source if that ever needs settling properly.
-
 ## Credits
 
-`readerboard/protocol/constants.py` came, with thanks, from
-[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), with some
-corrections noted in the file.
+The protocol is documented in the Alpha Sign Communications Protocol, form 9708-8061,
+published by Adaptive Micro Systems. Every byte value in
+`readerboard/protocol/constants.py` is transcribed from that document, and
+`tests/test_constant_values.py` pins each one against it with a citation per assertion.
 
-The protocol itself is documented in the Alpha Sign Communications Protocol, form
-9708-8061, published by Adaptive Micro Systems.
+An earlier version of this project took that table from
+[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), which is
+recorded here with thanks even though no code from it remains.

{readerboard-0.2.0 → readerboard-0.3.0}/README.md

@@ -30,8 +30,9 @@ until it is released, after which the rotation resumes.
 - **It survives restarts and outages.** The registered messages are persisted, and a
   write that arrives while the sign is unreachable is accepted and delivered when the
   link returns.
-- **Errors are errors.** A dead serial link is a 503, not an HTTP 200 with the word
-  ERROR in the body.
+- **Errors are errors.** A dead serial link is a 503 and a message the sign cannot
+  render is a 400, each with the reason in the body. Nothing here reports a failure
+  under a 200.
 
 ## Requirements
 
@@ -139,7 +140,7 @@ Swagger UI at `/docs`, the **Authorize** button puts it in once for the whole pa
 Register a message:
 
 ```
-curl -X PUT http://localhost:5001/v2/messages/temperature \
+curl -X PUT http://localhost:5001/messages/temperature \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<green>18.4<degree> <red><time>", "display_mode": "HOLD"}'
 ```
@@ -147,7 +148,7 @@ curl -X PUT http://localhost:5001/v2/messages/temperature \
 Register a second one and the sign rotates between them:
 
 ```
-curl -X PUT http://localhost:5001/v2/messages/doorbell \
+curl -X PUT http://localhost:5001/messages/doorbell \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<amber>Someone at the door", "ttl_seconds": 300}'
 ```
@@ -155,46 +156,25 @@ curl -X PUT http://localhost:5001/v2/messages/doorbell \
 Take the sign over for thirty seconds:
 
 ```
-curl -X POST http://localhost:5001/v2/alerts \
+curl -X POST http://localhost:5001/alerts \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<red><flash_on>SMOKE ALARM", "ttl_seconds": 30}'
 ```
 
-The full API, including every markup token and display mode, is at `/docs`.
+The full API is at `/docs`. Every markup token, display mode, text position and
+control command is listed by the `/enumerations` reads there, which answer at
+request time rather than being frozen into the description.
 
 ### Writing messages
 
 A message is plain text plus tokens written as `<name>`: `<green>18.4<degree>` is a
-colour change, a number, and a degree symbol. `GET /v2/enumerations/markup-tokens` lists
+colour change, a number, and a degree symbol. `GET /enumerations/markup-tokens` lists
 them all.
 
 Text is encoded against the sign's own character table rather than as UTF-8, so `café`
-displays correctly. A character the sign cannot render is rejected with a 400 on `/v2`,
-and replaced with `?` on the simpler endpoints described below.
-
-## A simpler set of endpoints
-
-Alongside `/v2` there is a smaller surface: `POST /Write/Message`,
-`POST /Write/ControlCommand`, and the `/Enumerations` reads.
-
-These follow one convention that `/v2` does not. **Every response is HTTP 200**, with the
-outcome in the body:
-
-```json
-{"result": "OK", "result_message": "Message displayed on sign"}
-```
-
-That suits a client which finds branching on status codes awkward, such as a Home
-Assistant `rest_command` or a shell one-liner in a cron job. The exceptions are the
-requests that never reach the endpoint at all: a missing or wrong API key is a 401, a
-service with no API key configured is a 503, and a body that is not the shape the endpoint
-declares gets FastAPI's own 422. A caller the service will not talk to, and a body it
-cannot read, are not the same as a request that failed.
-
-`POST /Write/Message` writes to one reserved slot, named `default`. It deliberately does
-not touch the sign's **priority** file, which by protocol suppresses every other message on
-the sign. Written to an ordinary slot it looks identical while it is the only message
-registered, and it shares the sign the moment anything else registers.
+displays correctly. A character the sign cannot render is rejected with a 400, as is an
+unknown token: a write is told what the sign would have made of it rather than being
+shown something it did not ask for.
 
 ## Configuration
 
@@ -279,35 +259,31 @@ claim. Read it before changing anything in `readerboard/protocol/`.
 `scripts/protocol_spike.py` settles the few questions the document cannot answer about
 this particular sign. It is destructive and refuses to run without `--confirm-erase`.
 
-`tools/signsim/` is a PySide6 stand-in for the sign, described above. Its own tests
-are collected by the `pytest` run here and need no Qt installed; the application does,
-and it is pinned separately so that nothing the service installs ever pulls Qt in.
+`tools/signsim/` is the sign simulator, a PySide6 stand-in for the sign, described
+above. `tools/apiclient/` is the client, a PySide6 application for calling the API by
+hand: every endpoint, responses shown as text rather than JSON, and a vocabulary it
+loads from the service rather than one compiled into it. The tests of both are
+collected by the `pytest` run here and need no Qt installed; the applications do, and
+each is pinned separately so that nothing the service installs ever pulls Qt in.
 
-`scripts/run_with_simulator.py` starts the service and the simulator together. Both
-editors have it as a launch configuration, "API and sign simulator" in
-`.vscode/launch.json` and "API and simulator" in `.idea/runConfigurations/`, along with
-configurations for each half on its own.
+`scripts/run_with_simulator.py` starts the service and the simulator together, and
+with `--with-client` the client as well, so the whole loop comes up from one command.
+Both editors carry it as a launch configuration under the same name, "readerboard and
+the sign simulator", in `.vscode/launch.json` and in `.idea/runConfigurations/`, beside
+configurations for running the pieces separately. Both carry the three way one as
+"readerboard, the sign simulator and the client" as well.
 
 ## Licence
 
 MIT. See [LICENSE](https://github.com/mjaksn/readerboard/blob/main/LICENSE).
 
-One caveat, recorded because it is easy to miss.
-`readerboard/protocol/constants.py` is vendored from
-[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), and that
-repository carries no license file. No license is not the same as a permissive one: it
-means no copying permission has been granted at all. That module is therefore the one
-part of this project whose provenance is not cleanly MIT.
-
-In practice it is a table of byte values dictated by the protocol rather than authored
-expression, and `docs/protocol-notes.md` now cites the protocol document directly, so the
-table can be regenerated from the primary source if that ever needs settling properly.
-
 ## Credits
 
-`readerboard/protocol/constants.py` came, with thanks, from
-[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), with some
-corrections noted in the file.
+The protocol is documented in the Alpha Sign Communications Protocol, form 9708-8061,
+published by Adaptive Micro Systems. Every byte value in
+`readerboard/protocol/constants.py` is transcribed from that document, and
+`tests/test_constant_values.py` pins each one against it with a citation per assertion.
 
-The protocol itself is documented in the Alpha Sign Communications Protocol, form
-9708-8061, published by Adaptive Micro Systems.
+An earlier version of this project took that table from
+[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), which is
+recorded here with thanks even though no code from it remains.

{readerboard-0.2.0 → readerboard-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "readerboard"
-version = "0.2.0"
-description = "An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, scheduling and clock sync"
+version = "0.3.0"
+description = "An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, expiring messages and clock sync"
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"
@@ -24,6 +24,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Home Automation",
     "Topic :: System :: Hardware",
     "Typing :: Typed",
@@ -36,7 +37,8 @@ classifiers = [
 #
 # The ceilings sit at the next major for the settled packages, and at the next
 # minor for the two still on 0.x, where a minor bump is where a breaking change
-# is allowed to live.
+# is allowed to live. tzdata is the exception and takes a floor only: it is a
+# calendar-versioned data package with no API to break.
 dependencies = [
     "fastapi>=0.141.1,<0.142",
     # Plain uvicorn, not the "standard" extra. That extra exists to make a busy
@@ -69,8 +71,9 @@ dev = [
 ]
 
 [project.scripts]
-# The whole command line. `python -m readerboard` runs the same thing out of a
-# checkout, which is what the systemd unit and the editor launch config use.
+# The whole command line, and what the systemd unit and the container image run.
+# `python -m readerboard` runs the same thing out of a checkout, which is what
+# the editor launch configurations use.
 readerboard = "readerboard.__main__:main"
 
 [project.urls]
@@ -80,8 +83,8 @@ Issues = "https://github.com/mjaksn/readerboard/issues"
 Changelog = "https://github.com/mjaksn/readerboard/blob/main/CHANGELOG.md"
 
 [tool.setuptools]
-# Named explicitly rather than auto-discovered: the flat layout puts `tests`
-# beside the package and it has an __init__.py, so discovery would ship it.
+# Named explicitly rather than auto-discovered: `tests`, `tools` and `scripts`
+# all sit beside the package in a flat layout, so what ships is decided here.
 packages = [
     "readerboard",
     "readerboard.api",
@@ -97,10 +100,12 @@ packages = [
 readerboard = ["py.typed"]
 
 [tool.pytest.ini_options]
-# The simulator under tools/ is collected too. Its tests import only the pure
-# half of it, never PySide6, so they run in CI where Qt is not installed, and
-# the round trip they check is against the frame builders in this package.
-testpaths = ["tests", "tools/signsim/tests"]
+# The two tools under tools/ are collected too. Their tests import only the
+# pure half of each, never PySide6, so they run in CI where Qt is not installed.
+# The simulator's round trip is checked against the frame builders in this
+# package; the client's catalogue is checked against docs/openapi.json, so a
+# route added here fails that tool's tests in the same commit.
+testpaths = ["tests", "tools/signsim/tests", "tools/apiclient/tests"]
 addopts = "-q --strict-markers --strict-config"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
@@ -135,20 +140,18 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
-# The vendored constants table is a wall of assignments with trailing comments,
-# and rewriting it into docstring-bearing prose would only obscure its origin.
-"readerboard/protocol/constants.py" = ["E501", "RUF001", "RUF003"]
 # A test's name is its documentation, and a docstring repeating it would be
-# worse than none. Tests that need explaining have one anyway. The simulator's
+# worse than none. Tests that need explaining have one anyway. The two tools'
 # tests are named separately because this glob is anchored at the project root
 # and does not reach into tools/.
 "tests/*" = ["D100", "D101", "D102", "D103", "D105", "D107"]
 "tools/signsim/tests/*" = ["D100", "D101", "D102", "D103", "D105", "D107"]
+"tools/apiclient/tests/*" = ["D100", "D101", "D102", "D103", "D105", "D107"]
 
 [tool.ruff.lint.isort]
-# The simulator is not under the project root, so import sorting would put it
-# in the third party block and then complain that it is in the wrong one.
-known-first-party = ["readerboard", "signsim"]
+# The two tools are not under the project root, so import sorting would put
+# them in the third party block and then complain they are in the wrong one.
+known-first-party = ["readerboard", "signsim", "apiclient"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "pep257"
@@ -166,7 +169,7 @@ module = ["serial", "serial.*"]
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
-# The vendored constants module is a flat table of byte literals; annotating
-# every one of them would add nothing a reader does not already see.
+# The constants module is a flat table of byte literals; annotating every one of
+# them would add nothing a reader does not already see.
 module = "readerboard.protocol.constants"
 disallow_untyped_defs = false

{readerboard-0.2.0 → readerboard-0.3.0}/readerboard/__init__.py

@@ -7,4 +7,4 @@ and against the release tag, before anything is published. See
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{readerboard-0.2.0 → readerboard-0.3.0}/readerboard/__main__.py

@@ -11,14 +11,14 @@ import argparse
 
 import uvicorn
 
-from readerboard import __version__, logging_setup
+from readerboard import __version__, logging_setup, names
 from readerboard.config import Settings
 
 
 def main() -> int:
     """Start the HTTP server."""
     parser = argparse.ArgumentParser(
-        prog="readerboard",
+        prog=names.IDENTIFIER,
         description=(
             "Serve the readerboard API, which drives a BetaBrite Classic sign. "
             "Settings come from the config file "
@@ -26,7 +26,7 @@ def main() -> int:
             "and from environment variables prefixed READERBOARD_."
         ),
     )
-    parser.add_argument("--version", action="version", version="readerboard %s" % __version__)
+    parser.add_argument("--version", action="version", version="%s %s" % (names.IDENTIFIER, __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(

{readerboard-0.2.0 → readerboard-0.3.0}/readerboard/api/app.py

@@ -18,26 +18,19 @@ import contextlib
 import logging
 from collections.abc import AsyncIterator, Awaitable, Callable
 
-from fastapi import FastAPI, Request, status
+from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
 
-from readerboard import __version__, logging_setup
-from readerboard.api import routes_simple, routes_v2
+from readerboard import __version__, logging_setup, names
+from readerboard.api import errors, routes
 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.alerts import AlertService
 from readerboard.services.clock import ClockService
-from readerboard.services.registry import (
-    MessageRegistry,
-    MessageTooLong,
-    UnknownSlot,
-)
+from readerboard.services.registry import MessageRegistry
 from readerboard.sign.controller import SignController
-from readerboard.sign.layout import Layout, LayoutFull
+from readerboard.sign.layout import Layout
 from readerboard.sign.state import StateStore
 from readerboard.transport.base import Transport, TransportError
 from readerboard.transport.serial_link import SerialTransport
@@ -56,11 +49,14 @@ Every write needs an `X-API-Key` header. Reads and `GET /health` do not. On this
 page, put the key in once with the **Authorize** button and every write below
 carries it.
 
-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, unless the request never reaches the route at all. A missing
-or wrong `X-API-Key` is a 401, a service with no API key configured is a 503, and
-a body that is not the shape the endpoint declares is a 422.
+A failure is reported by the status code, with the reason in a `detail` field:
+400 for a command the sign does not have, a parameter it will not accept, a
+message too long for its slot or markup the sign cannot render, 401 for a
+missing or wrong `X-API-Key`, 404 for a slot nothing has registered, 409 when
+every message slot is already in use, 503 when the sign is unreachable or no
+API key is configured at all, 500 for something the service has no code for,
+and 422 for a body that is not the shape the endpoint declares, which includes
+a display mode or a text position the sign does not have.
 """
 
 
@@ -196,7 +192,7 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
             logger.info("readerboard stopped")
 
     app = FastAPI(
-        title="readerboard",
+        title=names.DISPLAY_NAME,
         description=DESCRIPTION,
         version=__version__,
         lifespan=lifespan,
@@ -208,8 +204,7 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
     app.state.settings = settings
 
     _install_error_handlers(app)
-    app.include_router(routes_v2.router)
-    app.include_router(routes_simple.router)
+    app.include_router(routes.router)
 
     @app.get("/health", tags=["Health"], summary="Is the service talking to the sign")
     async def health(request: Request) -> HealthResponse:
@@ -246,7 +241,11 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
 
 
 def _install_error_handlers(app: FastAPI) -> None:
-    """Turn the service's own exceptions into the status codes they mean."""
+    """Turn the service's own exceptions into the status codes they mean.
+
+    Registered by walking the table in readerboard.api.errors, which is the one
+    place that decides what any of them means.
+    """
 
     def handler(code: int) -> Callable[[Request, Exception], Awaitable[JSONResponse]]:
         async def handle(_: Request, exc: Exception) -> JSONResponse:
@@ -256,15 +255,8 @@ def _install_error_handlers(app: FastAPI) -> None:
 
         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))
+    for kind, code in errors.STATUS_FOR_ERROR:
+        app.add_exception_handler(kind, handler(code))
 
 
 app = create_app()

{readerboard-0.2.0 → readerboard-0.3.0}/readerboard/api/deps.py

@@ -14,7 +14,6 @@ from typing import Annotated
 from fastapi import Depends, HTTPException, Request, Security, status
 from fastapi.security import APIKeyHeader
 
-from readerboard.config import Settings
 from readerboard.services.alerts import AlertService
 from readerboard.services.clock import ClockService
 from readerboard.services.registry import MessageRegistry
@@ -30,9 +29,8 @@ API_KEY_HEADER = "X-API-Key"
 # `auto_error=False` is load bearing. Left at its default the scheme rejects a
 # missing key itself, with its own wording and with no way to tell "you sent no
 # key" apart from "this service has no key configured at all". Those are
-# different answers, 401 and 503, and the simple endpoints document the
-# difference, so the checking stays in `require_api_key` below and this declares
-# the scheme and nothing else.
+# different answers, 401 and 503, and both are documented, so the checking stays
+# in `require_api_key` below and this declares the scheme and nothing else.
 # The scheme name becomes a key under `components.securitySchemes`, and the
 # OpenAPI specification requires those to match `^[a-zA-Z0-9\.\-_]+$` (section
 # 4.8.7.1). So it cannot be the prettier "API key", however much better that
@@ -51,12 +49,6 @@ api_key_scheme = APIKeyHeader(
 )
 
 
-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
@@ -91,9 +83,9 @@ def require_api_key(
     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.
+    A 401 rather than anything a route decides. A caller without the key is not
+    a caller whose request failed; it is a caller the service will not talk to,
+    and it never reaches a route to be answered by one.
     """
     expected: str = request.app.state.settings.api_key.get_secret_value()
 
@@ -114,7 +106,6 @@ def require_api_key(
         )
 
 
-SettingsDep = Annotated[Settings, Depends(get_settings)]
 ControllerDep = Annotated[SignController, Depends(get_controller)]
 RegistryDep = Annotated[MessageRegistry, Depends(get_registry)]
 AlertsDep = Annotated[AlertService, Depends(get_alerts)]

readerboard-0.3.0/readerboard/api/errors.py

@@ -0,0 +1,34 @@
+"""What each of the service's own exceptions means as a status code.
+
+One table, and one reader of it. Routes let these propagate; an exception
+handler registered from this table turns each into a status code with FastAPI's
+usual ``detail`` body. An exception this table does not name reaches nobody's
+handler and is a 500, which is the honest answer for a failure the service never
+planned for: it cannot say whose fault it was.
+
+Add an exception here and the handler for it is registered with it.
+"""
+
+from __future__ import annotations
+
+from fastapi import status
+
+from readerboard.protocol.frames import ProtocolError
+from readerboard.protocol.markup import MarkupError
+from readerboard.services import commands
+from readerboard.services.alerts import AlertTooLong
+from readerboard.services.registry import MessageTooLong, UnknownSlot
+from readerboard.sign.layout import LayoutFull
+from readerboard.transport.base import TransportError
+
+STATUS_FOR_ERROR: tuple[tuple[type[Exception], int], ...] = (
+    (MarkupError, status.HTTP_400_BAD_REQUEST),
+    (ProtocolError, status.HTTP_400_BAD_REQUEST),
+    (MessageTooLong, status.HTTP_400_BAD_REQUEST),
+    (AlertTooLong, status.HTTP_400_BAD_REQUEST),
+    (commands.UnknownCommand, status.HTTP_400_BAD_REQUEST),
+    (commands.BadParameter, status.HTTP_400_BAD_REQUEST),
+    (UnknownSlot, status.HTTP_404_NOT_FOUND),
+    (LayoutFull, status.HTTP_409_CONFLICT),
+    (TransportError, status.HTTP_503_SERVICE_UNAVAILABLE),
+)