feat(webrtc): add WebRTC transport scaffolding (spec compliance + tests)

docs/conf.py

@@ -314,6 +314,11 @@
     # Mocked ONLY for Sphinx/autodoc: this module does not exist in the codebase
     # but some doc tools may try to import it. No real code references this import.
     "libp2p.relay.circuit_v2.lib",
+    # aiortc is an optional dependency (install via libp2p[webrtc]).
+    # RTD doesn't have libsrtp2-dev so aiortc can't be installed there.
+    "aiortc",
+    "aiortc.rtcdtlstransport",
+    "aiortc.rtcconfiguration",
 ]
 
 # Documents to append as an appendix to all manuals.

docs/libp2p.transport.rst

@@ -19,6 +19,11 @@ Subpackages
 
    libp2p.transport.websocket
 
+.. toctree::
+   :maxdepth: 4
+
+   libp2p.transport.webrtc
+
 Submodules
 ----------
 

docs/libp2p.transport.webrtc.pb.rst

@@ -0,0 +1,21 @@
+libp2p.transport.webrtc.pb package
+==================================
+
+Submodules
+----------
+
+libp2p.transport.webrtc.pb.webrtc\_pb2 module
+---------------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.pb.webrtc_pb2
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: libp2p.transport.webrtc.pb
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/libp2p.transport.webrtc.rst

@@ -0,0 +1,134 @@
+libp2p.transport.webrtc package
+===============================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   libp2p.transport.webrtc.pb
+   libp2p.transport.webrtc.signaling_pb
+
+Submodules
+----------
+
+libp2p.transport.webrtc.certificate module
+------------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.certificate
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.config module
+-------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.config
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.connection module
+-----------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.connection
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.constants module
+----------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.constants
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.exceptions module
+-----------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.exceptions
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.listener module
+---------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.listener
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.multiaddr\_utils module
+-----------------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.multiaddr_utils
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.noise\_handshake module
+-----------------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.noise_handshake
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.private\_listener module
+------------------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.private_listener
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.private\_transport module
+-------------------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.private_transport
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.sdp module
+----------------------------------
+
+.. automodule:: libp2p.transport.webrtc.sdp
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.signaling module
+----------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.signaling
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.stream module
+-------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.stream
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.transport.webrtc.transport module
+----------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.transport
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: libp2p.transport.webrtc
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/libp2p.transport.webrtc.signaling_pb.rst

@@ -0,0 +1,21 @@
+libp2p.transport.webrtc.signaling\_pb package
+=============================================
+
+Submodules
+----------
+
+libp2p.transport.webrtc.signaling\_pb.signaling\_pb2 module
+-----------------------------------------------------------
+
+.. automodule:: libp2p.transport.webrtc.signaling_pb.signaling_pb2
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: libp2p.transport.webrtc.signaling_pb
+   :members:
+   :show-inheritance:
+   :undoc-members:

interop/transport/Dockerfile

@@ -2,13 +2,14 @@ FROM python:3.13-slim
 
 WORKDIR /app
 
-# Install system dependencies
+# Install system dependencies (includes libsrtp2-dev for aiortc/WebRTC)
 RUN apt-get update && apt-get install -y \
     redis-tools \
     build-essential \
     cmake \
     pkg-config \
     libgmp-dev \
