@litert/televoke 1.1.0 → 1.3.0

package/src/lib/client/Client.Constants.ts

@@ -0,0 +1,4 @@
+export enum EArgsEncodings {
+    JSON = 0,
+    RESERVED = 0x10000, // All customized encodings should be greater than this value.
+}

package/src/lib/client/Client.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.
@@ -23,6 +23,31 @@ export interface IChannelEvents extends Shared.IDefaultEvents {
     ['push_message'](msg: Buffer[]): void;
 }
 
+export interface IApiCallResult<T> {
+
+    /**
+     * The extension binary chunks replied from server.
+     *
+     * @optional only the server who supports `televoke/2.1` would send this field, if necessary.
+     */
+    binChunks?: Buffer[][];
+
+    /**
+     * The API call result.
+     */
+    result: T;
+}
+
+export interface IApiCallOptions {
+
+    /**
+     * The extension binary chunks to be sent to server.
+     *
+     * @optional only the server who supports `televoke/2.1` could recognize this field, and the old implementation will ignore this field.
+     */
+    binChunks?: Array<Buffer | string | Array<Buffer | string>>;
+}
+
 export interface IClient<TApis extends Shared.IObject>
     extends Shared.IEventListener<IChannelEvents>, Pick<
         Shared.IChannelBase<IChannelEvents>,
@@ -51,11 +76,26 @@ export interface IClient<TApis extends Shared.IObject>
     /**
      * Invoke an API.
      *
+     * > This method does not support extension added in `televoke/2.1`.
+     * > To use the extension feature, please use `callApi` instead.
+     *
      * @param name  The API name.
      * @param args  The arguments.
      */
     invoke<TName extends keyof TApis>(
         name: Shared.IfIsFn<TApis[TName], TName>,
-        ...args: TApis[TName] extends Shared.IFn<infer TArgs, any> ? TArgs : never
+        ...args: TApis[TName] extends Shared.IFn<infer TArgs, unknown> ? TArgs : never
     ): Promise<TApis[TName] extends Shared.IFn<any[], infer TRet> ? TRet : never>;
+
+    /**
+     * Invoke an API.
+     *
+     * @param name  The API name.
+     * @param args  The arguments.
+     */
+    callApi<TName extends keyof TApis>(
+        name: Shared.IfIsFn<TApis[TName], TName>,
+        args: TApis[TName] extends Shared.IFn<infer TArgs, unknown> ? TArgs : never,
+        opts?: IApiCallOptions,
+    ): Promise<TApis[TName] extends Shared.IFn<any[], infer TRet> ? IApiCallResult<TRet> : never>;
 }

package/src/lib/client/JsonApiClient.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.
@@ -16,6 +16,7 @@
 
 import * as Shared from '../shared';
 import type * as dC from './Client.decl';
+import * as cC from './Client.Constants';
 import type * as dT from '../transporters';
 import { EventEmitter } from 'node:events';
 import { AbstractTvChannelV2, encoder } from '../shared/Channel.impl';
@@ -144,9 +145,55 @@ class TvJsonApiClient<TApis extends Shared.IObject> extends EventEmitter impleme
 
         try {
 
-            const resp = await (await this._getChannel()).apiCall(name as string, JSON.stringify(args));
+            const resp = await (await this._getChannel()).apiCall(
+                name as string,
+                JSON.stringify(args),
+                cC.EArgsEncodings.JSON,
+            );
 
-            return buffer2json(resp);
+            return buffer2json(resp.body);
+        }
+        catch (e) {
+
+            if (e instanceof Shared.errors.app_error) {
+
+                let info: unknown;
+
+                try {
+
+                    info = JSON.parse(e.message);
+                }
+                catch {
+
+                    throw e;
+                }
+
+                throw new Shared.TvErrorResponse(info);
+            }
+
+            throw e;
+        }
+    }
+
+    public async callApi(
+        name: unknown,
+        args: any[],
+        opts?: dC.IApiCallOptions
+    ): Promise<any> {
+
+        try {
+
+            const resp = await (await this._getChannel()).apiCall(
+                name as string,
+                JSON.stringify(args),
+                cC.EArgsEncodings.JSON,
+                opts?.binChunks,
+            );
+
+            return {
+                result: buffer2json(resp.body),
+                binChunks: resp.binChunks,
+            } satisfies dC.IApiCallResult<any>;
         }
         catch (e) {
 
@@ -205,8 +252,10 @@ class TvClientChannel extends AbstractTvChannelV2 {
 
     public apiCall(
         name: string,
-        argsBody: Buffer | string | Buffer[],
-    ): Promise<Buffer[]> {
+        argsBody: v2.IEncBinItem,
+        argsEncoding: number,
+        extBinaryChunks?: Array<Buffer | string | Array<Buffer | string>>,
+    ): Promise<{ body: Buffer[]; binChunks?: Buffer[][]; }> {
 
         if (!this.writable) {
 
@@ -221,9 +270,11 @@ class TvClientChannel extends AbstractTvChannelV2 {
             'seq': seq,
             'ct': {
                 'name': name,
-                'body': typeof argsBody === 'string' ? Buffer.from(argsBody) : argsBody
+                'body': argsBody,
+                'bodyEnc': argsEncoding,
+                'binChunks': extBinaryChunks,
             }
-        } satisfies v2.IApiRequestPacket));
+        } satisfies v2.IApiRequestPacketEncoding));
 
         return new Promise((resolve, reject) => {
 
@@ -235,7 +286,7 @@ class TvClientChannel extends AbstractTvChannelV2 {
                     return;
                 }
 
-                resolve(resp.ct as Buffer[]);
+                resolve(resp.ct as v2.IApiReplyPacketDecoded['ct']);
             });
         });
     }

