fix: surface an unreadable IPV6_V6ONLY at warning, document best-effort bring-up

bdraco · bdraco · commit c93f53763f70 · 2026-06-22T10:14:06.000-05:00
A failed IPV6_V6ONLY read assumes dual-stack (returning False could loop
rebuilds when the rebuilt socket's read also fails), but if the socket really
were v6-only that skips a needed rebuild and strands an added IPv4 family, so
log it at warning rather than debug. Document that interface bring-up is
best-effort, and note the benign group leave on the rebuilt listen socket.
diff --git a/src/zeroconf/_core.py b/src/zeroconf/_core.py
@@ -454,9 +454,11 @@ async def async_update_interfaces(
         interface set is unchanged this is a no-op (no sockets touched,
         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. Re-announcement is
-        best-effort: a registration that fails to re-announce is logged, not
-        raised, so one failure cannot block the others.
+        construction. Concurrent calls are serialized. Bringing up interfaces
+        is best-effort: a requested interface that fails to bind, or fails to
+        re-join after a rebuild, is logged rather than raised, and likewise a
+        registration that fails to re-announce is logged so one failure cannot
+        block the others.
         """
         # 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
@@ -80,11 +80,13 @@ def _listen_socket_supports(
     try:
         supported = not listen_socket.getsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY)
     except OSError as exc:
-        # Reading IPV6_V6ONLY can fail (Windows rejects it on some sockets;
-        # other platforms shouldn't). Assume dual-stack so a read failure can't
-        # abort the rescan; at worst this skips a rebuild the next reconcile
-        # re-evaluates, consistent with make_wrapped_transport's fallback.
-        log.debug("Unable to read IPV6_V6ONLY, assuming dual-stack: %s", exc)
+        # Reading IPV6_V6ONLY essentially never fails on a valid AF_INET6
+        # socket. Assume dual-stack rather than abort the rescan; returning
+        # False instead could loop rebuilds if the rebuilt socket's read also
+        # fails. Log at warning, not debug, because if the socket really were
+        # v6-only this skips a needed rebuild and leaves an added IPv4 family
+        # unreceivable, which is worth surfacing.
+        log.warning("Unable to read IPV6_V6ONLY, assuming dual-stack: %s", exc)
     return supported
 
 
@@ -255,6 +257,9 @@ async def async_update_interfaces(
                 # The shared listen / dual-use socket is not a per-interface
                 # sender; leaving the group or closing it would break receive.
                 continue
+            # After a rebuild, listen_socket is the new socket, which this gone
+            # interface never joined (its membership died with the old socket);
+            # the leave is then a benign no-op that drop_multicast_member swallows.
             self._async_close_sender(wrapped, listen_socket)
 
         added = False
