RTCForge API Reference v1.1.1
    Preparing search index...

    Class SignalingServer

    WebSocket signaling server that brokers WebRTC negotiation between peers grouped into rooms.

    The server accepts WebSocket connections, authenticates each one through the AuthFunction configured in SignalingServerOptions.auth, places the peer into the room named by its auth payload, and relays directed signal and room-wide broadcast messages between peers. It also enforces per-peer rate limiting (SignalingServerOptions.rateLimit), prunes dead connections with a ping/pong heartbeat (SignalingServerOptions.pingInterval / SignalingServerOptions.pongTimeout), and — when SignalingServerOptions.cluster is set — shards rooms across nodes via a RoomRouter, redirecting connections that reach the wrong node.

    It extends the core EventEmitter and emits ServerEvent values: ServerEvent.RoomCreated, ServerEvent.RoomClosed, and ServerEvent.Error.

    import { SignalingServer, ServerEvent } from 'rtcforge-signaling'

    const server = new SignalingServer({
      port: 3000,
      auth: async (token) => {
        const claims = await verifyJwt(token)
        return { roomId: claims.room, peerId: claims.sub, role: claims.role }
      },
      maxPeersPerRoom: 8,
      rateLimit: { maxMessagesPerSecond: 50 },
    })

    server.on(ServerEvent.RoomCreated, (room) => {
      console.log('room created', room.id)
    })

    await server.start()
    // ... later
    await server.stop()

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Accessors

    port

    Methods

    attachHealthEndpoint emit getOwner getRoom getStats listenerCount off on once removeAllListeners start stop

    Constructors

    Accessors

    Methods

    • Registers a JSON health endpoint on an existing HTTP server.

      Parameters

      • server: Server

        The HTTP server to add the listener to.

      • path: string = '/health'

        The URL path to serve.

      Returns void

      Responds to GET {path} with 200 and a body of { status: 'ok', ...ServerStats }. Other methods and paths are ignored, so this can be attached alongside your own request handlers.

      '/health'

      import http from 'node:http'
      const httpServer = http.createServer()
      const server = new SignalingServer({ server: httpServer })
      server.attachHealthEndpoint(httpServer, '/healthz')
      httpServer.listen(3000)
      // GET /healthz -> { "status": "ok", "rooms": 0, "peers": 0, "uptime": 0 }

    • Synchronously invokes every listener registered for event, in registration order.

      Type Parameters

      • K extends keyof SignalingServerEvents

      Parameters

      • event: K

        The event name to emit.

      • ...args: SignalingServerEvents[K]

        The argument tuple to pass to each listener, matching Events[event].

      Returns boolean

      true if at least one listener was invoked, false if there were none.

      The listener list is snapshotted before dispatch, so mutations made by handlers take effect only on subsequent emissions. Listeners are isolated: if one throws, the remaining listeners still run and the error is surfaced via console.error rather than swallowed silently (consistent with LocalMessageBus).

    • Resolves which cluster node owns a given room.

      Parameters

      • roomId: string

        The room id to route.

      Returns NodeInfo | undefined

      The owning NodeInfo, or undefined when cluster mode is not enabled or the owner is unknown.

    • Looks up a room currently held by this server instance.

      Parameters

      • roomId: string

        The room id.

      Returns Room | undefined

      The Room, or undefined if no such room exists locally.

    • Returns the number of listeners currently registered for event.

      Type Parameters

      • K extends keyof SignalingServerEvents

      Parameters

      • event: K

        The event name to count listeners for.

      Returns number

      The count of registered listeners (0 if none).

    • Removes a previously registered listener for event.

      Type Parameters

      • K extends keyof SignalingServerEvents

      Parameters

      • event: K

        The event name the listener was registered for.

      • listener: (...args: SignalingServerEvents[K]) => void

        The exact function reference passed to on or once.

      Returns this

      This emitter, for chaining.

      If the listener is not currently registered, this is a no-op. Only the first matching registration is removed.

    • Registers a listener that is invoked every time event is emitted.

      Type Parameters

      • K extends keyof SignalingServerEvents

      Parameters

      • event: K

        The event name to listen for.

      • listener: (...args: SignalingServerEvents[K]) => void

        Callback invoked with the event's argument tuple.

      Returns this

      This emitter, for chaining.

    • Registers a listener that is invoked at most once: it is removed automatically before being called the first time event is emitted.

      Type Parameters

      • K extends keyof SignalingServerEvents

      Parameters

      • event: K

        The event name to listen for.

      • listener: (...args: SignalingServerEvents[K]) => void

        Callback invoked with the event's argument tuple on the next emission.

      Returns this

      This emitter, for chaining.

      Remove a pending one-time listener by passing the same function reference to off.

    • Removes listeners for a single event, or for all events.

      Parameters

      • Optionalevent: keyof SignalingServerEvents

        The event name to clear; if omitted, listeners for every event are removed.

      Returns this

      This emitter, for chaining.

    • Starts listening for connections and begins the heartbeat.

      Returns Promise<void>

      A promise that resolves when the server is listening.

      If SignalingServerOptions.server was provided, the WebSocket server attaches to it; otherwise a new HTTP server is created and bound to SignalingServerOptions.port (default 3000). Resolves once the server is accepting connections.

      If the underlying HTTP server fails to bind (e.g. port in use).

    • Gracefully shuts the server down.

      Returns Promise<void>

      A promise that resolves once all sockets are closed.

      Stops the heartbeat, disposes the cluster RoomRouter (if any), disconnects every peer with CloseReason.ServerStopping, and closes the WebSocket server (and the owned HTTP server, if one was created). Idempotent — calling it more than once is a no-op.

      If closing the WebSocket or HTTP server errors.

    Settings

    Member Visibility

    On This Page

    Constructors
    Accessors
    Methods