@litert/televoke 0.4.6 → 1.0.0-0

package/src/lib/shared/Shared.decl.ts

@@ -0,0 +1,347 @@
+/**
+* Copyright 2023 Angus.Fenying <fenying@litert.org>
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*   https://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+import { Readable } from 'node:stream';
+
+export type IFn<TArgs extends any[], TRet> = (...args: TArgs) => TRet;
+
+export type IVoidFn<TArgs extends any[]> = IFn<TArgs, void>;
+
+// eslint-disable-next-line @typescript-eslint/ban-types, @typescript-eslint/consistent-type-definitions
+export type IObject = {};
+
+export type IfIsFn<T, TTrue = T, TFalse = never> = T extends IFn<any[], any> ? TTrue : TFalse;
+
+export type IfIsOfFn<T, TFn extends IFn<any[], any>, TTrue = T, TFalse = never> = T extends TFn ? TTrue : TFalse;
+
+export interface IEventListener<T extends IDefaultEvents> {
+
+    /**
+     * Register a listener for the given event.
+     *
+     * > Alias for `addListener()`.
+     *
+     * @param event         The event name.
+     * @param listener      The listener function.
+     */
+    on<TKey extends keyof T>(event: TKey, listener: IfIsOfFn<T[TKey], IVoidFn<any[]>>): this;
+
+    /**
+     * Register a listener for the given event.
+     *
+     * > Alias for `addListener()`.
+     *
+     * @param event         The event name.
+     * @param listener      The listener function.
+     */
+    on(event: string | symbol, listener: IVoidFn<any[]>): this;
+
+    /**
+     * Register a one-time listener for the given event.
+     *
+     * > The listener is invoked only the next time the event is fired, after which it is removed.
+     *
+     * @param event         The event name.
+     * @param listener      The listener function.
+     */
+    once<TKey extends keyof T>(event: TKey, listener: IfIsOfFn<T[TKey], IVoidFn<any[]>>): this;
+
+    /**
+     * Register a one-time listener for the given event.
+     *
+     * > The listener is invoked only the next time the event is fired, after which it is removed.
+     *
+     * @param event         The event name.
+     * @param listener      The listener function.
+     */
+    once(event: string | symbol, listener: IVoidFn<any[]>): this;
+
+    /**
+     * Register a listener for the given event.
+     *
+     * > Alias for `on()`.
+     *
+     * @param event         The event name.
+     * @param listener      The listener function.
+     */
+    addListener<TKey extends keyof T>(event: TKey, listener: IfIsOfFn<T[TKey], IVoidFn<any[]>>): this;
+
+    /**
+     * Register a listener for the given event.
+     *
+     * > Alias for `on()`.
+     *
+     * @param event         The event name.
+     * @param listener      The listener function.
+     */
+    addListener(event: string | symbol, listener: IVoidFn<any[]>): this;
+
+    /**
+     * Remove the given listener for the given event.
+     *
+     * > Alias for `off()`.
+     *
+     * @param event     The event name.
+     * @param listener  The listener function.
+     */
+    removeListener<TKey extends keyof T>(event: TKey, listener: IVoidFn<any[]>): this;
+
+    /**
+     * Remove the given listener for the given event.
+     *
+     * > Alias for `off()`.
+     *
+     * @param event     The event name.
+     * @param listener  The listener function.
+     */
+    removeListener(event: string | symbol, listener: IVoidFn<any[]>): this;
+
+    /**
+     * Remove the given listener for the given event.
+     *
+     * > Alias for `removeListener()`.
+     *
+     * @param event     The event name.
+     * @param listener  The listener function.
+     */
+    off<TKey extends keyof T>(event: TKey, listener: IVoidFn<any[]>): this;
+
+    /**
+     * Remove the given listener for the given event.
+     *
+     * > Alias for `removeListener()`.
+     *
+     * @param event     The event name.
+     * @param listener  The listener function.
+     */
+    off(event: string | symbol, listener: IVoidFn<any[]>): this;
+
+    /**
+     * Remove all listeners for the given event.
+     *
+     * @param event     The event name.
+     */
+    removeAllListeners(event: keyof T): this;
+
+    /**
+     * Remove all listeners for the given event.
+     *
+     * @param event     The event name.
+     */
+    removeAllListeners(event: string): this;
+
+    /**
+     * Return the number of listeners for the given event.
+     *
+     * @param event     The event name.
+     */
+    listenerCount(event: keyof T): number;
+
+    /**
+     * Return the number of listeners for the given event.
+     *
+     * @param event     The event name.
+     */
+    listenerCount(event: string): number;
+
+    /**
+     * Set the maximum number of listeners for the given event.
+     *
+     * @param n     The new value of maximum listeners number.
+     */
+    setMaxListeners(n: number): this;
+}
+
+export interface IDefaultEvents {
+
+    error(error: unknown): void;
+}
+
+export interface ITransporter {
+
+    /**
+     * The transporting protocol.
+     */
+    readonly protocol: string;
+
+    readonly writable: boolean;
+
+    /**
+     * Get the names of all properties that are available on the transporter.
+     */
+    getPropertyNames(): readonly string[];
+
+    /**
+     * Get the value of a property.
+     *
+     * @param name The name of the property to get.
+     */
+    getProperty(name: string): unknown;
+
+    /**
+     * Get the values collection of all properties.
+     */
+    getAllProperties(): Record<string, unknown>;
+}
+
+export interface IBinaryReadStream extends Readable {
+
+    /**
+     * The unique id of binary stream.
+     */
+    readonly id: number;
+
+    /**
+     * Abort the binary stream before it's completed, and release the resource.
+     *
+     * > The `readableAborted` property will be set to `true` after calling this method.
+     *
+     * > A `stream_aborted` error will be emitted in event `error`.
+     *
+     * > **Note:** The binary stream will be closed immediately after calling this method,
+     * > whatever the stream is finished or not.
+     */
+    abort(): void;
+
+    /**
+     * Close the binary stream since it is completed, and release the resource.
+     *
+     * > **Note:** The binary stream will be closed immediately after calling this method,
+     * > whatever the stream is finished or not.
+     */
+    close(): void;
+
+    /**
+     * Set the timeout value of each chunk of this binary stream.
+     *
+     * > When the timeout is reached, the binary stream will be aborted and a `timeout` error will be emitted in event `error`.
+     *
+     * > Set to 0 to disable timeout.
+     *
+     * @param timeout  The timeout value in milliseconds.
+     */
+    setTimeout(timeout: number): void;
+}
+
+export interface IStreamManager {
+
+    /**
+     * The default initial timeout value of each new binary stream.
+     *
+     * > Set to 0 to disable timeout.
+     *
+     * @type uint
+     */
+    defaultTimeout: number;
+
+    /**
+     * The maximum number of binary streams that can be opened at the same time.
+     *
+     * > Set to -1 to disable the limit.
+     * > Set to 0 to disable opening any new binary streams.
+     *
+     * @type int
+     * @default 10
+     */
+    maxStreams: number;
+
+    /**
+     * Open a binary `Readable` stream on this side, to accept the binary data chunks from the remote side.
+     *
+     * There is an `id` in the binary stream, which is used to identify the stream. The remote side could use it to invoke
+     * `sendBinaryChunk()` method to send the binary data chunks to this side.
+     */
+    create(): IBinaryReadStream;
+
+    /**
+     * Get the binary stream by stream id.
+     *
+     * @param id    The `id` field in `IBinaryReadStream`.
+     */
+    get(id: number): IBinaryReadStream | null;
+
+    /**
+     * Close all binary streams in this manager, and destroy the manager.
+     */
+    close(): void;
+}
+
+export type IStreamManagerFactory = (channel: IChannelBase<any>) => IStreamManager;
+
+export interface IChannelBase<TEvents extends IDefaultEvents> extends IEventListener<TEvents> {
+
+    /**
+     * The transporter object is used to send and receive data to and from the remote endpoint.
+     */
+    readonly transporter: ITransporter;
+
+    /**
+     * Tells whether this channel is closed on the local side or not.
+     */
+    readonly finished: boolean;
+
+    /**
+     * Tells whether the channel is closed on the remote side or not.
+     */
+    readonly ended: boolean;
+
+    /**
+     * Whether this channel is writable.
+     */
+    readonly writable: boolean;
+
+    /**
+     * The stream manager of the binary streams.
+     */
+    readonly streams: IStreamManager;
+
+    /**
+     * The context object is used to store data that is shared on the channel.
+     *
+     * > **Note:** The context object is only available for the lifetime of the channel.
+     */
+    readonly context: Record<string, any>;
+
+    /**
+     * Send a PING command to the remote endpoint.
+     *
+     * @param msg   The message to send.
+     */
+    ping(msg?: Buffer | string): Promise<Buffer>;
+
+    /**
+     * Send a PUSH_MESSAGE command to the remote endpoint.
+     *
+     * @param msg   The message to send.
+     */
+    sendMessage(msg: Buffer | string): Promise<void>;
+
+    /**
+     * Send a binary data chunk to an opened binary stream on the remote side.
+     *
+     * > **NOTE: It is not recommended to send a large binary data chunk at once. A large binary chunk should be split**
+     * > **into several small chunks, and then send them one by one, in order.**
+     *
+     * @param id        The `id` field in `IBinaryReadStream`, opened by remote side.
+     * @param chunks    The binary data chunks to be sent.
+     */
+    sendBinaryChunk(id: number, chunk: Buffer | null): Promise<void>;
+
+    /**
+     * Close the channel.
+     */
+    close(): void;
+}

