Fix QUIC interop: Track Connection IDs for proper packet routing

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.rst

@@ -11,6 +11,7 @@ Examples
    examples.echo
    examples.echo_quic
    examples.ping
+   examples.interop
    examples.pubsub
    examples.bitswap
    examples.circuit_relay

docs/libp2p.transport.quic.rst

@@ -1,6 +1,55 @@
 libp2p.transport.quic package
 =============================
 
+Connection ID Management
+------------------------
+
+The QUIC transport implementation uses a sophisticated Connection ID (CID) management system
+inspired by the `quinn` Rust QUIC library. This system ensures proper packet routing and
+handles connection migration scenarios.
+
+Key Features
+~~~~~~~~~~~~
+
+**Sequence Number Tracking**
+   Each Connection ID is assigned a sequence number, starting at 0 for the initial CID.
+   Sequence numbers are used to ensure proper retirement ordering per the QUIC specification.
+
+**Initial vs. Established CIDs**
+   Initial CIDs (used during handshake) are tracked separately from established connection CIDs.
+   This separation allows for efficient packet routing and proper handling of handshake packets.
+
+**Fallback Routing**
+   When packets arrive with new Connection IDs before ``ConnectionIdIssued`` events are processed,
+   the system uses O(1) fallback routing based on address mappings. This handles race conditions
+   gracefully and ensures packets are routed correctly.
+
+**Retirement Ordering**
+   Connection IDs are retired in sequence order, ensuring compliance with the QUIC specification.
+   The ``ConnectionIDRegistry`` maintains sequence number mappings to enable proper retirement.
+
+Architecture
+~~~~~~~~~~~~
+
+The ``ConnectionIDRegistry`` class manages all Connection ID routing state:
+
+- **Established connections**: Maps Connection IDs to ``QUICConnection`` instances
+- **Pending connections**: Maps Connection IDs to ``QuicConnection`` (aioquic) instances during handshake
+- **Initial CIDs**: Separate tracking for handshake packet routing
+- **Sequence tracking**: Maps Connection IDs to sequence numbers and connections to sequence ranges
+- **Address mappings**: Bidirectional mappings between Connection IDs and addresses for O(1) fallback routing
+
+Performance Monitoring
+~~~~~~~~~~~~~~~~~~~~~~
+
+The registry tracks performance metrics including:
+
+- Fallback routing usage count
+- Sequence number distribution
+- Operation timings (when debug mode is enabled)
+
+These metrics can be accessed via the ``get_stats()`` method and reset using ``reset_stats()``.
+
 Submodules
 ----------
 

examples/interop/__init__.py

@@ -0,0 +1 @@
+"""Interoperability examples for py-libp2p."""