Documentation

---

Documentation / @forinda/video-sdk-signaling-adapter-express

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

Mount Forinda RTC SDK signaling onto an existing Express HTTP server. Reuses your app's http.Server for the WebSocket upgrade so signaling and your REST endpoints share one port.

Ships dual ESM + CJS because most Express codebases are still CJS-first.

For a no-Express, port-of-its-own server, use @forinda/video-sdk-signaling-server (CLI + library) or @forinda/video-sdk-signaling-adapter-ws (lower-level).

Install

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

Peer deps: express@^4 || ^5, ws@^8. Node ≥ 20.

Quick start

import express from "express";
import { createExpressSignaling } from "@forinda/video-sdk-signaling-adapter-express";

const app = express();

app.get("/", (_req, res) => {
  res.send("Hello + WebRTC signaling on /signaling");
});

const server = app.listen(3000, () => {
  console.log("HTTP + signaling on http://127.0.0.1:3000");
});

const signaling = createExpressSignaling({
  app,
  server,
  // Optional. Defaults to /signaling.
  path: "/signaling",
  authenticate: async (token, room) => verifyJwt(token, room),
});

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

Clients connect to ws://your-host:3000/signaling?token=… (the default token extractor reads ?token= from the upgrade URL).

API

createExpressSignaling(options) → ExpressSignalingHandle

Option	Type	Default	Description
app	express.Application	—	Required. Currently held for symmetry / future hooks; not used at runtime.
server	http.Server	—	Required. The HTTP server (typically the return value of app.listen(...)).
wss	WebSocketServer	new WebSocketServer({ noServer: true })	Bring your own server for advanced control (custom max-payload, perMessageDeflate, etc.).
path	string	/signaling	URL path the WebSocket upgrade fires on.
engine	SignalingEngine	defineSignalingEngine({...})	Pre-built engine. When omitted, the adapter constructs one passing authenticate + maxPeersPerRoom.
authenticate	AuthenticateFn	allow-all	Per-join auth. Forwarded to the default engine; ignored when engine is supplied.
maxPeersPerRoom	number	50	Capacity. Forwarded to the default engine.
socketId	(req: IncomingMessage) => string	crypto.randomUUID()	Per-connection identifier.
extractToken	(req: IncomingMessage) => string | undefined	reads ?token= from upgrade URL	Pulls the auth token off the upgrade request.

The handle returned has:

Field	Type	Purpose
wss	WebSocketServer	The underlying ws server.
engine	SignalingEngine	The engine driving validation and routing.
session	Session	The single shared session for all sockets.
close()	() => Promise<void>	Detach the upgrade listener and close the wss. Doesn't stop Express — call server.close() separately.

Sharing auth with Express middleware

The extractToken callback receives the raw Node IncomingMessage, so you can pull from cookies, headers, or any path-scoped auth pattern:

import cookie from "cookie";

createExpressSignaling({
  app,
  server,
  extractToken: (req) => {
    const cookies = cookie.parse(req.headers.cookie ?? "");
    return cookies["session"];
  },
  authenticate: async (sessionId, room) => {
    const user = await sessionStore.lookup(sessionId);
    return user !== null && user.roomsAllowed.includes(room);
  },
});

ESM + CJS interop

Both formats are exported from the same package:

// CJS
const { createExpressSignaling } = require("@forinda/video-sdk-signaling-adapter-express");

// ESM
import { createExpressSignaling } from "@forinda/video-sdk-signaling-adapter-express";

License

MIT.