package/src/lib/client/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/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/server/LegacyServerChannel.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.
@@ -18,7 +18,7 @@ import * as Shared from '../shared';
 import { EventEmitter } from 'node:events';
 import * as v2 from '../shared/Encodings/v2';
 
-export type ILegacyApiResponseCallback = (body: v2.IDataChunkField | Shared.TelevokeError) => void;
+export type ILegacyApiResponseCallback = (body: v2.IEncBinItem | Shared.TelevokeError) => void;
 
 const streamManager = Shared.createDisabledStreamManagerFactory()(null as any);
 

package/src/lib/server/Server.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.
@@ -35,9 +35,28 @@ export interface IRequestContext {
      * The channel which the request comes from.
      */
     readonly channel: IChannel;
+
+    /**
+     * The extension binary chunks carried by the request.
+     *
+     * @optional only the client implemented `televoke/2.1` will send this field, if necessary.
+     */
+    readonly requestBinaryChunks?: Buffer[][];
+
+    /**
+     * The extension binary chunks should be replied to the client.
+     *
+     * If the field is set, the client could receive the binary chunks in the reply.
+     *
+     * @optional only the client implemented `televoke/2.1` could recognize this field, and the old implementation will ignore this field.
+     */
+    replyBinaryChunks?: Array<Buffer[] | Buffer>;
 }
 
-export type IRouteApiCallback = (response: string | Buffer | Array<string | Buffer> | Shared.TelevokeError) => void;
+export type IRouteApiCallback = (
+    response: string | Buffer | Array<string | Buffer> | Shared.TelevokeError,
+    replyBinaryChunks?: Array<Buffer[] | Buffer>
+) => void;
 
 export type IRouteLegacyApiCallback = (response: unknown | Shared.TvErrorResponse | Shared.TelevokeError) => void;
 
