@litert/televoke 1.1.0 → 1.2.0

package/src/lib/transporters/lwdfx/LwDFX.UnixSocket.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.

package/src/lib/transporters/lwdfx/LwDFX.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/lwdfx/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/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.

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/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.

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/WorkerThread.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.

package/src/lib/transporters/worker-thread/WorkerThread.Constants.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/WorkerThread.Errors.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/WorkerThread.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.

package/src/lib/transporters/worker-thread/WorkerThread.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.

package/src/lib/transporters/worker-thread/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.