package/src/lib/shared/Utils.ts

@@ -0,0 +1,51 @@
+/**
+* Copyright 2023 Angus.Fenying <fenying@litert.org>
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*   https://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * Ensures that a function is only called once.
+ *
+ * @param fn    The function to call.
+ * @returns     The wrapped function.
+ */
+export function once<T extends (...args: any[]) => any>(fn: T): T {
+
+    let called = false;
+    let result: any;
+
+    return function(...args: any[]) {
+
+        if (!called) {
+
+            called = true;
+            result = fn(...args);
+        }
+
+        return result;
+    } as T;
+}
+
+export function buffer2json(data: Buffer[]): unknown {
+
+    let str = '';
+    const td = new TextDecoder('utf-8', { fatal: true });
+
+    for (const seg of data) {
+
+        str += td.decode(seg, { stream: true });
+    }
+
+    return JSON.parse(str);
+}

package/src/lib/shared/index.ts

@@ -0,0 +1,23 @@
+/**
+* Copyright 2023 Angus.Fenying <fenying@litert.org>
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*   https://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+export type * from './Shared.decl';
+export * from './Shared.decl';
+export * from './Constants';
+export * from './BinaryStream';
+export * from './BinaryStreamManager';
+export * from './Errors';
+export * as Encodings from './Encodings';

package/src/lib/transporters/Transporter.decl.ts

@@ -0,0 +1,117 @@
+/**
+* Copyright 2023 Angus.Fenying <fenying@litert.org>
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*   https://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+import type * as Shared from '../shared';
+
+export interface IRouter {
+
+    readonly encoding: string;
+}
+
+export interface IServer {
+
+    readonly router: IRouter;
+
+    /**
+     * Register a transporter into the server, turning it into a channel.
+     *
+     * @param transporter   The transporter object.
+     */
+    registerChannel(transporter: ITransporter): void;
+
+    /**
+     * Process api calls from legacy client.
+     *
+     * @param callback      The callback function.
+     * @param name          The api name.
+     * @param args          The api arguments, decoded as JavaScript values.
+     * @param transporter   The transporter object.
+     */
+    processLegacyApi(
+        callback: ILegacyApiResponseCallback,
+        name: string,
+        args: unknown,
+        transporter: Shared.ITransporter
+    ): void;
+}
+
+export interface IGateway extends Shared.IEventListener<Shared.IDefaultEvents> {
+
+    /**
+     * Whether the gateway is running.
+     */
+    readonly running: boolean;
+
+    /**
+     * Start the gateway.
+     */
+    start(): Promise<void>;
+
+    /**
+     * Stop the gateway.
+     */
+    stop(): Promise<void>;
+}
+
+export interface ITransporterEvents extends Shared.IDefaultEvents {
+
+    close(): void;
+
+    frame(frameChunks: Buffer[]): void;
+
+    end(): void;
+
+    finish(): void;
+}
+
+export interface ITransporter extends Shared.IEventListener<ITransporterEvents> {
+
+    /**
+     * Whether the transporter is writable.
+     */
+    readonly writable: boolean;
+
+    /**
+     * Ends writing through the transporter.
+     *
+     * @param lastFrame The last frame.
+     */
+    end(lastFrame?: Buffer | string | Array<Buffer | string>): void;
+
+    /**
+     * Destroy the transporter.
+     */
+    destroy(): void;
+
+    /**
+     * Write a frame through the transporter.
+     *
+     * @param frame The frame to write.
+     */
+    write(frame: Buffer | string | Array<Buffer | string>): void;
+}
+
+export interface IConnector {
+
+    /**
+     * Connect to the remote endpoint.
+     *
+     * The returned promise will be resolved with the transporter object.
+     */
+    connect(): Promise<ITransporter>;
+}
+
+export type ILegacyApiResponseCallback = (body: unknown) => void;

