@epicgames-ps/lib-pixelstreamingsignalling-ue5.8 0.1.0

package/dist/types/PlayerRegistry.d.ts

@@ -0,0 +1,66 @@
+import type { IncomingMessage } from 'http';
+import { SignallingProtocol, BaseMessage, EventEmitter } from '@epicgames-ps/lib-pixelstreamingcommon-ue5.8';
+import { IMessageLogger } from './LoggingUtils';
+import { IStreamer } from './StreamerRegistry';
+/**
+ * An interface that describes a player that can be added to the
+ * player registry.
+ */
+export interface IPlayer extends IMessageLogger {
+    playerId: string;
+    protocol: SignallingProtocol;
+    subscribedStreamer: IStreamer | null;
+    request?: IncomingMessage;
+    sendMessage(message: BaseMessage): void;
+    getPlayerInfo(): IPlayerInfo;
+}
+/**
+ * Used by the API to describe the current state of the player.
+ */
+export interface IPlayerInfo {
+    playerId: string;
+    type: string;
+    subscribedTo: string | undefined;
+    remoteAddress: string | undefined;
+}
+/**
+ * Handles all the player connections of a signalling server and
+ * can be used to lookup connections by id etc.
+ * Fires events when players are added or removed.
+ * Events:
+ *   'added': (playerId: string) Player was added.
+ *   'removed': (playerId: string) Player was removed.
+ */
+export declare class PlayerRegistry extends EventEmitter {
+    private players;
+    private nextPlayerId;
+    constructor();
+    /**
+     * Assigns a unique id to the player and adds it to the registry
+     */
+    add(player: IPlayer): void;
+    /**
+     * Removes a player from the registry. Does nothing if the id
+     * does not exist.
+     */
+    remove(player: IPlayer): void;
+    /**
+     * Tests if a player id exists in the registry.
+     */
+    has(playerId: string): boolean;
+    /**
+     * Gets a player from the registry using the player id.
+     * Returns undefined if the player doesn't exist.
+     */
+    get(playerId: string): IPlayer | undefined;
+    listPlayers(): IPlayer[];
+    /**
+     * Returns true when the registry is empty.
+     */
+    empty(): boolean;
+    /**
+     * Gets the total number of connected players.
+     */
+    count(): number;
+    private getUniquePlayerId;
+}

package/dist/types/SFUConnection.d.ts

@@ -0,0 +1,85 @@
+import type { IncomingMessage } from 'http';
+import WebSocket from 'ws';
+import { ITransport, SignallingProtocol, BaseMessage, EventEmitter } from '@epicgames-ps/lib-pixelstreamingcommon-ue5.8';
+import { IPlayer, IPlayerInfo } from './PlayerRegistry';
+import { IStreamer, IStreamerInfo } from './StreamerRegistry';
+import * as LogUtils from './LoggingUtils';
+import { SignallingServer } from './SignallingServer';
+/**
+ * A SFU connection to the signalling server.
+ * An SFU can act as both a streamer and a player. It can subscribe to
+ * streamers like a player, and other players can subscribe to the sfu.
+ * Therefore the SFU will have a streamer id and a player id and be
+ * registered in both streamer registries and player registries.
+ *
+ * Interesting internals:
+ * playerId: The player id of this connectiom.
+ * streamerId: The streamer id of this connection.
+ * transport: The ITransport where transport events can be subscribed to
+ * protocol: The SignallingProtocol where signalling messages can be
+ * subscribed to.
+ * streaming: True when the streamer is ready to accept subscriptions.
+ */
+export declare class SFUConnection extends EventEmitter implements IPlayer, IStreamer, LogUtils.IMessageLogger {
+    playerId: string;
+    streamerId: string;
+    transport: ITransport;
+    protocol: SignallingProtocol;
+    streaming: boolean;
+    subscribedStreamer: IStreamer | null;
+    remoteAddress?: string;
+    request?: IncomingMessage;
+    maxSubscribers: number;
+    subscribers: Set<string>;
+    private server;
+    private layerPreferenceListener;
+    private streamerIdChangeListener;
+    private streamerDisconnectedListener;
+    /**
+     * Construct a new SFU connection.
+     * @param server - The signalling server object that spawned this sfu.
+     * @param ws - The websocket coupled to this sfu connection.
+     * @param remoteAddress - The remote address of this connection. Only used as display.
+     * @param request - The HTTP upgrade request that opened this connection, if available.
+     */
+    constructor(server: SignallingServer, ws: WebSocket, remoteAddress?: string, request?: IncomingMessage);
+    /**
+     * Returns an identifier that is displayed in logs.
+     * @returns A string describing this connection.
+     */
+    getReadableIdentifier(): string;
+    /**
+     * Sends a signalling message to the SFU.
+     * @param message - The message to send.
+     */
+    sendMessage(message: BaseMessage): void;
+    /**
+     * Returns a descriptive object for the REST API inspection operations.
+     * @returns An IStreamerInfo object containing viewable information about this connection.
+     */
+    getStreamerInfo(): IStreamerInfo;
+    /**
+     * Returns a descriptive object for the REST API inspection operations.
+     * @returns An IPlayerInfo object containing viewable information about this connection.
+     */
+    getPlayerInfo(): IPlayerInfo;
+    private registerMessageHandlers;
+    private subscribe;
+    private unsubscribe;
+    private sendToStreamer;
+    private sendToPlayer;
+    private disconnect;
+    private onLayerPreference;
+    private onStreamerIdChanged;
+    private onStreamerDisconnected;
+    private onTransportError;
+    private onTransportClose;
+    private onSubscribeMessage;
+    private onUnsubscribeMessage;
+    private onListStreamers;
+    private onStreamerDataChannels;
+    private onEndpointId;
+    private onStartStreaming;
+    private onStopStreaming;
+    private onPingMessage;
+}

