feat: reconcile a Default single-family instance to an explicit set

bdraco · bdraco · commit 2d4b61b4bdca · 2026-06-22T00:40:14.000-05:00
Instead of raising, moving a Default single-family instance to an explicit
interface set now demotes its dual-use listen/responder socket to a pure
listener and rebuilds it clean, then adds per-interface responders for the
whole desired set. Rebuilding releases the dual-use socket's existing group
memberships so the new joins do not collide (EADDRINUSE) when the desired
set overlaps the interface it served, and demoting it first prevents double
announcements.
diff --git a/src/zeroconf/_core.py b/src/zeroconf/_core.py
@@ -448,8 +448,9 @@ async def async_update_interfaces(
         ``ip_version`` and ``apple_p2p`` each default to the value passed at
         construction; pass a new value to switch it. When the resulting
         interface set is unchanged this is a no-op (no sockets touched,
-        nothing re-announced). The shared listen socket's family and unicast
-        mode are fixed at construction. Concurrent calls are serialized.
+        nothing re-announced). The listen socket is rebuilt if the new set
+        needs a different address family; unicast mode is fixed at
+        construction. Concurrent calls are serialized.
         """
         # Resolve against the retained config but only commit it after the
         # engine reconcile succeeds, so a failed reconcile leaves the stored
diff --git a/src/zeroconf/_engine.py b/src/zeroconf/_engine.py
@@ -189,9 +189,10 @@ async def async_update_interfaces(
 
         Adds a per-interface responder socket for each interface that
         appeared and tears down the socket for each interface that
-        disappeared, diffing on the bound address. The shared listen
-        socket (including the Default single-family dual-use socket) is
-        never torn down here. Returns whether any responder socket was
+        disappeared, diffing on the bound address. A Default single-family
+        instance's dual-use listen/responder socket is converted to a pure
+        listener when moving to an explicit set; otherwise the shared listen
+        socket is left intact. Returns whether any responder socket was
         added, so the caller can skip re-announcing when nothing appeared.
         """
         assert self.loop is not None
