Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions docs/machine.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
169 changes: 169 additions & 0 deletions tests/test_discovery.py
Original file line number Diff line number Diff line change
Expand Up @@ -466,3 +466,172 @@ 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]


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"]
6 changes: 4 additions & 2 deletions warpedpinball/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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",
Expand Down
98 changes: 97 additions & 1 deletion warpedpinball/discovery.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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()