protoo Server Module

Common errors

• TypeError: peer.send is not a function

  cause 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

  cause 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

  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.
  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.

Warnings

• breaking The `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)`.
• breaking The `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.
• gotcha 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.
  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.

Install

• npm install protoo-server npm
• yarn add protoo-server yarn
• pnpm add protoo-server pnpm

Imports

• Server
  wrong:

  import { Server } from 'protoo-server';

  correct:

  import Server from 'protoo-server';

  The primary 'Server' class is the default export of the package.
• Room, Peer
  wrong:

  import Room, { Peer } from 'protoo-server';

  correct:

  import { Room, Peer } from 'protoo-server';

  These core classes are named exports. Do not attempt to import them as default.
• protoo-server (CommonJS)
  wrong:

  const Server = require('protoo-server');
  const { Server } = require('protoo-server');

  correct:

  const protoo = require('protoo-server');
  const Server = protoo.default;

  For CommonJS, access the default export via `.default`. Use named exports directly from the `require` result, e.g., `const { Room } = protoo;`

Quickstart

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 })');
});