⁠Implement WebRTC peer-to-peer mesh fallback in client/sw.js⁠

[ProofTubeProtocol]

Overview

Add WebRTC data-channel handling so client players can share HLS segment chunks directly with nearby peers when CDN bandwidth is constrained.

Core Requirements

• Implement signaling listener over Nostr relays to discover nearby video watchers.
• Seed downloaded HLS video segments to connected WebRTC peers.
• Verify segment hashes against master manifest to ensure chunk integrity.

Resources & Specs

Refer to Section 2.1 of WHITEPAPER.md.

[ProofTubeProtocol]

Hi @melvincarvalho! Following up on our Reddit chat regarding WebRTC implementations.
We're mapping out our peer-to-peer mesh fallback handling inside the Service Worker for ProofTube. Would love to get your thoughts or notes on this issue whenever you have a moment!

[melvincarvalho]

Hi! Thanks for the ping — happy to share notes. We've built and tested WebRTC signaling for JSS (JavaScriptSolidServer), and I think there's a real interop opportunity here. Three observations first, because they'll save you (and your AI tooling) weeks:

1. WebRTC APIs don't exist in service workers. RTCPeerConnection isn't available in the SW global scope, so the mesh described in this issue can't live in sw.js. The working architecture: peer connections in the page (or a dedicated worker), with the SW intercepting segment fetches and serving mesh-fetched chunks from Cache Storage.

2. PeerTube already ships the mesh. Since your whitepaper builds on the PeerTube engine — its player already does WebRTC segment sharing with hash verification via p2p-media-loader. The genuinely novel work in your design isn't the mesh; it's discovery and signaling over Nostr, which is worth doing well.

3. Make the content hash the room key, not just a check. If peers discover each other by SHA-256 of the content (segment/manifest), integrity is verifiable by construction and you inherit interop with the entire WebTorrent ecosystem — your S3/CDN fallback even has a standard form (HTTP webseeds, BEP 19).

On our side: JSS pods expose a signaling endpoint speaking three dialects on one WebSocket — identity-based (offer/answer/candidate/hangup routed by WebID or did:nostr, with presence — i.e. a calling protocol), content-addressed rooms (hex hash = room, anonymous OK), and the stock WebTorrent tracker protocol. A live one is running at wss://melvin.me/.webrtc — announce an info_hash from any WebTorrent client and it answers today.

Where I think interoperability lives is a thin layering, not a shared codebase: Nostr relays for wide-area discovery ("who has this content, anywhere?"), pod/WSS signaling for fast connection setup (trickle ICE will hurt on rate-limited relays), content hashes as the shared room key, and Nostr keys as identity — verified at the socket, then peer-to-peer via a signed challenge over the DataChannel (which is exactly the primitive your Proof-of-Viewer receipts need, and what makes "validating nodes" just another peer that fetches, verifies, and signs). Anything speaking those layers interoperates: HLS meshes, torrents, games, video calls.

Two honest caveats from our experience. First, NAT traversal is the unglamorous 15% that decides real-world connect rates — we've written TURN credential minting (coturn REST pattern) but haven't burned the operational hours yet; your whitepaper doesn't mention it, and it will matter more than most of the token layer. Second, since you're building with AI assistance: write the conformance tests before the implementation. Our signaling test suite caught two real races (messages lost while auth resolves; the welcome frame coalescing with the WS handshake) that any fresh implementation will hit. Happy to share the test client and golden transcripts as a starting point if useful.

[ProofTubeProtocol]

Hi Melvin (@melvincarvalho),

Thank you so much for taking the time to write such a comprehensive and actionable review. This is incredibly valuable feedback that saves us weeks of architectural dead-ends—especially regarding the Service Worker WebRTC limitation and using SHA-256 hashes for room discovery.

A few quick takeaways on our end based on your notes:

1. Architecture Alignment: We will adjust our client specification to keep RTCPeerConnection in the main thread/dedicated worker while using sw.js strictly for intercepting fetches and serving from Cache Storage.
2. Nostr Discovery & Signaling: Fully agree—focusing heavily on Nostr relays for wide-area discovery and Nostr keys for DataChannel authentication keeps our scope clean while enabling interoperability.
3. NAT Traversal & Testing: Adding TURN server integration to our infrastructure roadmap now. We would love to take you up on your offer to look at your signaling test suite and golden transcripts—that will be massive for preventing race conditions early.

Thanks again for the guidance and for sharing your signaling endpoint (wss://melvin.me/.webrtc). Looking forward to collaborating further as we refine the spec!

[melvincarvalho]

Glad it was useful! Here's the test material as promised.

The suite: webrtc/plugin.js (396 lines, all three dialects) and webrtc/test.js (284 lines) in the JSS plugins repo, plus turn/ for the TURN credential minting when you get to NAT traversal. The two races worth stealing the fixes for, since any fresh implementation hits them: (1) messages arriving while auth is still resolving must be buffered and replayed — attach a buffering listener at socket creation, swap handlers synchronously after auth; (2) the server's welcome frame can coalesce into the same TCP segment as the 101 handshake, so a client that attaches its message listener after await open silently misses it (browsers are safe; node ws clients aren't).

