ka9q-python 3.14.0__tar.gz → 3.14.1__tar.gz

{ka9q_python-3.14.0 → ka9q_python-3.14.1}/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [3.14.1] - 2026-05-14
+
+### Fixed
+
+- **`RadiodStream`: multi-interface multicast join (parity with
+  `MultiStream`).**  Extends Rob Robinett's `e3acb6a` fix from
+  `multi_stream.py` to `stream.py` so the per-stream `RadiodStream`
+  socket also joins on every local IPv4 interface instead of the
+  single one the kernel picks via `INADDR_ANY`.  Without this, a
+  `RadiodStream` consumer of a co-located radiod with `ttl=0` (or any
+  output that arrives on a non-default-route interface) silently
+  received zero packets.  Most visible to clients that use the
+  per-stream API directly (codar-sounder, hf-timestd's legacy T6
+  path) rather than the shared `MultiStream` socket.
+
+### Refactor
+
+- The helper that enumerates IPv4 interfaces and calls
+  `IP_ADD_MEMBERSHIP` on each is factored into a new package-private
+  `ka9q/_multicast.py` module.  Both `multi_stream.py` and `stream.py`
+  now import from it.  Same behaviour, one implementation.
+  `rtp_recorder.RtpRecorder` still uses the single-interface join —
+  separate fix.
+
+### Tests
+
+- 8 new in `tests/test_multicast_helpers.py`: enumerator behaviour,
+  per-interface join failure handling (one interface failing doesn't
+  abort the loop), empty-enumeration safety, both stream classes
+  pulling the helper from the shared module.
+
 ## [3.14.0] - 2026-05-13
 
 ### Added

{ka9q_python-3.14.0/ka9q_python.egg-info → ka9q_python-3.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.14.0
+Version: 3.14.1
 Summary: Python interface for ka9q-radio control and monitoring
 Home-page: https://github.com/mijahauan/ka9q-python
 Author: Michael Hauan AC0G

{ka9q_python-3.14.0 → ka9q_python-3.14.1}/ka9q/__init__.py

@@ -56,7 +56,7 @@ Lower-level usage (explicit control):
         )
         print(f"Created channel with SSRC: {ssrc}")
 """
-__version__ = '3.14.0'
+__version__ = '3.14.1'
 __author__ = 'Michael Hauan AC0G'
 
 from .control import RadiodControl, allocate_ssrc

ka9q_python-3.14.1/ka9q/_multicast.py

@@ -0,0 +1,90 @@
+"""Shared multicast helpers — multi-interface IP_ADD_MEMBERSHIP.
+
+Factored out of ``multi_stream.py`` (Rob Robinett's e3acb6a) so the
+same join-on-every-interface logic can also be used by
+``stream.RadiodStream`` and ``rtp_recorder.RtpRecorder`` without
+duplicating the SIOCGIFADDR enumeration code.
+
+This module is package-private — callers inside ``ka9q`` import the
+two public helpers below; nothing outside the package should rely on
+the symbol names.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import logging
+import socket
+import struct
+from typing import Iterator, List, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+# Linux SIOCGIFADDR — fetch IPv4 of an interface by name.  Used to enumerate
+# every UP IPv4 interface so the multicast group join can be made on each
+# of them.  Without this, joining with INADDR_ANY lets the kernel pick a
+# single interface (typically the default-route one), which misses:
+#
+#   * Loopback-only multicast emitted by a co-located radiod with TTL=0
+#     (packets sit on `lo`; the kernel won't deliver them to a socket
+#     joined on `ens0`).
+#   * Multi-homed stations where one radiod streams on lo and another
+#     on eth: a single receiver should consume both.
+#
+# Joining on EVERY local IPv4 interface lets one socket receive from any
+# radiod source on any path.
+_SIOCGIFADDR = 0x8915
+
+
+def iter_local_ipv4_interfaces() -> Iterator[Tuple[str, str]]:
+    """Yield (ifname, ipv4_addr_str) for every local interface with an IPv4.
+
+    Order is ``socket.if_nameindex()`` order — typically ``'lo'`` first,
+    then ``ens0``/``eth0``/``wlan0``/etc.  Interfaces without an IPv4
+    (IPv6-only, or freshly-created with no addr) are skipped silently.
+    Stays stdlib-only on Linux (no ``netifaces``/``psutil`` dependency).
+    """
+    try:
+        names = socket.if_nameindex()
+    except OSError:
+        return
+    probe = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        for _idx, ifname in names:
+            try:
+                raw = fcntl.ioctl(
+                    probe.fileno(),
+                    _SIOCGIFADDR,
+                    struct.pack("256s", ifname.encode()[:15]),
+                )
+                addr = socket.inet_ntoa(raw[20:24])
+            except OSError:
+                continue
+            yield ifname, addr
+    finally:
+        probe.close()
+
+
+def join_multicast_all_interfaces(sock: socket.socket,
+                                  multicast_address: str) -> List[str]:
+    """Join ``multicast_address`` on every local IPv4 interface.
+
+    Returns the list of interface names where the join succeeded.  Empty
+    list means no interface was usable (extremely rare — even a freshly-
+    booted box has ``lo``).  Per-interface failures are logged at DEBUG
+    and skipped (e.g., a virtual interface without an IPv4).
+    """
+    joined: List[str] = []
+    group = socket.inet_aton(multicast_address)
+    for ifname, ifaddr in iter_local_ipv4_interfaces():
+        mreq = struct.pack("=4s4s", group, socket.inet_aton(ifaddr))
+        try:
+            sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mreq)
+            joined.append(ifname)
+        except OSError as exc:
+            logger.debug(
+                "multicast join on %s (%s) failed: %s",
+                ifname, ifaddr, exc,
+            )
+    return joined

