feat: add multicast_addresses to bind/multicast independently

bluetoothbot · bluetoothbot · commit f265d95fd701 · 2026-05-21T23:22:52.000Z
iOS and other sandboxed platforms allow joining the mDNS multicast group on a physical interface but forbid binding port 5353 on it because the system mDNS daemon owns the port. The existing ``interfaces`` parameter conflates the two: every entry both joins the multicast group and gets a respond socket bound to that interface's address. Add an optional ``multicast_addresses`` parameter on ``Zeroconf`` / ``AsyncZeroconf`` / ``create_sockets`` for additional addresses that are joined to the listen socket's multicast group without creating a respond socket. The default behavior is unchanged. Fixes #1520
diff --git a/src/zeroconf/_core.py b/src/zeroconf/_core.py
@@ -27,7 +27,7 @@
 import random
 import sys
 import threading
-from collections.abc import Awaitable
+from collections.abc import Awaitable, Sequence
 from types import TracebackType
 
 from ._cache import DNSCache
@@ -162,6 +162,7 @@ def __init__(
         ip_version: IPVersion | None = None,
         apple_p2p: bool = False,
         use_asyncio: bool | None = None,
+        multicast_addresses: Sequence[str | int | tuple[tuple[str, int, int], int]] | None = None,
     ) -> None:
         """Creates an instance of the Zeroconf class, establishing
         multicast communications, listening and reaping threads.
@@ -185,6 +186,13 @@ def __init__(
             already has an event loop (e.g. Jupyter) but you want blocking
             semantics. ``True`` raises :class:`RuntimeError` immediately if no
             running event loop is found, instead of falling back to the thread.
+        :param multicast_addresses: optional list of additional IP addresses to
+            add to the listen socket's multicast group. No respond socket is
+            created for these — they extend multicast membership without
+            requiring a bind on the corresponding interface. Useful on
+            sandboxed platforms (e.g. iOS) where port 5353 cannot be bound on
+            physical interfaces but multicast membership is still needed to
+            receive queries arriving on them.
         """
         if ip_version is None:
             ip_version = autodetect_ip_version(interfaces)
