# ECP-0058: One-to-Many Web Bootstrap via Stream Relay DO (WebSocket)

Status: Draft

## Problem

Our initial web viewer path used a direct WebRTC data channel between publisher and viewer.
That path is fundamentally 1:1: once one viewer consumes the offer/answer, additional viewers
cannot join, which breaks the "send a link to mom" requirement and contradicts the project's
one-to-many goal.

TURN improves NAT traversal but does not change the 1:1 nature of WebRTC offers/answers.

We need a bootstrap path that:
- is one-to-many by construction
- works in a normal browser without plugins
- carries the same CMAF object stream the native pipeline already produces
- remains obviously replaceable by MoQ/WebTransport later (no long-term lock-in)

## Proposal

Add a per-stream fanout relay implemented as a Durable Object:

- `GET /api/stream/ws?stream_id=<id>&role=sub|pub`
  - Upgrades to a WebSocket.
  - `role=pub` registers a single publisher for the stream.
  - `role=sub` registers a subscriber.

Publisher behavior:
- Connect once to the relay DO (`role=pub`).
- Send the CMAF object stream as "direct-wire" chunked messages (same framing as the existing
  WebRTC direct path).
- Continue to refresh the directory listing while publishing (multiple viewers are supported).

Subscriber behavior:
- Connect to the relay DO (`role=sub`).
- Receive the live message stream.
- On connect, receive a buffered init segment (`chunk_index=0`) plus a small ring buffer of recent
  segments so playback can start immediately.

Web app behavior:
- The global live list (`/api/directory`) remains the discovery surface.
- "Watch" connects by `stream_id` to the relay websocket and plays via MSE.

## Wire Framing

We reuse the existing "direct-wire" message format:

- Each WebSocket message is binary and begins with a 1-byte tag:
  - `0x01` = STREAM chunk (payload is a slice of `[u32be frame_len][frame_bytes...]`)
  - `0x00` = FRAME (optional; not required)
  - `0x02` = PING (ignored)
- `frame_bytes` is `ec-moq::encode_object_frame(meta_json, data)`:
  - `[u32be meta_len][meta_json_bytes][data_bytes...]`

The relay DO decodes publisher STREAM chunks into frames only for buffering (to identify init vs
segments). For live fanout, it forwards publisher messages to subscribers as-is.

## Limits / Abuse Notes

This is not spam-resistant. It is a bootstrap relay.

Defensive bounds:
- Buffer only `init` plus the last N segments (currently 12) per stream DO.
- If publisher reassembly buffer grows beyond a few MiB (garbage input), reset it.

Future ECPs cover signatures/manifests/merkle/anti-junk.

## Rollout

1. Deploy Worker changes:
   - add Durable Object binding/class `StreamRelayDO`
   - route `/api/stream/ws` to it
2. Add `ec-node ws-publish` / `ec-node ws-subscribe`.
3. Update the web viewer to prefer the relay path for global watching.