76 lines
4 KiB
Markdown
76 lines
4 KiB
Markdown
# ECP-0063: Cloudflare MoQ Relay + WebTransport-Only Web Watch
|
|
|
|
Status: Draft
|
|
|
|
## Decision
|
|
|
|
Adopt Cloudflare's MoQ relay preview as the default "global" distribution layer and make the web watcher path WebTransport-only.
|
|
|
|
Concrete changes:
|
|
|
|
1. `ec-node` gains a WebTransport MoQ publisher path that can publish a live CMAF (fMP4) stream to a relay URL (default: `https://interop-relay.cloudflare.mediaoverquic.com/`).
|
|
2. `every.channel` (the deployed static site) becomes a real web watcher by embedding a WebTransport-capable MoQ player component (`<hang-watch>`).
|
|
3. The existing WebRTC/WS bootstrap directory/relay remains temporarily for compatibility, but is treated as deprecated once MoQ/WebTransport is stable.
|
|
|
|
## Motivation
|
|
|
|
The project goal is one-to-many live streaming at global scale without rebuilding a bespoke stateful SFU stack.
|
|
|
|
MoQ over WebTransport moves the core system boundary to:
|
|
- publisher produces timed objects (CMAF fragments),
|
|
- relays cache/fanout,
|
|
- subscribers fetch via a single WebTransport session.
|
|
|
|
This aligns the "global watcher" story with an infrastructure-native model rather than point-to-point rendezvous.
|
|
|
|
## Scope
|
|
|
|
In scope for this ECP:
|
|
- "Watch from the web" using WebTransport to a MoQ relay.
|
|
- "Publish from a node" to the relay, using ffmpeg to create fMP4 fragments.
|
|
- A shareable link format for `every.channel` to open a specific relay + broadcast name.
|
|
|
|
Out of scope (explicitly deferred):
|
|
- Global discovery/index of broadcasts.
|
|
- Manifest signing / Merkle availability / anti-junk (separate ECPs already exist).
|
|
- Safari support guarantees (implement anyway; provide guidance/flag notes).
|
|
- Multi-variant ladders and ABR (follow-on ECP once single-variant publish/watch works end-to-end).
|
|
|
|
## Technical Notes
|
|
|
|
### Relay default
|
|
|
|
Default relay endpoint is:
|
|
- `https://interop-relay.cloudflare.mediaoverquic.com/`
|
|
|
|
Nodes may override via CLI flags for self-hosted relays or future Cloudflare relay endpoints.
|
|
As of February 20, 2026, the production relay endpoint (`https://relay.cloudflare.mediaoverquic.com/`) is observed to close sessions immediately after MoQ `SETUP` for current clients, while the interop relay completes `SETUP` and `ANNOUNCE` tests.
|
|
|
|
### Web player
|
|
|
|
Use the `@kixelated/hang` web component:
|
|
- `<hang-watch url="..." name="..." controls>`
|
|
|
|
This is WebTransport + WebCodecs based, and is expected to interoperate with Cloudflare's current relay preview.
|
|
|
|
### Transport compatibility
|
|
|
|
Cloudflare's public relay currently implements a subset of the IETF MoQ Transport draft-07 and may not interoperate with
|
|
newer draft implementations.
|
|
|
|
Implementation choice:
|
|
- Cloudflare's relay preview currently does **not** support `ANNOUNCE` (namespace-style publishing). `ec-node wt-publish` uses the `moq-lite` publish model via `quinn` + `web-transport-quinn` + `moq-lite` and `moq-mux` (fMP4 ingestion) for Cloudflare relay compatibility.
|
|
- `ec-node wt-publish` is QUIC/WebTransport-only (no WebSocket fallback). NixOS deployments also set `MOQ_CLIENT_WEBSOCKET_ENABLED=false` as a belt-and-suspenders default for any other binaries that use `moq-native`.
|
|
- For Cloudflare relay interop, we patch `web-transport-proto` to send and accept the standard WebTransport subprotocol negotiation header (`sec-webtransport-protocol`) in addition to the legacy `wt-available-protocols`/`wt-protocol` headers. Without subprotocol negotiation, the relay may not select a `moqt-*` protocol and can close the session immediately after MoQ `SETUP`.
|
|
- If the relay does not select a WebTransport subprotocol, `ec-node wt-publish` attempts MoQ `SETUP` with protocol overrides (`moqt-16`, `moqt-15`, `moq-00`) before falling back to "no protocol".
|
|
|
|
### Share link
|
|
|
|
Web share link:
|
|
- `https://every.channel/watch?url=<relay-url>&name=<broadcast-name>`
|
|
|
|
## Rollout / Reversibility
|
|
|
|
- Keep existing `/api/*` bootstrap endpoints during migration.
|
|
- Make the web site prefer MoQ/WebTransport; keep legacy paths hidden behind "advanced" until removed.
|
|
- Reversible by switching the deployed assets back to the previous UI build, and/or pointing users at the legacy paths.
|