package/src/lib/transporters/http-listener/AbstractHttpListener.ts

@@ -0,0 +1,57 @@
+/**
+* Copyright 2023 Angus.Fenying <fenying@litert.org>
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*   https://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+import * as Http from 'node:http';
+import * as dH from './Http.Decl';
+import { EventEmitter } from 'node:events';
+
+export abstract class AbstractHttpListener extends EventEmitter implements dH.IHttpListener {
+
+    protected _gateway: Http.Server | null = null;
+
+    public port: number = 0;
+
+    protected _upgradeProcessor: dH.IUpgradeProcessor = dH.DEFAULT_UPGRADE_PROCESSOR;
+
+    protected _apiProcessor: dH.ILegacyHttpApiProcessor = dH.DEFAULT_LEGACY_HTTP_API_PROCESSOR;
+
+    public setLegacyApiProcessor(processor: dH.ILegacyHttpApiProcessor | null): void {
+
+        this._apiProcessor = processor ?? dH.DEFAULT_LEGACY_HTTP_API_PROCESSOR;
+
+        this._gateway
+            ?.removeAllListeners('request')
+            .addListener('request', this._apiProcessor);
+    }
+
+    public setUpgradeProcessor(processor: dH.IUpgradeProcessor | null): void {
+
+        this._upgradeProcessor = processor ?? dH.DEFAULT_UPGRADE_PROCESSOR;
+
+        this._gateway
+            ?.removeAllListeners('upgrade')
+            .addListener('upgrade', this._upgradeProcessor);
+    }
+
+    public get running(): boolean {
+
+        return !!this._gateway;
+    }
+
+    public abstract start(): Promise<void>;
+
+    public abstract stop(): Promise<void>;
+}