@litert/televoke 1.0.3 → 1.2.0

package/src/lib/transporters/memory/Memory.Impl.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2024 Angus.Fenying <fenying@litert.org>
+ * Copyright 2025 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.
@@ -176,18 +176,13 @@ class MemorySocket extends EventEmitter implements dT.ITransporter, Shared.ITran
         };
     }
 
-    public write(data: string | Buffer | Array<string | Buffer>): void {
+    public write(data: Array<string | Buffer>): void {
 
         if (this._exchange.isEnded(this._endpoint)) {
 
             throw new Shared.errors.network_error({ reason: 'conn_lost' });
         }
 
-        if (!Array.isArray(data)) {
-
-            data = [data];
-        }
-
         for (let i = 0; i < data.length; ++i) {
 
             if (!(data[i] instanceof Buffer)) {
@@ -204,12 +199,7 @@ class MemorySocket extends EventEmitter implements dT.ITransporter, Shared.ITran
         this._exchange.close();
     }
 
-    public end(lastChunk?: any): void {
-
-        if (lastChunk !== undefined) {
-
-            this.write(lastChunk);
-        }
+    public end(): void {
 
         this._exchange.end(this._endpoint);
     }

package/src/lib/transporters/memory/README.md

@@ -0,0 +1,7 @@
+# Televoke2/Memory
+
+This module provides the Televoke2 protocol in-memory. It allows you to simulate a server and client in the same process (thread).
+
+## Examples
+
+- [Go to examples](../../../examples/memory.ts)

package/src/lib/transporters/memory/index.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2024 Angus.Fenying <fenying@litert.org>
+ * Copyright 2025 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.

package/src/lib/transporters/websocket/README.md

@@ -0,0 +1,14 @@
+# Televoke2/Websocket
+
+This module provides the Televoke2 protocol over websocket. It allows you to connect to the Televoke2 server with websocket.
+
+> `@litert/websocket` is required to use this module.
+>
+> And by default it uses unmasked data frames in client-side, which maybe incompatible with some server implementations. You could enable the mask feature by yourself, and improved the masking performance by use the `@litert/ws-utils` module, which is a C++ addon.
+
+## Examples
+
+- [Server](../../../examples/network/server.ts)
+- [Client over TCP](../../../examples/network/ws-client.ts)
+- [Client over TLS](../../../examples/network/wss-client.ts)
+- [Client over Unix Domain Socket](../../../examples/network/ws-unix-client.ts)

package/src/lib/transporters/websocket/WebSocket.Client.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2024 Angus.Fenying <fenying@litert.org>
+ * Copyright 2025 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.
@@ -15,13 +15,28 @@
  */
 
 import * as LibWS from '@litert/websocket';
+import type * as NodeHttp from 'node:http';
 import * as dWS from './WebSocket.decl';
 import type * as dT from '../Transporter.decl';
 import { WebSocketTransporter } from './WebSocket.Transporter';
 
-class WsConnector implements dT.IConnector {
+class WsConnector implements IWsConnector {
 
-    public constructor(private readonly _opts: LibWS.IWsConnectOptions) {}
+    public constructor(private readonly _opts: LibWS.IWsConnectOptions) {
+        this._opts.headers ??= {};
+    }
+
+    public setHeaders(newHeaders: NodeHttp.OutgoingHttpHeaders, append: boolean = true): void {
+
+        if (append) {
+
+            Object.assign(this._opts.headers!, newHeaders);
+        }
+        else {
+
+            this._opts.headers = newHeaders;
+        }
+    }
 
     public async connect(): Promise<dT.ITransporter> {
 
@@ -41,9 +56,23 @@ class WsConnector implements dT.IConnector {
     }
 }
 
-class WssConnector implements dT.IConnector {
+class WssConnector implements IWsConnector {
+
+    public constructor(private readonly _opts: LibWS.IWssConnectOptions) {
+        this._opts.headers ??= {};
+    }
+
+    public setHeaders(newHeaders: NodeHttp.OutgoingHttpHeaders, append: boolean = true): void {
 
-    public constructor(private readonly _opts: LibWS.IWssConnectOptions) {}
+        if (append) {
+
+            Object.assign(this._opts.headers!, newHeaders);
+        }
+        else {
+
+            this._opts.headers = newHeaders;
+        }
+    }
 
     public async connect(): Promise<dT.ITransporter> {
 
@@ -63,13 +92,29 @@ class WssConnector implements dT.IConnector {
     }
 }
 
-export function createWsConnector(opts: LibWS.IWsConnectOptions): dT.IConnector {
+export interface IWsConnector extends dT.IConnector {
+
+    /**
+     * Setup the custom headers for websocket negotiation on each connection.
+     *
+     * **WARNING:**
+     * **In browser environment, the Websocket class cannot send custom headers.**
+     * **Considering the compatibility, custom headers in Websocket protocol are not recommended to use.**
+     * ***Don't use this feature unless you don't care about the compatibility in browser environment.***
+     *
+     * @param newHeaders    The new headers to set.
+     * @param append        Whether to append the new headers to existing headers, or replace all headers. [Default: true]
+     */
+    setHeaders(newHeaders: NodeHttp.OutgoingHttpHeaders, append?: boolean): void;
+}
+
+export function createWsConnector(opts: LibWS.IWsConnectOptions): IWsConnector {
 
     opts.frameReceiveMode = LibWS.EFrameReceiveMode.LITE;
     return new WsConnector(opts);
 }
 
-export function createWssConnector(opts: LibWS.IWssConnectOptions): dT.IConnector {
+export function createWssConnector(opts: LibWS.IWssConnectOptions): IWsConnector {
 
     opts.frameReceiveMode = LibWS.EFrameReceiveMode.LITE;
     return new WssConnector(opts);

package/src/lib/transporters/websocket/WebSocket.Server.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2024 Angus.Fenying <fenying@litert.org>
+ * Copyright 2025 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.
@@ -15,27 +15,47 @@
  */
 
 import * as LibWS from '@litert/websocket';
+import type * as NodeHttp from 'node:http';
 import * as dWS from './WebSocket.decl';
 import type * as Listener from '../http-listener';
 import type * as dT from '../Transporter.decl';
 import { EventEmitter } from 'node:events';
 import { WebSocketTransporter } from './WebSocket.Transporter';
 
+export interface IRegisterListenerOptions {
+
+    onErrorCallback: (e: Error) => void;
+
+    onUpgradeCallback: (req: NodeHttp.IncomingMessage, socket: NodeJS.Socket, head: Buffer) => void;
+}
+
+export interface IRegisterListenerResult {
+
+    stop?: () => void | Promise<void>;
+
+    start?: () => void | Promise<void>;
+
+    readonly running: boolean;
+}
+
 class WebSocketGateway extends EventEmitter implements dT.IGateway {
 
     private readonly _wsServer: LibWS.IServer;
 
+    private readonly _listener: IRegisterListenerResult;
+
     public constructor(
-        private readonly _listener: Listener.IHttpListener,
+        registerListener: (opts: IRegisterListenerOptions) => IRegisterListenerResult,
         private readonly _server: dT.IServer,
         timeout?: number,
     ) {
 
         super();
 
-        this._listener
-            .on('error', (e) => this.emit('error', e))
-            .setUpgradeProcessor(this._onUpgrade);
+        this._listener = registerListener({
+            'onErrorCallback': (e) => this.emit('error', e),
+            'onUpgradeCallback': this._onUpgrade,
+        });
 
         this._wsServer = LibWS.createServer({
             frameReceiveMode: LibWS.EFrameReceiveMode.LITE,
@@ -91,7 +111,7 @@ class WebSocketGateway extends EventEmitter implements dT.IGateway {
             return;
         }
 
-        await this._listener.start();
+        await this._listener.start?.();
     }
 
     public async stop(): Promise<void> {
@@ -101,7 +121,7 @@ class WebSocketGateway extends EventEmitter implements dT.IGateway {
             return;
         }
 
-        await this._listener.stop();
+        await this._listener.stop?.();
     }
 }
 
@@ -118,7 +138,9 @@ export interface IWebSocketGatewayOptions {
 }
 
 /**
- * Create a WebSocket gateway.
+ * Create a WebSocket gateway, binding to a simple built-in HTTP(S) listener.
+ *
+ * > When using built-in HTTP server, the api will ignore other headers, path and query string in the URL.
  *
  * @param listener      The HTTP(S) listener object.
  * @param server        The televoke server object.
@@ -129,5 +151,29 @@ export function createWebsocketGateway(
     options: IWebSocketGatewayOptions = {}
 ): dT.IGateway {
 
-    return new WebSocketGateway(listener, server, options.timeout);
+    return new WebSocketGateway((o) => {
+
+        listener.on('error', o.onErrorCallback);
+        listener.setUpgradeProcessor(o.onUpgradeCallback);
+
+        return listener;
+
+    }, server, options.timeout);
+}
+
+/**
+ * Create a WebSocket gateway, binding to a custom HTTP server.
+ *
+ * > When using a custom HTTP server, it's able to preprocess the request before passing to the server, like
+ * > authentication, rate limiting, custom routing, etc.
+ *
+ * @param registerListener  The function to register the listener to the custom HTTP server.
+ * @param server            The server to process the requests.
+ */
+export function createCustomWebsocketGateway(
+    registerListener: (opts: IRegisterListenerOptions) => IRegisterListenerResult,
+    server: dT.IServer
+): dT.IGateway {
+
+    return new WebSocketGateway(registerListener, server);
 }

package/src/lib/transporters/websocket/WebSocket.Transporter.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2024 Angus.Fenying <fenying@litert.org>
+ * Copyright 2025 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.
@@ -93,7 +93,7 @@ export class WebSocketTransporter extends EventEmitter implements dT.ITransporte
         return this._conn.connected;
     }
 
-    public write(frame: string | Buffer | Array<string | Buffer>): void {
+    public write(frame: Array<string | Buffer>): void {
 
         if (!this._conn.writable) {
 
@@ -110,22 +110,10 @@ export class WebSocketTransporter extends EventEmitter implements dT.ITransporte
         }
     }
 
-    public end(frame?: Buffer | string): void {
+    public end(): void {
 
         if (this._conn.writable) {
 
-            if (frame) {
-
-                try {
-
-                    this._conn.writeBinary(frame);
-                }
-                catch (e) {
-
-                    throw new Shared.errors.network_error({ reason: 'conn_lost', cause: e });
-                }
-            }
-
             this._conn.end();
         }
     }

package/src/lib/transporters/websocket/WebSocket.decl.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2024 Angus.Fenying <fenying@litert.org>
+ * Copyright 2025 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.

package/src/lib/transporters/websocket/index.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2024 Angus.Fenying <fenying@litert.org>
+ * Copyright 2025 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.

package/src/lib/transporters/worker-thread/README.md

@@ -0,0 +1,18 @@
+# Televoke2/WorkerThread
+
+This module provides the Televoke2 protocol over Node.js Worker Threads, which allows you to connect the main thread and
+worker threads with the Televoke2 protocol.
+
+You could either make the main thread as a server or a client, and the worker threads as clients or servers.
+
+## Examples
+
+- Main Thread As Server
+
+    - Check the [server code (main thread)](../../../examples/worker-thread/main-server.ts)
+    - Check the [client code (worker thread)](../../../examples/worker-thread/worker-client.ts)
+
+- Worker Thread As Server
+
+    - Check the [server code (worker thread)](../../../examples/worker-thread/worker-server.ts)
+    - Check the [client code (main thread)](../../../examples/worker-thread/main-client.ts)

package/src/lib/transporters/worker-thread/WorkerThread.Client.ts

@@ -0,0 +1,88 @@
+/**
+ * Copyright 2025 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 NodeWorker from 'node:worker_threads';
+import type * as dT from '../Transporter.decl';
+import * as eWT from './WorkerThread.Errors';
+import { MAIN_THREAD_PROTOCOL_NAME } from './WorkerThread.Constants';
+import { MainThreadTransporter, WorkerThreadTransporter } from './WorkerThread.Transporter';
+
+class MainServerConnector implements dT.IConnector {
+
+    private _transporter: dT.ITransporter | null = null;
+
+    public async connect(): Promise<dT.ITransporter> {
+
+        return Promise.resolve(this._transporter ??= new WorkerThreadTransporter(MAIN_THREAD_PROTOCOL_NAME));
+    }
+}
+
+class WorkerServerConnector implements dT.IConnector {
+
+    private _worker: NodeWorker.Worker | null = null;
+
+    public constructor(worker: NodeWorker.Worker) {
+
+        this._worker = worker
+            .on('exit', () => { this._worker = null; });
+    }
+
+    private _transporter: dT.ITransporter | null = null;
+
+    public async connect(): Promise<dT.ITransporter> {
+
+        if (!this._worker) {
+
+            throw new eWT.E_WORKER_THREAD_OFFLINE();
+        }
+
+        this._transporter ??= new MainThreadTransporter(MAIN_THREAD_PROTOCOL_NAME, this._worker);
+
+        return Promise.resolve(this._transporter);
+    }
+}
+
+let inst: MainServerConnector | null = null;
+
+/**
+ * Create a connector to connect to the server running in the main thread.
+ *
+ * @experimental
+ */
+export function connectToMainThreadServer(): dT.IConnector {
+
+    if (NodeWorker.isMainThread) {
+
+        throw new eWT.E_WORKER_THREAD_ONLY();
+    }
+
+    return inst ??= new MainServerConnector();
+}
+
+/**
+ * Create a connector to connect to the server running in the worker thread.
+ *
+ * @experimental
+ */
+export function connectToWorkerThreadServer(worker: NodeWorker.Worker): dT.IConnector {
+
+    if (!NodeWorker.isMainThread) {
+
+        throw new eWT.E_MAIN_THREAD_ONLY();
+    }
+
+    return new WorkerServerConnector(worker);
+}

package/src/lib/transporters/worker-thread/WorkerThread.Constants.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright 2025 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 const MAIN_THREAD_PROTOCOL_NAME = 'worker_thread/main';
+
+export const WORKER_THREAD_PROTOCOL_NAME = 'worker_thread/worker';

package/src/lib/transporters/worker-thread/WorkerThread.Errors.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright 2025 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 { TelevokeError } from '../../shared';
+
+export const E_WORKER_THREAD_OFFLINE = class extends TelevokeError {
+
+    public constructor(origin: unknown = null) {
+
+        super(
+            'worker_thread_offline',
+            'The worker thread is offline.',
+            origin
+        );
+    }
+};
+
+export const E_MAIN_THREAD_ONLY = class extends TelevokeError {
+
+    public constructor(origin: unknown = null) {
+
+        super(
+            'main_thread_only',
+            'The operation is only allowed in the main thread.',
+            origin
+        );
+    }
+};
+
+export const E_WORKER_THREAD_ONLY = class extends TelevokeError {
+
+    public constructor(origin: unknown = null) {
+
+        super(
+            'worker_thread_only',
+            'The operation is only allowed in a worker thread.',
+            origin
+        );
+    }
+};

package/src/lib/transporters/worker-thread/WorkerThread.Server.ts

@@ -0,0 +1,136 @@
+/**
+ * Copyright 2025 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 NodeWorker from 'node:worker_threads';
+import type * as dT from '../Transporter.decl';
+import * as cWT from './WorkerThread.Constants';
+import { EventEmitter } from 'node:events';
+import { MainThreadTransporter, WorkerThreadTransporter } from './WorkerThread.Transporter';
+import * as eWT from './WorkerThread.Errors';
+
+export interface IMainThreadGateway extends dT.IGateway {
+
+    /**
+     * Add a worker thread to the gateway, so that the gateway can communicate with it.
+     *
+     * > The worker thread must be online already.
+     *
+     * @param worker    The worker instance on the main thread.
+     */
+    registerWorker(worker: NodeWorker.Worker): void;
+}
+
+const VOID_OK_PROMISE = Promise.resolve();
+
+class MainThreadGateway extends EventEmitter implements IMainThreadGateway {
+
+    public constructor(
+        private readonly _server: dT.IServer,
+    ) { super(); }
+
+    public get running(): boolean {
+
+        return true;
+    }
+
+    public start(): Promise<void> {
+
+        return VOID_OK_PROMISE;
+    }
+
+    public stop(): Promise<void> {
+
+        return VOID_OK_PROMISE;
+    }
+
+    public registerWorker(worker: NodeWorker.Worker): void {
+
+        if (worker?.threadId === -1) {
+
+            throw new eWT.E_WORKER_THREAD_OFFLINE();
+        }
+
+        this._server.registerChannel(new MainThreadTransporter(cWT.MAIN_THREAD_PROTOCOL_NAME, worker));
+    }
+}
+
+class WorkerThreadGateway extends EventEmitter implements dT.IGateway {
+
+    private _transporter: WorkerThreadTransporter | null = null;
+
+    public constructor(
+        private readonly _server: dT.IServer,
+    ) { super(); }
+
+    public get running(): boolean {
+
+        return !!this._transporter;
+    }
+
+    public start(): Promise<void> {
+
+        if (this._transporter) {
+
+            return VOID_OK_PROMISE;
+        }
+
+        this._server.registerChannel(this._transporter = new WorkerThreadTransporter(cWT.WORKER_THREAD_PROTOCOL_NAME));
+
+        return VOID_OK_PROMISE;
+    }
+
+    public stop(): Promise<void> {
+
+        this._transporter?.end();
+        this._transporter = null;
+
+        return VOID_OK_PROMISE;
+    }
+}
+
+/**
+ * Create a gateway that runs in the main thread.
+ *
+ * @param server    The server instance.
+ * @experimental
+ */
+export function createMainThreadGateway(server: dT.IServer): IMainThreadGateway {
+
+    if (!NodeWorker.isMainThread) {
+
+        throw new eWT.E_MAIN_THREAD_ONLY();
+    }
+
+    return new MainThreadGateway(server);
+}
+
+let workerThreadGateway: WorkerThreadGateway | null = null;
+
+/**
+ * Create a gateway that runs in the worker thread.
+ *
+ * @param server    The server instance.
+ * @experimental
+ */
+export function createWorkerThreadGateway(server: dT.IServer): dT.IGateway {
+
+    if (NodeWorker.isMainThread) {
+
+        throw new eWT.E_WORKER_THREAD_ONLY();
+    }
+
+    return workerThreadGateway ??= new WorkerThreadGateway(server);
+}