@egodigital/egoose/lib/http/websockets.d.ts

Helper classes and functions for Node.js 10 or later.

/**
 * This file is part of the @egodigital/egoose distribution.
 * Copyright (c) e.GO Digital GmbH, Aachen, Germany (https://www.e-go-digital.com/)
 *
 * @egodigital/egoose is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, version 3.
 *
 * @egodigital/egoose is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */
/// <reference types="node" />
import { Predicate } from '../index';
import * as events from 'events';
import * as http from 'http';
import * as https from 'https';
import * as ws from 'ws';
/**
 * Context of a client verifier.
 */
export interface WebSocketHostClientVerifierContext {
    /**
     * Indicates if connection is secure or not.
     */
    isSecure: boolean;
    /**
     * The request context.
     */
    request: http.IncomingMessage;
}
/**
 * Verifies a remote client.
 *
 * @param {WebSocketHostClientVerifierContext} context The context.
 *
 * @return {boolean|PromiseLike<boolean>} The result, that indicates, if client is valid or not.
 */
export declare type WebSocketHostClientVerifier = (context: WebSocketHostClientVerifierContext) => boolean | PromiseLike<boolean>;
/**
 * Options for a 'WebSocketHost'.
 */
export interface WebSocketHostOptions {
    /**
     * The custom TCP port. Default: 5979
     */
    port?: number;
    /**
     * A factory function, that creates a custom server instance.
     */
    serverFactory?: WebSocketHostServerFactory;
    /**
     * An optional function to verify a client.
     */
    verifyClient?: WebSocketHostClientVerifier;
}
/**
 * Describes a factory function, that creates a custom server instance.
 *
 * @return {WebSocketHostServerFactoryResult|PromiseLike<WebSocketHostServerFactoryResult>} The result with the new server instance.
 */
export declare type WebSocketHostServerFactory = () => WebSocketHostServerFactoryResult | PromiseLike<WebSocketHostServerFactoryResult>;
/**
 * A possible result of 'WebSocketHostServerFactory'.
 */
export declare type WebSocketHostServerFactoryResult = http.Server | https.Server;
/**
 * A web socket message.
 */
export interface WebSocketMessage<TData = any> {
    /**
     * The data.
     */
    data?: TData;
    /**
     * The type.
     */
    type: string;
}
/**
 * Possible values for 'onType' first argument.
 */
export declare type WebSocketOnTypeCheckArgument = RegExp | string | Predicate<string>;
/**
 * An event for an 'onType' event.
 *
 * @param {TData} data The data.
 * @param {string} type The type.
 */
export declare type WebSocketOnTypeEventListener<TData = any> = (data: TData, type: string) => void;
/**
 * A web socket host.
 */
export declare class WebSocketHost extends events.EventEmitter {
    readonly options?: WebSocketHostOptions;
    private _server;
    /**
     * Initializes a new instance of that class.
     *
     * @param {WebSocketHostOptions} [options] Custom options for the host.
     */
    constructor(options?: WebSocketHostOptions);
    /**
     * Gets if the server is currently running or not.
     */
    get isRunning(): boolean;
    /**
     * Starts the host.
     *
     * @return {Promise<boolean>} The promise that indicates if operation was succesfull or not.
     */
    start(): Promise<boolean>;
    /**
     * Stops the host.
     *
     * @return {Promise<boolean>} The promise that indicates if operation was succesfull or not.
     */
    stop(): Promise<boolean>;
}
/**
 * A web socket client.
 */
export declare class WebSocketClient extends events.EventEmitter {
    readonly host: WebSocketHost;
    readonly socket: ws;
    /**
     * Initializes a new instance of that class.
     *
     * @param {WebSocketHost} host The underlying host.
     * @param {ws} socket The underlying socket.
     */
    constructor(host: WebSocketHost, socket: ws);
    /**
     * Initializes the instance.
     */
    init(): void;
    /**
     * Registers an event listener for a message type.
     *
     * @param {RegExp} pattern The Regex pattern, that checks the type.
     * @param {WebSocketOnTypeEventListener<TData>} listener The listener.
     *
     * @return {Function} The "real" event listener.
     */
    onType<TData = any>(pattern: RegExp, listener: WebSocketOnTypeEventListener<TData>): Function;
    /**
     * Registers an event listener for a message type.
     *
     * @param {string} type The type.
     * @param {WebSocketOnTypeEventListener<TData>} listener The listener.
     *
     * @return {Function} The "real" event listener.
     */
    onType<TData = any>(type: string, listener: WebSocketOnTypeEventListener<TData>): Function;
    /**
     * Registers an event listener for a message type.
     *
     * @param {Predicate<string>} predicate The predicate, that checks the type.
     * @param {WebSocketOnTypeEventListener<TData>} listener The listener.
     *
     * @return {Function} The "real" event listener.
     */
    onType<TData = any>(predicate: Predicate<string>, listener: WebSocketOnTypeEventListener<TData>): Function;
    /**
     * Sends a message to the remote client.
     *
     * @param {string} type The type.
     * @param {any} [data] The data to send.
     */
    send(type: string, data?: any): Promise<void>;
}