Registry / http-networking / protoo-server

protoo-server

JSON →
library4.0.8jsnpmunverified

protoo-server is a Node.js module that forms the server-side component of the protoo signaling framework. This framework is designed for building minimalist and extensible signaling layers for multi-party Real-Time Communication (RTC) applications, such as video conferencing or collaborative tools. Currently at version 4.0.8, the library maintains a steady release cadence, evidenced by its significant major version updates. It differentiates itself by providing a clear, event-driven API for managing WebSocket connections, peers, and rooms, allowing developers to focus on RTC logic rather than low-level WebSocket intricacies. The module facilitates the creation of `Room`s to organize connected `Peer`s, enabling efficient message routing and state management within a signaling context. Its focus on being "minimalist" means it provides core signaling primitives without enforcing complex architectural patterns.

npm install protoo-server
INSTALL
IMPORT
SIG · PROTOO-SERVER
P
protoo-server
http-networkingjavascriptv4.0.8
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Server
import Server from 'protoo-server';
import { Server } from 'protoo-server';
The primary 'Server' class is the default export of the package.
Room, Peer
import { Room, Peer } from 'protoo-server';
import Room, { Peer } from 'protoo-server';
These core classes are named exports. Do not attempt to import them as default.
protoo-server (CommonJS)
const protoo = require('protoo-server'); const Server = protoo.default;
const Server = require('protoo-server'); const { Server } = require('protoo-server');
For CommonJS, access the default export via `.default`. Use named exports directly from the `require` result, e.g., `const { Room } = protoo;`

This quickstart sets up a basic protoo-server instance using WebSocket over HTTP. It demonstrates how to handle incoming peer connections, process requests and notifications from connected peers, and respond to a simple 'echo' or 'joinRoom' request, illustrating a fundamental signaling flow.

import * as http from 'http'; import { WebSocketServer } from 'ws'; import Server from 'protoo-server'; const httpServer = http.createServer(); const wsServer = new WebSocketServer({ server: httpServer, noServer: true }); const protooServer = new Server(); wsServer.on('connection', (ws, request) => { const { url } = request; if (!url) { ws.close(); return; } const peerId = url.split('/').pop() || `peer-${Date.now()}`; console.log(`New WebSocket connection from peer: ${peerId}`); let peer; try { peer = protooServer.createPeer(peerId, ws); } catch (error) { console.error(`Error creating protoo peer: ${error}`); ws.close(); return; } peer.on('request', async (request, accept, reject) => { console.log(`Peer '${peer.id}' sent request:`, request); try { const response = await handlePeerRequest(peer, request); accept(response); } catch (error) { reject(error); } }); peer.on('notification', (notification) => { console.log(`Peer '${peer.id}' sent notification:`, notification); }); peer.on('close', () => { console.log(`Peer '${peer.id}' disconnected.`); }); }); httpServer.on('upgrade', (request, socket, head) => { wsServer.handleUpgrade(request, socket, head, (ws) => { wsServer.emit('connection', ws, request); }); }); async function handlePeerRequest(peer, request) { switch (request.method) { case 'echo': return { message: `Echoing: ${request.data.text}` }; case 'joinRoom': // In a real app, you'd manage rooms here and add the peer console.log(`Peer '${peer.id}' wants to join room '${request.data.roomId}'`); peer.notify('roomJoined', { roomId: request.data.roomId, peers: [] }); return { joined: true }; default: throw new Error(`Unknown method: ${request.method}`); } } const PORT = process.env.PORT || 8080; httpServer.listen(PORT, () => { console.log(`protoo-server listening on ws://localhost:${PORT}`); console.log('Connect with protoo-client: protoo-client.createPeer(wsUrl, { requestTimeout: 3000 })'); });
Debug
Known issues
breakingThe `peer.send()` method has been renamed to `peer.request()`. Calls to the old method will result in a runtime error.
fix
Update all instances of `peer.send(data)` to `peer.request(data)`.
affects: >=4.0.0
breakingThe `room.spread()` method has been entirely removed from the `Room` class, affecting functionality for broadcasting messages.
fix
Remove any usage of `room.spread()`. You will need to implement custom logic for broadcasting messages to peers within a room, likely by iterating through `room.peers` and calling `peer.notify()` or `peer.request()` individually.
affects: >=4.0.0
gotchaprotoo-server relies on an external WebSocket server implementation (e.g., `ws` package) for the underlying transport. It does not provide its own WebSocket server.
fix
Ensure you have `ws` or a compatible WebSocket server installed and correctly configured to pass its instance or connections to `protoo-server.Server` during initialization.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: peer.send is not a function
Attempting to use the deprecated `send()` method on a `Peer` instance in protoo-server v4 or later.
fix
Rename `peer.send()` calls to `peer.request()`.
TypeError: room.spread is not a function
Attempting to use the removed `spread()` method on a `Room` instance in protoo-server v4 or later.
fix
The `room.spread()` method has been removed. Replace its functionality with custom iteration over `room.peers` to send notifications or requests to each peer.
Error: WebSocket connection to 'ws://localhost:8080' failed: WebSocket opening handshake timed out
The Node.js HTTP server or WebSocket server is not listening on the expected port, or there's a firewall/network issue preventing connection.
fix
Verify that `httpServer.listen()` is correctly called and that the port is not already in use. Check server logs for startup errors. Ensure the client is connecting to the correct WebSocket URL.
Upgrade
Version history
4.0.8latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
protoo-server — npm install protoo-server · libregistry