package/dist/types/SignallingServer.d.ts

@@ -0,0 +1,48 @@
+import http from 'http';
+import https from 'https';
+import * as wslib from 'ws';
+import { StreamerRegistry, StreamerIdAuthorizer } from './StreamerRegistry';
+import { PlayerRegistry } from './PlayerRegistry';
+/**
+ * An interface describing the possible options to pass when creating
+ * a new SignallingServer object.
+ */
+export interface IServerConfig {
+    httpServer?: http.Server;
+    httpsServer?: https.Server;
+    streamerPort: number;
+    playerPort?: number;
+    sfuPort?: number;
+    peerOptions: unknown;
+    streamerWsOptions?: wslib.ServerOptions;
+    playerWsOptions?: wslib.ServerOptions;
+    sfuWsOptions?: wslib.ServerOptions;
+    maxSubscribers?: number;
+    playerKeepaliveTimeout?: number;
+    authorizeStreamerId?: StreamerIdAuthorizer;
+}
+export type ProtocolConfig = {
+    [key: string]: any;
+};
+/**
+ * The main signalling server object.
+ * Contains a streamer and player registry and handles setting up of websockets
+ * to listen for incoming connections.
+ */
+export declare class SignallingServer {
+    config: IServerConfig;
+    protocolConfig: ProtocolConfig;
+    streamerRegistry: StreamerRegistry;
+    playerRegistry: PlayerRegistry;
+    startTime: Date;
+    /**
+     * Initializes the server object and sets up listening sockets for streamers
+     * players and optionally SFU connections.
+     * @param config - A collection of options for this server.
+     */
+    constructor(config: IServerConfig);
+    private sendConfigMessage;
+    private onStreamerConnected;
+    private onPlayerConnected;
+    private onSFUConnected;
+}

package/dist/types/StreamerConnection.d.ts

