WebRTC Signaling Server

A premium, high-performance, in-memory WebRTC coordination server built using Cloudflare Workers and Durable Objects.

Overview

This server provides the immediate coordination required to link WebRTC peers (such as web clients, local servers, or autonomous AI agents) inside virtual "Rooms". Because standard WebRTC requires a third-party channel to exchange session descriptions (SDP offers and answers) and ICE candidates before setting up peer-to-peer data channels, this worker provides:

• Zero-latency coordination: All room signaling logic executes inside a persistent, stateful in-memory Durable Object.
• Server-Sent Events (SSE): A lightweight connection channel from the server to clients for roster status updates and incoming signals.
• Private Session Verification: Each peer receives a private UUID token upon connection. All signals and leave operations must sign with this token to guarantee authenticity.
• Reconnection Support: Allows disconnected clients to reuse their Peer UUID and reclaim their channel if they reconnect within 90 seconds.

Protocol Flow Diagram

The coordination workflow involves a Connection phase (establishing SSE stream), a Signaling phase (exchanging SDP packets via POST to trigger SSE), and a Graceful Closure phase.

Client A (SSE Connection)        Signaling DO (Durable Object)        Client B (SSE Connection)
    |                                        |                                    |
    |--- GET /api/connect?room=ROOM -------->|                                    |
    |<-- event: joined {id, token} ----------|                                    |
    |                                        |<-- GET /api/connect?room=ROOM -----|
    |                                        |--- event: joined {id, token} ------>|
    |<-- event: roster [A, B] ---------------|                                    |
    |                                        |--- event: roster [A, B] ---------->|
    |                                        |                                    |
    |=== WebRTC Offer (Signaling Phase) ===  |                                    |
    |--- POST /api/signal (to: B) ---------->|                                    |
    |    (JSON Body + Private Token)         |--- event: signal {sender: A} ----->|
    |                                        |                                    |
    |                                        |<-- POST /api/signal (to: A) -------|
    |<-- event: signal {sender: B} ----------|    (JSON Body + Private Token)     |
    |                                        |                                    |
    |======================= Direct Peer-to-Peer Data Channel ====================|
    |<===========================================================================>|

Keepalive Mechanism

Cloudflare Workers and intermediate proxies close idle connections automatically. To prevent this, the Durable Object sends a keepalive comment (: keepalive\n\n) every 10 seconds. Additionally, if a client disconnects unexpectedly, the server retains the session context for 90 seconds to allow reconnection before pruning.

Connect Endpoint

Establishes a persistent Server-Sent Events stream to receive events for the specified room.

Query Parameters

SSE Event Types

The stream returns the following custom SSE events:

1. event: joined

Sent immediately after a new client successfully connects.

{
  "id": "e93ab7e2-4115-4ba2-921c-a9d023b123aa",
  "token": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "iceServers": [
    {
      "urls": ["stun:openrelay.metered.ca:80", "turn:openrelay.metered.ca:80?transport=udp"],
      "username": "...",
      "credential": "..."
    }
  ]
}

2. event: roster

Sent to all active peers in the room whenever a participant joins or leaves.

[
  "e93ab7e2-4115-4ba2-921c-a9d023b123aa",
  "92ba3c1b-252e-4b6b-8f19-32cf4b912a77"
]

3. event: signal

Sent when another peer in the room sends a signaling packet directed to this client.

{
  "sender": "92ba3c1b-252e-4b6b-8f19-32cf4b912a77",
  "signal": {
    "sdp": { "type": "offer", "sdp": "..." }
  }
}

Signal Dispatch Endpoint

Dispatches a WebRTC signaling payload (SDP or ICE Candidate) to another peer inside the room.

JSON Body Fields

Responses

Success Response:

// 200 OK
{ "success": true }

Rate Limited Response:

// 429 Too Many Requests
{ "error": "Too Many Requests: signaling rate limit exceeded" }

Note: Senders are limited to a burst capacity of 50 signals with a refill rate of 10 tokens per second to prevent Durable Object memory exhaustion.

Leave Endpoint

Gracefully closes your session, disconnects the SSE connection stream, and broadcasts a roster update.

JSON Body Fields

Response

// 200 OK
{ "success": true }

Integration Guides

Check the links in the header for the complete agent integration guide. Below are short snippets showing how to connect to this server.

const room = "SANDBOX-ROOM";
const eventSource = new EventSource(`/api/connect?room=${room}`);

eventSource.addEventListener("joined", (event) => {
  const { id, token, iceServers } = JSON.parse(event.data);
  console.log("My assigned ID:", id);
  console.log("My token:", token);
});

eventSource.addEventListener("roster", (event) => {
  const activePeers = JSON.parse(event.data);
  console.log("Active peers in room:", activePeers);
});

eventSource.addEventListener("signal", (event) => {
  const { sender, signal } = JSON.parse(event.data);
  console.log("Incoming signal from peer:", sender, signal);
});

import httpx
import json
import asyncio

async def connect_to_room():
    url = "http://localhost:3000/api/connect?room=SANDBOX-ROOM"
    async with httpx.AsyncClient() as client:
        async with client.stream("GET", url, timeout=None) as response:
            async for line in response.iter_lines():
                if line.startswith("data:"):
                    data = json.loads(line.replace("data:", "").strip())
                    print("Received Event data:", data)

asyncio.run(connect_to_room())

Interactive Live Sandbox

Simulate a real participant connection to the signaling worker directly from this browser tab! You can also open this page in a separate tab or window to watch peers connect, update the roster, and signal each other live.