✨ Feat: add Thin Waist address validation utilities and integrate into echo example

examples/advanced/network_discover.py

@@ -0,0 +1,63 @@
+"""
+Advanced demonstration of Thin Waist address handling.
+
+Run:
+    python -m examples.advanced.network_discovery
+"""
+
+from __future__ import annotations
+
+from multiaddr import Multiaddr
+
+try:
+    from libp2p.utils.address_validation import (
+        expand_wildcard_address,
+        get_available_interfaces,
+        get_optimal_binding_address,
+    )
+except ImportError:
+    # Fallbacks if utilities are missing
+    def get_available_interfaces(port: int, protocol: str = "tcp"):
+        return [Multiaddr(f"/ip4/0.0.0.0/{protocol}/{port}")]
+
+    def expand_wildcard_address(addr: Multiaddr, port: int | None = None):
+        if port is None:
+            return [addr]
+        addr_str = str(addr).rsplit("/", 1)[0]
+        return [Multiaddr(addr_str + f"/{port}")]
+
+    def get_optimal_binding_address(port: int, protocol: str = "tcp"):
+        return Multiaddr(f"/ip4/0.0.0.0/{protocol}/{port}")
+
+
+def main() -> None:
+    port = 8080
+    interfaces = get_available_interfaces(port)
+    print(f"Discovered interfaces for port {port}:")
+    for a in interfaces:
+        print(f"  - {a}")
+
+    wildcard_v4 = Multiaddr(f"/ip4/0.0.0.0/tcp/{port}")
+    expanded_v4 = expand_wildcard_address(wildcard_v4)
+    print("\nExpanded IPv4 wildcard:")
+    for a in expanded_v4:
+        print(f"  - {a}")
+
+    wildcard_v6 = Multiaddr(f"/ip6/::/tcp/{port}")
+    expanded_v6 = expand_wildcard_address(wildcard_v6)
+    print("\nExpanded IPv6 wildcard:")
+    for a in expanded_v6:
+        print(f"  - {a}")
+
+    print("\nOptimal binding address heuristic result:")
+    print(f"  -> {get_optimal_binding_address(port)}")
+
+    override_port = 9000
+    overridden = expand_wildcard_address(wildcard_v4, port=override_port)
+    print(f"\nPort override expansion to {override_port}:")
+    for a in overridden:
+        print(f"  - {a}")
+
+
+if __name__ == "__main__":
+    main()

examples/echo/echo.py

@@ -1,4 +1,6 @@
 import argparse
+import random
+import secrets
 
 import multiaddr
 import trio
@@ -12,40 +14,55 @@
 from libp2p.custom_types import (
     TProtocol,
 )
+from libp2p.network.stream.exceptions import (
+    StreamEOF,
+)
 from libp2p.network.stream.net_stream import (
     INetStream,
 )
 from libp2p.peer.peerinfo import (
     info_from_p2p_addr,
 )
+from libp2p.utils.address_validation import (
+    find_free_port,
+    get_available_interfaces,
+)
 
 PROTOCOL_ID = TProtocol("/echo/1.0.0")
 MAX_READ_LEN = 2**32 - 1
 
 
 async def _echo_stream_handler(stream: INetStream) -> None:
-    # Wait until EOF
-    msg = await stream.read(MAX_READ_LEN)
-    await stream.write(msg)
-    await stream.close()
+    try:
+        peer_id = stream.muxed_conn.peer_id
+        print(f"Received connection from {peer_id}")
+        # Wait until EOF
+        msg = await stream.read(MAX_READ_LEN)
+        print(f"Echoing message: {msg.decode('utf-8')}")
+        await stream.write(msg)
+    except StreamEOF:
+        print("Stream closed by remote peer.")
+    except Exception as e:
+        print(f"Error in echo handler: {e}")
+    finally:
+        await stream.close()
 
 
 async def run(port: int, destination: str, seed: int | None = None) -> None:
-    listen_addr = multiaddr.Multiaddr(f"/ip4/0.0.0.0/tcp/{port}")
+    # CHANGED: previously hardcoded 0.0.0.0
+    if port <= 0:
+        port = find_free_port()
+    listen_addr = get_available_interfaces(port)
 
     if seed:
-        import random
-
         random.seed(seed)
         secret_number = random.getrandbits(32 * 8)
         secret = secret_number.to_bytes(length=32, byteorder="big")
     else:
-        import secrets
-
         secret = secrets.token_bytes(32)
 
     host = new_host(key_pair=create_new_key_pair(secret))
-    async with host.run(listen_addrs=[listen_addr]), trio.open_nursery() as nursery:
+    async with host.run(listen_addrs=listen_addr), trio.open_nursery() as nursery:
         # Start the peer-store cleanup task
         nursery.start_soon(host.get_peerstore().start_cleanup_task, 60)
 
@@ -54,10 +71,15 @@ async def run(port: int, destination: str, seed: int | None = None) -> None:
         if not destination:  # its the server
             host.set_stream_handler(PROTOCOL_ID, _echo_stream_handler)
 
+            # Print all listen addresses with peer ID (JS parity)
+            print("Listener ready, listening on:\n")
+            peer_id = host.get_id().to_string()
+            for addr in listen_addr:
+                print(f"{addr}/p2p/{peer_id}")
+
             print(
-                "Run this from the same folder in another console:\n\n"
-                f"echo-demo "
-                f"-d {host.get_addrs()[0]}\n"
+                "\nRun this from the same folder in another console:\n\n"
+                f"echo-demo -d {host.get_addrs()[0]}\n"
             )
             print("Waiting for incoming connections...")
             await trio.sleep_forever()

examples/pubsub/pubsub.py

@@ -1,6 +1,5 @@
 import argparse
 import logging
-import socket
 
 import base58
 import multiaddr
@@ -31,6 +30,9 @@
 from libp2p.tools.async_service.trio_service import (
     background_trio_service,
 )
+from libp2p.utils.address_validation import (
+    find_free_port,
+)
 
 # Configure logging
 logging.basicConfig(
@@ -77,13 +79,6 @@ async def publish_loop(pubsub, topic, termination_event):
             await trio.sleep(1)  # Avoid tight loop on error
 
 
-def find_free_port():
-    """Find a free port on localhost."""
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-        s.bind(("", 0))  # Bind to a free port provided by the OS
-        return s.getsockname()[1]
-
-
 async def monitor_peer_topics(pubsub, nursery, termination_event):
     """
     Monitor for new topics that peers are subscribed to and

libp2p/network/swarm.py

@@ -249,9 +249,11 @@ async def listen(self, *multiaddrs: Multiaddr) -> bool:
         # We need to wait until `self.listener_nursery` is created.
         await self.event_listener_nursery_created.wait()
 
+        success_count = 0
         for maddr in multiaddrs:
             if str(maddr) in self.listeners:
-                return True
+                success_count += 1
+                continue
 
             async def conn_handler(
                 read_write_closer: ReadWriteCloser, maddr: Multiaddr = maddr
@@ -302,13 +304,14 @@ async def conn_handler(
                 # Call notifiers since event occurred
                 await self.notify_listen(maddr)
 
-                return True
+                success_count += 1
+                logger.debug("successfully started listening on: %s", maddr)
             except OSError:
                 # Failed. Continue looping.
                 logger.debug("fail to listen on: %s", maddr)
 
-        # No maddr succeeded
-        return False
+        # Return true if at least one address succeeded
+        return success_count > 0
 
     async def close(self) -> None:
         """

libp2p/utils/__init__.py

@@ -15,6 +15,13 @@
     get_agent_version,
 )
 
+from libp2p.utils.address_validation import (
+    get_available_interfaces,
+    get_optimal_binding_address,
+    expand_wildcard_address,
+    find_free_port,
+)
+
 __all__ = [
     "decode_uvarint_from_stream",
     "encode_delim",
@@ -26,4 +33,8 @@
     "decode_varint_from_bytes",
     "decode_varint_with_size",
     "read_length_prefixed_protobuf",
+    "get_available_interfaces",
+    "get_optimal_binding_address",
+    "expand_wildcard_address",
+    "find_free_port",
 ]