@@ -201,30 +202,35 @@ async def async_update_interfaces(
         listen_transport = self._listen_transport
         listen_socket = listen_transport.sock if listen_transport is not None else None
 
-        # A Default single-family instance shares the listen socket as its
-        # only sender; adding per-interface senders alongside it would double
-        # every announcement. Switching interface kind at runtime is not
-        # supported, so raise (before any state changes) rather than
-        # double-send. The no-arg refresh of a Default instance keys to the
-        # listen socket and never reaches here.
+        # The listen socket's family is fixed at construction, so a desired
+        # interface of another family (e.g. an IPv6 interface added to an IPv4
+        # instance) needs a fresh listen socket before senders are reconciled,
+        # otherwise the current senders would be torn down with no replacements
+        # bound.
+        needs_rebuild = listen_socket is not None and any(
+            not _listen_socket_supports(listen_socket, interface) for interface in desired.values()
+        )
+
+        # A Default single-family instance shares the listen socket as its only
+        # sender (the dual-use socket). Moving it to an explicit interface set
+        # abandons that optimization: demote the socket so it stops responding
+        # (otherwise it would double every announcement on the overlapping
+        # interface) and rebuild it as a pure listener (its existing group
+        # memberships would otherwise collide with the new per-interface joins).
+        # Once demoted it no longer counts as a per-interface sender, so the
+        # interface it served gets a fresh responder like any other. The no-arg
+        # refresh of a Default instance leaves desired == {its interface} and so
+        # neither demotes nor rebuilds.
         if listen_transport is not None and any(
             wrapped.transport is listen_transport.transport for wrapped in self.senders
         ):
             listen_key = listen_transport.interface_key
             if any(key != listen_key for key in desired):
-                raise RuntimeError(
-                    "Cannot change interfaces on a Default single-family Zeroconf instance; "
-                    "recreate it to use an explicit interface set"
-                )
-
-        # The listen socket's family is fixed at construction. If a desired
-        # interface cannot be joined on it (e.g. an IPv6 interface added to an
-        # IPv4 instance), rebuild the listen socket for the new family before
-        # reconciling senders, otherwise the current senders would be torn down
-        # with no replacements bound.
-        if listen_socket is not None and any(
-            not _listen_socket_supports(listen_socket, interface) for interface in desired.values()
-        ):
+                self.senders = [w for w in self.senders if w.transport is not listen_transport.transport]
+                current = {wrapped.interface_key: wrapped for wrapped in self.senders}
+                needs_rebuild = True
+
+        if needs_rebuild:
             await self._async_rebuild_listen_socket(apple_p2p, desired, current)
             listen_transport = self._listen_transport
             listen_socket = listen_transport.sock if listen_transport is not None else None
@@ -310,9 +316,9 @@ async def _async_rebuild_listen_socket(
         """Replace the listen socket with one whose family covers the desired set.
 
         The listen socket's family is otherwise fixed at construction; this
-        lets an instance start receiving a newly added address family. Only
-        called when a desired interface cannot be joined on the current listen
-        socket. The replacement family is derived from the desired set (not the
+        lets an instance start receiving a newly added address family, and is
+        also used to convert a Default dual-use socket to a pure listener. The
+        replacement family is derived from the desired set (not the
         requested ip_version, which an explicit list can contradict) so it
         always covers every desired interface and never needs an immediate
         re-rebuild. Interfaces that are staying are re-joined on the new socket,
diff --git a/tests/test_interface_update.py b/tests/test_interface_update.py
@@ -432,22 +432,71 @@ async def test_update_interfaces_keeps_dual_use_listen_socket(aiozc_loopback: As
 
 
 @pytest.mark.asyncio
-async def test_update_interfaces_default_explicit_list_raises(aiozc_loopback: AsyncZeroconf) -> None:
-    """An explicit set on a dual-use instance raises before any state change or rebuild."""
+async def test_update_interfaces_default_to_explicit_reconciles(aiozc_loopback: AsyncZeroconf) -> None:
+    """Moving a dual-use instance to an explicit set demotes its socket and rebuilds clean."""
     engine = aiozc_loopback.zeroconf.engine
     await aiozc_loopback.zeroconf.async_wait_for_start()
     listen = engine._listen_transport
     assert listen is not None
+    old_underlying = listen.transport
+    # Simulate a Default single-family instance: the listen socket is the sole sender.
     engine.senders = [listen]
+    new_listen_sock = Mock()
+    new_listen_sock.family = socket.AF_INET
+
+    async def fake_wrap(sock: object, is_sender: bool) -> _WrappedTransport:
+        wrapped = _make_wrapped(("wrapped", 0), transport=Mock())
+        (engine.senders if is_sender else engine.readers).append(wrapped)
+        return wrapped
+
     with (
         patch.object(_engine, "normalize_interface_choice", return_value=["192.168.1.5"]),
-        patch.object(_engine, "new_listen_socket") as mock_new_listen,
-        pytest.raises(RuntimeError, match="Default single-family"),
+        patch.object(_engine, "new_listen_socket", return_value=new_listen_sock) as mock_new_listen,
+        patch.object(_engine, "add_interface", return_value=Mock()),
+        patch.object(_engine, "drop_multicast_member"),
+        patch.object(_engine.AsyncEngine, "_async_wrap_socket", new=AsyncMock(side_effect=fake_wrap)),
     ):
-        await engine.async_update_interfaces(["unused"], IPVersion.V4Only, False)
-    assert engine.senders == [listen]
-    # The dual-use guard takes precedence; it never falls through to a rebuild.
-    mock_new_listen.assert_not_called()
+        added = await engine.async_update_interfaces(["unused"], IPVersion.V4Only, False)
+
+    # The dual-use socket is rebuilt as a pure listener (demoted and closed),
+    # a fresh listener replaces it, and the explicit interface gains a responder.
+    assert added is True
+    mock_new_listen.assert_called_once()
+    assert engine._listen_transport is not listen
+    assert listen not in engine.senders
+    assert listen not in engine.readers
+    assert old_underlying.is_closing()
+    # One brand-new responder (for 192.168.1.5) is the only sender now.
+    assert len(engine.senders) == 1
+    assert engine.senders[0] is not listen
+
+
+@pytest.mark.asyncio
+async def test_update_interfaces_default_to_explicit_real(aiozc_loopback: AsyncZeroconf) -> None:
+    """A real dual-use socket with an overlapping membership reconciles without EADDRINUSE."""
+    engine = aiozc_loopback.zeroconf.engine
+    await aiozc_loopback.zeroconf.async_wait_for_start()
+    listen = engine._listen_transport
+    assert listen is not None
+    assert listen.sock.family == socket.AF_INET
+    old_underlying = listen.transport
+    # Simulate a Default dual-use instance whose listen socket already joined
+    # the loopback group, so a naive demote-and-rejoin would hit EADDRINUSE.
+    _engine.add_multicast_member(listen.sock, "127.0.0.1")
+    engine.senders = [listen]
+
+    with patch.object(_engine, "normalize_interface_choice", return_value=["127.0.0.1"]):
+        added = await engine.async_update_interfaces(["unused"], IPVersion.V4Only, False)
+
+    assert added is True
+    new_listen = engine._listen_transport
+    assert new_listen is not None
+    assert new_listen is not listen
+    assert new_listen.sock.family == socket.AF_INET
+    assert old_underlying.is_closing()
+    # The overlapping interface got a real responder on the fresh listen socket.
+    assert len(engine.senders) == 1
+    assert engine.senders[0] is not listen
 
 
 @pytest.mark.asyncio