{ka9q_python-3.14.0 → ka9q_python-3.14.1}/ka9q/multi_stream.py

@@ -59,6 +59,9 @@ from .stream_quality import GapEvent, GapSource, StreamQuality
 logger = logging.getLogger(__name__)
 
 
+from ._multicast import join_multicast_all_interfaces
+
+
 @dataclass
 class _ChannelSlot:
     """Per-SSRC state within a MultiStream."""
@@ -322,12 +325,26 @@ class MultiStream:
 
         sock.bind(("0.0.0.0", self._port))
 
-        mreq = struct.pack(
-            "=4s4s",
-            socket.inet_aton(self._multicast_address),
-            socket.inet_aton("0.0.0.0"),
+        # Join the multicast group on EVERY local IPv4 interface, not
+        # via INADDR_ANY (which lets the kernel pick a single interface
+        # — typically the default route — and silently misses radiod
+        # outputs on other paths, e.g. TTL=0 loopback packets from a
+        # co-located radiod).  Helper lives in ka9q._multicast so
+        # stream.RadiodStream uses identical logic.
+        joined = join_multicast_all_interfaces(
+            sock, self._multicast_address,
         )
-        sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mreq)
+        if not joined:
+            logger.warning(
+                "MultiStream: no interface accepted the multicast "
+                "join for %s — recvfrom() will return nothing",
+                self._multicast_address,
+            )
+        else:
+            logger.debug(
+                "MultiStream: joined %s on interfaces: %s",
+                self._multicast_address, ", ".join(joined),
+            )
         sock.settimeout(1.0)
         return sock
 

{ka9q_python-3.14.0 → ka9q_python-3.14.1}/ka9q/stream.py

@@ -36,6 +36,7 @@ import numpy as np
 from datetime import datetime, timezone
 from typing import Optional, Callable, List
 
+from ._multicast import join_multicast_all_interfaces
 from .discovery import ChannelInfo
 from .rtp_recorder import RTPHeader, parse_rtp_header, rtp_to_wallclock
 from .resequencer import PacketResequencer, RTPPacket
@@ -232,22 +233,34 @@ class RadiodStream:
         
         # Bind to port
         sock.bind(('0.0.0.0', self.channel.port))
