WebRTC Validation

Audience: contributors.

This checklist validates EP-02 #011 / #012 acceptance behavior for transport: 'webrtc':

• two-peer connection across machines
• STUN default and override behavior
• ICE gather default timeout (5000ms) and explicit timeout validation
• DataChannel defaults (ordered: true, reliable by default)
• connect-time BroadcastChannel fallback when signaling is unavailable on the same origin
• room lifecycle events (connected, peer:join, peer:leave, disconnected, error)

1) Start Relay Signaling Server

From repo root:

pnpm install
pnpm --filter @roomful/relay build
pnpm --filter @roomful/relay start

Default address: ws://127.0.0.1:8787.

Optional relay env overrides:

HOST=0.0.0.0 PORT=8787 MAX_CONNECTIONS=1000 pnpm --filter @roomful/relay start
curl http://127.0.0.1:8787/health

For cross-machine validation, use a reachable host/IP:

• Local machine relay example: ws://<host-lan-ip>:8787
• Cloud relay example: wss://relay.example.com

2) Configure Two Clients (Two Machines)

Open the same app build on machine A and machine B (different networks allowed).

Configure both clients with:

const room = createRoom('validation-room-1', {
  transport: 'webrtc',
  relayUrl: 'ws://<reachable-relay-host>:8787',
  webrtc: {
    // defaults shown explicitly for validation clarity
    iceGatherTimeoutMs: 5000,
    dataChannel: {
      ordered: true,
      protocol: 'roomful-v1',
      // no maxRetransmits => reliable default
    },
  },
});

Default behavior if omitted:

• stunUrls: uses Google public STUN (stun:stun.l.google.com:19302)
• webrtc.iceGatherTimeoutMs: 5000
• webrtc.dataChannel.ordered: true
• webrtc.dataChannel.maxRetransmits: unset (reliable)

3) Two-Machine Event Sequence Checklist

1. Connect machine A room instance.
2. Connect machine B room instance.
3. Expected:
   • both emit connected
   • both observe peer:join
   • peerCount increments to 1 on each side
4. Send event payload from A to B (room.useEvents().emit(...)), verify receipt on B.
5. Send event payload from B to A, verify receipt on A.
6. Close machine B tab/app.
7. Expected on A:
   • peer:leave emitted for B
   • peerCount decrements
8. If signaling disconnects while connected, expected on both affected clients:
   • room emits disconnected with reason
   • room status transitions to disconnected

4) BroadcastChannel Fallback Verification

1. Open two clients on the same origin (for example, two tabs of the same local app build).
2. Configure both clients with transport: 'webrtc' and an unreachable relayUrl value.
3. Keep BroadcastChannel available in the runtime.
4. Expected:
   • both clients still emit connected
   • both observe peer:join
   • event payloads still flow between the two tabs
5. Confirm this is same-origin only:
   • cross-machine peers should not connect in this fallback mode
   • if BroadcastChannel is unavailable, the connect attempt should fail instead of silently downgrading

5) ICE Timeout Verification

1. Temporarily set webrtc.iceGatherTimeoutMs to a low value (for example 25).
2. Induce a gather timeout condition in the test environment/network.
3. Expected:
   • transport error path is triggered
   • room emits error
4. Reset timeout to default (5000) after validation.

6) maxPeers Verification

1. Configure maxPeers to a small value (for example 2 total peers including self).
2. Attempt to join additional peers.
3. Expected:
   • no new peer connection contexts created beyond limit
   • existing peers continue to function

Related Docs

• Development setup
• Rooms and transports
• Core API
• Type reference
• Docs index