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

    Interface SignalingServerOptions

    Configuration for a SignalingServer. Every field is optional; an empty object yields an unauthenticated server listening on port 3000 with default heartbeat timings.

    For production deployments you will almost always set SignalingServerOptions.auth. See SignalingServerOptions.cluster to enable horizontal sharding via RoomRouter.

    interface SignalingServerOptions {
        allowedOrigins?: string[];
        auditLog?: (event: AuditEvent) => void;
        auth?: AuthFunction;
        cluster?: { membership: Membership; selfId: string };
        iceServersHook?: (
            peerId: string,
            roomId: string,
        ) =>
            | IceServerConfig[]
            | Promise<IceServerConfig[] | null | undefined>
            | null
            | undefined;
        logger?: Logger;
        maxConnections?: number;
        maxPayloadBytes?: number;
        maxPeersPerRoom?: number;
        maxRooms?: number;
        metrics?: MetricsCollector;
        onRedirect?: (
            peerId: string,
            roomId: string,
            owner: NodeInfo | undefined,
        ) => void;
        pingInterval?: number;
        pongTimeout?: number;
        port?: number;
        rateLimit?: { maxMessagesPerSecond?: number };
        roomIdleTimeoutMs?: number;
        roomMaxDurationMs?: number;
        server?: Server<typeof IncomingMessage, typeof ServerResponse>;
        serverAssignedPeerId?: boolean;
    }
    Index

    Properties

    allowedOrigins? auditLog? auth? cluster? iceServersHook? logger? maxConnections? maxPayloadBytes? maxPeersPerRoom? maxRooms? metrics? onRedirect? pingInterval? pongTimeout? port? rateLimit? roomIdleTimeoutMs? roomMaxDurationMs? server? serverAssignedPeerId?

    Properties

    allowedOrigins?: string[]

    Allowlist of Origin header values that may connect (CSWSH defense for browser clients). A connection whose Origin is not listed is closed with CloseCode.PolicyViolation. Omit to allow any origin (non-browser clients typically send no Origin, which is always allowed).

    auditLog?: (event: AuditEvent) => void

    Sink for AuditEvents covering peer and room lifecycle transitions.

    auth?: AuthFunction

    Token verification hook. When omitted, connections are admitted using whatever identity the transport supplies — do not omit in production. See AuthFunction.

    cluster?: { membership: Membership; selfId: string }

    Enables cluster mode. When set, the server constructs a RoomRouter and routes each room to its owning node; connections for rooms owned by another node are redirected. See RoomRouter for the sharding flow.

    Type Declaration

    • membership: Membership

      Live roster of cluster nodes used to build the hash ring.

    • selfId: string

      Stable id of this node within the cluster.

    iceServersHook?: (
        peerId: string,
        roomId: string,
    ) =>
        | IceServerConfig[]
        | Promise<IceServerConfig[] | null | undefined>
        | null
        | undefined

    Hook to supply per-connection ICE servers (e.g. short-lived TURN credentials) sent to the joining peer. Return null/undefined to omit ICE servers for that peer. May be async.

    Type Declaration

      • (
            peerId: string,
            roomId: string,
        ):
            | IceServerConfig[]
            | Promise<IceServerConfig[] | null | undefined>
            | null
            | undefined

      • Parameters

        • peerId: string

          Id of the joining peer.

        • roomId: string

          Id of the room being joined.

        Returns
            | IceServerConfig[]
            | Promise<IceServerConfig[] | null | undefined>
            | null
            | undefined

        The ICE servers to advertise, or nothing.

    logger?: Logger

    Structured log sink.

    noopLogger

    maxConnections?: number

    Hard cap on total concurrent connections across all rooms. Connections beyond the cap are closed with CloseReason.ServerAtCapacity.

    10000

    maxPayloadBytes?: number

    Maximum inbound WebSocket message size in bytes; larger frames are rejected by ws before reaching application code. Blunts memory-exhaustion floods.

    262144 (256 KiB)

    maxPeersPerRoom?: number

    Hard cap on concurrent peers per room; excess peers are closed with CloseReason.RoomFull. Bounded out of the box; raise it for larger rooms.

    100

    maxRooms?: number

    Hard cap on the number of concurrent rooms. A connection that would create a new room past this cap is rejected.

    10000

    metrics?: MetricsCollector

    Metrics sink.

    noopMetrics

    onRedirect?: (
        peerId: string,
        roomId: string,
        owner: NodeInfo | undefined,
    ) => void

    Called when an incoming connection targets a room owned by another node, just before the connection is closed with CloseReason.WrongNode. Use it to inform the client (or a load balancer) of the correct owner.

    Type Declaration

      • (peerId: string, roomId: string, owner: NodeInfo | undefined): void

      • Parameters

        • peerId: string

          Id of the peer that was redirected.

        • roomId: string

          Id of the room it tried to join.

        • owner: NodeInfo | undefined

          The node that owns the room, if known.

        Returns void

    pingInterval?: number

    Interval in milliseconds between heartbeat pings sent to each peer.

    30000

    pongTimeout?: number

    Grace period in milliseconds after which a peer that has not ponged is pruned.

    60000

    port?: number

    TCP port to listen on when the server creates its own HTTP server.

    3000

    rateLimit?: { maxMessagesPerSecond?: number }

    Per-peer inbound rate limiting. Enabled by default at 100 msg/s; set maxMessagesPerSecond to 0 (or a negative value) to disable.

    Type Declaration

    • OptionalmaxMessagesPerSecond?: number

      Maximum inbound messages per second per peer; excess messages are dropped and PeerEvent.RateLimitExceeded fires. 0 or negative disables the limiter.

      100

    roomIdleTimeoutMs?: number

    Idle timeout in milliseconds; a room with no relay/broadcast activity for this long is closed.

    roomMaxDurationMs?: number

    Maximum lifetime of a room in milliseconds; on expiry all peers are disconnected and the room closes.

    server?: Server<typeof IncomingMessage, typeof ServerResponse>

    Existing Node HTTP server to attach the WebSocket server to instead of creating one. Takes precedence over SignalingServerOptions.port.

    serverAssignedPeerId?: boolean

    When true, the server assigns each peer's id rather than trusting the client-supplied id.

    Settings

    Member Visibility

    On This Page

    Properties