@forinda/video-sdk-signaling-adapter-ws

Node ws-backed WebSocket signaling server adapter for the Forinda RTC SDK. Wires a SignalingEngine to a real WebSocketServer so any WebRTC client built with @forinda/video-sdk-core (or @forinda/video-sdk-react, or @forinda/video-sdk-elements) can negotiate against it.

For a no-config "just give me a server" experience, use @forinda/video-sdk-signaling-server — it wraps this adapter with a CLI and sensible defaults. Use this package directly when you want to run the adapter inside an existing Node process or share a WebSocketServer with another protocol.

Install

pnpm add @forinda/video-sdk-signaling-adapter-ws @forinda/video-sdk-signaling-protocol ws

Peer dep: ws@^8. Node ≥ 20.

Quick start

Stand up a server on its own port:

import { defineWebSocketSignalingServer } from "@forinda/video-sdk-signaling-adapter-ws";

const server = defineWebSocketSignalingServer({ port: 8787 });

console.log(`signaling on ws://127.0.0.1:${(server.wss.address() as { port: number }).port}`);

process.on("SIGTERM", async () => {
  await server.close();
  process.exit(0);
});

Or share an existing WebSocketServer (e.g. one already mounted on your HTTP server):

import { WebSocketServer } from "ws";
import { defineWebSocketSignalingServer } from "@forinda/video-sdk-signaling-adapter-ws";

const wss = new WebSocketServer({ port: 8080 });
const server = defineWebSocketSignalingServer({ wss });
// server.wss === wss

API

defineWebSocketSignalingServer(options) → WebSocketSignalingServer

Option	Type	Default	Description
wss	WebSocketServer	created on port	Bring your own ws server. Required when port is omitted.
port	number	—	Bind a freshly-created WebSocketServer to this port. Use 0 for an OS-assigned port.
engine	SignalingEngine	defineSignalingEngine({...})	Pre-built engine. When omitted, the adapter constructs one passing authenticate + maxPeersPerRoom below.
authenticate	AuthenticateFn	allow-all	Per-join auth callback. Forwarded to the default engine; ignored when engine is supplied.
maxPeersPerRoom	number	50	Capacity. Forwarded to the default engine; ignored when engine is supplied.
socketId	(req: IncomingMessage) => string	crypto.randomUUID()	Per-connection identifier (used internally by the engine for routing).
extractToken	(req: IncomingMessage) => string | undefined	reads ?token= from request URL	Pulls the auth token off the upgrade request before passing to authenticate.

The handle returned has:

Field	Type	Purpose
wss	WebSocketServer	The underlying ws server (yours or new).
engine	SignalingEngine	The engine driving validation and routing.
session	Session	The single shared session for all sockets.
close()	() => Promise<void>	Drain clients, detach listeners, close the wss.

Authentication

const server = defineWebSocketSignalingServer({
  port: 8787,
  authenticate: async (token, room) => {
    if (token === undefined) return false;
    const claims = await verifyJwt(token);
    return claims.allowedRooms.includes(room);
  },
});

Tokens are extracted from ?token=… on the WebSocket upgrade URL by default. Override extractToken to pull from a header or cookie:

defineWebSocketSignalingServer({
  port: 8787,
  extractToken: (req) => req.headers["x-room-token"]?.toString(),
  authenticate: (token, room) => verifyJwt(token, room),
});

What it doesn't do

• No HTTP layer. Use @forinda/video-sdk-signaling-adapter-express when you need an Express HTTP app sharing the same port, or wrap your own http.Server and pass its WebSocketServer via wss.
• No persistence. Rooms and presence live in-process. For horizontal-scale deployments you'll need a Redis pub/sub layer (on the roadmap).
• No rate limiting. Per-peer rate limits are on the roadmap. Until then, gate at the WebSocket layer (ws's maxPayload, OS-level connection limits, or a reverse-proxy quota).

License

MIT.

---

Browse the per-symbol API reference for @forinda/video-sdk-signaling-adapter-ws →