@@ -53,12 +72,14 @@ export interface IRouter extends Shared.IEventListener<Shared.IDefaultEvents> {
      *
      * @param cb        The callback function of processing result.
      * @param name      The API name.
+     * @param argsEnc   The encoding of the API arguments.
      * @param args      The API arguments.
      * @param context   The request context.
      */
     processApi(
         cb: IRouteApiCallback,
         name: string,
+        argsEnc: number,
         args: Buffer[],
         context: IRequestContext
     ): void;

package/src/lib/server/Server.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.
@@ -62,9 +62,10 @@ export class TvServer extends EventEmitter implements dS.IServer, dT.IServer {
         );
 
         (this._channels[id] as Shared.IChannelBase<IChannelEvents>)
-            .on('api_call', (cb, name, body) => {
-                this.router.processApi(cb, name, body, {
-                    channel: this._channels[id],
+            .on('api_call', (cb, name, argsBody, _seq, argsEnc, binChunks) => {
+                this.router.processApi(cb, name, argsEnc, argsBody, {
+                    'channel': this._channels[id],
+                    'requestBinaryChunks': binChunks
                 });
             })
             .on('error', (err) => this.emit('error', err))

package/src/lib/server/ServerChannel.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/server/SimpleJsonApiRouter.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.
@@ -18,6 +18,7 @@ import type * as dS from './Server.decl';
 import * as Shared from '../shared';
 import { buffer2json } from '../shared/Utils';
 import { EventEmitter } from 'node:events';
+import { v2 } from '../shared/Encodings';
 
 export type ISimpleJsonApiHandler = (ctx: dS.IRequestContext, ...args: any[]) => unknown;
 
@@ -39,7 +40,19 @@ export class SimpleJsonApiRouter extends EventEmitter implements dS.IRouter {
         return this;
     }
 
-    public processApi(cb: dS.IRouteApiCallback, name: string, body: Buffer[], ctx: dS.IRequestContext): void {
+    public processApi(
+        cb: dS.IRouteApiCallback,
+        name: string,
+        argsEnc: number,
+        body: Buffer[],
+        ctx: dS.IRequestContext
+    ): void {
+
+        if (argsEnc !== v2.JSON_API_ARGS_ENCODING) {
+
+            cb(new Shared.errors.unk_api_enc());
+            return;
+        }
 
         if (!this._apiHandlers[name]) {
             cb(new Shared.errors.api_not_found({ name }));
@@ -70,7 +83,7 @@ export class SimpleJsonApiRouter extends EventEmitter implements dS.IRouter {
 
                         try {
 
-                            cb(JSON.stringify(data ?? null));
+                            cb(JSON.stringify(data ?? null), ctx.replyBinaryChunks);
                         }
                         catch (e) {
 
@@ -82,7 +95,7 @@ export class SimpleJsonApiRouter extends EventEmitter implements dS.IRouter {
             }
             else {
 
-                cb(JSON.stringify(result ?? null));
+                cb(JSON.stringify(result ?? null), ctx.replyBinaryChunks);
             }
         }
         catch (e) {

package/src/lib/server/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/BinaryStream.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/BinaryStreamManager.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/Channel.impl.ts

@@ -1,5 +1,6 @@
+/* eslint-disable max-lines */
 /**
- * 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.
@@ -26,10 +27,15 @@ export interface IChannelEvents extends Shared.IDefaultEvents {
     close(): void;
 
     ['api_call'](
-        callback: (response: v2.IDataChunkField | E.TelevokeError | E.TvErrorResponse) => void,
+        callback: (
+            result: string | Buffer | Array<string | Buffer> | E.TelevokeError | E.TvErrorResponse,
+            binChunks?: Array<Buffer | Buffer[]>,
+        ) => void,
         name: string,
         args: Buffer[],
         sequence: number,
+        argsEncoding: number,
+        extBinChunks?: Buffer[][],
     ): void;
 
     ['push_message'](
@@ -290,7 +296,7 @@ export abstract class AbstractTvChannelV2
         request.callback(packet);
     }
 
-    private _reply(packet: v2.ICommandPacket): void {
+    private _reply<T extends v2.ICommandPacket = v2.ICommandPacket>(packet: T): void {
 
         try {
 
@@ -403,30 +409,44 @@ export abstract class AbstractTvChannelV2
 
                 this.emit(
                     'api_call',
-                    once((response: v2.IDataChunkField | E.TelevokeError) => {
+                    once((response: v2.IEncBinItem | E.TelevokeError, binChunks?: v2.IEncBinItem[]) => {
 
                         this._recvRequests--;
 
-                        this._reply({
-                            'cmd': v2.ECommand.API_CALL,
-                            'typ': response instanceof E.TelevokeError ?
-                                v2.EPacketType.ERROR_RESPONSE :
-                                v2.EPacketType.SUCCESS_RESPONSE,
-                            'seq': packet.seq,
-                            'ct': response,
-                        });
+                        if (response instanceof E.TelevokeError) {
+
+                            this._reply<v2.IErrorReplyPacket>({
+                                'cmd': v2.ECommand.API_CALL,
+                                'typ': v2.EPacketType.ERROR_RESPONSE,
+                                'seq': packet.seq,
+                                'ct': response,
+                            });
+                        }
+                        else {
+                            this._reply<v2.IApiReplyPacketEncoding>({
+                                'cmd': v2.ECommand.API_CALL,
+                                'typ': v2.EPacketType.SUCCESS_RESPONSE,
+                                'seq': packet.seq,
+                                'ct': {
+                                    'body': response,
+                                    binChunks,
+                                },
+                            });
+                        }
                         this._tryClean();
                     }),
-                    (packet as v2.IApiRequestPacket).ct.name,
-                    (packet as v2.IApiRequestPacket).ct.body,
-                    packet.seq
+                    (packet as v2.IApiRequestPacketDecoded).ct.name,
+                    (packet as v2.IApiRequestPacketDecoded).ct.body,
+                    packet.seq,
+                    (packet as v2.IApiRequestPacketDecoded).ct.bodyEnc,
+                    (packet as v2.IApiRequestPacketDecoded).ct.binChunks,
                 );
 
                 break;
 
             case v2.ECommand.BINARY_CHUNK: {
 
-                const stream = this.streams.get((packet as v2.IBinaryChunkRequestPacket).ct.streamId)!;
+                const stream = this.streams.get((packet as v2.IBinaryChunkRequestPacketEncoding).ct.streamId)!;
 
                 if (!stream) {
 
@@ -435,16 +455,16 @@ export abstract class AbstractTvChannelV2
                         'typ': v2.EPacketType.ERROR_RESPONSE,
                         'seq': packet.seq,
                         'ct': new E.errors.stream_not_found({
-                            'sid': (packet as v2.IBinaryChunkRequestPacket).ct.streamId,
+                            'sid': (packet as v2.IBinaryChunkRequestPacketEncoding).ct.streamId,
                             'chId': this.id,
                         }),
                     });
                     break;
                 }
 
-                const chunkSegments = (packet as v2.IBinaryChunkRequestPacket).ct.body as Buffer[];
+                const chunkSegments = (packet as v2.IBinaryChunkRequestPacketEncoding).ct.body as Buffer[];
 
-                const chunkIndex = (packet as v2.IBinaryChunkRequestPacket).ct.index;
+                const chunkIndex = (packet as v2.IBinaryChunkRequestPacketEncoding).ct.index;
 
                 if (chunkIndex === 0xFFFFFFFF) {
 
@@ -457,7 +477,7 @@ export abstract class AbstractTvChannelV2
                         'typ': v2.EPacketType.ERROR_RESPONSE,
                         'seq': packet.seq,
                         'ct': new E.errors.stream_index_mismatch({
-                            'sid': (packet as v2.IBinaryChunkRequestPacket).ct.streamId,
+                            'sid': (packet as v2.IBinaryChunkRequestPacketEncoding).ct.streamId,
                             'chId': this.id,
                         }),
                     });
@@ -541,7 +561,7 @@ export abstract class AbstractTvChannelV2
             'typ': v2.EPacketType.REQUEST,
             'seq': seq,
             'ct': message,
-        } satisfies v2.IPingRequestPacket));
+        } satisfies v2.IPingRequestPacketEncoding));
 
         return new Promise((resolve, reject) => {
 
@@ -584,7 +604,7 @@ export abstract class AbstractTvChannelV2
                 'index': index === false ? 0xFFFFFFFF : index,
                 'body': chunk ?? [],
             }
-        } satisfies v2.IBinaryChunkRequestPacket));
+        } satisfies v2.IBinaryChunkRequestPacketEncoding));
 
         return new Promise((resolve, reject) => {
 
@@ -616,7 +636,7 @@ export abstract class AbstractTvChannelV2
             'typ': v2.EPacketType.REQUEST,
             'seq': seq,
             'ct': message,
-        } satisfies v2.IPushMessageRequestPacket));
+        } satisfies v2.IPushMessageRequestPacketEncoding));
 
         return new Promise((resolve, reject) => {
 

package/src/lib/shared/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/shared/Encodings/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/Encodings/v1/EncoderV1.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/Encodings/v1/Protocol.v1.decls.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/Encodings/v1/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/Encodings/v2/Constants.v2.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.
@@ -28,4 +28,23 @@ export enum EPacketType {
     ERROR_RESPONSE = 0x02,
 }
 
+export const JSON_API_ARGS_ENCODING = 0x00; // JSON encoding
+export const DEFAULT_API_ARGS_ENCODING = JSON_API_ARGS_ENCODING;
+
 export const HEADER_SIZE = 8;
+
+export const API_CALL_REQ_EXT_HEADER_SIZE = 12;
+export const API_CALL_RESP_EXT_HEADER_SIZE = 8;
+
+export enum EApiCallReqExtHeaderFieldOffset {
+
+    LENGTH = 0,
+    BODY_ENC = 4,
+    BIN_CHUNK_QTY = 8
+}
+
+export enum EApiCallRespExtHeaderFieldOffset {
+
+    LENGTH = 0,
+    BIN_CHUNK_QTY = 4
+}