@litert/televoke 1.1.0 → 1.3.0

package/src/lib/shared/Encodings/v2/Encoding.v2.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.
@@ -17,122 +17,174 @@
 import type * as CS from './Constants.v2';
 import type { TelevokeError } from '../../Errors';
 
-export type IDataChunkArray = Array<string | Buffer>;
+export type IBinLike = Buffer | string;
 
-export type IDataChunkField = string | Buffer | IDataChunkArray;
+export type IBinLikeArray = IBinLike[];
+
+export type IDecBinItem = Buffer[];
+
+export type IEncBinItem = IBinLike | IBinLikeArray;
 
 export interface ICommandPacket {
 
     /**
      * The command of this packet.
      */
-    readonly cmd: CS.ECommand;
+    cmd: CS.ECommand;
 
     /**
      * The type of this packet.
      */
-    readonly typ: CS.EPacketType;
+    typ: CS.EPacketType;
 
     /**
      * The sequence number of this packet.
      */
-    readonly seq: number;
+    seq: number;
 
     /**
      * The content of this packet.
      */
-    readonly ct: unknown;
+    ct: unknown;
 }
 
 export interface IRequestPacket extends ICommandPacket {
 
-    readonly typ: CS.EPacketType.REQUEST;
+    typ: CS.EPacketType.REQUEST;
 }
 
