mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/wireless/monitor.py

@@ -0,0 +1,332 @@
+"""The transport monitor: the service that keeps each phone on the cable or on Wi-Fi (SPEC §3.7 items 2, 5-7)."""
+
+import logging
+import threading
+import time
+
+from . import devicectl, store, transport
+from .relay import check_target
+
+log = logging.getLogger("mobster.wireless")
+
+TICK = 10.0
+SLOW = 60.0               # devicectl at most this often while every phone with Wi-Fi on is on the cable
+START_TIMEOUT = 120.0     # a runner started over Wi-Fi answers within this, or it is stopped and retried
+LOST_AFTER = 30.0         # a Wi-Fi runner that stops answering for this long (and no task) is restarted
+NETWORK_EVERY = 60.0      # the network check, at most this often while a phone with Wi-Fi on can't be found
+
+
+def task_on(runtime, phone, udid):
+    # when it can't be told, it counts as busy
+    try:
+        keys = dict.fromkeys(key for key in (udid, getattr(phone, "key", None)) if key)
+        if any(runtime.device_busy(key) for key in keys):
+            return True
+    except Exception:  # noqa: BLE001
+        return True
+    in_use = getattr(getattr(runtime, "fleet", None), "in_use", None)
+    if not callable(in_use):
+        return False
+    try:
+        return bool(in_use(phone))
+    except Exception:  # noqa: BLE001
+        return True
+
+
+class Monitor:
+    def __init__(self, runtime, *, lister=None, bring_up=None, attached=None, nwi=None, clock=None, publish=None,
+                 through=None, network_check=None):
+        from ..mac_tools import usb_attached
+        from . import network
+        self.runtime = runtime
+        self.through = through or network.through_tunnel
+        self.network_check = network_check or network.peer_check
+        self.network = None        # the last network.peer_check result, or None before one ran
+        self.network_at = None
+        self.lister = lister or devicectl.list_devices
+        self.bring_up = bring_up or devicectl.bring_up
+        self.attached = attached or usb_attached
+        self.nwi = nwi or (lambda: network.signature(network.nwi()))
+        self.clock = clock or time.monotonic
+        self.publish = publish or getattr(runtime, "publish", None) or (lambda topic, event: None)
+        self.backoffs = {}         # UDID -> transport.Backoff
+        self.starting = {}         # UDID -> when a Wi-Fi start began
+        self.silent = {}           # UDID -> since when a Wi-Fi runner stopped answering
+        self.peers = {}            # UDID -> devicectl.Peer
+        self.peers_at = None
+        self.devicectl_problem = None
+        self.net = None
+        self.known = set()
+        self.lock = threading.Lock()
+        self.stopping = threading.Event()
+        self.kicked = threading.Event()
+        self.thread = None
+
+    # -- the service ----------------------------------------------------------------------------------------------
+
+    @property
+    def running(self):
+        return self.thread is not None and self.thread.is_alive()
+
+    def start(self):
+        if self.running:
+            return
+        self.stopping.clear()
+        self.thread = threading.Thread(target=self._loop, name="mobster-wifi-monitor", daemon=True)
+        self.thread.start()
+
+    def stop(self, timeout=2.0):
+        self.stopping.set()
+        self.kicked.set()
+        if self.thread is not None:
+            self.thread.join(timeout)
+
+    def kick(self, udid=None):
+        """Look again now; with ``udid``, forget its backoff first (Try again, Wi-Fi just turned on)."""
+        if udid:
+            self.backoff(udid).reset()
+            self.peers_at = None
+        self.kicked.set()
+
+    def _loop(self):
+        while not self.stopping.is_set() and not getattr(self.runtime, "closing", False):
+            try:
+                self.tick()
+            except Exception:  # noqa: BLE001 -- the monitor never stops Mobster
+                log.exception("the Wi-Fi monitor's check failed")
+            self.kicked.wait(self.pause())
+            self.kicked.clear()
+
+    def pause(self):
+        now = self.clock()
+        due = [backoff.next_at - now for backoff in list(self.backoffs.values()) if backoff.failures]
+        return max(0.5, min([TICK, *due]))
+
+    def backoff(self, udid):
+        return self.backoffs.setdefault(str(udid).upper(), transport.Backoff())
+
+    # -- one look at every phone ----------------------------------------------------------------------------------
+
+    def tick(self):
+        with self.lock:
+            if getattr(self.runtime, "closing", False):
+                return
+            fleet = getattr(self.runtime, "fleet", None)
+            if fleet is None or fleet.data_dir is None:
+                return
+            now = self.clock()
+            phones = fleet.usb_managers()
+            enabled = store.enabled_udids(fleet.data_dir)
+            signature = self.nwi()
+            if signature is not None and self.net is not None and signature != self.net:
+                # Another Wi-Fi, a new address, a VPN: the tunnel is set up again, so look again at once.
+                for backoff in list(self.backoffs.values()):
+                    backoff.reset()
+                self.peers_at = None
+                self.network_at = None
+            if signature is not None:
+                self.net = signature
+            usb = {udid.upper(): self._usb(udid) for _, udid, _ in phones}
+            off_cable = [udid for _, udid, _ in phones if udid.upper() in enabled and usb[udid.upper()] is not True]
+            due = SLOW if not off_cable else TICK * 0.9
+            if enabled and (self.peers_at is None or now - self.peers_at >= due):
+                self._refresh(now)
+            away = [udid for udid in off_cable if not self.peers.get(udid.upper()) or
+                    not self.peers[udid.upper()].network]
+            if away and (self.network_at is None or now - self.network_at >= NETWORK_EVERY):
+                self._check_network(now)
+            managed = set()
+            for phone, udid, manager in phones:
+                managed.add(udid.upper())
+                try:
+                    self._step(phone, udid, manager, udid.upper() in enabled, usb[udid.upper()], now)
+                except Exception:  # noqa: BLE001 -- one phone never stops the others
+                    log.exception("the Wi-Fi monitor's check of one phone failed")
+            for gone in self.known - managed:
+                transport.forget(gone)
+            self.known = managed
+
+    def busy(self, phone, udid):
+        return task_on(self.runtime, phone, udid)
+
+    def _usb(self, udid):
+        try:
+            return self.attached(udid)
+        except Exception:
+            return None
+
+    def _refresh(self, now):
+        self.peers_at = now
+        try:
+            self.peers = self.lister()
+            self.devicectl_problem = None
+        except devicectl.DevicectlError as error:
+            self.peers = {}
+            if error.code == "hang":
+                self.devicectl_problem = "devicectl_hang"
+            else:
+                self.devicectl_problem = "no_xcode" if error.code == "no_xcode" else "not_seen"
+        except RuntimeError:
+            self.peers, self.devicectl_problem = {}, "not_seen"   # MOBSTER_NO_DEVICES=1
+
+    def _check_network(self, now):
+        self.network_at = now
+        try:
+            self.network = self.network_check()
+        except Exception:  # noqa: BLE001 -- a check that fails says nothing
+            log.exception("the Wi-Fi monitor's network check failed")
+            self.network = None
+
+    def network_problem(self):
+        from .words import NETWORK_PROBLEMS
+        return NETWORK_PROBLEMS.get((self.network or {}).get("state"))
+
+    def _tunnel(self, udid):
+        peer = self.peers.get(udid.upper())
+        if peer is None or not peer.network:
+            return ("unknown" if peer is None else "down"), None, False
+        address = None
+        if peer.tunnel == "up" and peer.address:
+            try:
+                address = check_target(peer.address)
+            except ValueError:
+                return "up", None, True
+            # only an address this Mac reaches through its CoreDevice tunnel, never through Wi-Fi, Ethernet or a VPN
+            if not self.through(address):
+                return "up", None, True
+        return peer.tunnel, address, True
+
+    @staticmethod
+    def _now(manager):
+        """(what the phone's runner uses now, or None when it isn't running)."""
+        running = manager.runner is not None and manager.runner.running
+        return getattr(manager, "transport", None) if running else None
+
+    def _step(self, phone, udid, manager, enabled, usb, now):
+        key = udid.upper()
+        current = self._now(manager)
+        tunnel, address, seen = self._tunnel(udid) if enabled else ("unknown", None, False)
+        reachable = bool(current == "wifi" and address is None and manager.wda_ready(timeout=1.5))
+        route_lost = False
+        if current == "wifi" and enabled and usb is not True and reachable and address is None:
+            # Answering over Wi-Fi: devicectl not answering (or not listing it this time) doesn't end a working link,
+            # while this Mac still reaches its address through the tunnel.
+            route_lost = not self.through(manager.wifi_address)
+            if not route_lost:
+                address, tunnel = manager.wifi_address, "up"
+        desired = transport.choose(usb is True, enabled, address is not None)
+        busy = self.busy(phone, udid)
+        step = transport.next_step(current, desired, busy)
+        if step == "stay" and current == "wifi" and address and manager.wifi_address != address and not busy:
+            step = "switch"   # the tunnel came back with another address: start again on it
+        backoff = self.backoff(udid)
+        problem, waiting = None, step == "wait"
+
+        if step == "switch" and desired == "wifi":
+            problem, _started = self._start_wifi(udid, manager, address, backoff, now)
+        elif step == "switch" and current == "wifi":
+            manager.stop_runner()
+            self.starting.pop(key, None)
+            self.silent.pop(key, None)
+            if desired == "usb":
+                manager.autostart()          # the cable's runner, as at launch
+            else:
+                backoff.fail(now)
+                problem = "route" if route_lost else "tunnel_down" if seen else (self.devicectl_problem or "not_seen")
+        elif desired is None and enabled and usb is not True and current != "wifi" and not busy:
+            problem = self._bring_up(udid, tunnel, seen, backoff, now)
+
+        current = self._now(manager)
+        reachable = bool(current is not None and manager.wda_ready(timeout=1.5))
+        if current == "wifi":
+            problem = self._watch_wifi(udid, manager, reachable, busy, backoff, now) or problem
+            current = self._now(manager)
+            reachable = reachable and current == "wifi"
+        # Switching: a change waits for a task, or a start over Wi-Fi hasn't answered yet.
+        switching = waiting or (current == "wifi" and key in self.starting and not reachable)
+        if not enabled:
+            problem = None
+        elif problem == "not_seen":
+            problem = self.network_problem() or problem
+        before, after = transport.update(udid, transport=current, tunnel=tunnel if enabled else "unknown",
+                                         reachable=reachable, problem=problem, switching=bool(switching))
+        if before is None or (before.transport, before.reachable) != (after.transport, after.reachable):
+            self.publish("devices", {"event": "transport_changed", "device": udid, "transport": after.transport,
+                                     "reachable": after.reachable})
+
+    def _start_wifi(self, udid, manager, address, backoff, now):
+        if not manager.settings().get("autostart"):
+            return None, False   # stopped in Setup: stays stopped on Wi-Fi too
+        if not backoff.ready(now):
+            return ("runner" if backoff.failures else None), False
+        try:
+            manager.start_wifi_runner(address, self.peers[udid.upper()].udid)
+        except LookupError as error:
+            backoff.fail(now)
+            text = str(error)
+            return ("identity" if "different iPhone" in text else "address" if "isn't available" in text else
+                    "port_busy" if "port" in text else "not_set_up" if "Build" in text or "Setup" in text else
+                    "runner"), False
+        self.starting[udid.upper()] = now
+        self.silent.pop(udid.upper(), None)
+        return None, True
+
+    def _watch_wifi(self, udid, manager, reachable, busy, backoff, now):
+        key = udid.upper()
+        if reachable:
+            self.starting.pop(key, None)
+            self.silent.pop(key, None)
+            backoff.reset()
+            return None
+        if busy:
+            return None
+        started = self.starting.get(key)
+        if started is not None:
+            if now - started < START_TIMEOUT:
+                return None
+        else:
+            since = self.silent.setdefault(key, now)
+            if now - since < LOST_AFTER:
+                return None
+        manager.stop_runner()
+        self.starting.pop(key, None)
+        self.silent.pop(key, None)
+        backoff.fail(now)
+        return "runner"
+
+    def _bring_up(self, udid, tunnel, seen, backoff, now):
+        """Unplugged with Wi-Fi on and no usable tunnel: ask CoreDevice to bring it up, at the backoff's pace."""
+        if self.devicectl_problem in ("no_xcode", "devicectl_hang"):
+            return self.devicectl_problem
+        if not seen:
+            return "not_seen"
+        if tunnel == "up":
+            return "address"   # up, but its address isn't a tunnel address: never used
+        if not backoff.ready(now):
+            return "tunnel_down"
+        try:
+            self.peers.update(self.bring_up(udid))
+            self.peers_at = None   # read the list again next time
+        except devicectl.DevicectlError as error:
+            backoff.fail(now)
+            if error.code == "hang":
+                return "devicectl_hang"
+            return "tunnel_down"
+        except (RuntimeError, ValueError):
+            backoff.fail(now)
+            return "tunnel_down"
+        self.kicked.set()   # look again soon: the tunnel may be up now
+        return "tunnel_down"
+
+    def retire(self):
+        with self.lock:
+            fleet = getattr(self.runtime, "fleet", None)
+            for phone, udid, manager in (fleet.usb_managers() if fleet is not None else ()):
+                if getattr(manager, "transport", None) == "wifi" and not self.busy(phone, udid):
+                    try:
+                        manager.stop_runner()
+                        manager.autostart()
+                    except Exception:  # noqa: BLE001
+                        log.exception("couldn't stop a runner on Wi-Fi")
+                transport.forget(udid)
+            self.known = set()