@@ -0,0 +1,61 @@
+import type { IncomingMessage } from 'http';
+import WebSocket from 'ws';
+import { ITransport, SignallingProtocol, BaseMessage, EventEmitter } from '@epicgames-ps/lib-pixelstreamingcommon-ue5.8';
+import { IStreamer, IStreamerInfo } from './StreamerRegistry';
+import * as LogUtils from './LoggingUtils';
+import { SignallingServer } from './SignallingServer';
+/**
+ * A connection between the signalling server and a streamer connection.
+ * This is where messages expected to be handled by the streamer come in
+ * and where messages are sent to the streamer.
+ *
+ * Interesting internals:
+ * streamerId: The unique id string of this streamer.
+ * transport: The ITransport where transport events can be subscribed to
+ * protocol: The SignallingProtocol where signalling messages can be
+ * subscribed to.
+ * streaming: True when the streamer is ready to accept subscriptions.
+ */
+export declare class StreamerConnection extends EventEmitter implements IStreamer, LogUtils.IMessageLogger {
+    streamerId: string;
+    transport: ITransport;
+    protocol: SignallingProtocol;
+    streaming: boolean;
+    remoteAddress?: string;
+    request?: IncomingMessage;
+    maxSubscribers: number;
+    subscribers: Set<string>;
+    private server;
+    /**
+     * Initializes a new connection with given and sane values. Adds listeners for the
+     * websocket close and error and will emit a disconnected event when disconneted.
+     * @param server - The signalling server object that spawned this streamer.
+     * @param ws - The websocket coupled to this streamer connection.
+     * @param remoteAddress - The remote address of this connection. Only used as display.
+     * @param request - The HTTP upgrade request that opened this connection, if available.
+     */
+    constructor(server: SignallingServer, ws: WebSocket, remoteAddress?: string, request?: IncomingMessage);
+    /**
+     * Returns an identifier that is displayed in logs.
+     * @returns A string describing this connection.
+     */
+    getReadableIdentifier(): string;
+    /**
+     * Sends a signalling message to the player.
+     * @param message - The message to send.
+     */
+    sendMessage(message: BaseMessage): void;
+    /**
+     * Returns a descriptive object for the REST API inspection operations.
+     * @returns An IStreamerInfo object containing viewable information about this connection.
+     */
+    getStreamerInfo(): IStreamerInfo;
+    private registerMessageHandlers;
+    private forwardMessage;
+    private onTransportError;
+    private onTransportClose;
+    private onEndpointId;
+    private onDisconnectPlayerRequest;
+    private onLayerPreference;
+    private onPingMessage;
+}

package/dist/types/StreamerRegistry.d.ts

@@ -0,0 +1,96 @@
+import { ITransport, SignallingProtocol, BaseMessage, EventEmitter } from '@epicgames-ps/lib-pixelstreamingcommon-ue5.8';
+import type { IncomingMessage } from 'http';
+import { IMessageLogger } from './LoggingUtils';
+import { IPlayerInfo } from './PlayerRegistry';
+/**
+ * An interface that describes a streamer that can be added to the
+ * streamer registry.
+ */
+export interface IStreamer extends EventEmitter, IMessageLogger {
+    streamerId: string;
+    transport: ITransport;
+    protocol: SignallingProtocol;
+    streaming: boolean;
+    maxSubscribers: number;
+    subscribers: Set<string>;
+    request?: IncomingMessage;
+    sendMessage(message: BaseMessage): void;
+    getStreamerInfo(): IStreamerInfo;
+}
+/**
+ * The details of a streamer's request to be known by a given id, passed to a
+ * {@link StreamerIdAuthorizer} so a consumer can decide whether to allow it.
+ */
+export interface IStreamerIdAuthRequest {
+    streamer: IStreamer;
+    requestedId: string;
+    sanitizedId: string;
+    collided: boolean;
+}
+/**
+ * An optional consumer-supplied hook that decides the id a streamer is allowed to register as.
+ * Return the id to commit (the sanitized id to accept the default, or any other unique id to
+ * override, e.g. to namespace per tenant), or null to reject the streamer and disconnect it.
+ * This is the seam for implementing anti-squatting / ownership policy without the project
+ * providing an authentication scheme.
+ */
+export type StreamerIdAuthorizer = (request: IStreamerIdAuthRequest) => string | null;
+/**
+ * Used by the API to describe a streamer.
+ */
+export interface IStreamerInfo {
+    streamerId: string;
+    type: string;
+    streaming: boolean;
+    remoteAddress: string | undefined;
+    subscribers: IPlayerInfo[];
+}
+/**
+ * Handles all the streamer connections of a signalling server and
+ * can be used to lookup connections by id etc.
+ * Fires events when streamers are added or removed.
+ * Events:
+ *   'added': (playerId: string) Player was added.
+ *   'removed': (playerId: string) Player was removed.
+ */
+export declare class StreamerRegistry extends EventEmitter {
+    streamers: IStreamer[];
+    defaultStreamerIdPrefix: string;
+    authorizeStreamerId?: StreamerIdAuthorizer;
+    constructor(authorizeStreamerId?: StreamerIdAuthorizer);
+    /**
+     * Adds a streamer to the registry. If the streamer already has an id
+     * it will be sanitized (checked against existing ids and altered if
+     * there are collisions), or if it has no id it will be assigned a
+     * default unique id.
+     * @returns True if the add was successful.
+     */
+    add(streamer: IStreamer): boolean;
+    /**
+     * Removes a streamer from the registry. If the streamer isn't found
+     * it does nothing.
+     * @returns True if the streamer was removed.
+     */
+    remove(streamer: IStreamer): boolean;
+    /**
+     * Attempts to find the given streamer id in the registry.
+     */
+    find(streamerId: string): IStreamer | undefined;
+    /**
+     * Used by players who haven't subscribed but try to send a message.
+     * This is to cover legacy connections that do not know how to subscribe.
+     * The player will be assigned the first streamer in the list.
+     * @returns The first streamerId in the registry or null if there are none.
+     */
+    getFirstStreamerId(): string | null;
+    /**
+     * Returns true when the registry is empty.
+     */
+    empty(): boolean;
+    /**
+     * Returns the total number of connected streamers.
+     */
+    count(): number;
+    private onEndpointId;
+    private sanitizeStreamerId;
+}

