From fad7b3ae4606017c26022a9154a3e4f6bffed002 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 5 Sep 2026 01:33:11 +0000 Subject: [PATCH 1/2] Add discovery.watch() for services that need to hear the network change discover() asks the network once and returns, which is the right shape for a CLI and the wrong one for a service. A board broadcasts HELLO about ten seconds after it boots; a poller only finds out when its interval next comes round, so a machine that rebooted is invisible for up to that long. watch() keeps the socket open and yields as things happen: "joined" when a board announces itself, "roster" for a FULL frame. FULL is worth surfacing separately because it is the registry board's complete list and every board on the network checks it against what it knows and corrects it -- the closest thing to ground truth about who is live. It reuses discover()'s probing so quiet networks still answer (a lone board only announces itself every 15 s unprovoked), and it owns the discovery port while running, which the docstring says plainly since a concurrent discover() would be pushed to an ephemeral port and go deaf. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01VmtVSp58rDkDBRPzL9hJkt --- docs/machine.md | 22 ++++++++ tests/test_discovery.py | 100 +++++++++++++++++++++++++++++++++++++ warpedpinball/__init__.py | 6 ++- warpedpinball/discovery.py | 98 +++++++++++++++++++++++++++++++++++- 4 files changed, 223 insertions(+), 3 deletions(-) diff --git a/docs/machine.md b/docs/machine.md index d34dfe0..bc04db9 100644 --- a/docs/machine.md +++ b/docs/machine.md @@ -34,6 +34,28 @@ with warpedpinball.connect("elvira") as m: `AmbiguousMachineError` (listing the candidates) when a name doesn't resolve to exactly one board. +`discover()` asks once and returns. A long-running service usually wants +`watch()` instead, which keeps listening and yields as the network changes: + +```python +from warpedpinball import discovery + +for event in discovery.watch(): + if event.kind == "roster": + # A FULL frame: the registry board's complete list of live boards. + # Every board checks this against what it knows and corrects it, so + # it is the authoritative answer to what is on the network right now. + print("live boards:", [(m.ip, m.name) for m in event.machines]) + elif event.kind == "joined": + # A HELLO: one board announcing itself, about ten seconds after boot. + print("came up:", event.machines[0].name) +``` + +That means a rebooted board is noticed when it announces itself, rather than +whenever a polling interval happens to come round. `watch()` owns the +discovery port while it runs, so don't call `discover()` concurrently in the +same process. + Boards service discovery every 1.5 s, so results usually arrive within about two seconds; the default 20 s cap (`connect(..., timeout=...)` / `discover(timeout=...)` to change it) only matters on a genuinely quiet diff --git a/tests/test_discovery.py b/tests/test_discovery.py index 53deb78..6b3539c 100644 --- a/tests/test_discovery.py +++ b/tests/test_discovery.py @@ -466,3 +466,103 @@ def close(self): discovery._open_socket() # Fell back to an ephemeral port after the fixed port was taken. assert binds == [("0.0.0.0", discovery.DISCOVERY_PORT), ("0.0.0.0", 0)] + + +# -- watch(): continuous discovery ------------------------------------------ + + +def _watch_events(monkeypatch, frames, **kwargs): + """Drain watch() over a fixed set of queued frames.""" + monkeypatch.setattr(discovery, "_open_socket", lambda: FakeSocket(frames)) + monkeypatch.setattr(discovery, "_probe_sockets", lambda ips: []) + return list(discovery.watch(timeout=0.05, **kwargs)) + + +def test_watch_yields_the_roster_from_a_full_frame(monkeypatch): + frame = full_frame(peer("10.0.0.1", "Elvira"), peer("10.0.0.2", "Pinbot")) + events = _watch_events(monkeypatch, [frame]) + + assert len(events) == 1 + assert events[0].kind == "roster" + assert events[0].machines == [ + DiscoveredMachine(ip="10.0.0.1", name="Elvira"), + DiscoveredMachine(ip="10.0.0.2", name="Pinbot"), + ] + + +def test_watch_yields_a_board_announcing_itself(monkeypatch): + # A board broadcasts HELLO about ten seconds after it boots. + events = _watch_events(monkeypatch, [(hello_frame("Elvira"), "10.0.0.5")]) + + assert len(events) == 1 + assert events[0].kind == "joined" + assert events[0].machines == [DiscoveredMachine(ip="10.0.0.5", name="Elvira")] + + +def test_watch_keeps_going_after_each_event(monkeypatch): + # Unlike discover(), a FULL frame does not end the watch. + frames = [ + full_frame(peer("10.0.0.1", "Elvira")), + (hello_frame("Pinbot"), "10.0.0.2"), + full_frame(peer("10.0.0.1", "Elvira"), peer("10.0.0.2", "Pinbot")), + ] + kinds = [event.kind for event in _watch_events(monkeypatch, frames)] + + assert kinds == ["roster", "joined", "roster"] + + +def test_watch_ignores_its_own_probes_looping_back(monkeypatch): + monkeypatch.setattr(discovery, "_local_ip", lambda: "10.0.0.9") + monkeypatch.setattr(discovery, "_local_ips", lambda: ["10.0.0.9"]) + frames = [(hello_frame("Echo"), "10.0.0.9"), (hello_frame("Real"), "10.0.0.5")] + + events = _watch_events(monkeypatch, frames) + + assert [m.name for e in events for m in e.machines] == ["Real"] + + +def test_watch_ignores_pongs_and_garbage(monkeypatch): + frames = [bytes([4]), b"", b"\x99garbage", (hello_frame("Real"), "10.0.0.5")] + + events = _watch_events(monkeypatch, frames) + + assert [e.kind for e in events] == ["joined"] + + +def test_watch_probes_the_network(monkeypatch): + monkeypatch.setattr(discovery, "_local_ip", lambda: "192.168.4.7") + monkeypatch.setattr(discovery, "_local_ips", lambda: ["192.168.4.7"]) + monkeypatch.setattr(discovery, "_probe_sockets", lambda ips: []) + sent = [] + + class RecordingSocket(FakeSocket): + def sendto(self, data, addr): + sent.append((data, addr)) + super().sendto(data, addr) + + monkeypatch.setattr(discovery, "_open_socket", lambda: RecordingSocket([])) + list(discovery.watch(timeout=0.05)) + + # A lone board only announces itself every 15 s unprovoked, so the watch + # prompts it the same way discover() does. + frames = {data for data, _addr in sent} + assert bytes([3]) in frames + assert bytes([5, 192, 168, 4, 7]) in frames + + +def test_watch_closes_its_sockets_when_the_caller_stops(monkeypatch): + closed = [] + + class ClosingSocket(FakeSocket): + def close(self): + closed.append(True) + + frame = full_frame(peer("10.0.0.1", "Elvira")) + monkeypatch.setattr(discovery, "_open_socket", lambda: ClosingSocket([frame] * 5)) + monkeypatch.setattr(discovery, "_probe_sockets", lambda ips: []) + + watcher = discovery.watch() + next(watcher) # one event, then walk away + watcher.close() + + assert closed == [True] diff --git a/warpedpinball/__init__.py b/warpedpinball/__init__.py index 0102d4b..bde00a9 100644 --- a/warpedpinball/__init__.py +++ b/warpedpinball/__init__.py @@ -14,7 +14,7 @@ import ipaddress from typing import List, Optional -from .discovery import DiscoveredMachine, discover +from .discovery import DiscoveredMachine, DiscoveryEvent, discover, watch from .exceptions import ( AmbiguousMachineError, AuthenticationError, @@ -33,12 +33,14 @@ from .origin import OriginAuthError from .transports.http import HttpTransport -__version__ = "0.4.0" +__version__ = "0.5.0" __all__ = [ "connect", "connect_usb", "discover", + "watch", + "DiscoveryEvent", "list_serial_ports", "Machine", "GameEvent", diff --git a/warpedpinball/discovery.py b/warpedpinball/discovery.py index 9adc199..4a49aaa 100644 --- a/warpedpinball/discovery.py +++ b/warpedpinball/discovery.py @@ -47,7 +47,7 @@ import socket import time from dataclasses import dataclass -from typing import Dict, List, Optional +from typing import Dict, Iterator, List, Optional DISCOVERY_PORT = 37020 BROADCAST_ADDR = "255.255.255.255" @@ -336,3 +336,99 @@ def discover( for ip, seen_name in sightings.items(): found.setdefault(ip, DiscoveredMachine(ip=ip, name=seen_name or "")) return list(found.values()) + + +@dataclass(frozen=True) +class DiscoveryEvent: + """Something a board said about who is on the network. + + ``kind`` is ``"roster"`` for a FULL frame -- the registry board's complete + list of live boards, and the closest thing the network has to ground truth + -- or ``"joined"`` for a HELLO, which one board sends when it comes up. + + ``machines`` is the whole roster for ``"roster"``, and the single board + that announced itself for ``"joined"``. + """ + + kind: str + machines: List[DiscoveredMachine] + + +def watch( + probe_interval: float = 30.0, + timeout: Optional[float] = None, +) -> Iterator[DiscoveryEvent]: + """Watch the network and yield boards joining and full roster updates. + + :func:`discover` asks once and returns. This keeps listening, which is what + a long-running service wants: a board broadcasts HELLO about ten seconds + after it boots, so a listener hears a machine come back on its own instead + of waiting out a polling interval. FULL frames arrive whenever the registry + board republishes its list -- every board on the network checks that list + against what it knows and corrects it, so it is the authoritative answer to + "what is on this network right now". + + Probes go out every ``probe_interval`` seconds to keep quiet networks + talking (a lone board only announces itself every 15 s unprovoked). This + owns the discovery port for as long as it runs, so don't call + :func:`discover` concurrently in the same process -- that second socket + would be pushed to an ephemeral port and go deaf to the replies it wants. + + Runs until ``timeout`` seconds have passed, or forever when it is ``None``. + Stops cleanly if the caller stops iterating. + """ + sock = _open_socket() + local_ip = _local_ip() + local_ips = _local_ips() + probe_socks = _probe_sockets(local_ips) + targets = [BROADCAST_ADDR] + _directed_broadcasts(local_ips) + probes = [build_ping(), build_offline(local_ip)] + + deadline = None if timeout is None else time.monotonic() + timeout + next_probe = 0.0 + try: + while True: + now = time.monotonic() + if deadline is not None and now >= deadline: + return + if now >= next_probe: + for frame in probes: + for out in [sock] + probe_socks: + for addr in targets: + try: + out.sendto(frame, (addr, DISCOVERY_PORT)) + except OSError: + pass # interface without a broadcast route + next_probe = now + probe_interval + + wait = next_probe - now + if deadline is not None: + wait = min(wait, deadline - now) + sock.settimeout(max(min(wait, 1.0), 0.01)) + try: + data, addr = sock.recvfrom(4096) + except socket.timeout: + continue + except ConnectionResetError: + # Windows reports a bounced datagram on the next receive; not + # a socket failure, keep listening. + continue + except OSError: + return + + if len(data) >= 2 and data[0] == MSG_FULL: + yield DiscoveryEvent("roster", parse_full(data)) + continue + + src = addr[0] + if src == local_ip or src in local_ips: + continue # our own probe looped back + name = parse_hello(data) + if name is not None: + yield DiscoveryEvent( + "joined", [DiscoveredMachine(ip=src, name=name)] + ) + finally: + sock.close() + for out in probe_socks: + out.close() From 2f3e0cb3654407e60921354ee1c268d62295b5cc Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 5 Sep 2026 02:40:23 +0000 Subject: [PATCH 2/2] Cover watch()'s error paths The coverage gate was right to complain: watch() had four unexercised branches, and each is a real behaviour rather than defensive padding. - An interface with no broadcast route makes sendto fail, and that must not stop the watch -- probing is best effort across every interface. - Windows reports an earlier datagram's ICMP port-unreachable on the next receive. It looks like a socket error and is not one. - A socket that genuinely dies ends the watch by returning, so the caller can start a fresh one, rather than raising into it. - The per-interface probe sockets get closed alongside the listening one. warpedpinball/discovery.py is back to 100%. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01VmtVSp58rDkDBRPzL9hJkt --- tests/test_discovery.py | 69 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/tests/test_discovery.py b/tests/test_discovery.py index 6b3539c..9f69a99 100644 --- a/tests/test_discovery.py +++ b/tests/test_discovery.py @@ -566,3 +566,72 @@ def close(self): watcher.close() assert closed == [True] + + +def test_watch_keeps_going_when_one_interface_refuses_a_probe(monkeypatch): + frame = full_frame(peer("10.0.0.1", "Elvira")) + + class PickySocket(FakeSocket): + def sendto(self, data, addr): + # A host with an interface that has no broadcast route. + raise OSError("network is unreachable") + + monkeypatch.setattr(discovery, "_open_socket", lambda: PickySocket([frame])) + monkeypatch.setattr(discovery, "_probe_sockets", lambda ips: []) + + events = list(discovery.watch(timeout=0.05)) + + assert [e.kind for e in events] == ["roster"] + + +def test_watch_survives_windows_reporting_a_bounced_datagram(monkeypatch): + frame = full_frame(peer("10.0.0.1", "Elvira")) + + class BouncingSocket(FakeSocket): + def recvfrom(self, bufsize): + # Windows reports an earlier datagram's ICMP port-unreachable on + # the next receive. It is not a socket failure. + if not getattr(self, "_bounced", False): + self._bounced = True + raise ConnectionResetError("WSAECONNRESET") + return super().recvfrom(bufsize) + + monkeypatch.setattr(discovery, "_open_socket", lambda: BouncingSocket([frame])) + monkeypatch.setattr(discovery, "_probe_sockets", lambda ips: []) + + events = list(discovery.watch(timeout=0.5)) + + assert [e.kind for e in events] == ["roster"] + + +def test_watch_ends_when_the_socket_dies(monkeypatch): + closed = [] + + class DeadSocket(FakeSocket): + def recvfrom(self, _bufsize): + raise OSError("socket closed") + + def close(self): + closed.append("listen") + + monkeypatch.setattr(discovery, "_open_socket", lambda: DeadSocket([])) + monkeypatch.setattr(discovery, "_probe_sockets", lambda ips: []) + + # Returns rather than raising, so a caller can start a fresh watch. + assert list(discovery.watch()) == [] + assert closed == ["listen"] + + +def test_watch_closes_the_per_interface_probe_sockets(monkeypatch): + closed = [] + + class ProbeSocket(FakeSocket): + def close(self): + closed.append("probe") + + monkeypatch.setattr(discovery, "_open_socket", lambda: FakeSocket([])) + monkeypatch.setattr(discovery, "_probe_sockets", lambda ips: [ProbeSocket([])]) + + list(discovery.watch(timeout=0.05)) + + assert closed == ["probe"]