-        
-        # Join multicast group
-        mreq = struct.pack(
-            '=4s4s',
-            socket.inet_aton(self.channel.multicast_address),
-            socket.inet_aton('0.0.0.0')
+
+        # Join the multicast group on EVERY local IPv4 interface (lo,
+        # ens0, etc.) — not via INADDR_ANY, which leaves the choice to
+        # the kernel's routing table and silently misses radiod outputs
+        # that arrive on a non-default interface.  Most notably, a
+        # co-located radiod with TTL=0 emits only on `lo`; an
+        # INADDR_ANY join typically resolves to `ens0` and never sees
+        # those packets.  Same helper used by MultiStream (the shared-
+        # socket abstraction) so both classes have identical behaviour.
+        joined = join_multicast_all_interfaces(
+            sock, self.channel.multicast_address,
         )
-        sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mreq)
-        
+        if not joined:
+            logger.warning(
+                "RadiodStream: no interface accepted the multicast "
+                "join for %s — recvfrom() will return nothing",
+                self.channel.multicast_address,
+            )
+        else:
+            logger.debug(
+                "RadiodStream: joined %s:%d on interfaces: %s",
+                self.channel.multicast_address, self.channel.port,
+                ", ".join(joined),
+            )
+
         # Timeout for periodic running check
         sock.settimeout(1.0)
-        
-        logger.debug(
-            f"Joined multicast {self.channel.multicast_address}:{self.channel.port}"
-        )
-        
+
         return sock
     
     def _receive_loop(self):