mobile_agent/wireless/network.py

@@ -0,0 +1,334 @@
+"""This Mac's network, read without changing it: changes, a VPN, Local Network permission, peers and routes."""
+
+import errno
+import hashlib
+import ipaddress
+import os
+import re
+import select
+import socket
+import subprocess
+import threading
+import time
+
+SCUTIL = "/usr/sbin/scutil"
+ROUTE = "/sbin/route"
+IFCONFIG = "/sbin/ifconfig"
+DNS_SD = "/usr/bin/dns-sd"
+VPN_INTERFACE = re.compile(r"^(utun|ipsec|ppp|tun|tap|wg)\d*$")
+# A network this Mac can share with an iPhone: Wi-Fi or Ethernet (en0, en7, ...), or a bridge.
+LAN_INTERFACE = re.compile(r"^(en|bridge)\d+$")
+# Apple's CoreDevice tunnel to a phone is a utun interface on this Mac that holds this Mac's end of the link: an
+# address on the phone's own /64 (or a narrower network), or a point-to-point address whose peer is the phone. A VPN
+# is a utun too, so the route must also be more than a default route, and the utun not one macOS marks as a VPN.
+TUNNEL_INTERFACE = re.compile(r"^utun\d+$")
+TUNNEL_PREFIX = 64
+# `ifconfig -v`'s marks of a VPN: the IS_VPN interface flag, or a NetworkExtension VPN agent.
+VPN_MARK = re.compile(r"\bIS_VPN\b|agent domain:NetworkExtension type:VPN\b")
+INET6 = re.compile(r"^\s*inet6\s+([0-9a-fA-F:.]+)(?:%\S+)?(?:\s+-->\s+([0-9a-fA-F:.]+))?\s+prefixlen\s+(\d+)", re.M)
+# What phones, TVs, speakers, printers and computers advertise. Info.plist's NSBonjourServices lists the same.
+PEER_TYPES = ("_companion-link._tcp", "_airplay._tcp", "_raop._tcp", "_apple-mobdev2._tcp", "_remotepairing._tcp",
+              "_googlecast._tcp", "_hap._tcp", "_ipp._tcp", "_sleep-proxy._udp", "_spotify-connect._tcp")
+BROWSE_SECONDS = 2.5
+# mDNSResponder's "policy denied": macOS's Local Network privacy refused the browse.
+POLICY_DENIED = "-65570"
+LOOPBACK_INDEX = 1
+
+
+def read_output(argv, timeout=3):
+    try:
+        completed = subprocess.run(argv, capture_output=True, text=True, timeout=timeout, stdin=subprocess.DEVNULL)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return completed.stdout if completed.returncode == 0 else None
+
+
+def nwi(reader=None):
+    """`scutil --nwi`: the network state macOS routes by (interfaces, addresses, reachability), or None."""
+    return (reader or read_output)([SCUTIL, "--nwi"])
+
+
+def signature(text):
+    if text is None:
+        return None
+    lines = [" ".join(line.split()) for line in text.splitlines() if line.strip()]
+    return hashlib.sha256("\n".join(lines).encode()).hexdigest()[:16]
+
+
+def ipv4_interfaces(text):
+    """The interfaces `scutil --nwi` lists under IPv4, in its order (the primary first)."""
+    interfaces, section = [], None
+    for line in (text or "").splitlines():
+        stripped = line.strip()
+        if stripped.startswith("IPv4 network interface information"):
+            section = "v4"
+            continue
+        if stripped.startswith("IPv6 network interface information") or stripped.startswith("Network interfaces:"):
+            section = None
+            continue
+        if section == "v4":
+            match = re.match(r"^([a-z]+\d+)\s*:\s*flags", stripped)
+            if match:
+                interfaces.append(match.group(1))
+    return interfaces
+
+
+def vpn_interface(text):
+    """The IPv4 interface of a VPN when one carries this Mac's traffic (utun, ipsec, ppp, ...), else None."""
+    return next((name for name in ipv4_interfaces(text) if VPN_INTERFACE.match(name)), None)
+
+
+def default_gateway(reader=None):
+    """The IPv4 default gateway (`route -n get default`), or None."""
+    text = (reader or read_output)([ROUTE, "-n", "get", "default"])
+    match = re.search(r"^\s*gateway:\s*(\S+)\s*$", text or "", re.M)
+    if not match:
+        return None
+    try:
+        return str(ipaddress.IPv4Address(match.group(1)))
+    except ValueError:
+        return None
+
+
+# macOS's Local Network privacy refuses with EHOSTUNREACH to a gateway that is there; any other answer means allowed.
+def local_network_allowed(gateway, timeout=0.6, connect=None):
+    if not gateway:
+        return None
+    attempt = connect or socket.create_connection
+    try:
+        attempt((gateway, 9), timeout).close()
+        return True
+    except ConnectionRefusedError:
+        return True
+    except (socket.timeout, TimeoutError):
+        return True
+    except OSError as error:
+        if error.errno in (errno.EHOSTUNREACH, errno.EPERM, errno.EACCES):
+            return False
+        return None
+
+
+def resolve(hostnames, timeout=4.0, lookup=None):
+    lookup = lookup or socket.getaddrinfo
+    found = {"ipv4": [], "ipv6": []}
+    for name in hostnames:
+        result = []
+
+        def ask(name=name, result=result):
+            try:
+                result.extend(lookup(name, None, 0, socket.SOCK_STREAM))
+            except (OSError, UnicodeError):
+                pass
+
+        worker = threading.Thread(target=ask, name="mobster-wifi-resolve", daemon=True)
+        worker.start()
+        worker.join(timeout)
+        for family, *_rest, sockaddr in list(result):
+            address = sockaddr[0].split("%", 1)[0]
+            try:
+                parsed = ipaddress.ip_address(address)
+            except ValueError:
+                continue
+            # the tunnel's fd00::/8 end is not an address on the Wi-Fi network
+            if parsed.version == 6 and parsed in ipaddress.IPv6Network("fd00::/8"):
+                continue
+            key = "ipv4" if parsed.version == 4 else "ipv6"
+            if sockaddr[0] not in found[key]:
+                found[key].append(sockaddr[0])
+    return found
+
+
+def port_open(host, port, timeout=2.0, connect=None):
+    attempt = connect or socket.create_connection
+    try:
+        attempt((host, port), timeout).close()
+        return True
+    except OSError:
+        return False
+
+
+def primary_interface(reader=None):
+    text = (reader or read_output)([ROUTE, "-n", "get", "default"])
+    match = re.search(r"^\s*interface:\s*(\S+)\s*$", text or "", re.M)
+    return match.group(1) if match else None
+
+
+def _field(text, key):
+    """One ``key: value`` line of `route -n get`'s answer, or None."""
+    match = re.search(rf"^\s*{key}:\s*(\S+)\s*$", text or "", re.M)
+    return match.group(1) if match else None
+
+
+def tunnel_route(address, reader=None):
+    """(interface, None) when this Mac reaches ``address``, the phone's end of its CoreDevice tunnel, through that
+    tunnel; else (the interface or None, why not). Whatever it can't tell apart from a VPN is refused: no route, a
+    route through Wi-Fi or Ethernet, only a default route, a utun macOS marks as a VPN, or a utun that holds no
+    address on a link to ``address``."""
+    read = reader or read_output
+    try:
+        target = ipaddress.IPv6Address(str(address).strip("[]"))
+    except ValueError:
+        return None, f"{address} isn't an IPv6 address"
+    shown = target.compressed
+    route = read([ROUTE, "-n", "get", "-inet6", shown])
+    name = _field(route, "interface")
+    if not (name and TUNNEL_INTERFACE.match(name)):
+        return name, f"this Mac reaches {shown} through {name or 'no interface'}, not a tunnel (utun)"
+    if _field(route, "destination") == "default":
+        return name, f"this Mac reaches {shown} only through {name}'s default route, which a VPN sets, not a tunnel"
+    facts = read([IFCONFIG, "-v", name])
+    if facts is None:
+        return name, f"this Mac couldn't read {name}'s addresses"
+    if VPN_MARK.search(facts):
+        return name, f"this Mac reaches {shown} through {name}, which is a VPN, not the tunnel"
+    if not link_end(facts, target):
+        held = ", ".join(f"{own}/{prefix}" + (f" to {peer}" if peer else "")
+                         for own, peer, prefix in INET6.findall(facts)
+                         if not own.lower().startswith("fe80:")) or "only link-local addresses"
+        return name, f"{name} holds no address on a link to {shown} ({held}), so it isn't the tunnel to the phone"
+    return name, None
+
+
+def link_end(facts, target):
+    """Whether an address `ifconfig` lists in ``facts`` is this Mac's end of a link to ``target``: one whose
+    point-to-point peer is ``target``, or whose network, /64 or narrower, holds it."""
+    for own, peer, prefix in INET6.findall(facts or ""):
+        try:
+            own, peer = ipaddress.IPv6Address(own), ipaddress.IPv6Address(peer) if peer else None
+        except ValueError:
+            continue
+        if own.is_link_local or own == target:
+            continue
+        if peer == target or (TUNNEL_PREFIX <= int(prefix) < 128
+                              and target in ipaddress.IPv6Network(f"{own}/{prefix}", strict=False)):
+            return True
+    return False
+
+
+def through_tunnel(address, reader=None):
+    return tunnel_route(address, reader)[1] is None
+
+
+def parse_browse(text):
+    found, denied = [], POLICY_DENIED in (text or "")
+    for line in (text or "").splitlines():
+        parts = line.split(None, 6)
+        if len(parts) == 7 and parts[1] == "Add" and parts[3].isdigit():
+            found.append((int(parts[3]), parts[6].strip()))
+    return found, denied
+
+
+def _browse_one(service, seconds, stop, sink):
+    # dns-sd buffers its output unless it writes to a terminal, so it gets a pseudo-terminal
+    import pty
+    try:
+        master, slave = pty.openpty()
+    except OSError:
+        return False
+    try:
+        process = subprocess.Popen([DNS_SD, "-B", service, "local."], stdin=subprocess.DEVNULL, stdout=slave,
+                                   stderr=slave, start_new_session=True)
+    except OSError:
+        os.close(master)
+        os.close(slave)
+        return False
+    os.close(slave)
+    deadline = time.monotonic() + seconds
+    try:
+        while time.monotonic() < deadline and not stop.is_set():
+            ready, _, _ = select.select([master], [], [], 0.1)
+            if not ready:
+                continue
+            try:
+                data = os.read(master, 4096)
+            except OSError:
+                break
+            if not data:
+                break
+            sink.append(data)
+    finally:
+        try:
+            os.killpg(process.pid, 9)
+        except (ProcessLookupError, PermissionError):
+            pass
+        try:
+            process.wait(timeout=2)
+        except subprocess.TimeoutExpired:
+            pass
+        os.close(master)
+    return True
+
+
+def browse(interface_index, types=PEER_TYPES, seconds=BROWSE_SECONDS, settle=1.0):
+    if not os.access(DNS_SD, os.X_OK):
+        return {service: None for service in types}
+    stop = threading.Event()
+    sinks = {service: [] for service in types}
+    ran = {}
+
+    def run(service):
+        ran[service] = _browse_one(service, seconds, stop, sinks[service])
+
+    def outputs():
+        return {service: b"".join(list(sinks[service])).decode("utf-8", "replace") if ran.get(service, True)
+                else None for service in types}
+
+    workers = [threading.Thread(target=run, args=(service,), name="mobster-wifi-bonjour", daemon=True)
+               for service in types]
+    began = time.monotonic()
+    for worker in workers:
+        worker.start()
+    while any(worker.is_alive() for worker in workers) and time.monotonic() - began < seconds + 3:
+        time.sleep(0.1)
+        # after `settle`, this Mac's own services have shown on the loopback interface too
+        if time.monotonic() - began >= settle and peers_heard(outputs(), interface_index)[0]:
+            stop.set()
+    stop.set()
+    for worker in workers:
+        worker.join(3)
+    return outputs()
+
+
+def peers_heard(outputs, interface_index):
+    own, others, denied, ran = set(), [], False, False
+    for text in outputs.values():
+        if text is None:
+            continue
+        ran = True
+        found, refused = parse_browse(text)
+        denied = denied or refused
+        # macOS also lists this Mac's own services on the loopback interface: they aren't other devices
+        own.update(name for index, name in found if index == LOOPBACK_INDEX)
+        others += [name for index, name in found if index == interface_index]
+    return sorted({name for name in others if name not in own}), denied, ran
+
+
+def peer_check(*, interface=None, gateway=None, allowed=None, outputs=None, index_of=None):
+    from .. import native_helpers
+    if outputs is None and not native_helpers.devices_allowed():
+        return {"state": "unknown", "interface": interface, "peers": 0}
+    interface = primary_interface() if interface is None else interface
+    if not interface:
+        return {"state": "offline", "interface": None, "peers": 0}
+    if VPN_INTERFACE.match(interface):
+        return {"state": "vpn", "interface": interface, "peers": 0}
+    if not LAN_INTERFACE.match(interface):
+        return {"state": "unknown", "interface": interface, "peers": 0}
+    gateway = default_gateway() if gateway is None else gateway
+    allowed = local_network_allowed(gateway) if allowed is None else allowed
+    if allowed is False:
+        return {"state": "no_permission", "interface": interface, "peers": 0}
+    try:
+        index = (index_of or socket.if_nametoindex)(interface)
+    except OSError:
+        return {"state": "unknown", "interface": interface, "peers": 0}
+    if outputs is None:
+        outputs = browse(index)
+    names, denied, ran = peers_heard(outputs, index)
+    if names:
+        return {"state": "ok", "interface": interface, "peers": len(names)}
+    if denied:
+        return {"state": "no_permission", "interface": interface, "peers": 0}
+    if not ran:
+        return {"state": "unknown", "interface": interface, "peers": 0}
+    return {"state": "blocked", "interface": interface, "peers": 0}