+    libsrtp2-dev \
     git \
     curl \
     && rm -rf /var/lib/apt/lists/*

interop/transport/ping_test.py

@@ -172,7 +172,7 @@ def __init__(self, test_plans: bool = False) -> None:
         if not self.transport:
             raise ValueError("TRANSPORT environment variable is required")
 
-        standalone_transports = ["quic-v1"]
+        standalone_transports = ["quic-v1", "webrtc-direct"]
 
         self.muxer: str | None = None
         self.security: str | None = None
@@ -242,11 +242,11 @@ def __init__(self, test_plans: bool = False) -> None:
 
     def validate_configuration(self) -> None:
         """Validate configuration parameters."""
-        valid_transports = ["tcp", "ws", "wss", "quic-v1"]
+        valid_transports = ["tcp", "ws", "wss", "quic-v1", "webrtc-direct"]
         valid_security = ["noise", "plaintext", "tls"]
         valid_muxers = ["mplex", "yamux"]
-        # Standalone transports don't use separate security/muxer
-        standalone_transports = ["quic-v1"]
+        # Standalone transports have security + muxing built-in
+        standalone_transports = ["quic-v1", "webrtc-direct"]
 
         if self.transport not in valid_transports:
             raise ValueError(
@@ -271,7 +271,7 @@ def create_security_options(
         """Create security options based on configuration."""
         # Standalone transports (like quic-v1) have security built-in,
         # no separate security needed
-        standalone_transports = ["quic-v1"]
+        standalone_transports = ["quic-v1", "webrtc-direct"]
         if self.transport in standalone_transports:
             # For standalone transports, return empty security options
             # The security is handled by the transport itself
@@ -310,7 +310,7 @@ def create_muxer_options(self) -> Any:
         """Create muxer options based on configuration."""
         # Standalone transports (like quic-v1) have muxing built-in,
         # no separate muxer needed
-        standalone_transports = ["quic-v1"]
+        standalone_transports = ["quic-v1", "webrtc-direct"]
         if self.transport in standalone_transports:
             # For standalone transports, return None (no separate muxer)
             # The muxing is handled by the transport itself
@@ -479,6 +479,17 @@ def _encapsulate_with_p2p(
             return addr.encapsulate(multiaddr.Multiaddr(f"/p2p/{p2p_value}"))
         return addr
 
+    def _build_webrtc_direct_addr(
+        self, ip_value: str, port: int
+    ) -> multiaddr.Multiaddr:
+        """Build WebRTC Direct address: /ip4|ip6/{ip}/udp/{port}/webrtc-direct."""
+        is_ipv6 = ":" in ip_value
+        if is_ipv6:
+            base = multiaddr.Multiaddr(f"/ip6/{ip_value}/udp/{port}")
+        else:
+            base = multiaddr.Multiaddr(f"/ip4/{ip_value}/udp/{port}")
+        return base.encapsulate(multiaddr.Multiaddr("/webrtc-direct"))
+
     def _build_quic_addr(self, ip_value: str, port: int) -> multiaddr.Multiaddr:
         """
         Build QUIC address from IP and port.
@@ -528,6 +539,27 @@ def create_listen_addresses(self, port: int = 0) -> list[multiaddr.Multiaddr]:
                 return quic_addrs
             return [self._build_quic_addr("0.0.0.0", port)]
 
+        elif self.transport == "webrtc-direct":
+            # WebRTC Direct uses UDP like QUIC
+            webrtc_addrs = []
+            for addr in base_addrs:
+                try:
+                    ip_value = self._get_ip_value(addr)
+                    tcp_port = addr.value_for_protocol("tcp") or port
+                    if ip_value:
+                        wrtc_addr = self._build_webrtc_direct_addr(ip_value, tcp_port)
+                        _, p2p_value = self._extract_and_preserve_p2p(addr)
+                        wrtc_addr = self._encapsulate_with_p2p(wrtc_addr, p2p_value)
+                        webrtc_addrs.append(wrtc_addr)
+                except Exception as e:
+                    print(
+                        f"Error building webrtc-direct addr from {addr}: {e}",
+                        file=sys.stderr,
+                    )
+            if webrtc_addrs:
+                return webrtc_addrs
+            return [self._build_webrtc_direct_addr("0.0.0.0", port)]
+
         elif self.transport == "ws":
             # Add /ws protocol to TCP addresses
             # WebSocket addresses are used for both WS and WSS transports
@@ -737,8 +769,10 @@ def _filter_addresses_by_transport(
                 filtered.append(addr)
             elif self.transport == "quic-v1" and "quic-v1" in protocols:
                 filtered.append(addr)
+            elif self.transport == "webrtc-direct" and "webrtc-direct" in protocols:
+                filtered.append(addr)
             elif self.transport == "tcp" and not any(
-                p in protocols for p in ["ws", "wss", "quic-v1"]
+                p in protocols for p in ["ws", "wss", "quic-v1", "webrtc-direct"]
             ):
                 filtered.append(addr)
         return filtered if filtered else addresses
@@ -859,6 +893,7 @@ async def run_listener(self) -> None:
             muxer_opt=muxer_opt,
             listen_addrs=listen_addrs,
             enable_quic=(self.transport == "quic-v1"),
+            enable_webrtc=(self.transport == "webrtc-direct"),
             tls_client_config=tls_client_config,
             tls_server_config=tls_server_config,
         )
@@ -1191,6 +1226,7 @@ async def run_dialer(self) -> None:
                 "sec_opt": sec_opt,
                 "muxer_opt": muxer_opt,
                 "enable_quic": (self.transport == "quic-v1"),
+                "enable_webrtc": (self.transport == "webrtc-direct"),
                 "tls_client_config": tls_client_config,
                 "tls_server_config": tls_server_config,
             }

interop/transport/pyproject.toml

@@ -12,7 +12,7 @@ authors = [
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-    "libp2p @ file:///app/py-libp2p", # local libp2p dependency is a snapshot based on ${commitSha} in Makefile
+    "libp2p[webrtc] @ file:///app/py-libp2p", # local libp2p with WebRTC extra
     "redis>=4.0.0",
     "typing-extensions>=4.0.0",
     "cryptography>=41.0.0",  # Required for TLS/WSS support

libp2p/__init__.py

@@ -287,6 +287,7 @@ def new_swarm(
     muxer_preference: Literal["YAMUX", "MPLEX"] | None = None,
     listen_addrs: Sequence[multiaddr.Multiaddr] | None = None,
     enable_quic: bool = False,
+    enable_webrtc: bool = False,
     enable_autotls: bool = False,
     retry_config: RetryConfig | None = None,
     connection_config: ConnectionConfig | QUICTransportConfig | None = None,
@@ -378,6 +379,13 @@ def new_swarm(
             enable_autotls=enable_autotls,
         )
 
+    # If enable_webrtc is True, force WebRTC Direct transport
+    if enable_webrtc:
+        from libp2p.transport.webrtc.transport import WebRTCDirectTransport
+
+        logger.debug("new_swarm: Creating WebRTC Direct transport")
+        transport = WebRTCDirectTransport(private_key=key_pair.private_key)
+
     logger.debug(f"new_swarm: Final transport type: {type(transport)}")
 
     # Generate X25519 keypair for Noise
@@ -471,6 +479,7 @@ def new_host(
     bootstrap: list[str] | None = None,
     negotiate_timeout: int = DEFAULT_NEGOTIATE_TIMEOUT,
     enable_quic: bool = False,
+    enable_webrtc: bool = False,
     quic_transport_opt: QUICTransportConfig | None = None,
     tls_client_config: ssl.SSLContext | None = None,
     tls_server_config: ssl.SSLContext | None = None,
@@ -534,6 +543,7 @@ def new_host(
 
     swarm = new_swarm(
         enable_quic=enable_quic,
+        enable_webrtc=enable_webrtc,
         key_pair=key_pair,
         muxer_opt=muxer_opt,
         sec_opt=sec_opt,

libp2p/abc.py

@@ -3002,6 +3002,11 @@ class ITransport(ABC):
 
     """
 
+    # Transports that provide their own stream multiplexing (QUIC, WebRTC)
+    # override this to True.  The swarm skips the TransportUpgrader for
+    # these transports and passes the connection directly to add_conn().
+    provides_native_muxing: bool = False
+
     @abstractmethod
     async def dial(self, maddr: Multiaddr) -> IRawConnection:
         """