feat: add opt-in periodic interface-change monitor

bdraco · bdraco · commit 05467e4e1ec8 · 2026-06-22T09:38:25.000-05:00
diff --git a/src/zeroconf/_core.py b/src/zeroconf/_core.py
@@ -59,6 +59,7 @@
     wait_for_future_set_or_timeout,
     wait_future_or_timeout,
 )
+from ._utils.interface_monitor import _DEFAULT_INTERFACE_MONITOR_INTERVAL, InterfaceMonitor
 from ._utils.name import service_type_name
 from ._utils.net import (
     InterfaceChoice,
@@ -225,6 +226,7 @@ def __init__(
         # Serializes async_update_interfaces so overlapping calls (a bursty
         # adapter-change source) don't diff against a stale sender snapshot.
         self._interface_update_lock = asyncio.Lock()
+        self._interface_monitor: InterfaceMonitor | None = None
         self.loop: asyncio.AbstractEventLoop | None = None
         self._loop_thread: threading.Thread | None = None
 
@@ -492,6 +494,28 @@ async def async_update_interfaces(
             if isinstance(result, Exception):
                 log.warning("Error re-announcing %s after interface update: %s", info.name, result)
 
+    async def async_start_interface_monitor(
+        self, interval: float = _DEFAULT_INTERFACE_MONITOR_INTERVAL
+    ) -> None:
+        """Start an opt-in poller that rescans interfaces when adapters change.
+
+        Interface change detection is platform specific; by default zeroconf
+        leaves it to the consumer. This polls every ``interval`` seconds and
+        calls `async_update_interfaces` when the address set changes. It is a
+        no-op if the monitor is already running.
+        """
+        await self.async_wait_for_start()
+        if self._interface_monitor is None:
+            self._interface_monitor = InterfaceMonitor(self, interval)
+            self._interface_monitor.start()
+
+    async def async_stop_interface_monitor(self) -> None:
+        """Stop the interface monitor if it is running."""
+        monitor = self._interface_monitor
+        if monitor is not None:
+            self._interface_monitor = None
+            await monitor.async_stop()
+
     async def async_get_service_info(
         self,
         type_: str,
@@ -829,6 +853,7 @@ async def _async_close(self) -> None:
         before calling this function
         """
         self._close()
+        await self.async_stop_interface_monitor()
         await self.engine._async_close()  # pylint: disable=protected-access
         self._shutdown_threads()
 
diff --git a/src/zeroconf/_utils/interface_monitor.py b/src/zeroconf/_utils/interface_monitor.py
@@ -0,0 +1,71 @@
+"""Optional periodic interface-change monitor.
+
+Interface change detection is platform specific and is left to the consumer
+by default. This convenience monitor polls ``ifaddr.get_adapters`` and calls
+``Zeroconf.async_update_interfaces`` when the set of interface addresses
+changes, so a consumer that has no native change signal can still reconcile
+sockets without restarting the instance.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from typing import TYPE_CHECKING
+
+import ifaddr
+
+from .._logger import log
+
+if TYPE_CHECKING:
+    from .._core import Zeroconf
+
+_DEFAULT_INTERFACE_MONITOR_INTERVAL = 5.0  # seconds
+
+
+def _adapter_snapshot() -> frozenset[tuple[int | None, str]]:
+    """Return a hashable snapshot of every adapter index and address."""
+    return frozenset((adapter.index, str(ip.ip)) for adapter in ifaddr.get_adapters() for ip in adapter.ips)
+
+
+class InterfaceMonitor:
+    """Poll for adapter changes and rescan interfaces when they change."""
+
+    __slots__ = ("_interval", "_snapshot", "_task", "_zc")
+
+    def __init__(self, zc: Zeroconf, interval: float = _DEFAULT_INTERFACE_MONITOR_INTERVAL) -> None:
+        self._zc = zc
+        self._interval = interval
+        self._snapshot = _adapter_snapshot()
+        self._task: asyncio.Task[None] | None = None
+
+    def start(self) -> None:
+        """Start the poll task on the running loop."""
+        assert self._zc.loop is not None
+        if self._task is None:
+            self._task = self._zc.loop.create_task(self._async_run())
+
+    async def async_stop(self) -> None:
+        """Cancel the poll task and wait for it to finish."""
+        task = self._task
+        if task is None:
+            return
+        self._task = None
+        task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await task
+
+    async def _async_run(self) -> None:
+        """Rescan interfaces whenever the adapter snapshot changes."""
+        while True:
+            await asyncio.sleep(self._interval)
+            snapshot = _adapter_snapshot()
+            if snapshot == self._snapshot:
+                continue
+            self._snapshot = snapshot
+            try:
+                await self._zc.async_update_interfaces()
+            except Exception:
+                # A transient failure must not kill the monitor; the next
+                # change still triggers a rescan.
+                log.exception("Interface rescan failed")
diff --git a/src/zeroconf/asyncio.py b/src/zeroconf/asyncio.py
@@ -34,6 +34,7 @@
 from ._services.browser import _ServiceBrowserBase
 from ._services.info import AsyncServiceInfo, ServiceInfo
 from ._services.types import ZeroconfServiceTypes
+from ._utils.interface_monitor import _DEFAULT_INTERFACE_MONITOR_INTERVAL
 from ._utils.net import InterfaceChoice, InterfacesType, IPVersion
 from .const import _BROWSER_TIME, _MDNS_PORT, _SERVICE_TYPE_ENUMERATION_NAME
 
@@ -240,6 +241,21 @@ async def async_update_interfaces(
         """
         await self.zeroconf.async_update_interfaces(interfaces, ip_version, apple_p2p)
 
+    async def async_start_interface_monitor(
+        self, interval: float = _DEFAULT_INTERFACE_MONITOR_INTERVAL
+    ) -> None:
+        """Start an opt-in poller that rescans interfaces when adapters change.
+
+        Interface change detection is platform specific; by default zeroconf
+        leaves it to the consumer. This polls every ``interval`` seconds and
+        reconciles the sockets in use when the address set changes.
+        """
+        await self.zeroconf.async_start_interface_monitor(interval)
+
+    async def async_stop_interface_monitor(self) -> None:
+        """Stop the interface monitor if it is running."""
+        await self.zeroconf.async_stop_interface_monitor()
+
     async def async_close(self) -> None:
         """Ends the background threads, and prevent this instance from
         servicing further queries."""
diff --git a/tests/test_interface_monitor.py b/tests/test_interface_monitor.py
@@ -0,0 +1,154 @@
+"""Unit tests for the opt-in periodic interface-change monitor."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from unittest.mock import Mock, patch
+
+import pytest
+
+from zeroconf._utils import interface_monitor as im
+from zeroconf._utils.interface_monitor import InterfaceMonitor
+from zeroconf.asyncio import AsyncZeroconf
+
+
+def _snapshot_cycler(snapshots: list[frozenset]) -> Callable[[], frozenset]:
+    """Return the next snapshot each call, sticking on the last one."""
+    it = iter(snapshots)
+
+    def _next() -> frozenset:
+        try:
+            return next(it)
+        except StopIteration:
+            return snapshots[-1]
+
+    return _next
+
+
+def test_adapter_snapshot() -> None:
+    adapter = Mock()
+    adapter.index = 1
+    ip = Mock()
+    ip.ip = "192.168.1.5"
+    adapter.ips = [ip]
+    with patch.object(im.ifaddr, "get_adapters", return_value=[adapter]):
+        assert im._adapter_snapshot() == frozenset({(1, "192.168.1.5")})
+
+
+@pytest.mark.asyncio
+async def test_monitor_rescans_on_change(aiozc_loopback: AsyncZeroconf) -> None:
+    """A changed adapter snapshot triggers a rescan."""
+    zc = aiozc_loopback.zeroconf
+    await zc.async_wait_for_start()
+    updated = asyncio.Event()
+
+    async def _fake_update() -> None:
+        updated.set()
+
+    with (
+        patch.object(
+            im, "_adapter_snapshot", side_effect=_snapshot_cycler([frozenset({"a"}), frozenset({"b"})])
+        ),
+        patch.object(zc, "async_update_interfaces", side_effect=_fake_update),
+    ):
+        await aiozc_loopback.async_start_interface_monitor(interval=0.001)
+        await asyncio.wait_for(updated.wait(), timeout=1.0)
+        await aiozc_loopback.async_stop_interface_monitor()
+
+
+@pytest.mark.asyncio
+async def test_monitor_no_rescan_when_unchanged(aiozc_loopback: AsyncZeroconf) -> None:
+    """An unchanged snapshot does not trigger a rescan."""
+    zc = aiozc_loopback.zeroconf
+    await zc.async_wait_for_start()
+    with (
+        patch.object(im, "_adapter_snapshot", return_value=frozenset({"same"})),
+        patch.object(zc, "async_update_interfaces") as mock_update,
+    ):
+        await aiozc_loopback.async_start_interface_monitor(interval=0.001)
+        await asyncio.sleep(0.02)
+        await aiozc_loopback.async_stop_interface_monitor()
+    mock_update.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_monitor_survives_rescan_error(aiozc_loopback: AsyncZeroconf) -> None:
+    """A failed rescan is logged and the monitor keeps running."""
+    zc = aiozc_loopback.zeroconf
+    await zc.async_wait_for_start()
+    calls = []
+
+    async def _boom() -> None:
+        calls.append(1)
+        raise RuntimeError("boom")
+
+    snapshots = [frozenset({"a"}), frozenset({"b"}), frozenset({"c"})]
+    with (
+        patch.object(im, "_adapter_snapshot", side_effect=_snapshot_cycler(snapshots)),
+        patch.object(zc, "async_update_interfaces", side_effect=_boom),
+    ):
+        await aiozc_loopback.async_start_interface_monitor(interval=0.001)
+        await asyncio.sleep(0.05)
+        await aiozc_loopback.async_stop_interface_monitor()
+    assert len(calls) >= 2
+
+
+@pytest.mark.asyncio
+async def test_start_interface_monitor_idempotent(aiozc_loopback: AsyncZeroconf) -> None:
+    """Starting an already-running monitor is a no-op."""
+    zc = aiozc_loopback.zeroconf
+    await zc.async_wait_for_start()
+    with patch.object(im, "_adapter_snapshot", return_value=frozenset()):
+        await aiozc_loopback.async_start_interface_monitor(interval=10)
+        monitor = zc._interface_monitor
+        assert monitor is not None
+        task = monitor._task
+        await aiozc_loopback.async_start_interface_monitor(interval=10)
+        assert zc._interface_monitor is monitor
+        assert monitor._task is task
+        await aiozc_loopback.async_stop_interface_monitor()
+
+
+@pytest.mark.asyncio
+async def test_monitor_start_idempotent(aiozc_loopback: AsyncZeroconf) -> None:
+    """InterfaceMonitor.start is a no-op when a task is already scheduled."""
+    zc = aiozc_loopback.zeroconf
+    await zc.async_wait_for_start()
+    with patch.object(im, "_adapter_snapshot", return_value=frozenset()):
+        monitor = InterfaceMonitor(zc, interval=10)
+    monitor.start()
+    task = monitor._task
+    monitor.start()
+    assert monitor._task is task
+    await monitor.async_stop()
+
+
+@pytest.mark.asyncio
+async def test_monitor_stop_without_start(aiozc_loopback: AsyncZeroconf) -> None:
+    """Stopping a monitor that never started is a no-op."""
+    zc = aiozc_loopback.zeroconf
+    await zc.async_wait_for_start()
+    with patch.object(im, "_adapter_snapshot", return_value=frozenset()):
+        monitor = InterfaceMonitor(zc)
+    await monitor.async_stop()
+
+
+@pytest.mark.asyncio
+async def test_core_stop_interface_monitor_when_none(aiozc_loopback: AsyncZeroconf) -> None:
+    """Stopping the monitor when none is running is a no-op."""
+    await aiozc_loopback.zeroconf.async_wait_for_start()
+    await aiozc_loopback.async_stop_interface_monitor()
+
+
+@pytest.mark.asyncio
+async def test_monitor_stopped_on_close() -> None:
+    """async_close stops a running interface monitor."""
+    aiozc = AsyncZeroconf(interfaces=["127.0.0.1"])
+    zc = aiozc.zeroconf
+    await zc.async_wait_for_start()
+    with patch.object(im, "_adapter_snapshot", return_value=frozenset()):
+        await aiozc.async_start_interface_monitor(interval=10)
+    assert zc._interface_monitor is not None
+    await aiozc.async_close()
+    assert zc._interface_monitor is None
