feat(webrtc): WebRTC-Direct v2 flow (libp2p/specs#715) — listener accepts v2, dialer opt-in

[yashksaini-coder]

What

The v2 flow from libp2p/specs#715, on top of the v1 listener that landed in #1449.

• Listener accepts libp2p+webrtc+v2/ first contacts alongside v1: recovers client_pwd by stripping the prefix (rejected unless a valid ice-pwd, 22–256), infers the offer with ice-ufrag=client_ufrag / ice-pwd=client_pwd, and sets its own ufrag and pwd to server_ufrag verbatim. Unknown/missing prefix still rejected; v1 unchanged (pwd = client half).
• Dialer gets an opt-in WebRTCTransportConfig(webrtc_direct_dial_version=2): no munging — it reads its aioice-generated pwd and encodes it in the synthetic answer's ufrag/pwd as libp2p+webrtc+v2/<client_pwd>. Default stays v1 until specs#715 merges.
• Docs: README + module docstrings; newsfragment extended.

Verified

• Loopback: echo over stun-v1 / stun-v2 / harness, mixed v1+v2 dials on one port, no-munge assertion, short-pwd reject leaves no state. 235 tests; mypy/ruff/pyrefly clean.
• Live against go-libp2p v0.49.0: go v2 dialer → py listener and py v2 dialer → go listener both connect (needs the framing fix in fix(webrtc): decode data-channel framing as a byte stream; SCTP stream-id parity by DTLS role #1460).

Stacked on #1460. Refs #1437 (v2 item); go/js interop tests come next.

[yashksaini-coder]

@seetadev @acul71 Ready for review — stacked on #1460, CI 37/37 green, rebased on current main (re-checked against the new varint error-type changes from #1462; decode_varint_with_size's documented contract is exactly what our framing relies on). go v2 dialer ↔ py and py v2 dialer ↔ go verified live.

[acul71]

🤖 AI-Assisted Maintainer Review (acul71)

Reviewed on branch feat/webrtc-direct-v2 (0 behind / 10 ahead of main).
Checks: make lint ✅ · make typecheck ✅ · make test ⚠️ 3 pre-existing Kademlia flakes, 3459 passed · make linux-docs ✅ · merge conflicts: none.

---

Overall

Good, spec-faithful implementation of WebRTC-Direct v2 on top of #1449. The credential derivation, no-munge dialer path, _decode_frames byte-stream accumulation, and SCTP stream-id parity fix are all correct and well-commented. The 3 test failures are pre-existing Kademlia flakiness unrelated to this PR.

Quality: Good · Security impact: Low · Merge readiness: Needs minor fixes

---

🔴 Required before merge

[M1] _decode_frames — head[consumed - 1] wraps silently if consumed == 0

libp2p/transport/webrtc/stream.py, inside _decode_frames:

length, consumed = decode_varint_with_size(bytes(head))
if head[consumed - 1] & 0x80:   # ← wraps to head[-1] if consumed == 0

decode_varint_with_size on a non-empty buf should always return consumed >= 1, but that assumption is not enforced here. Add a guard:

if consumed == 0:
    raise ValueError("empty varint prefix")

[M2] _apply_batch_on_trio_thread — processing continues after a RESET frame mid-batch

libp2p/transport/webrtc/stream.py:

for payload, flag in items:
    if payload:
        self._read_send.send_nowait(payload)   # called after RESET
    ...
    elif flag == Message.RESET:
        self._reset_locally()
    # loop continues — subsequent items still delivered to a reset stream

After _reset_locally() sets StreamState.RESET, the inner loop keeps running. A malformed or adversarial peer could craft a batch with RESET followed by more data and still have it enqueued. Fix:

for payload, flag in items:
    if self._state == StreamState.RESET:
        break
    ...

---

🟡 Should fix before merge

[m2] assert hasattr(dtls, "_role") is stripped by -O

libp2p/transport/webrtc/_aiortc_helpers.py line 358:

assert hasattr(dtls, "_role"), "RTCDtlsTransport has no attribute '_role'"

assert is a no-op with PYTHONOPTIMIZE=1. If _role disappears in a future aiortc version the parity re-seed silently falls through and stream-id collisions reappear. Replace with:

if not hasattr(dtls, "_role"):
    logger.warning(
        "channel %d: RTCDtlsTransport has no '_role'; using aiortc default parity",
        channel_id,
    )
else:
    role = dtls._role

[m5] README needs an "experimental / spec pending" callout for webrtc_direct_dial_version=2

The README documents WebRTCTransportConfig(webrtc_direct_dial_version=2) without a visible note that specs#715 is still unmerged and v2 interop is not yet guaranteed. The config.py comment says this, but README readers won't see it. Add a short caveat next to the v2 example.

---

🟢 Minor / optional

• [m1] newsfragments/1437.{bugfix,feature}.rst are now very long single-line strings. towncrier reflows them fine, but they're hard to diff. Consider wrapping at ~80 chars.
• [m3] _data_channel_id is re-seeded before every createDataChannel call. A comment explaining why repeating this on subsequent channels is safe (aiortc bumps past in-use ids) would help future maintainers.
• [m4] test_ids_follow_dtls_role_and_are_recycled uses asyncio.run(self._run()) instead of @pytest.mark.trio. Not a blocker, but inconsistent with project convention.

---

Questions for @yashksaini-coder

1. Stacking on #1460 — the current branch already contains all of #1460's commits (framing + stream-id parity). Is the plan to merge this PR and close #1460 as superseded, or to merge #1460 first and rebase?
2. Mid-batch RESET (M2) — can a valid peer ever send a RESET frame followed by more data in the same batch? If not, the break guard is unconditionally safe to add.
3. read(n=None) spin (minor) — the while not self._buffer and await self._fill(): pass loop in DataChannelReadWriter could spin on a stream of flag-only frames with no payload bytes. Is there a Noise-handshake timeout that would bound this in practice?
4. Go/JS interop follow-up — is there an issue or planned PR for the interop tests mentioned in the PR description?

[yashksaini-coder]

@acul71 All items in via d87292c1 (merged up from #1460) + d3906467:

• M1 consumed == 0 guard (raises, with a regression test — rationale on fix(webrtc): decode data-channel framing as a byte stream; SCTP stream-id parity by DTLS role #1460).
• M2 batch application stops at RESET — a crafted [RESET, data] batch no longer delivers the trailing data (test added). To your Q2: correct, a valid peer never sends post-RESET data, so the guard is unconditional.
• m2 the _role assert is now a warning + fallback. m5 README marks dial v2 experimental with a specs#715 link. m1 newsfragments wrapped. m3 the re-seed safety note is in the _create_channel comment ("aiortc bumps by 2 past ids in use"). m4 asyncio.run there follows the module's documented outside-trio_mode convention — can convert if preferred.

Q1 (stacking): merge #1460 first and I'll rebase this, or merge this and close #1460 as superseded — your call, both are ready. Q3 (flag-only spin): each _fill iteration awaits one channel message from the peer, and both handshake call sites sit inside trio.fail_after(handshake_timeout), so it's bounded at 30 s. Q4: yes — go/js interop tests are the next PR on #1437; the live go-v0.49 harness used to verify this stack is its seed.