@@ -199,7 +207,13 @@ def __init__(
 
         self.unicast = unicast
         self._use_asyncio = use_asyncio
-        listen_socket, respond_sockets = create_sockets(interfaces, unicast, ip_version, apple_p2p=apple_p2p)
+        listen_socket, respond_sockets = create_sockets(
+            interfaces,
+            unicast,
+            ip_version,
+            apple_p2p=apple_p2p,
+            multicast_addresses=multicast_addresses,
+        )
         log.debug("Listen socket %s, respond sockets %s", listen_socket, respond_sockets)
 
         self.engine = AsyncEngine(self, listen_socket, respond_sockets)
diff --git a/src/zeroconf/_utils/net.py b/src/zeroconf/_utils/net.py
@@ -444,19 +444,37 @@ def create_sockets(
     unicast: bool = False,
     ip_version: IPVersion = IPVersion.V4Only,
     apple_p2p: bool = False,
+    multicast_addresses: Sequence[str | int | tuple[tuple[str, int, int], int]] | None = None,
 ) -> tuple[socket.socket | None, list[socket.socket]]:
+    """Create the listen and respond sockets.
+
+    ``multicast_addresses`` is an optional list of additional addresses that
+    are added to the listen socket's multicast group without creating respond
+    sockets for them. This is useful on sandboxed platforms (notably iOS)
+    where binding port 5353 on a physical interface is blocked by the system
+    mDNS daemon but multicast membership on that interface is still required
+    to receive incoming queries.
+    """
+    if multicast_addresses and unicast:
+        raise ValueError("multicast_addresses is incompatible with unicast=True")
+
     if unicast:
         listen_socket = None
     else:
         listen_socket = new_socket(bind_addr=("",), ip_version=ip_version, apple_p2p=apple_p2p)
 
     normalized_interfaces = normalize_interface_choice(interfaces, ip_version)
+    extra_multicast_members = (
+        normalize_interface_choice(list(multicast_addresses), ip_version) if multicast_addresses else []
+    )
 
     # If we are using InterfaceChoice.Default with only IPv4 or only IPv6, we can use
     # a single socket to listen and respond.
     if not unicast and interfaces is InterfaceChoice.Default and ip_version != IPVersion.All:
         for interface in normalized_interfaces:
             add_multicast_member(cast(socket.socket, listen_socket), interface)
+        for interface in extra_multicast_members:
+            add_multicast_member(cast(socket.socket, listen_socket), interface)
         # Sent responder socket options to the dual-use listen socket
         set_respond_socket_multicast_options(cast(socket.socket, listen_socket), ip_version)
         return listen_socket, [cast(socket.socket, listen_socket)]
@@ -473,6 +491,9 @@ def create_sockets(
         if respond_socket is not None:
             respond_sockets.append(respond_socket)
 
+    for interface in extra_multicast_members:
+        add_multicast_member(cast(socket.socket, listen_socket), interface)
+
     return listen_socket, respond_sockets
 
 
diff --git a/src/zeroconf/asyncio.py b/src/zeroconf/asyncio.py
@@ -24,7 +24,7 @@
 
 import asyncio
 import contextlib
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Sequence
 from types import TracebackType  # used in type hints
 
 from ._core import Zeroconf
@@ -151,6 +151,7 @@ def __init__(
         ip_version: IPVersion | None = None,
         apple_p2p: bool = False,
         zc: Zeroconf | None = None,
+        multicast_addresses: Sequence[str | int | tuple[tuple[str, int, int], int]] | None = None,
     ) -> None:
         """Creates an instance of the Zeroconf class, establishing
         multicast communications, and listening.
@@ -166,12 +167,16 @@ def __init__(
         :param ip_version: IP versions to support. If `choice` is a list, the default is detected
             from it. Otherwise defaults to V4 only for backward compatibility.
         :param apple_p2p: use AWDL interface (only macOS)
+        :param multicast_addresses: optional list of additional IP addresses to
+            add to the listen socket's multicast group; see
+            :class:`Zeroconf` for details.
         """
         self.zeroconf = zc or Zeroconf(
             interfaces=interfaces,
             unicast=unicast,
             ip_version=ip_version,
             apple_p2p=apple_p2p,
+            multicast_addresses=multicast_addresses,
         )
         self.async_browsers: dict[ServiceListener, AsyncServiceBrowser] = {}
 
diff --git a/tests/test_core.py b/tests/test_core.py
@@ -184,6 +184,20 @@ def test_use_asyncio_default_starts_thread_without_loop(self):
         finally:
             zc.close()
 
+    def test_multicast_addresses_forwarded_to_create_sockets(self):
+        """Zeroconf forwards multicast_addresses to create_sockets unchanged."""
+        with patch("zeroconf._core.create_sockets", return_value=(None, [])) as mock_create:
+            zc = r.Zeroconf(
+                interfaces=["127.0.0.1"],
+                multicast_addresses=["192.168.1.5"],
+                unicast=True,
+            )
+            try:
+                _, kwargs = mock_create.call_args
+                assert kwargs["multicast_addresses"] == ["192.168.1.5"]
+            finally:
+                zc.close()
+
     def test_async_updates_from_response(self):
         def mock_incoming_msg(
             service_state_change: r.ServiceStateChange,
diff --git a/tests/utils/test_net.py b/tests/utils/test_net.py
@@ -433,3 +433,94 @@ def call_to_tuple(c):
         expected_calls_set = {call_to_tuple(c) for c in expected_calls}
 
         assert actual_calls_set == expected_calls_set
+
+
+def test_create_sockets_multicast_addresses_v4() -> None:
+    """Extra IPv4 addresses join the listen socket multicast group but get no respond socket."""
+    listen_mock = Mock(spec=socket.socket)
+    respond_mock = Mock(spec=socket.socket)
+
+    def _new_socket(bind_addr, **kwargs):
+        return listen_mock if bind_addr == ("",) else respond_mock
+
+    with (
+        patch("zeroconf._utils.net.new_socket", side_effect=_new_socket),
+        patch("zeroconf._utils.net.add_multicast_member", return_value=True) as mock_add,
+        patch("zeroconf._utils.net.set_respond_socket_multicast_options"),
+        patch("zeroconf._utils.net.socket.socket.setsockopt"),
+    ):
+        listen_socket, respond_sockets = r.create_sockets(
+            interfaces=["127.0.0.1"],
+            multicast_addresses=["192.168.1.5", "10.0.0.5"],
+            ip_version=r.IPVersion.V4Only,
+        )
+
+    assert listen_socket is listen_mock
+    assert respond_sockets == [respond_mock]
+    joined = [c.args[1] for c in mock_add.call_args_list if c.args[0] is listen_mock]
+    assert "127.0.0.1" in joined
+    assert "192.168.1.5" in joined
+    assert "10.0.0.5" in joined
+
+
+def test_create_sockets_multicast_addresses_v6() -> None:
+    """Extra IPv6 addresses join the listen socket multicast group."""
+    listen_mock = Mock(spec=socket.socket)
+    respond_mock = Mock(spec=socket.socket)
+
+    def _new_socket(bind_addr, **kwargs):
+        return listen_mock if bind_addr == ("",) else respond_mock
+
+    with (
+        patch("zeroconf._utils.net.new_socket", side_effect=_new_socket),
+        patch("zeroconf._utils.net.add_multicast_member", return_value=True) as mock_add,
+        patch("zeroconf._utils.net.set_respond_socket_multicast_options"),
+        patch(
+            "zeroconf._utils.net.ifaddr.get_adapters",
+            return_value=_generate_mock_adapters(),
+        ),
+        patch("zeroconf._utils.net.socket.socket.setsockopt"),
+    ):
+        r.create_sockets(
+            interfaces=[1],
+            multicast_addresses=["2001:db8::"],
+            ip_version=r.IPVersion.V6Only,
+        )
+
+    joined = [c.args[1] for c in mock_add.call_args_list if c.args[0] is listen_mock]
+    # Both the interface index 1 and the extra multicast address resolve to the
+    # same adapter tuple — what matters is the listen socket joined that group.
+    assert (("2001:db8::", 1, 1), 1) in joined
+
+
+def test_create_sockets_multicast_addresses_unicast_rejected() -> None:
+    """multicast_addresses is incompatible with unicast=True (there is no listen socket)."""
+    with pytest.raises(ValueError):
+        r.create_sockets(
+            interfaces=["127.0.0.1"],
+            multicast_addresses=["192.168.1.5"],
+            unicast=True,
+        )
+
+
+def test_create_sockets_multicast_addresses_default_path() -> None:
+    """multicast_addresses also works on the InterfaceChoice.Default fast path."""
+    listen_mock = Mock(spec=socket.socket)
+
+    with (
+        patch("zeroconf._utils.net.new_socket", return_value=listen_mock),
+        patch("zeroconf._utils.net.add_multicast_member", return_value=True) as mock_add,
+        patch("zeroconf._utils.net.set_respond_socket_multicast_options"),
+        patch("zeroconf._utils.net.socket.socket.setsockopt"),
+    ):
+        listen_socket, respond_sockets = r.create_sockets(
+            interfaces=r.InterfaceChoice.Default,
+            multicast_addresses=["192.168.1.5"],
+            ip_version=r.IPVersion.V4Only,
+        )
+
+    assert listen_socket is listen_mock
+    assert respond_sockets == [listen_mock]
+    joined = [c.args[1] for c in mock_add.call_args_list if c.args[0] is listen_mock]
+    assert "0.0.0.0" in joined
+    assert "192.168.1.5" in joined
