Merge branch 'main' into feature/tls-example

Author: acul71

.github/workflows/tox.yml

@@ -69,6 +69,12 @@ jobs:
           cd tests/interop/nim_libp2p
           ./scripts/setup_nim_echo.sh
 
+      - name: Setup Node.js for interop testing
+        if: matrix.toxenv == 'interop'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
       - run: |
           uv venv venv
           source venv/bin/activate

.gitignore

@@ -45,6 +45,11 @@ coverage.xml
 *.cover
 .pytest_cache/
 
+# Test result files
+tests/**/results/*.json
+tests/**/results/*.xml
+tests/**/results/*.html
+
 # Translations
 *.mo
 *.pot

docs/conf.py

@@ -310,7 +310,7 @@
     "tests.factories",
     # 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"
+    "libp2p.relay.circuit_v2.lib",
 ]
 
 # Documents to append as an appendix to all manuals.

docs/examples.interop.rst

@@ -0,0 +1,47 @@
+Interoperability Testing
+========================
+
+This example provides a standalone console script for testing libp2p ping functionality
+without Docker or Redis dependencies. It supports both listener and dialer roles and
+measures ping RTT and handshake times.
+
+Usage
+-----
+
+Run as listener (waits for connection):
+
+.. code-block:: console
+
+    $ python -m examples.interop.local_ping_test --listener --port 8000
+    Listener ready, listening on:
+      /ip4/127.0.0.1/tcp/8000/p2p/Qm...
+    Waiting for dialer to connect...
+
+Run as dialer (connects to listener):
+
+.. code-block:: console
+
+    $ python -m examples.interop.local_ping_test --dialer --destination /ip4/127.0.0.1/tcp/8000/p2p/Qm...
+    Connecting to listener at: /ip4/127.0.0.1/tcp/8000/p2p/Qm...
+    Connected successfully
+    Performing ping test
+    {"handshakePlusOneRTTMillis": 15.2, "pingRTTMilllis": 2.1}
+
+Options
+-------
+
+- ``--listener``: Run as listener (wait for connection)
+- ``--dialer``: Run as dialer (connect to listener)
+- ``--destination ADDR``: Destination multiaddr (required for dialer)
+- ``--port PORT``: Port number (0 = auto-select)
+- ``--transport {tcp,ws,quic-v1}``: Transport protocol (default: tcp)
+- ``--muxer {mplex,yamux}``: Stream muxer (default: mplex)
+- ``--security {noise,plaintext}``: Security protocol (default: noise)
+- ``--test-timeout SECONDS``: Test timeout in seconds (default: 180)
+- ``--debug``: Enable debug logging
+
+The full source code for this example is below:
+
+.. literalinclude:: ../examples/interop/local_ping_test.py
+    :language: python
+    :linenos:

docs/examples.nat.rst

@@ -0,0 +1,37 @@
+examples.nat package
+====================
+
+Submodules
+----------
+
+examples.nat.dialer module
+--------------------------
+
+.. automodule:: examples.nat.dialer
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+examples.nat.listener module
+----------------------------
+
+.. automodule:: examples.nat.listener
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+examples.nat.relay module
+-------------------------
+
+.. automodule:: examples.nat.relay
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: examples.nat
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/examples.rst

@@ -11,11 +11,14 @@ Examples
    examples.echo
    examples.echo_quic
    examples.ping
+   examples.interop
    examples.pubsub
    examples.bitswap
    examples.circuit_relay
    examples.kademlia
    examples.mDNS
+   examples.nat
    examples.rendezvous
    examples.random_walk
    examples.multiple_connections
+   examples.websocket

docs/examples.websocket.rst

@@ -0,0 +1,241 @@
+WebSocket Transport Examples
+============================
+
+This guide demonstrates how to use the WebSocket transport in py-libp2p, including WS (WebSocket) and WSS (WebSocket Secure) protocols, SOCKS proxy support, AutoTLS, and advanced configuration options.
+
+Quick Start
+-----------
+
+Basic WebSocket transport setup:
+
+.. code-block:: python
+
+    from libp2p import new_host
+    from libp2p.transport.websocket import WebsocketTransport, WebsocketConfig
+    from libp2p.transport.upgrader import TransportUpgrader
+    from libp2p.security.insecure.transport import PLAINTEXT_PROTOCOL_ID, InsecureTransport
+    from libp2p.stream_muxer.yamux.yamux import Yamux
+    from libp2p.custom_types import TProtocol
+    from libp2p.crypto.rsa import create_new_key_pair
+    from multiaddr import Multiaddr
+
+    # Generate a key pair
+    key_pair = create_new_key_pair()
+
+    # Create upgrader with security and muxer
+    upgrader = TransportUpgrader(
+        secure_transports_by_protocol={
+            TProtocol(PLAINTEXT_PROTOCOL_ID): InsecureTransport(key_pair)
+        },
+        muxer_transports_by_protocol={TProtocol("/yamux/1.0.0"): Yamux}
+    )
+
+    # Create WebSocket transport
+    config = WebsocketConfig()
+    transport = WebsocketTransport(upgrader, config=config)
+
+    # Create host with WebSocket transport
+    # Note: new_host handles transport creation internally if not overridden,
+    # but this shows how to set it up manually if needed.
+    host = new_host(
+        listen_addrs=[Multiaddr("/ip4/127.0.0.1/tcp/8080/ws")]
+    )
+
+WS vs WSS
+---------
+
+**WS (Insecure WebSocket):**
+
+Use for development and testing. No TLS encryption:
+
+.. code-block:: python
+
+    ws_addr = Multiaddr("/ip4/127.0.0.1/tcp/8080/ws")
+    host = new_host(listen_addrs=[ws_addr])
+
+**WSS (Secure WebSocket):**
+
+Use for production. Requires TLS configuration:
+
+.. code-block:: python
+
+    import ssl
+
+    # Create TLS context
+    tls_context = ssl.create_default_context()
+    tls_context.check_hostname = False
+    tls_context.verify_mode = ssl.CERT_NONE  # For testing only
+
+    # Configure transport with TLS
+    config = WebsocketConfig(tls_server_config=tls_context)
+    transport = WebsocketTransport(upgrader, config=config)
+
+    wss_addr = Multiaddr("/ip4/127.0.0.1/tcp/8080/wss")
+    host = new_host(listen_addrs=[wss_addr])
+
+SOCKS Proxy Configuration
+-------------------------
+
+**Using Proxy Factory Function:**
+
+.. code-block:: python
+
+    from libp2p.transport.websocket import WithProxy
+
+    # Configure with SOCKS5 proxy
+    config = WithProxy(
+        proxy_url="socks5://proxy.example.com:1080",
+        auth=("username", "password")  # Optional
+    )
+    transport = WebsocketTransport(upgrader, config=config)
+
+**Using Environment Variables:**
+
+.. code-block:: python
+
+    from libp2p.transport.websocket import WithProxyFromEnvironment
+
+    # Reads HTTP_PROXY or HTTPS_PROXY environment variables
+    config = WithProxyFromEnvironment()
+    transport = WebsocketTransport(upgrader, config=config)
+
+**Environment Variable Format:**
+
+.. code-block:: bash
+
+    export HTTP_PROXY=socks5://proxy.example.com:1080
+    export HTTPS_PROXY=socks5://proxy.example.com:1080
+
+AutoTLS Configuration
+---------------------
+
+AutoTLS automatically generates and manages TLS certificates for browser integration:
+
+.. code-block:: python
+
+    from libp2p.transport.websocket import WithAutoTLS, AutoTLSConfig
+
+    autotls_config = AutoTLSConfig(
+        enabled=True,
+        default_domain="localhost",
+        cert_validity_days=365
+    )
+
+    config = WithAutoTLS(autotls_config)
+    transport = WebsocketTransport(upgrader, config=config)
+
+**Browser Integration:**
+
+AutoTLS is particularly useful for browser-based applications where you need trusted certificates for WebSocket connections.
+
+Advanced TLS Configuration
+---------------------------
+
+For production deployments with custom certificates:
+
+.. code-block:: python
+
+    from libp2p.transport.websocket import WithAdvancedTLS
+    from libp2p.transport.websocket.tls_config import (
+        TLSConfig,
+        CertificateValidationMode
+    )
+
+    tls_config = TLSConfig(
+        cert_file="path/to/cert.pem",
+        key_file="path/to/key.pem",
+        ca_file="path/to/ca.pem",
+        validation_mode=CertificateValidationMode.STRICT
+    )
+
+    config = WithAdvancedTLS(tls_config)
+    transport = WebsocketTransport(upgrader, config=config)
+
+Connection Management
+---------------------
+
+Configure connection limits and timeouts:
+
+.. code-block:: python
+
+    from libp2p.transport.websocket import (
+        WithMaxConnections,
+        WithHandshakeTimeout
+    )
+
+    config = WebsocketConfig(
+        max_connections=1000,
+        handshake_timeout=15.0,
+        max_buffered_amount=4 * 1024 * 1024,  # 4MB
+        max_message_size=32 * 1024 * 1024     # 32MB
+    )
+
+    transport = WebsocketTransport(upgrader, config=config)
+
+**Monitoring Connection Statistics:**
+
+.. code-block:: python
+
+    # Get transport statistics
+    stats = transport.get_stats()
+    print(f"Total connections: {stats['total_connections']}")
+    print(f"Current connections: {stats['current_connections']}")
+    print(f"Failed connections: {stats['failed_connections']}")
+
+    # Get connection details
+    connections = await transport.get_connections()
+    for conn_id, conn in connections.items():
+        conn_stats = conn.get_stats()
+        print(f"Connection {conn_id}: {conn_stats}")
+
+Complete Example
+----------------
+
+A complete example demonstrating WebSocket transport with all features:
+
+.. literalinclude:: ../examples/websocket/websocket_demo.py
+    :language: python
+    :linenos:
+
+Multiaddr Formats
+-----------------
+
+WebSocket transport supports various multiaddr formats:
+
+- **WS (Insecure):** ``/ip4/127.0.0.1/tcp/8080/ws``
+- **WSS (Secure):** ``/ip4/127.0.0.1/tcp/8080/wss``
+- **TLS/WS Format:** ``/ip4/127.0.0.1/tcp/8080/tls/ws``
+- **IPv6:** ``/ip6/::1/tcp/8080/ws``
+- **DNS:** ``/dns/example.com/tcp/443/wss``
+
+Production Considerations
+--------------------------
+
+1. **Security:**
+   - Always use WSS in production
+   - Use proper CA-signed certificates
+   - Enable certificate validation
+   - AutoTLS is for development/testing only
+
+2. **Performance:**
+   - Configure appropriate connection limits
+   - Set reasonable timeouts
+   - Monitor connection statistics
+   - Use connection pooling for high-traffic scenarios
+
+3. **Error Handling:**
+   - Handle ``OpenConnectionError`` for connection failures
+   - Implement retry logic for transient failures
+   - Monitor failed connection counts
+
+4. **Proxy Configuration:**
+   - Use environment variables for flexible deployment
+   - Test proxy connectivity before production deployment
+   - Monitor proxy connection statistics
+
+See Also
+--------
+
+- :doc:`libp2p.transport.websocket` - Full API documentation
+- :doc:`examples.echo` - Basic echo protocol example
+- :doc:`examples.echo_quic` - QUIC transport example for comparison