spike: aiortc ICE mux / STUN USERNAME exposure for webrtc-direct v2 listener

[yashksaini-coder]

Sub-spike of #546. Required before a spec-aligned /webrtc-direct listener can land.

Background

WebRTC-Direct v1 (libp2p/specs#672) and v2 (libp2p/specs#715) are no-signaling transports. The listener reconstructs the dialer's offer from the inbound STUN connectivity-check, reading the USERNAME attribute to recover ICE credentials and (for v2) the version-prefix dispatch (libp2p+webrtc+v1/ vs libp2p+webrtc+v2/).

js-libp2p solved this at the native ICE layer (murat-dogan/node-datachannel#420 exposes localUfrag on IceUdpMuxRequest). go-libp2p uses pion's ICE mux internals similarly.

py-libp2p uses aiortc. Whether aiortc gives us equivalent hooks is unknown today.

Goal

Determine — without committing to an implementation — whether aiortc exposes (or can be made to expose, via subclassing / monkey-patch / upstream PR):

1. Inbound STUN parsing: the USERNAME attribute of incoming connectivity checks before/during ICE negotiation, so the listener can branch on the version-prefix and reconstruct the dialer's offer.
2. Server-side credential override: setting local ufrag / pwd to the value parsed out of the STUN USERNAME before generating the answer (v2 step 6 in libp2p/specs#715).
3. ICE mux / shared UDP socket across multiple concurrent inbound dials, so one listening UDP port can demux to per-dial RTCPeerConnections without spinning up a port per peer.

Deliverables

• A spike doc (in this issue, a comment thread, or a short markdown PR) covering:
  • Which of the 3 capabilities aiortc currently exposes (public API, private-but-accessible, or genuinely absent).
  • For absent ones: feasibility of a subclass / monkey-patch / upstream contribution and a rough effort estimate.
• A go / no-go recommendation: does py-libp2p WebRTC-Direct listener land on aiortc, or do we need a different ICE / DTLS backend (e.g. wrap a Rust / C library)?

Why this isn't blocking #1309

PR #1309 lands experimental v1 node-to-node scaffolding (HTTP POST /sdp signaling, documented as a py-to-py temporary harness). Browser dial and go / js interop are explicitly out of scope there; the STUN listener path is a separate piece of work this spike unblocks.

Refs #546, #1309.

[yashksaini-coder]

Spike: aiortc ICE mux / STUN USERNAME hooks — findings

TL;DR: Two of the three required capabilities are achievable via small patches; ICE mux (#3) is the blocker and requires either a significant upstream contribution to aioice or a different ICE/DTLS backend.

---

Capability 1 — STUN USERNAME parsing before ICE negotiation

Verdict: NOT exposed via public API; private-accessible via monkey-patch.

What aioice does internally (aioice/ice.py):

# aioice/ice.py — Connection.request_received (private)
if self.remote_username is not None:
    rx_username = "%s:%s" % (self.local_username, self.remote_username)
    if message.attributes.get("USERNAME") != rx_username:
        raise ValueError("Wrong username")

The USERNAME attribute is only parsed and validated deep inside Connection._connection_handle_stun → request_received. There is no callback, hook, or event surfaced to callers before this point. The Connection has already been constructed by the time STUN packets arrive.

Can we hook it? Yes, but invasively: subclass aioice.Connection, override request_received, and inspect message.attributes.get("USERNAME") before calling super(). This would let a listener dispatch on the libp2p+webrtc+v1/ vs libp2p+webrtc+v2/ prefix in the ufrag. Effort: small (one method override), but fragile against aioice internal refactors.

---

Capability 2 — Server-side credential override (ufrag / pwd preset)

Verdict: Achievable; aiortc has a 3-line bug that silently drops the params.

aioice.Connection.__init__ directly accepts local_username and local_password — this works correctly at the aioice layer.

aiortc.RTCIceGatherer.__init__ accepts them in its signature:

def __init__(
    self,
    iceServers=None,
    local_username: Optional[str] = None,  # accepted...
    local_password: Optional[str] = None,  # ...but silently dropped
) -> None:
    ice_kwargs = connection_kwargs(iceServers)
    self._connection = Connection(ice_controlling=False, **ice_kwargs)
    # ↑ local_username / local_password never forwarded to Connection

Fix: Monkey-patch or subclass RTCIceGatherer.__init__ to pass local_username/local_password into the Connection constructor. That's the full fix — 3 lines. Would be worth upstreaming to aiortc as a bugfix.

---

Capability 3 — ICE mux / shared UDP socket across concurrent inbound dials

Verdict: NOT supported; architecturally absent from both aiortc and aioice.

aioice creates one OS UDP socket per Connection via:

# aioice/ice.py — Connection._gather_candidates
transport, protocol = await loop.create_datagram_endpoint(
    lambda: StunProtocol(self), local_addr=(address, 0)  # ephemeral port, not shared
)

Every Connection instance binds a fresh ephemeral port. There is no UdpMux abstraction, no shared socket, and no incoming-STUN-to-connection dispatch table anywhere in aioice or aiortc. The word "mux" appears in aiortc only for RTP/RTCP media mux — unrelated.

Impact on WebRTC-Direct listener: The listener needs to advertise a single fixed UDP port in its multiaddr. With the current aioice architecture, each inbound dialer would land on a different ephemeral port, which means we can't satisfy the protocol's "one advertised address demuxes multiple concurrent dials" requirement.

What it would take to add ICE mux to aioice:

• New UdpMux class owning one DatagramTransport
• Dispatch table mapping ufrag prefix → aioice.Connection
• Connection would need a constructor path that accepts an external transport instead of binding its own
• Roughly 200–400 lines of new aioice code; would need to be upstreamed or maintained as a fork

---

Go / No-Go recommendation

No-go for a spec-aligned WebRTC-Direct listener on aiortc/aioice without additional work.

Capability	Status	Effort to fix
1. STUN USERNAME dispatch	Accessible via subclass override	Low (fragile)
2. Credential preset	Bug in aiortc; fixable with 3-line patch	Low
3. ICE mux / shared UDP port	Architecturally absent	High

ICE mux (#3) is the hard blocker. Two paths forward:

Path A — Upstream aioice UdpMux: Implement UdpMux in aioice and open an upstream PR. High effort (~2–3 weeks), correct long-term, keeps us on aiortc. Feasibility: aioice is actively maintained and a UdpMux API is a natural extension.

Path B — Different ICE/DTLS backend: Wrap a library that already has ICE mux. node-datachannel solves this for js-libp2p. For Python, libdatachannel (the C++ library behind node-datachannel) exposes Python bindings via python-libdatachannel. pion (Go) is another option via subprocess/gRPC, but heavyweight. Effort: medium, but trades one binding for another.

Recommendation: Pursue Path A (aioice UdpMux). The aiortc/aioice stack is already integrated; the capability gap is narrowly in the socket layer, not in DTLS or SCTP. Opening a minimal UdpMux PR against aioice unblocks both py-libp2p and any other Python WebRTC-Direct implementor, and the credential-preset fix (#2) can go upstream as a separate aiortc bugfix immediately.

Refs: aioice ice.py:983 (socket binding), ice.py:1095 (STUN USERNAME validation), aiortc/rtcicetransport.py:184 (credential drop bug).