@litert/televoke 1.0.3 → 1.2.0

package/src/lib/shared/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.
@@ -36,6 +36,7 @@ export class ProtocolError extends TelevokeError {
 
     public constructor(
         message: string,
+        public readonly data: unknown,
         origin: unknown,
     ) {
 
@@ -52,9 +53,9 @@ function defineProtocolError<T extends string>(name: T): Record<T, new (
 
         [name]: class extends ProtocolError {
 
-            public constructor(public readonly data: unknown = null, origin: unknown = null) {
+            public constructor(data: unknown = null, origin: unknown = null) {
 
-                super(name, origin);
+                super(name, data, origin);
             }
         },
     } as any;

package/src/lib/shared/Shared.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.
@@ -20,7 +20,7 @@ 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
+// eslint-disable-next-line @typescript-eslint/no-restricted-types, @typescript-eslint/consistent-type-definitions
 export type IObject = {};
 
 export type IfIsFn<T, TTrue = T, TFalse = never> = T extends IFn<any[], any> ? TTrue : TFalse;
@@ -303,6 +303,16 @@ export interface IChannelBase<TEvents extends IDefaultEvents> extends IEventList
      */
     readonly transporter: ITransporter;
 
+    /**
+     * Whether this channel supports server-push messages or not.
+     */
+    readonly isMessageSupported: boolean;
+
+    /**
+     * Whether this channel supports binary streams or not.
+     */
+    readonly isBinaryStreamSupported: boolean;
+
     /**
      * Tells whether this channel is closed on the local side or not.
      */
@@ -362,5 +372,5 @@ export interface IChannelBase<TEvents extends IDefaultEvents> extends IEventList
     /**
      * Close the channel.
      */
-    close(): void;
+    close(): void | Promise<void>;
 }

package/src/lib/shared/Utils.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/shared/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/Transporter.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.
@@ -89,7 +89,7 @@ export interface ITransporter extends Shared.IEventListener<ITransporterEvents>
      *
      * @param lastFrame The last frame.
      */
-    end(lastFrame?: Buffer | string | Array<Buffer | string>): void;
+    end(): void;
 
     /**
      * Destroy the transporter.
@@ -101,7 +101,7 @@ export interface ITransporter extends Shared.IEventListener<ITransporterEvents>
      *
      * @param frame The frame to write.
      */
-    write(frame: Buffer | string | Array<Buffer | string>): void;
+    write(frame: Array<Buffer | string>): void;
 }
 
 export interface IConnector {

package/src/lib/transporters/http-listener/AbstractHttpListener.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.
@@ -24,7 +24,7 @@ export abstract class AbstractHttpListener extends EventEmitter implements dH.IH
 
     public port: number = 0;
 
-    protected _upgradeProcessor: dH.IUpgradeProcessor = dH.DEFAULT_UPGRADE_PROCESSOR;
+    protected _upgradeProcessor: dH.IUpgradeProcessor | null = null;
 
     protected _apiProcessor: dH.ILegacyHttpApiProcessor = dH.DEFAULT_LEGACY_HTTP_API_PROCESSOR;
 
@@ -39,11 +39,19 @@ export abstract class AbstractHttpListener extends EventEmitter implements dH.IH
 
     public setUpgradeProcessor(processor: dH.IUpgradeProcessor | null): void {
 
-        this._upgradeProcessor = processor ?? dH.DEFAULT_UPGRADE_PROCESSOR;
+        this._upgradeProcessor = processor;
 
-        this._gateway
-            ?.removeAllListeners('upgrade')
-            .addListener('upgrade', this._upgradeProcessor);
+        if (!this._gateway) {
+
+            return;
+        }
+
+        this._gateway.removeAllListeners('upgrade');
+
+        if (this._upgradeProcessor !== null) {
+
+            this._gateway.addListener('upgrade', this._upgradeProcessor);
+        }
     }
 
     public get running(): boolean {

package/src/lib/transporters/http-listener/Http.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.
@@ -75,31 +75,6 @@ export const DEFAULT_LEGACY_HTTP_API_PROCESSOR: ILegacyHttpApiProcessor = functi
     resp.end(DEFAULT_REFUSE_PAYLOAD);
 };
 
-/**
- * The default upgrade processor, it will destroy the socket.
- */
-export const DEFAULT_UPGRADE_PROCESSOR: IUpgradeProcessor = function(req): void {
-
-    const socket = req.socket;
-
-    const header: Http.OutgoingHttpHeaders = {
-        'Content-Type': 'text/plain',
-        'Content-Length': DEFAULT_REFUSE_PAYLOAD.byteLength,
-    };
-
-    socket.write([
-        `HTTP/1.1 ${DEFAULT_REFUSE_STATUS_CODE}`,
-        ...Object.entries(header).map(([k, v]) => `${k}: ${v as string}`),
-        ''
-    ].join('\r\n'));
-
-    socket.write(DEFAULT_REFUSE_PAYLOAD);
-
-    socket.write('\r\n');
-
-    socket.end();
-};
-
 export interface IHttpListenerOptions {
 
     /**

package/src/lib/transporters/http-listener/HttpListener.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.
@@ -46,13 +46,21 @@ class HttpListener extends AbstractHttpListener {
             }).on('listening', () => {
 
                 gateway.removeAllListeners('error');
+
                 this._gateway = gateway;
+
                 if (this.port === 0) {
 
                     this.port = (gateway.address() as $Net.AddressInfo).port;
                 }
+
                 gateway.on('error', (e) => this.emit('error', e));
-                gateway.on('upgrade', this._upgradeProcessor);
+
+                if (this._upgradeProcessor !== null) {
+
+                    gateway.on('upgrade', this._upgradeProcessor);
+                }
+
                 resolve();
             });
         });

package/src/lib/transporters/http-listener/HttpUnixSocketListener.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.
@@ -45,13 +45,21 @@ class HttpUnixSocketListener extends AbstractHttpListener {
             }).on('listening', () => {
 
                 gateway.removeAllListeners('error');
+
                 this._gateway = gateway;
+
                 if (this.port === 0) {
 
                     this.port = (gateway.address() as $Net.AddressInfo).port;
                 }
+
                 gateway.on('error', (e) => this.emit('error', e));
-                gateway.on('upgrade', this._upgradeProcessor);
+
+                if (this._upgradeProcessor !== null) {
+
+                    gateway.on('upgrade', this._upgradeProcessor);
+                }
+
                 resolve();
             });
         });

package/src/lib/transporters/http-listener/HttpsListener.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.
@@ -46,13 +46,21 @@ class HttpsListener extends AbstractHttpListener {
             }).on('listening', () => {
 
                 gateway.removeAllListeners('error');
+
                 this._gateway = gateway;
-                if (this._opts.port === 0) {
 
-                    this._opts.port = (gateway.address() as $Net.AddressInfo).port;
+                if (this.port === 0) {
+
+                    this.port = (gateway.address() as $Net.AddressInfo).port;
                 }
+
                 gateway.on('error', (e) => this.emit('error', e));
-                gateway.on('upgrade', this._upgradeProcessor);
+
+                if (this._upgradeProcessor !== null) {
+
+                    gateway.on('upgrade', this._upgradeProcessor);
+                }
+
                 resolve();
             });
         });

package/src/lib/transporters/http-listener/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/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/legacy-http/LegacyHttp.Client.Native.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.
@@ -29,7 +29,18 @@ const DEFAULT_TIMEOUT = 30_000;
 
 const disabledStreamManager = Shared.createDisabledStreamManagerFactory()(null as any);
 
-class TvLegacyHttpClient extends EventEmitter implements C.IClient<any> {
+export interface ILegacyHttpClient<T extends Shared.IObject> extends C.IClient<T> {
+
+    /**
+     * Setup the headers for the every HTTP request.
+     *
+     * @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: $Http.OutgoingHttpHeaders, append?: boolean): void;
+}
+
+class TvLegacyHttpClient extends EventEmitter implements ILegacyHttpClient<any> {
 
     public onError!: any;
 
@@ -42,6 +53,8 @@ class TvLegacyHttpClient extends EventEmitter implements C.IClient<any> {
     ) {
 
         super();
+
+        this._opts.headers ??= {};
     }
 
     public get timeout(): number {
@@ -62,6 +75,18 @@ class TvLegacyHttpClient extends EventEmitter implements C.IClient<any> {
 
     public readonly transporter = null;
 
+    public setHeaders(newHeaders: $Http.OutgoingHttpHeaders, append: boolean = true): void {
+
+        if (append) {
+
+            Object.assign(this._opts.headers!, newHeaders);
+        }
+        else {
+
+            this._opts.headers = newHeaders;
+        }
+    }
+
     public sendBinaryChunk(): Promise<void> {
 
         return Promise.reject(new Shared.errors.cmd_not_impl());
@@ -312,7 +337,9 @@ export interface IHttpClientUnixSocketOptions extends IHttpClientOptionsBase {
 
 export type IHttpClientOptions = IHttpClientNetworkOptions | IHttpClientUnixSocketOptions;
 
-export function createLegacyHttpClient<TAPIs extends Shared.IObject>(opts: IHttpClientOptions): C.IClient<TAPIs> {
+export function createLegacyHttpClient<TAPIs extends Shared.IObject>(
+    opts: IHttpClientOptions,
+): ILegacyHttpClient<TAPIs> {
 
     return new TvLegacyHttpClient(
         opts.https ? $Https.request : $Http.request,

package/src/lib/transporters/legacy-http/LegacyHttp.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.
@@ -57,10 +57,28 @@ export interface IHttpGatewayOptions {
     backlog?: number;
 }
 
+export interface IRegisterListenerOptions {
+
+    onErrorCallback: (e: Error) => void;
+
+    onRequestCallback: (req: Http.IncomingMessage, resp: Http.ServerResponse) => void;
+}
+
+export interface IRegisterListenerResult {
+
+    stop?: () => void | Promise<void>;
+
+    start?: () => void | Promise<void>;
+
+    readonly running: boolean;
+}
+
 class LegacyHttpGateway extends EventEmitter implements dT.IGateway {
 
+    private readonly _listener: IRegisterListenerResult;
+
     public constructor(
-        private readonly _listener: Listener.IHttpListener,
+        registerListener: (opts: IRegisterListenerOptions) => IRegisterListenerResult,
         private readonly _server: dT.IServer,
     ) {
 
@@ -71,9 +89,10 @@ class LegacyHttpGateway extends EventEmitter implements dT.IGateway {
             throw new TypeError('Legacy HTTP gateway only supports JSON encoding');
         }
 
-        this._listener
-            .on('error', (e) => this.emit('error', e))
-            .setLegacyApiProcessor(this._onRequest);
+        this._listener = registerListener({
+            onErrorCallback: (e) => this.emit('error', e),
+            onRequestCallback: this._onRequest,
+        });
     }
 
     private _sendResponse(resp: Http.ServerResponse, data: string): void {
@@ -157,7 +176,7 @@ class LegacyHttpGateway extends EventEmitter implements dT.IGateway {
 
                 let input: any;
 
-                if (offset !== length || buf[0] !== 123 || buf[offset - 1] !== 125) {
+                if (offset !== length) {
 
                     refuseBadRequest(resp);
                     return;
@@ -212,6 +231,19 @@ class LegacyHttpGateway extends EventEmitter implements dT.IGateway {
                                 recvAt
                             ));
                         }
+                        else if (result instanceof Shared.ProtocolError) {
+
+                            this._sendResponse(resp, encoder.encodeApiErrorResponse(
+                                input.rid,
+                                v1.EResponseCode.SYSTEM_ERROR,
+                                JSON.stringify({
+                                    name: result.name,
+                                    message: result.message,
+                                    data: result.data,
+                                }),
+                                recvAt
+                            ));
+                        }
                         else {
 
                             this._sendResponse(resp, encoder.encodeApiErrorResponse(
@@ -256,7 +288,7 @@ class LegacyHttpGateway extends EventEmitter implements dT.IGateway {
             return;
         }
 
-        await this._listener.start();
+        await this._listener.start?.();
     }
 
     public async stop(): Promise<void> {
@@ -266,14 +298,43 @@ class LegacyHttpGateway extends EventEmitter implements dT.IGateway {
             return Promise.resolve();
         }
 
-        await this._listener.stop();
+        await this._listener.stop?.();
     }
 }
 
+/**
+ * Create a legacy HTTP gateway, binding to a built-in simple HTTP server.
+ *
+ * > When using built-in HTTP server, the api will ignore headers, path and query string in the URL.
+ *
+ * @param listener  The built-in HTTP listener to bind to.
+ * @param server    The server to process the requests.
+ */
 export function createLegacyHttpGateway(
     listener: Listener.IHttpListener,
     server: dT.IServer
 ): dT.IGateway {
 
-    return new LegacyHttpGateway(listener, server);
+    return new LegacyHttpGateway((o) => {
+        listener.on('error', o.onErrorCallback);
+        listener.setLegacyApiProcessor(o.onRequestCallback);
+        return listener;
+    }, server);
+}
+
+/**
+ * Create a legacy HTTP 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, etc.
+ *
+ * @param registerListener  The function to register the listener to the custom HTTP server.
+ * @param server            The server to process the requests.
+ */
+export function createCustomLegacyHttpGateway(
+    registerListener: (opts: IRegisterListenerOptions) => IRegisterListenerResult,
+    server: dT.IServer
+): dT.IGateway {
+
+    return new LegacyHttpGateway(registerListener, server);
 }

package/src/lib/transporters/legacy-http/LegacyHttp.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/legacy-http/README.md

@@ -0,0 +1,13 @@
+# Televoke1/Http
+
+This module provides the http/1.1 transporter for Televoke1 protocol. It's a compatibility module for Televoke1, working
+with the Televoke v1.x library.
+
+> It's okay to use the Televoke1 as a fallback if both Televoke1 and Televoke2 are used.
+
+## Examples
+
+- [Server](../../../examples/network/server.ts)
+- [Client over TCP](../../../examples/network/legacy-http-client.ts)
+- [Client over TLS](../../../examples/network/legacy-https-client.ts)
+- [Client over Unix Domain Socket](../../../examples/network/legacy-http-unix-client.ts)

package/src/lib/transporters/legacy-http/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/lwdfx/LwDFX.Tcp.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/lwdfx/LwDFX.Tcp.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.Tls.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/lwdfx/LwDFX.Tls.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.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.
@@ -75,7 +75,7 @@ export class LwDFXTransporter extends EventEmitter implements dT.ITransporter, S
         return this._conn.connected;
     }
 
-    public write(frame: string | Buffer | Array<string | Buffer>): void {
+    public write(frame: Array<string | Buffer>): void {
 
         if (!this._conn.writable) {
 
@@ -85,15 +85,10 @@ export class LwDFXTransporter extends EventEmitter implements dT.ITransporter, S
         this._conn.write(frame);
     }
 
-    public end(frame?: Buffer | string): void {
+    public end(): void {
 
         if (this._conn.writable) {
 
-            if (frame) {
-
-                this._conn.write(frame);
-            }
-
             this._conn.end();
         }
     }

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

@@ -0,0 +1,12 @@
+# Televoke2/LwDFX
+
+This module provides the Televoke2 protocol over LwDFXv1. It allows you to connect to the Televoke2 server with LwDFXv1.
+
+> `@litert/lwdfx` is required to use this module.
+
+## Examples
+
+- [Server](../../../examples/network/server.ts)
+- [Client over TCP](../../../examples/network/lwdfx-tcp-client.ts)
+- [Client over TLS](../../../examples/network/lwdfx-tls-client.ts)
+- [Client over Unix Domain Socket](../../../examples/network/lwdfx-unix-client.ts)

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.