tiny-server-essentials/dist/proxy/server/index.d.mts

A good utility toolkit to unify Express v5 and Socket.IO v4 into a seamless development experience with modular helpers, server wrappers, and WebSocket tools.

export default SocketIoProxyServer;
/**
 * Represents a disconnection report sent to the proxy server.
 */
export type ProxyUserDisconnect = {
    /**
     * - Disconnected user socket ID.
     */
    id: string;
    /**
     * - Reason provided by Socket.IO.
     */
    reason: import("socket.io").DisconnectReason;
    /**
     * - Additional description or error object.
     */
    desc: any;
};
/**
 * Represents a diff patch of updated user connection data.
 */
export type ProxyUserConnectionUpdated = {
    /**
     * - User socket ID.
     */
    id: string;
    /**
     * - Only changed fields.
     */
    changes: ProxyUserConnection;
};
/**
 * Represents all serializable data of a connected socket.
 * This object is transmitted to the proxy server so it can simulate
 * remote access to all user details without having direct access to the runtime socket.
 *
 * This enables:
 * - fully remote introspection
 * - remote user operations
 * - remote room joins/leaves
 * - remote event emission
 */
export type ProxyUserConnection = {
    /**
     * - Unique socket identifier.
     */
    id: string;
    /**
     * - All rooms the socket currently belongs to.
     */
    rooms: string[];
    /**
     * - Full handshake information sent by the client.
     */
    handshake: {
        address: string;
        headers: {
            [x: string]: any;
        };
        query: {
            [x: string]: any;
        };
        time: string;
        secure: boolean;
        xdomain: boolean;
        issued: number;
        url: string;
    };
    /**
     * - Safe subset of Engine.IO internal metadata.
     */
    engine: {
        readyState: string;
        transport: string;
        protocol: number;
    };
    /**
     * - Namespace the client is connected to.
     */
    namespace: string;
};
export type ProxyRequest = [id: string, ...import("socket.io").Event];
/**
 * @typedef {Object} ProxyUserDisconnect
 * Represents a disconnection report sent to the proxy server.
 *
 * @property {string} id - Disconnected user socket ID.
 * @property {import('socket.io').DisconnectReason} reason - Reason provided by Socket.IO.
 * @property {any} desc - Additional description or error object.
 */
/**
 * @typedef {Object} ProxyUserConnectionUpdated
 * Represents a diff patch of updated user connection data.
 *
 * @property {string} id - User socket ID.
 * @property {ProxyUserConnection} changes - Only changed fields.
 */
/**
 * @typedef {Object} ProxyUserConnection
 * Represents all serializable data of a connected socket.
 * This object is transmitted to the proxy server so it can simulate
 * remote access to all user details without having direct access to the runtime socket.
 *
 * This enables:
 * - fully remote introspection
 * - remote user operations
 * - remote room joins/leaves
 * - remote event emission
 *
 * @property {string} id - Unique socket identifier.
 *
 * @property {string[]} rooms - All rooms the socket currently belongs to.
 *
 * @property {Object} handshake - Full handshake information sent by the client.
 * @property {string} handshake.address - Client IP address.
 * @property {Object.<string, any>} handshake.headers - HTTP headers from the client request.
 * @property {Object.<string, any>} handshake.query - Incoming connection query-string params.
 * @property {string} handshake.time - Connection timestamp.
 * @property {boolean} handshake.secure - Whether the handshake occurred over HTTPS/WSS.
 * @property {boolean} handshake.xdomain - Whether the request originated from another domain.
 * @property {number} handshake.issued - Unix timestamp for handshake issuance.
 * @property {string} handshake.url - Full request URL.
 *
 * @property {Object} engine - Safe subset of Engine.IO internal metadata.
 * @property {string} engine.readyState - Engine.IO connection state.
 * @property {string} engine.transport - Current transport ("polling" or "websocket").
 * @property {number} engine.protocol - Engine.IO protocol version.
 *
 * @property {string} namespace - Namespace the client is connected to.
 */
/**
 * @typedef {[id: string, ...import('socket.io').Event]} ProxyRequest
 */
/**
 * SocketIoProxyServer
 *
 * This class creates a **remote control layer** on top of a Socket.IO server.
 *
 * It exposes:
 * - A **single authenticated controlling socket** (the operator)
 * - All connected users with full serializable metadata
 * - Automatic change detection via diffing
 * - Remote room operations (join, leave)
 * - Remote broadcasting
 * - Remote event emission
 * - Proxied user events with return-path back to the operator
 *
 * It is effectively a "virtualized mirror" of all socket activity,
 * allowing external systems to observe and interact with real users
 * without having direct access to the socket server runtime.
 *
 * @beta
 */
declare class SocketIoProxyServer extends EventEmitter<[never]> {
    /**
     * Creates a full Socket.IO proxy server instance.
     *
     * @param {import('socket.io').ServerOptions} proxyCfg - Socket.IO server config.
     * @param {Object} [rlCfg] - Rate limiter settings.
     * @param {number} [rlCfg.maxHits=3] - Maximum hits before blocking.
     * @param {number} [rlCfg.interval=1000] - Rate limiter interval.
     * @param {number} [rlCfg.cleanupInterval=60000] - Cleanup frequency.
     */
    constructor(proxyCfg: import("socket.io").ServerOptions, { maxHits, interval, cleanupInterval }?: {
        maxHits?: number | undefined;
        interval?: number | undefined;
        cleanupInterval?: number | undefined;
    });
    /** @returns {boolean} */
    get isDestroyed(): boolean;
    /** @returns {null|import('socket.io').Socket} */
    get socket(): null | import("socket.io").Socket;
    /** @returns {import('socket.io').Server} */
    get server(): import("socket.io").Server;
    /**
     * Sets the authentication value required by the operator client.
     * Only one socket is allowed to become the proxy operator.
     *
     * @param {null|string|number} value - Authentication secret.
     */
    set auth(value: null | string | number);
    /**
     * Sets the maximum allowed time (ms) before a newly connected socket
     * must authenticate as the proxy operator.
     * If authentication does not occur in time, the socket is forcibly disconnected.
     *
     * @param {null|number} value
     */
    set connTimeout(value: null | number);
    /** @returns {null|number} */
    get connTimeout(): null | number;
    /**
     * Extracts all safe, serializable information from a Socket.IO socket instance.
     * Used for:
     * - initial connection sync
     * - remote inspection
     * - diff computation
     *
     * @param {import('socket.io').Socket} socket
     * @returns {ProxyUserConnection}
     */
    extractSocketInfo(socket: import("socket.io").Socket): ProxyUserConnection;
    /**
     * Returns an object representation of all active sockets.
     * Key = socket.id
     * Value = socket instance
     *
     * @returns {Record<string, import('socket.io').Socket>}
     */
    get sockets(): Record<string, import("socket.io").Socket>;
    /**
     * Hooks into the adapter layer of a specific namespace, allowing detection of:
     * - join-room
     * - leave-room
     *
     * This ensures room-level changes emit diffs to the proxy operator.
     *
     * @param {string} where - Namespace path.
     */
    listenAdapter(where: string): import("socket.io-adapter").Adapter;
    /**
     * Fully destroys the proxy server, closing the Socket.IO instance
     * and clearing all tracked state from memory.
     */
    destroy(): void;
    #private;
}
import { EventEmitter } from 'events';
//# sourceMappingURL=index.d.mts.map