package/dist/types/Utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cirular reference safe version of JSON.stringify
+ */
+export declare function stringify(obj: any): string;
+/**
+ * Circular reference save version of JSON.stringify with extra formatting.
+ */
+export declare function beautify(obj: any): string;

package/dist/types/WebServer.d.ts

@@ -0,0 +1,42 @@
+import express from 'express';
+import http from 'http';
+import https from 'https';
+/**
+ * Options for configuring CORS on the Express app. When `enabled` is true the
+ * `cors` middleware is registered so that browser-based clients hosted on a
+ * different origin (e.g. a custom frontend) can call the REST API or other
+ * routes mounted on the app. Use `allowedOrigins` to restrict which origins
+ * are accepted; an empty / unset list means "allow all origins" (`*`).
+ */
+export interface ICorsConfig {
+    enabled?: boolean;
+    allowedOrigins?: string[];
+    allowedMethods?: string[];
+    allowedHeaders?: string[];
+    credentials?: boolean;
+}
+/**
+ * An interface that describes the possible options to pass to
+ * WebServer.
+ */
+export interface IWebServerConfig {
+    httpPort: number;
+    root: string;
+    homepageFile: string;
+    perMinuteRateLimit?: number;
+    httpsPort?: number;
+    ssl_key?: Buffer;
+    ssl_cert?: Buffer;
+    https_redirect?: boolean;
+    serveStatic?: boolean;
+    cors?: ICorsConfig;
+}
+/**
+ * An object to manage the initialization of a web server. Used to serve the
+ * pixel streaming frontend.
+ */
+export declare class WebServer {
+    httpServer: http.Server | undefined;
+    httpsServer: https.Server | undefined;
+    constructor(app: express.Express, config: IWebServerConfig);
+}

package/dist/types/pixelstreamingsignalling.d.ts

@@ -0,0 +1,9 @@
+export * from './Logger';
+export * from './LoggingUtils';
+export * from './PlayerConnection';
+export * from './PlayerRegistry';
+export * from './SFUConnection';
+export * from './SignallingServer';
+export * from './StreamerConnection';
+export * from './StreamerRegistry';
+export * from './WebServer';

package/docs/Logger/README.md

@@ -0,0 +1,19 @@
+[**@epicgames-ps/lib-pixelstreamingsignalling-ue5.5**](../README.md)
+
+***
+
+[@epicgames-ps/lib-pixelstreamingsignalling-ue5.5](../README.md) / Logger
+
+# Logger
+
+## Interfaces
+
+- [IConfig](interfaces/IConfig.md)
+
+## Variables
+
+- [Logger](variables/Logger.md)
+
+## Functions
+
+- [InitLogging](functions/InitLogging.md)

package/docs/Logger/functions/InitLogging.md