-export interface IErrorResponsePacket extends ICommandPacket {
+export interface IErrorReplyPacket extends ICommandPacket {
 
-    readonly typ: CS.EPacketType.ERROR_RESPONSE;
+    typ: CS.EPacketType.ERROR_RESPONSE;
 
-    readonly ct: TelevokeError;
+    ct: TelevokeError;
 }
 
-export interface ISuccessResponsePacket extends ICommandPacket {
+export interface IOkReplyPacket extends ICommandPacket {
 
-    readonly typ: CS.EPacketType.SUCCESS_RESPONSE;
+    typ: CS.EPacketType.SUCCESS_RESPONSE;
 }
 
-export interface IApiRequestPacket extends IRequestPacket {
+export interface IApiRequestPacket<TIsReq extends boolean> extends IRequestPacket {
 
-    readonly cmd: CS.ECommand.API_CALL;
+    cmd: CS.ECommand.API_CALL;
 
-    readonly ct: {
+    ct: {
 
         /**
          * The name of the API to be invoked.
          */
-        readonly name: string;
+        name: string;
 
         /**
          * The arguments of the API to be invoked.
          */
-        readonly body: IDataChunkField;
+        body: TIsReq extends true ? IEncBinItem : Buffer[];
+
+        /**
+         * The encoding identifier of the body.
+         *
+         * @default 0 which means JSON
+         */
+        bodyEnc?: number;
+
+        /**
+         * The extension binary chunks of the API to be invoked.
+         */
+        binChunks?: TIsReq extends true ? IEncBinItem[] : Buffer[][];
     };
 }
 
-export interface IPingRequestPacket extends IRequestPacket {
+export type IApiRequestPacketEncoding = IApiRequestPacket<true>;
+
+export type IApiRequestPacketDecoded = IApiRequestPacket<false>;
+
+export interface IApiReplyPacket<TIsReq extends boolean> extends IOkReplyPacket {
 
-    readonly cmd: CS.ECommand.PING;
+    cmd: CS.ECommand.API_CALL;
 
-    readonly ct: IDataChunkField;
+    ct: {
+
+        body: TIsReq extends true ? IEncBinItem : Buffer[];
+
+        /**
+         * The extension binary chunks of the API to be invoked.
+         */
+        binChunks?: TIsReq extends true ? IEncBinItem[] : Buffer[][];
+    };
 }
 
-export interface IPushMessageRequestPacket extends IRequestPacket {
+export type IApiReplyPacketEncoding = IApiReplyPacket<true>;
 
-    readonly cmd: CS.ECommand.PUSH_MESSAGE;
+export type IApiReplyPacketDecoded = IApiReplyPacket<false>;
 
-    readonly ct: IDataChunkField;
+// PING Command
+
+export interface IPingRequestPacket<TIsReq extends boolean> extends IRequestPacket {
+
+    cmd: CS.ECommand.PING;
+
+    ct: TIsReq extends true ? IEncBinItem : IDecBinItem;
 }
 
+export type IPingRequestPacketEncoding = IPingRequestPacket<true>;
+
+export type IPingRequestPacketDecoded = IPingRequestPacket<false>;
+
+export interface IPingReplyPacket<TIsReq extends boolean> extends IOkReplyPacket {
+
+    cmd: CS.ECommand.PING;
+
+    ct: TIsReq extends true ? IEncBinItem : Buffer[];
+}
+
+export type IPingReplyPacketEncoding = IPingReplyPacket<true>;
+
+export type IPingReplyPacketDecoded = IPingReplyPacket<false>;
+
+// PUSH_MESSAGE Command
+
+export interface IPushMessageRequestPacket<TIsReq extends boolean> extends IRequestPacket {
+
+    cmd: CS.ECommand.PUSH_MESSAGE;
+
+    ct: TIsReq extends true ? IEncBinItem : Buffer[];
+}
+
+export type IPushMessageRequestPacketEncoding = IPushMessageRequestPacket<true>;
+
+export type IPushMessageRequestPacketDecoded = IPushMessageRequestPacket<false>;
+
 export interface ICloseRequestPacket extends IRequestPacket {
 
-    readonly cmd: CS.ECommand.CLOSE;
+    cmd: CS.ECommand.CLOSE;
 
-    readonly ct: null;
+    ct: null;
 }
 
-export interface IBinaryChunkRequestPacket extends IRequestPacket {
+export interface IBinaryChunkRequestPacket<TIsReq extends boolean> extends IRequestPacket {
 
-    readonly cmd: CS.ECommand.BINARY_CHUNK;
+    cmd: CS.ECommand.BINARY_CHUNK;
 
-    readonly ct: {
+    ct: {
 
         /**
          * The stream ID of this chunk should be sent to.
          */
-        readonly streamId: number;
+        streamId: number;
 
         /**
          * The index of this chunk in the stream.
          */
-        readonly index: number;
+        index: number;
 
         /**
          * The chunk data.
          */
-        readonly body: IDataChunkField;
+        body: TIsReq extends true ? IEncBinItem : Buffer[];
     };
 }
 
-export interface IApiResponsePacket extends ISuccessResponsePacket {
+export type IBinaryChunkRequestPacketEncoding = IBinaryChunkRequestPacket<true>;
 
-    readonly cmd: CS.ECommand.API_CALL;
-
-    readonly ct: IDataChunkField;
-}
-
-export interface IPingResponsePacket extends ISuccessResponsePacket {
-
-    readonly cmd: CS.ECommand.PING;
-
-    readonly ct: IDataChunkField;
-}
+export type IBinaryChunkRequestPacketDecoded = IBinaryChunkRequestPacket<false>;

package/src/lib/shared/Encodings/v2/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/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.
@@ -69,6 +69,7 @@ const errorCtors = {
     ...defineProtocolError('channel_inactive'),
     ...defineProtocolError('channel_closed'),
     ...defineProtocolError('api_not_found'),
+    ...defineProtocolError('unk_api_enc'),
     ...defineProtocolError('cmd_not_impl'),
     ...defineProtocolError('network_error'),
     ...defineProtocolError('stream_not_found'),

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.
@@ -14,18 +14,23 @@
  * limitations under the License.
  */
 
-import { Readable } from 'node:stream';
+import type { Readable } from 'node:stream';
 
-export type IFn<TArgs extends any[], TRet> = (...args: TArgs) => TRet;
+export type IFn<TArgs extends unknown[], TRet> = (...args: TArgs) => TRet;
 
-export type IVoidFn<TArgs extends any[]> = IFn<TArgs, void>;
+export type IVoidFn<TArgs extends any[] = 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;
+export type IfIsFn<T, TTrue = T, TFalse = never> = T extends IFn<any[], unknown> ? TTrue : TFalse;
 
-export type IfIsOfFn<T, TFn extends IFn<any[], any>, TTrue = T, TFalse = never> = T extends TFn ? TTrue : TFalse;
+export type IfIsOfFn<
+    T,
+    TFn extends IFn<unknown[], unknown>,
+    TTrue = T,
+    TFalse = never
+> = T extends TFn ? TTrue : TFalse;
 
 export interface IEventListener<T extends IDefaultEvents> {
 
@@ -37,7 +42,7 @@ export interface IEventListener<T extends IDefaultEvents> {
      * @param event         The event name.
      * @param listener      The listener function.
      */
-    on<TKey extends keyof T>(event: TKey, listener: IfIsOfFn<T[TKey], IVoidFn<any[]>>): this;
+    on<TKey extends keyof T>(event: TKey, listener: IfIsOfFn<T[TKey], IVoidFn>): this;
 
     /**
      * Register a listener for the given event.
@@ -47,7 +52,7 @@ export interface IEventListener<T extends IDefaultEvents> {
      * @param event         The event name.
      * @param listener      The listener function.
      */
-    on(event: string | symbol, listener: IVoidFn<any[]>): this;
+    on(event: string | symbol, listener: IVoidFn): this;
 
     /**
      * Register a one-time listener for the given event.
@@ -57,7 +62,7 @@ export interface IEventListener<T extends IDefaultEvents> {
      * @param event         The event name.
      * @param listener      The listener function.
      */
-    once<TKey extends keyof T>(event: TKey, listener: IfIsOfFn<T[TKey], IVoidFn<any[]>>): this;
+    once<TKey extends keyof T>(event: TKey, listener: IfIsOfFn<T[TKey], IVoidFn>): this;
 
     /**
      * Register a one-time listener for the given event.
@@ -67,7 +72,7 @@ export interface IEventListener<T extends IDefaultEvents> {
      * @param event         The event name.
      * @param listener      The listener function.
      */
-    once(event: string | symbol, listener: IVoidFn<any[]>): this;
+    once(event: string | symbol, listener: IVoidFn): this;
 
     /**
      * Register a listener for the given event.
@@ -77,7 +82,7 @@ export interface IEventListener<T extends IDefaultEvents> {
      * @param event         The event name.
      * @param listener      The listener function.
      */
-    addListener<TKey extends keyof T>(event: TKey, listener: IfIsOfFn<T[TKey], IVoidFn<any[]>>): this;
+    addListener<TKey extends keyof T>(event: TKey, listener: IfIsOfFn<T[TKey], IVoidFn>): this;
 
     /**
      * Register a listener for the given event.
@@ -87,7 +92,7 @@ export interface IEventListener<T extends IDefaultEvents> {
      * @param event         The event name.
      * @param listener      The listener function.
      */
-    addListener(event: string | symbol, listener: IVoidFn<any[]>): this;
+    addListener(event: string | symbol, listener: IVoidFn): this;
 
     /**
      * Remove the given listener for the given event.
@@ -97,7 +102,7 @@ export interface IEventListener<T extends IDefaultEvents> {
      * @param event     The event name.
      * @param listener  The listener function.
      */
-    removeListener<TKey extends keyof T>(event: TKey, listener: IVoidFn<any[]>): this;
+    removeListener<TKey extends keyof T>(event: TKey, listener: IVoidFn): this;
 
     /**
      * Remove the given listener for the given event.
@@ -107,7 +112,7 @@ export interface IEventListener<T extends IDefaultEvents> {
      * @param event     The event name.
      * @param listener  The listener function.
      */
-    removeListener(event: string | symbol, listener: IVoidFn<any[]>): this;
+    removeListener(event: string | symbol, listener: IVoidFn): this;
 
     /**
      * Remove the given listener for the given event.
@@ -117,7 +122,7 @@ export interface IEventListener<T extends IDefaultEvents> {
      * @param event     The event name.
      * @param listener  The listener function.
      */
-    off<TKey extends keyof T>(event: TKey, listener: IVoidFn<any[]>): this;
+    off<TKey extends keyof T>(event: TKey, listener: IVoidFn): this;
 
     /**
      * Remove the given listener for the given event.
@@ -127,7 +132,7 @@ export interface IEventListener<T extends IDefaultEvents> {
      * @param event     The event name.
      * @param listener  The listener function.
      */
-    off(event: string | symbol, listener: IVoidFn<any[]>): this;
+    off(event: string | symbol, listener: IVoidFn): this;
 
     /**
      * Remove all listeners for the given event.
@@ -372,5 +377,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.
@@ -20,10 +20,10 @@
  * @param fn    The function to call.
  * @returns     The wrapped function.
  */
-export function once<T extends (...args: any[]) => any>(fn: T): T {
+export function once<T extends (...args: any[]) => unknown>(fn: T): T {
 
     let called = false;
-    let result: any;
+    let result: unknown;
 
     return function(...args: any[]) {
 

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.

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.
@@ -67,7 +67,6 @@ const DEFAULT_REFUSE_STATUS_CODE = 400;
  */
 export const DEFAULT_LEGACY_HTTP_API_PROCESSOR: ILegacyHttpApiProcessor = function(_req, resp): void {
 
-    // eslint-disable-next-line @typescript-eslint/naming-convention
     resp.writeHead(DEFAULT_REFUSE_STATUS_CODE, {
         'Content-Type': 'text/plain',
         'Content-Length': DEFAULT_REFUSE_PAYLOAD.byteLength,
@@ -75,31 +74,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.