A golden transcript, captured just now against the live endpoint — two anonymous peers meeting in a content-addressed room and exchanging SDP through it:

# wss://melvin.me/.webrtc — room = c0ffee006a6f34f5 (fresh; the hex hash is the only rendezvous)
A -> {"type":"announce","resource":"c0ffee006a6f34f5","offers":[]}
A <- {"type":"resource-peers","resource":"c0ffee006a6f34f5","count":0}
B -> {"type":"announce","resource":"c0ffee006a6f34f5","offers":[{"offer_id":"o1","sdp":"v=0 (dummy offer B)"}]}
A <- {"type":"offer","resource":"c0ffee006a6f34f5","from":"4","offer_id":"o1","sdp":"v=0 (dummy offer B)"}
B <- {"type":"resource-peers","resource":"c0ffee006a6f34f5","count":1}
A -> {"type":"answer","resource":"c0ffee006a6f34f5","to":"4","offer_id":"o1","sdp":"v=0 (dummy answer A)"}
B <- {"type":"answer","resource":"c0ffee006a6f34f5","from":"5","offer_id":"o1","sdp":"v=0 (dummy answer A)"}
A -> {"type":"leave","resource":"c0ffee006a6f34f5"}
B -> {"type":"leave","resource":"c0ffee006a6f34f5"}

Note the semantics: offers flow from the announcing peer to peers already in the room (WebTorrent tracker convention), and after the answer the pod's job is done — media/data flows peer-to-peer. If your client speaks this plus the tracker dialect, it interoperates with JSS pods and stock WebTorrent today; swap the room hash for your segment/manifest SHA-256 and this is your mesh discovery. For your conformance suite, I'd suggest replaying transcripts like this against your implementation as the first test — then adding your Nostr-discovery layer on top with the same discipline.

[ProofTubeProtocol]

Thanks for passing this along Melvin! This test material and golden transcript are really helpful for our WebRTC setup.

[melvincarvalho]

No worries! I have a few servers running, if you want to test, or try out some use cases. Things im already using it for testing:

• some realtime games
• webtorrent
• bitcoin validating node with block sharing

Here is a webrtc playground we made: https://play-grounds.github.io/webrtc/

Source: https://github.com/play-grounds/webrtc

[ProofTubeProtocol]

Thanks Melvin, this playground and source code are huge! Since you already have the test servers running and the playground built, I'd love to collaborate with you on building out the ProofTube client module.
How would you like to structure this? Do you want to take the lead on the signaling integration, or should we break down a few GitHub issues together to track the build?

[melvincarvalho]

Happy to keep supporting this! On structure, though, I'd suggest a different split: the client module should be your code, in your repo — that's also what any grant reviewer will want to see from your team. Here's what I can commit to from my side:

• The live endpoint stays up (wss://melvin.me/.webrtc) for you to develop against, and I'll flag any breaking changes ahead of time.
• I'll review PRs on your client against the golden transcript — replaying it should be your first passing test, before any UI.
• Questions answered here on protocol semantics, the auth dialects, or the Nostr discovery layer as you design it.

A suggested first milestone that's small enough to be real: a page (no video yet) that joins a content-addressed room for a hard-coded hash, completes offer/answer with a second tab through the endpoint, opens a DataChannel, and transfers one SHA-256-verified chunk. That's the entire mesh in miniature — everything else (HLS, receipts, Nostr discovery) layers on top of it. Once that's green in your repo, I'm glad to pair on the genuinely hard parts — ICE edge cases and the relay-based discovery design.

[melvincarvalho]

We've written up how our side works as a standalone spec: Pod Signaling Protocol, draft 0.0.1 — CC0, so you can take all of it, parts of it, or none of it under your MIT license without any entanglement with our AGPL code. To be clear about its ambitions: it's documentation of what we built and why, not a standard — the timing rules and error tables are there because they bit us, and the conformance section is just "replay the golden transcript in both roles."

What I think would be genuinely valuable next: a smoke test of two independent servers. If you stand up your own signaling server (implementing whichever dialects you keep), we test in three steps: (1) both servers pass the same transcript; (2) crossed clients — your client against wss://melvin.me/.webrtc, our test client against yours; (3) the interesting one: a peer joins the same content-hash room on both servers and bridges a mesh between a peer on yours and a peer on ours. Step 3 works with no server-to-server protocol at all — and it surfaces the real open question, which is discovery: how does a peer learn which servers host a room? That's exactly where your Nostr-relay layer belongs, and I'd rather design it from a working two-server demo than from prose.

Then simple use cases to find the rough edges: one SHA-256-verified chunk between two tabs; a stock WebTorrent client meeting a spec-implementing client in the same info-hash room; a call between two authenticated agents. Known rough edges you'll hit early, so they're not surprises: cold room joins cost two round trips (announce empty, read the peer count, re-announce with that many offers), and the room dialect has no trickle ICE — candidates ride in the SDP. Both are fixable; whether they're worth fixing is what the smoke test is for.

[ProofTubeProtocol]

Hi Melvin,
• ••
I've set up the project repository and deployed the minimal single-page WebRTC
test client live here:
https://prooftubeprotocol.github.io/
prooftube!
The page successfully establishes a WebSocket connection to wss:// melvin.me/.webrtc and transmits the initial announce payload. Currently, the server
returns {"type": "error", "message": "Invalid resource hash"}.
Could you provide an active resource/ stream hash from your backend so we can test the full peer-to-peer DataChannel handshake between two clients?

[jjohare]

hello!!! I have a bunch of WebRTC in my ecosystem that's JSS adjacent, this looks like something I need to align to as soon as I get the time. Thanks both, for all the detail.

[ProofTubeProtocol]

Thanks John! Really glad to hear that. Once Melvin drops an active hash and we finish testing the DataChannel flow, we'd love to collaborate on aligning it with the JSS/WebRTC tooling.

[melvincarvalho]

Great — a live client on day one is exactly the right move! The error is a one-word fix, plus a few spec mismatches you'd hit right after it. In order:

1. The field is resource, not room (SPEC §6). Your hash is valid — no need for anything from our backend, and that's the key concept: rooms aren't provisioned server-side. Any hex hash matching ^[a-fA-F0-9]{8,128}$ becomes a room the moment the first peer announces into it. Pick any hash you like; in production it's the SHA-256 of the content, so discovery and integrity are the same act.
2. Room offers travel inside announce, not as standalone frames (§6). A bare {type:"offer"} without resource is dispatched to the identity dialect (§3) and will get Authentication required. Flow: announce with empty offers, read resource-peers.count, then re-announce with offers: [{offer_id:"o1", sdp}] — one offer per peer you want to reach.
3. count already excludes you — it's "peers already present," so offer when count > 0. With your current count > 1, two tabs will sit staring at each other forever.
4. Wait for ICE gathering to complete before sending SDP. The room dialect has no trickle ICE (this is one of the rough edges I mentioned), so candidates must be baked into the SDP: after setLocalDescription, wait for icegatheringstatechange === "complete" and send pc.localDescription.sdp, not the initial offer.sdp.
5. Small one: peer ids are server-assigned — the from you receive is the server's id for the other peer (your generated peer_id is ignored). Your to: msg.from in the answer is already correct once the field names match.

With those five changes, two tabs of your page should complete the DataChannel handshake against wss://melvin.me/.webrtc as-is. The golden transcript in SPEC §10 shows the exact frames you should see in your log console — if your log matches it line-for-line, you've effectively passed the first conformance test without writing a test harness.

[ProofTubeProtocol]

Hey Melvin, gave the WebRTC fallback testing a run across two local client tabs tonight. Both clients connect to ⁠wss://melvin.me/.webrtc⁠ fine and announce to the room hash, but the signaling server returns ⁠"count": 0⁠ to both peers—even when joined within seconds of each other. Because count stays at 0, neither client triggers the WebRTC offer/answer exchange before the WebSocket times out and closes .

[melvincarvalho]

Good news: the server's fine — I just replayed your exact frames (same hash, peer_id field and all) against the live endpoint: first socket gets count:0, second gets count:1, offers relay. Three things are biting you, one of them ours:

1. count:0 for the first tab is correct — count excludes you; it's "peers already there when you announced." The second tab sees count:1 and is the one that should offer. But your handler can't see it: the condition msg.type === "announce" || msg.type === "peers" || msg["resource-peers"] never matches the actual frame {type:"resource-peers", ...} — the third clause checks a property, not the type. It should be msg.type === "resource-peers".
2. Two fixes from my last comment are still pending and will bite next: the standalone {type:"offer"} frame (offers must ride inside a re-announce: {type:"announce", resource, offers:[{offer_id,sdp}]} — as sent, yours will get Authentication required), and peer matching — relayed offers carry a server-assigned from (your peer_id field is ignored), answers arrive with from/offer_id, not to. Match on those. Also still needed: wait for icegatheringstatechange === "complete" before sending SDP.
3. The timeout is real, and it's on our side of the fence: idle sockets are dropped after ~50s (close 1006) by the reverse proxy in front of the endpoint. Until we improve that, send a keepalive while waiting: re-announce (with empty offers) every ~25s — announce is an idempotent membership refresh, so this is spec-clean. The spec now documents this in §2.1; this is exactly the kind of rough edge the smoke testing was meant to surface, so thanks for the report.

Sequence your log should show, verbatim, when it works: the golden transcript in SPEC §10.