readerboard 0.7.0__tar.gz → 0.7.1__tar.gz

{readerboard-0.7.0/readerboard.egg-info → readerboard-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.7.0
+Version: 0.7.1
 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
@@ -34,7 +34,7 @@ Requires-Dist: pydantic-settings<3,>=2.15.0
 Requires-Dist: pyserial<4,>=3.5
 Requires-Dist: tzdata>=2026.3; sys_platform == "win32"
 Provides-Extra: dev
-Requires-Dist: pytest<10,>=9.1.1; extra == "dev"
+Requires-Dist: pytest<9.2,>=9.1.1; extra == "dev"
 Requires-Dist: pytest-asyncio<2,>=1.4.0; extra == "dev"
 Requires-Dist: httpx2<3,>=2.10.0; extra == "dev"
 Requires-Dist: anyio<4.15,>=4.14.2; extra == "dev"
@@ -184,6 +184,22 @@ sign shows nothing or shows rubbish, and the adapter answers on port 23, it is
 probably negotiating telnet rather than passing bytes through, and `rfc2217://`
 is the form that speaks that.
 
+An adapter that drops off the network says nothing as it goes. The service asks
+the operating system to give a network link up about a minute after the adapter
+stops answering: on Linux, a minute after the first write it did not
+acknowledge, or, if nothing was written, about a minute after it last answered,
+found by keepalive probes. A platform that does not take one of these options
+keeps its own default for it, which can be much longer. The service itself only
+finds out at its first read or write after the link has gone, and `GET /health`
+shows `"connected": false` from then on. A sign with a variable updated every
+minute is written to that often. One left alone is written to at the refresh,
+every `refresh_interval_seconds`, which is 15 minutes by default, and a refresh
+that lands before the link has gone is buffered like any other write, so on a
+quiet sign `link.connected` can stay true for a refresh interval and a minute
+after the adapter has gone. It is still worth a monitor watching, and needs no
+key, but a ping of the adapter answers within a minute however quiet the sign
+is, and is the better alarm.
+
 ### The API key, and config.local.toml
 
 The key is not an argument. A launch configuration is a tracked file and a

{readerboard-0.7.0 → readerboard-0.7.1}/README.md

@@ -140,6 +140,22 @@ sign shows nothing or shows rubbish, and the adapter answers on port 23, it is
 probably negotiating telnet rather than passing bytes through, and `rfc2217://`
 is the form that speaks that.
 
+An adapter that drops off the network says nothing as it goes. The service asks
+the operating system to give a network link up about a minute after the adapter
+stops answering: on Linux, a minute after the first write it did not
+acknowledge, or, if nothing was written, about a minute after it last answered,
+found by keepalive probes. A platform that does not take one of these options
+keeps its own default for it, which can be much longer. The service itself only
+finds out at its first read or write after the link has gone, and `GET /health`
+shows `"connected": false` from then on. A sign with a variable updated every
+minute is written to that often. One left alone is written to at the refresh,
+every `refresh_interval_seconds`, which is 15 minutes by default, and a refresh
+that lands before the link has gone is buffered like any other write, so on a
+quiet sign `link.connected` can stay true for a refresh interval and a minute
+after the adapter has gone. It is still worth a monitor watching, and needs no
+key, but a ping of the adapter answers within a minute however quiet the sign
+is, and is the better alarm.
+
 ### The API key, and config.local.toml
 
 The key is not an argument. A launch configuration is a tracked file and a

{readerboard-0.7.0 → readerboard-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "readerboard"
-version = "0.7.0"
+version = "0.7.1"
 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"
@@ -63,7 +63,12 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
-    "pytest>=9.1.1,<10",
+    # pytest 9.2 renamed CallSpec2 and deprecated the old name, which the anyio
+    # held below 4.15 further down still imports in its pytest plugin. That is
+    # the same collection error again, raised as the plugin loads, so no test
+    # runs at all. anyio 4.16 copes with the rename, so this ceiling comes off
+    # when the anyio one does.
+    "pytest>=9.1.1,<9.2",
     "pytest-asyncio>=1.4.0,<2",
     # starlette's TestClient moved to httpx2; plain httpx now raises a
     # deprecation warning, which this suite is configured to treat as an error.

{readerboard-0.7.0 → readerboard-0.7.1}/readerboard/__init__.py

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

{readerboard-0.7.0 → readerboard-0.7.1}/readerboard/transport/serial_link.py

@@ -14,11 +14,20 @@ 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.
+
+A link over the network is also told to notice a peer that has gone. An adapter
+that drops off the network says nothing as it goes, and without being told
+otherwise the operating system keeps accepting writes to it: Linux retries an
+unacknowledged one for about a quarter of an hour before reporting anything, and
+an idle connection is never checked at all. Meanwhile ``GET /health`` says the
+link is up and the sign holds whatever it was last sent, which on a sign showing
+the time looks exactly like a working one. See :func:`_notice_a_dead_peer`.
 """
 
 from __future__ import annotations
 
 import logging
+import socket
 import threading
 import time
 from collections.abc import Callable
@@ -35,6 +44,20 @@ logger = logging.getLogger(__name__)
 # lock, and never let the controller reach its deadline.
 READ_LIMIT_BYTES = 4096
 
+# How a network link finds out that the adapter at the other end has gone. An
+# idle connection is probed after KEEPALIVE_IDLE_SECONDS of quiet, every
+# KEEPALIVE_INTERVAL_SECONDS after that, and given up after KEEPALIVE_PROBES
+# unanswered probes: about a minute. Probes are only sent while nothing is
+# waiting to be acknowledged, and a write that went out as the adapter vanished
+# is exactly that, so Linux is also told to give up on unacknowledged data after
+# UNACKNOWLEDGED_TIMEOUT_SECONDS rather than its own quarter of an hour. Windows
+# already gives up on a retransmission within a minute, and Python exposes no
+# equivalent of that option there.
+KEEPALIVE_IDLE_SECONDS = 30
+KEEPALIVE_INTERVAL_SECONDS = 10
+KEEPALIVE_PROBES = 3
+UNACKNOWLEDGED_TIMEOUT_SECONDS = 60
+
 
 class SerialTransport:
     """A held-open pyserial link with capped exponential backoff on failure."""
@@ -186,6 +209,8 @@ class SerialTransport:
             self._port = None
             raise TransportError("could not open %s: %s" % (self._url, err)) from err
 
+        _notice_a_dead_peer(self._port, self._url)
+
         if self._failures:
             logger.info("link to %s is back after %d failed attempts", self._url, self._failures)
         else:
@@ -245,3 +270,41 @@ class SerialTransport:
             # 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)
+
+
+def _notice_a_dead_peer(port: object, url: str) -> None:
+    """Tell a network link's socket to find out when the other end has gone.
+
+    Only ``socket://`` and ``rfc2217://`` links have a socket, and pyserial
+    keeps it on a private attribute, so it is looked for rather than assumed: a
+    cable and ``loop://`` have none and are left alone. A test pins the
+    attribute against the pyserial this is installed with, so that an upgrade
+    renaming it fails the suite rather than quietly losing this.
+
+    Each option is set on its own and a refusal is logged and passed over, so
+    that a platform without one of them still opens the link with the rest. An
+    option this platform does not define at all is skipped in the same way.
+    """
+    sock = getattr(port, "_socket", None)
+    if not isinstance(sock, socket.socket):
+        return
+
+    # macOS spells the idle time TCP_KEEPALIVE; everywhere else it is
+    # TCP_KEEPIDLE. Each is looked up by name because not every platform
+    # defines every one of them.
+    idle_option = "TCP_KEEPIDLE" if hasattr(socket, "TCP_KEEPIDLE") else "TCP_KEEPALIVE"
+    options = [
+        (socket.SOL_SOCKET, "SO_KEEPALIVE", 1),
+        (socket.IPPROTO_TCP, idle_option, KEEPALIVE_IDLE_SECONDS),
+        (socket.IPPROTO_TCP, "TCP_KEEPINTVL", KEEPALIVE_INTERVAL_SECONDS),
+        (socket.IPPROTO_TCP, "TCP_KEEPCNT", KEEPALIVE_PROBES),
+        (socket.IPPROTO_TCP, "TCP_USER_TIMEOUT", UNACKNOWLEDGED_TIMEOUT_SECONDS * 1000),
+    ]
+    for level, name, value in options:
+        option = getattr(socket, name, None)
+        if option is None:
+            continue
+        try:
+            sock.setsockopt(level, option, value)
+        except OSError as err:
+            logger.debug("could not set %s on the link to %s: %s", name, url, err)

{readerboard-0.7.0 → readerboard-0.7.1/readerboard.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.7.0
+Version: 0.7.1
 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
@@ -34,7 +34,7 @@ Requires-Dist: pydantic-settings<3,>=2.15.0
 Requires-Dist: pyserial<4,>=3.5
 Requires-Dist: tzdata>=2026.3; sys_platform == "win32"
 Provides-Extra: dev
-Requires-Dist: pytest<10,>=9.1.1; extra == "dev"
+Requires-Dist: pytest<9.2,>=9.1.1; extra == "dev"
 Requires-Dist: pytest-asyncio<2,>=1.4.0; extra == "dev"
 Requires-Dist: httpx2<3,>=2.10.0; extra == "dev"
 Requires-Dist: anyio<4.15,>=4.14.2; extra == "dev"
@@ -184,6 +184,22 @@ sign shows nothing or shows rubbish, and the adapter answers on port 23, it is
 probably negotiating telnet rather than passing bytes through, and `rfc2217://`
 is the form that speaks that.
 
+An adapter that drops off the network says nothing as it goes. The service asks
+the operating system to give a network link up about a minute after the adapter
+stops answering: on Linux, a minute after the first write it did not
+acknowledge, or, if nothing was written, about a minute after it last answered,
+found by keepalive probes. A platform that does not take one of these options
+keeps its own default for it, which can be much longer. The service itself only
+finds out at its first read or write after the link has gone, and `GET /health`
+shows `"connected": false` from then on. A sign with a variable updated every
+minute is written to that often. One left alone is written to at the refresh,
+every `refresh_interval_seconds`, which is 15 minutes by default, and a refresh
+that lands before the link has gone is buffered like any other write, so on a
+quiet sign `link.connected` can stay true for a refresh interval and a minute
+after the adapter has gone. It is still worth a monitor watching, and needs no
+key, but a ping of the adapter answers within a minute however quiet the sign
+is, and is the better alarm.
+
 ### The API key, and config.local.toml
 
 The key is not an argument. A launch configuration is a tracked file and a

{readerboard-0.7.0 → readerboard-0.7.1}/readerboard.egg-info/requires.txt

@@ -8,7 +8,7 @@ pyserial<4,>=3.5
 tzdata>=2026.3
 
 [dev]
-pytest<10,>=9.1.1
+pytest<9.2,>=9.1.1
 pytest-asyncio<2,>=1.4.0
 httpx2<3,>=2.10.0
 anyio<4.15,>=4.14.2

{readerboard-0.7.0 → readerboard-0.7.1}/tests/test_transport.py

@@ -11,10 +11,47 @@ import threading
 import time
 
 import pytest
+import serial
+from serial.rfc2217 import PortManager
 
 from readerboard.transport.base import Transport, TransportError
 from readerboard.transport.fake import FakeTransport
-from readerboard.transport.serial_link import READ_LIMIT_BYTES, SerialTransport
+from readerboard.transport.serial_link import (
+    KEEPALIVE_IDLE_SECONDS,
+    KEEPALIVE_INTERVAL_SECONDS,
+    KEEPALIVE_PROBES,
+    READ_LIMIT_BYTES,
+    UNACKNOWLEDGED_TIMEOUT_SECONDS,
+    SerialTransport,
+)
+
+
+def assert_told_to_notice_a_dead_peer(transport: SerialTransport) -> None:
+    """Check that an open network link's socket has every option it was given.
+
+    The socket is a private attribute of pyserial's. The first assertion is the
+    one that fails if an upgrade renames it, rather than the link quietly opening
+    without any of what follows. An option this platform does not define is not
+    set, so it is not checked either.
+    """
+    sock = transport._port._socket
+    assert isinstance(sock, socket.socket)
+
+    assert sock.getsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE) != 0
+    # The same choice of name the code makes: macOS calls the idle time
+    # TCP_KEEPALIVE, and checking only TCP_KEEPIDLE would check nothing there.
+    idle_option = "TCP_KEEPIDLE" if hasattr(socket, "TCP_KEEPIDLE") else "TCP_KEEPALIVE"
+    expected = {
+        idle_option: KEEPALIVE_IDLE_SECONDS,
+        "TCP_KEEPINTVL": KEEPALIVE_INTERVAL_SECONDS,
+        "TCP_KEEPCNT": KEEPALIVE_PROBES,
+        "TCP_USER_TIMEOUT": UNACKNOWLEDGED_TIMEOUT_SECONDS * 1000,
+    }
+    for name, value in expected.items():
+        option = getattr(socket, name, None)
+        if option is None:
+            continue
+        assert sock.getsockopt(socket.IPPROTO_TCP, option) == value, name
 
 
 class Clock:
@@ -150,6 +187,69 @@ class TestSerialTransportOverASocket:
             listener.close()
             server.join(5)
 
+    def test_the_link_is_told_to_notice_an_adapter_that_has_gone(self):
+        # An adapter that drops off the network says nothing as it goes. These
+        # options are what make the operating system find out, and the link
+        # stays reported as up until it does.
+        listener = socket.socket()
+        listener.bind(("127.0.0.1", 0))
+        listener.listen(1)
+        transport = SerialTransport("socket://127.0.0.1:%d" % listener.getsockname()[1])
+        try:
+            transport.ensure_open()
+            assert_told_to_notice_a_dead_peer(transport)
+        finally:
+            transport.close()
+            listener.close()
+
+    # pyserial's RFC 2217 client starts its reader thread with the deprecated
+    # setDaemon and setName. They are not ours to fix, and filterwarnings =
+    # ["error"] would otherwise fail the open before anything here is checked.
+    @pytest.mark.filterwarnings(
+        "ignore:set(Daemon|Name)\\(\\) is deprecated:DeprecationWarning"
+    )
+    def test_an_rfc2217_link_is_told_the_same(self):
+        # pyserial's RFC 2217 handler is a separate class from its socket one
+        # and keeps its own socket, so it is pinned separately. It will not
+        # open against a listener that only accepts: it negotiates first, so
+        # the other end is pyserial's own RFC 2217 server, driving a loop://
+        # port that stands in for the serial side of an adapter.
+        listener = socket.socket()
+        listener.bind(("127.0.0.1", 0))
+        listener.listen(1)
+        done = threading.Event()
+
+        def serve() -> None:
+            conn, _ = listener.accept()
+            with conn, serial.serial_for_url("loop://") as port:
+                conn.settimeout(0.1)
+
+                class Connection:
+                    def write(self, data: bytes) -> None:
+                        conn.sendall(data)
+
+                manager = PortManager(port, Connection())
+                while not done.is_set():
+                    try:
+                        data = conn.recv(1024)
+                    except TimeoutError:
+                        continue
+                    if not data:
+                        return
+                    port.write(b"".join(manager.filter(data)))
+
+        server = threading.Thread(target=serve, daemon=True)
+        server.start()
+        transport = SerialTransport("rfc2217://127.0.0.1:%d" % listener.getsockname()[1])
+        try:
+            transport.ensure_open()
+            assert_told_to_notice_a_dead_peer(transport)
+        finally:
+            done.set()
+            transport.close()
+            listener.close()
+            server.join(5)
+
     def test_a_link_that_never_stops_delivering_still_hands_back(self):
         # Without the cap this read would never return, and the controller
         # would never reach its deadline.