@@ -0,0 +1,26 @@
+[**@epicgames-ps/lib-pixelstreamingsignalling-ue5.5**](../../README.md)
+
+***
+
+[@epicgames-ps/lib-pixelstreamingsignalling-ue5.5](../../README.md) / [Logger](../README.md) / InitLogging
+
+# Function: InitLogging()
+
+> **InitLogging**(`config`): `void`
+
+Defined in: [Signalling/src/Logger.ts:68](https://github.com/EpicGamesExt/PixelStreamingInfrastructure/blob/4dc9339cfc185a91d37d078aa9dd0951dfbae1a5/Signalling/src/Logger.ts#L68)
+
+Call this as early as possible to setup the logging module with your
+preferred settings.
+
+## Parameters
+
+### config
+
+[`IConfig`](../interfaces/IConfig.md)
+
+The settings to init the logger with. See IConfig interface
+
+## Returns
+
+`void`

package/docs/Logger/interfaces/IConfig.md

@@ -0,0 +1,41 @@
+[**@epicgames-ps/lib-pixelstreamingsignalling-ue5.5**](../../README.md)
+
+***
+
+[@epicgames-ps/lib-pixelstreamingsignalling-ue5.5](../../README.md) / [Logger](../README.md) / IConfig
+
+# Interface: IConfig
+
+Defined in: [Signalling/src/Logger.ts:20](https://github.com/EpicGamesExt/PixelStreamingInfrastructure/blob/4dc9339cfc185a91d37d078aa9dd0951dfbae1a5/Signalling/src/Logger.ts#L20)
+
+## Properties
+
+### logDir?
+
+> `optional` **logDir**: `string`
+
+Defined in: [Signalling/src/Logger.ts:22](https://github.com/EpicGamesExt/PixelStreamingInfrastructure/blob/4dc9339cfc185a91d37d078aa9dd0951dfbae1a5/Signalling/src/Logger.ts#L22)
+
+***
+
+### logLevelConsole?
+
+> `optional` **logLevelConsole**: `string`
+
+Defined in: [Signalling/src/Logger.ts:28](https://github.com/EpicGamesExt/PixelStreamingInfrastructure/blob/4dc9339cfc185a91d37d078aa9dd0951dfbae1a5/Signalling/src/Logger.ts#L28)
+
+***
+
+### logLevelFile?
+
+> `optional` **logLevelFile**: `string`
+
+Defined in: [Signalling/src/Logger.ts:31](https://github.com/EpicGamesExt/PixelStreamingInfrastructure/blob/4dc9339cfc185a91d37d078aa9dd0951dfbae1a5/Signalling/src/Logger.ts#L31)
+
+***
+
+### logMessagesToConsole?
+
+> `optional` **logMessagesToConsole**: `string`
+
+Defined in: [Signalling/src/Logger.ts:25](https://github.com/EpicGamesExt/PixelStreamingInfrastructure/blob/4dc9339cfc185a91d37d078aa9dd0951dfbae1a5/Signalling/src/Logger.ts#L25)

package/docs/Logger/variables/Logger.md

@@ -0,0 +1,15 @@
+[**@epicgames-ps/lib-pixelstreamingsignalling-ue5.5**](../../README.md)
+
+***
+
+[@epicgames-ps/lib-pixelstreamingsignalling-ue5.5](../../README.md) / [Logger](../README.md) / Logger
+
+# Variable: Logger
+
+> **Logger**: `Logger`
+
+Defined in: [Signalling/src/Logger.ts:18](https://github.com/EpicGamesExt/PixelStreamingInfrastructure/blob/4dc9339cfc185a91d37d078aa9dd0951dfbae1a5/Signalling/src/Logger.ts#L18)
+
+The actual logger object. This is just a winston logger.
+You can use InitLogging to get a decent result, or you can
+completely create your own winston logger and assign it.

package/docs/LoggingUtils/README.md

@@ -0,0 +1,19 @@
+[**@epicgames-ps/lib-pixelstreamingsignalling-ue5.5**](../README.md)
+
+***
+
+[@epicgames-ps/lib-pixelstreamingsignalling-ue5.5](../README.md) / LoggingUtils
+
+# LoggingUtils
+
+## Interfaces
+
+- [IMessageLogger](interfaces/IMessageLogger.md)
+- [IProtoLogObj](interfaces/IProtoLogObj.md)
+
+## Functions
+
+- [createHandlerListener](functions/createHandlerListener.md)
+- [logForward](functions/logForward.md)
+- [logIncoming](functions/logIncoming.md)
+- [logOutgoing](functions/logOutgoing.md)

package/docs/LoggingUtils/functions/createHandlerListener.md

@@ -0,0 +1,42 @@
+[**@epicgames-ps/lib-pixelstreamingsignalling-ue5.5**](../../README.md)
+
+***
+
+[@epicgames-ps/lib-pixelstreamingsignalling-ue5.5](../../README.md) / [LoggingUtils](../README.md) / createHandlerListener
+
+# Function: createHandlerListener()
+
+> **createHandlerListener**(`obj`, `handler`): (`message`) => `void`
+
+Defined in: [Signalling/src/LoggingUtils.ts:74](https://github.com/EpicGamesExt/PixelStreamingInfrastructure/blob/4dc9339cfc185a91d37d078aa9dd0951dfbae1a5/Signalling/src/LoggingUtils.ts#L74)
+
+We don't want to log every incoming and outgoing messages. This is because some messages are simply
+forwarded to other connections. This results in duplicated spam. So we only want to log incoming
+messages that we handle internally, and any messages that we forward we only log once for the recv
+and send events.
+This creation method allows a simple way to enforce this. Any events we handle directly will
+be preceded by the logging call.
+
+## Parameters
+
+### obj
+
+[`IMessageLogger`](../interfaces/IMessageLogger.md)
+
+### handler
+
+(`message`) => `void`
+
+## Returns
+
+`Function`
+
+### Parameters
+
+#### message
+
+`BaseMessage`
+
+### Returns
+
+`void`

package/docs/LoggingUtils/functions/logForward.md

@@ -0,0 +1,36 @@
+[**@epicgames-ps/lib-pixelstreamingsignalling-ue5.5**](../../README.md)
+
+***
+
+[@epicgames-ps/lib-pixelstreamingsignalling-ue5.5](../../README.md) / [LoggingUtils](../README.md) / logForward
+
+# Function: logForward()
+
+> **logForward**(`recvr`, `target`, `message`): `void`
+
+Defined in: [Signalling/src/LoggingUtils.ts:56](https://github.com/EpicGamesExt/PixelStreamingInfrastructure/blob/4dc9339cfc185a91d37d078aa9dd0951dfbae1a5/Signalling/src/LoggingUtils.ts#L56)
+
+Call this for messages being forwarded to this connection. That is messages received on
+one connection and being sent to another with only minor changes being made.
+
+## Parameters
+
+### recvr
+
+[`IMessageLogger`](../interfaces/IMessageLogger.md)
+
+The connection the message was received on.
+
+### target
+
+[`IMessageLogger`](../interfaces/IMessageLogger.md)
+
+The connection the message is being sent to.
+
+### message
+
+`BaseMessage`
+
+## Returns
+
+`void`

package/docs/LoggingUtils/functions/logIncoming.md

@@ -0,0 +1,30 @@
+[**@epicgames-ps/lib-pixelstreamingsignalling-ue5.5**](../../README.md)
+
+***
+
+[@epicgames-ps/lib-pixelstreamingsignalling-ue5.5](../../README.md) / [LoggingUtils](../README.md) / logIncoming
+
+# Function: logIncoming()
+
+> **logIncoming**(`recvr`, `message`): `void`
+
+Defined in: [Signalling/src/LoggingUtils.ts:26](https://github.com/EpicGamesExt/PixelStreamingInfrastructure/blob/4dc9339cfc185a91d37d078aa9dd0951dfbae1a5/Signalling/src/LoggingUtils.ts#L26)
+
+Call to log messages received on a connection that we will handle here at the server.
+Do not call this for messages being forwarded to another connection.
+
+## Parameters
+
+### recvr
+
+[`IMessageLogger`](../interfaces/IMessageLogger.md)
+
+IMessageLogger The connection the message was received on.
+
+### message
+
+`BaseMessage`
+
+## Returns
+
+`void`