{"id":11599,"library":"protoo-server","title":"protoo Server Module","description":"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.","status":"active","version":"4.0.8","language":"javascript","source_language":"en","source_url":"https://github.com/ibc/protoo","tags":["javascript","nodejs","websocket"],"install":[{"cmd":"npm install protoo-server","lang":"bash","label":"npm"},{"cmd":"yarn add protoo-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add protoo-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary 'Server' class is the default export of the package.","wrong":"import { Server } from 'protoo-server';","symbol":"Server","correct":"import Server from 'protoo-server';"},{"note":"These core classes are named exports. Do not attempt to import them as default.","wrong":"import Room, { Peer } from 'protoo-server';","symbol":"Room, Peer","correct":"import { Room, Peer } from 'protoo-server';"},{"note":"For CommonJS, access the default export via `.default`. Use named exports directly from the `require` result, e.g., `const { Room } = protoo;`","wrong":"const Server = require('protoo-server');\nconst { Server } = require('protoo-server');","symbol":"protoo-server (CommonJS)","correct":"const protoo = require('protoo-server');\nconst Server = protoo.default;"}],"quickstart":{"code":"import * as http from 'http';\nimport { WebSocketServer } from 'ws';\nimport Server from 'protoo-server';\n\nconst httpServer = http.createServer();\nconst wsServer = new WebSocketServer({ server: httpServer, noServer: true });\n\nconst protooServer = new Server();\n\nwsServer.on('connection', (ws, request) => {\n  const { url } = request;\n  if (!url) {\n    ws.close();\n    return;\n  }\n  const peerId = url.split('/').pop() || `peer-${Date.now()}`;\n  console.log(`New WebSocket connection from peer: ${peerId}`);\n\n  let peer;\n  try {\n    peer = protooServer.createPeer(peerId, ws);\n  } catch (error) {\n    console.error(`Error creating protoo peer: ${error}`);\n    ws.close();\n    return;\n  }\n\n  peer.on('request', async (request, accept, reject) => {\n    console.log(`Peer '${peer.id}' sent request:`, request);\n    try {\n      const response = await handlePeerRequest(peer, request);\n      accept(response);\n    } catch (error) {\n      reject(error);\n    }\n  });\n\n  peer.on('notification', (notification) => {\n    console.log(`Peer '${peer.id}' sent notification:`, notification);\n  });\n\n  peer.on('close', () => {\n    console.log(`Peer '${peer.id}' disconnected.`);\n  });\n});\n\nhttpServer.on('upgrade', (request, socket, head) => {\n  wsServer.handleUpgrade(request, socket, head, (ws) => {\n    wsServer.emit('connection', ws, request);\n  });\n});\n\nasync function handlePeerRequest(peer, request) {\n  switch (request.method) {\n    case 'echo':\n      return { message: `Echoing: ${request.data.text}` };\n    case 'joinRoom':\n      // In a real app, you'd manage rooms here and add the peer\n      console.log(`Peer '${peer.id}' wants to join room '${request.data.roomId}'`);\n      peer.notify('roomJoined', { roomId: request.data.roomId, peers: [] });\n      return { joined: true };\n    default:\n      throw new Error(`Unknown method: ${request.method}`);\n  }\n}\n\nconst PORT = process.env.PORT || 8080;\nhttpServer.listen(PORT, () => {\n  console.log(`protoo-server listening on ws://localhost:${PORT}`);\n  console.log('Connect with protoo-client: protoo-client.createPeer(wsUrl, { requestTimeout: 3000 })');\n});\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Update all instances of `peer.send(data)` to `peer.request(data)`.","message":"The `peer.send()` method has been renamed to `peer.request()`. Calls to the old method will result in a runtime error.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"The `room.spread()` method has been entirely removed from the `Room` class, affecting functionality for broadcasting messages.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"protoo-server relies on an external WebSocket server implementation (e.g., `ws` package) for the underlying transport. It does not provide its own WebSocket server.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Rename `peer.send()` calls to `peer.request()`.","cause":"Attempting to use the deprecated `send()` method on a `Peer` instance in protoo-server v4 or later.","error":"TypeError: peer.send is not a function"},{"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.","cause":"Attempting to use the removed `spread()` method on a `Room` instance in protoo-server v4 or later.","error":"TypeError: room.spread is not a function"},{"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.","cause":"The Node.js HTTP server or WebSocket server is not listening on the expected port, or there's a firewall/network issue preventing connection.","error":"Error: WebSocket connection to 'ws://localhost:8080' failed: WebSocket opening handshake timed out"}],"ecosystem":"npm"}