{ka9q_python-3.14.0 → ka9q_python-3.14.1/ka9q_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.14.0
+Version: 3.14.1
 Summary: Python interface for ka9q-radio control and monitoring
 Home-page: https://github.com/mijahauan/ka9q-python
 Author: Michael Hauan AC0G

{ka9q_python-3.14.0 → ka9q_python-3.14.1}/ka9q_python.egg-info/SOURCES.txt

@@ -36,6 +36,7 @@ examples/tune_example.py
 examples/diagnostics/diagnose_packets.py
 examples/diagnostics/repro_utc_bug.py
 ka9q/__init__.py
+ka9q/_multicast.py
 ka9q/addressing.py
 ka9q/cli.py
 ka9q/compat.py
@@ -81,6 +82,7 @@ tests/test_lifetime.py
 tests/test_listen_multicast.py
 tests/test_managed_stream_recovery.py
 tests/test_monitor.py
+tests/test_multicast_helpers.py
 tests/test_multihomed.py
 tests/test_native_discovery.py
 tests/test_performance_fixes.py

{ka9q_python-3.14.0 → ka9q_python-3.14.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ka9q-python"
-version = "3.14.0"
+version = "3.14.1"
 description = "Python interface for ka9q-radio control and monitoring"
 readme = "README.md"
 authors = [

ka9q_python-3.14.1/tests/test_multicast_helpers.py

@@ -0,0 +1,135 @@
+"""Unit tests for ka9q._multicast helpers.
+
+Locks in the multi-interface IP_ADD_MEMBERSHIP behaviour that both
+MultiStream and RadiodStream rely on for TTL=0 / multi-homed reception.
+Rob Robinett (e3acb6a) introduced the logic inside multi_stream.py;
+this refactor moved it to ka9q._multicast and extended RadiodStream to
+use it too.
+"""
+
+from __future__ import annotations
+
+import socket
+import struct
+import unittest
+from unittest.mock import MagicMock, patch
+
+from ka9q._multicast import (
+    join_multicast_all_interfaces,
+    iter_local_ipv4_interfaces,
+)
+
+
+class TestIterLocalIPv4Interfaces(unittest.TestCase):
+    """`iter_local_ipv4_interfaces` should walk `if_nameindex` and skip
+    interfaces SIOCGIFADDR doesn't answer for."""
+
+    def test_enumerates_via_if_nameindex(self):
+        """Smoke-test: at least one interface must come back on a real host."""
+        ifaces = list(iter_local_ipv4_interfaces())
+        # Every Linux box has 'lo' with 127.0.0.1.  If this list is
+        # empty something is very wrong (privileged container with no
+        # network? broken socket()?).
+        self.assertGreater(len(ifaces), 0)
+        names = [n for n, _ in ifaces]
+        self.assertIn('lo', names)
+        # Find lo and verify it has the expected loopback address.
+        for name, addr in ifaces:
+            if name == 'lo':
+                self.assertEqual(addr, '127.0.0.1')
+                break
+        else:
+            self.fail("lo not present in enumeration")
+
+    def test_handles_if_nameindex_failure(self):
+        """If if_nameindex() raises, we get an empty iterator (not a crash)."""
+        with patch('socket.if_nameindex', side_effect=OSError("no /proc/net")):
+            self.assertEqual(list(iter_local_ipv4_interfaces()), [])
+
+    def test_skips_interfaces_without_ipv4(self):
+        """An interface that has no IPv4 (SIOCGIFADDR errors) is silently
+        skipped — we just don't see it in the output."""
+        # Real-host probe should not include made-up interfaces.
+        ifaces = list(iter_local_ipv4_interfaces())
+        names = [n for n, _ in ifaces]
+        self.assertNotIn('this-interface-does-not-exist', names)
+
+
+class TestJoinMulticastAllInterfaces(unittest.TestCase):
+    """`join_multicast_all_interfaces` must call setsockopt once per
+    enumerated interface and return the names where the join succeeded."""
+
+    def test_joins_each_enumerated_interface(self):
+        sock = MagicMock(spec=socket.socket)
+        sock.setsockopt = MagicMock()
+
+        fake_ifaces = [('lo', '127.0.0.1'),
+                       ('ens0', '192.168.1.50'),
+                       ('tailscale0', '100.64.0.5')]
+        with patch('ka9q._multicast.iter_local_ipv4_interfaces',
+                   return_value=iter(fake_ifaces)):
+            joined = join_multicast_all_interfaces(sock, '239.1.2.3')
+
+        self.assertEqual(joined, ['lo', 'ens0', 'tailscale0'])
+        self.assertEqual(sock.setsockopt.call_count, 3)
+
+        # Verify each setsockopt got the right (group, iface) mreq.
+        for call, (_ifname, ifaddr) in zip(sock.setsockopt.call_args_list, fake_ifaces):
+            args = call.args
+            self.assertEqual(args[0], socket.IPPROTO_IP)
+            self.assertEqual(args[1], socket.IP_ADD_MEMBERSHIP)
+            expected_mreq = struct.pack(
+                "=4s4s",
+                socket.inet_aton('239.1.2.3'),
+                socket.inet_aton(ifaddr),
+            )
+            self.assertEqual(args[2], expected_mreq)
+
+    def test_per_interface_failure_skipped(self):
+        """A setsockopt OSError on one interface skips it but doesn't
+        abort the loop or raise — the other interfaces still join."""
+        sock = MagicMock(spec=socket.socket)
+        # ens0 fails, lo + tailscale0 succeed.
+        def setsockopt_side_effect(level, opt, value):
+            mreq_iface = socket.inet_ntoa(value[4:8])
+            if mreq_iface == '192.168.1.50':
+                raise OSError(99, "Cannot assign requested address")
+            return None
+        sock.setsockopt.side_effect = setsockopt_side_effect
+
+        fake_ifaces = [('lo', '127.0.0.1'),
+                       ('ens0', '192.168.1.50'),
+                       ('tailscale0', '100.64.0.5')]
+        with patch('ka9q._multicast.iter_local_ipv4_interfaces',
+                   return_value=iter(fake_ifaces)):
+            joined = join_multicast_all_interfaces(sock, '239.1.2.3')
+
+        self.assertEqual(joined, ['lo', 'tailscale0'])  # ens0 dropped
+
+    def test_empty_enumeration_returns_empty(self):
+        """No interfaces enumerated → empty join list, no exception."""
+        sock = MagicMock(spec=socket.socket)
+        with patch('ka9q._multicast.iter_local_ipv4_interfaces',
+                   return_value=iter([])):
+            joined = join_multicast_all_interfaces(sock, '239.1.2.3')
+        self.assertEqual(joined, [])
+        sock.setsockopt.assert_not_called()
+
+
+class TestStreamClassesUseHelper(unittest.TestCase):
+    """RadiodStream and MultiStream must both call the shared helper, so a
+    future change to join semantics applies uniformly."""
+
+    def test_radiodstream_imports_helper(self):
+        # Ensure the import succeeded — would raise ImportError at
+        # collection time if the symbol moved.
+        from ka9q import stream
+        self.assertTrue(hasattr(stream, 'join_multicast_all_interfaces'))
+
+    def test_multistream_imports_helper(self):
+        from ka9q import multi_stream
+        self.assertTrue(hasattr(multi_stream, 'join_multicast_all_interfaces'))
+
+
+if __name__ == '__main__':
+    unittest.main()