@litert/televoke 1.0.0-0 → 1.0.0-10

package/src/lib/client/LegacyHttpClient.impl.ts

@@ -36,7 +36,8 @@ class TvLegacyHttpClient extends EventEmitter implements C.IClient<any> {
         private readonly _request: (opts: any, cb: (resp: $Http.IncomingMessage) => void) => $Http.ClientRequest,
         private readonly _opts: $Https.RequestOptions,
         private readonly _agent: $Http.Agent,
-        private readonly _apiNameWrapper?: (name: string) => string
+        private readonly _retryOnConnReset: boolean = true,
+        private readonly _apiNameWrapper?: (name: string) => string,
     ) {
 
         super();
@@ -75,7 +76,26 @@ class TvLegacyHttpClient extends EventEmitter implements C.IClient<any> {
         return Promise.reject(new Shared.errors.cmd_not_impl());
     }
 
-    public invoke(api: any, ...args: any[]): Promise<any> {
+    public async invoke(api: any, ...args: any[]): Promise<any> {
+
+        try {
+
+            return await this._invoke(api, ...args);
+        }
+        catch (e) {
+
+            if (this._retryOnConnReset && (e as any)?.code === 'ECONNRESET') {
+
+                return this._invoke(api, ...args);
+            }
+            else {
+
+                throw e;
+            }
+        }
+    }
+
+    private _invoke(api: any, ...args: any[]): Promise<any> {
 
         const CST = Date.now();
 
@@ -84,7 +104,7 @@ class TvLegacyHttpClient extends EventEmitter implements C.IClient<any> {
             rid: 0,
             cst: CST,
             args,
-            api: this._apiNameWrapper ? this._apiNameWrapper(api) : api
+            api: this._apiNameWrapper?.(api) ?? api
         });
 
         return new Promise((resolve, reject) => {
@@ -174,7 +194,7 @@ class TvLegacyHttpClient extends EventEmitter implements C.IClient<any> {
                         case v1.EResponseCode.MALFORMED_ARGUMENTS:
                         case v1.EResponseCode.SYSTEM_ERROR:
                         default:
-                            reject(new Shared.errors.unknown({
+                            reject(new Shared.errors.server_internal_error({
                                 api, ...data
                             }));
                             break;
@@ -207,7 +227,7 @@ class TvLegacyHttpClient extends EventEmitter implements C.IClient<any> {
     }
 }
 
-export interface IHttpClientNetworkOptions extends $Https.RequestOptions {
+interface IHttpClientOptionsBase extends $Https.RequestOptions {
 
     /**
      * Whether to use HTTPS.
@@ -217,44 +237,43 @@ export interface IHttpClientNetworkOptions extends $Https.RequestOptions {
     https?: boolean;
 
     /**
-     * The hostname of HTTP server.
+     * Wrap the API name before sending to server.
      *
-     * @default 'localhost'
+     * @default null
      */
-    hostname: string;
+    apiNameWrapper?: (name: string) => string;
 
     /**
-     * The port of HTTP server.
+     * Whether to retry on connection reset.
      *
-     * @default 80 or 443
+     * @default true
      */
-    port?: number;
+    retryOnConnReset?: boolean;
+}
+
+export interface IHttpClientNetworkOptions extends IHttpClientOptionsBase {
 
     /**
-     * The path to the RPC entry.
+     * The hostname of HTTP server.
      *
-     * @default '/'
+     * @default 'localhost'
      */
-    path?: string;
-
-    apiNameWrapper?: (name: string) => string;
-}
-
-export interface IHttpClientUnixSocketOptions extends $Https.RequestOptions {
+    hostname: string;
 
     /**
-     * Whether to use HTTPS.
+     * The port of HTTP server.
      *
-     * > Always `false` for Unix domain socket.
+     * @default 80 or 443
      */
-    https?: false;
+    port?: number;
+}
+
+export interface IHttpClientUnixSocketOptions extends IHttpClientOptionsBase {
 
     /**
      * The path of Unix domain socket to connect to.
      */
     socketPath: string;
-
-    apiNameWrapper?: (name: string) => string;
 }
 
 export type IHttpClientOptions = IHttpClientNetworkOptions | IHttpClientUnixSocketOptions;
@@ -265,14 +284,15 @@ export function createLegacyHttpClient<TAPIs extends Shared.IObject>(opts: IHttp
         opts.https ? $Https.request : $Http.request,
         opts,
         opts.https ? new $Https.Agent({
-            maxSockets: 0,
-            keepAlive: true,
-            keepAliveMsecs: DEFAULT_TIMEOUT
+            'maxSockets': 0,
+            'keepAlive': true,
+            'keepAliveMsecs': DEFAULT_TIMEOUT
         }) : new $Http.Agent({
-            maxSockets: 0,
-            keepAlive: true,
-            keepAliveMsecs: DEFAULT_TIMEOUT
+            'maxSockets': 0,
+            'keepAlive': true,
+            'keepAliveMsecs': DEFAULT_TIMEOUT
         }),
-        opts.apiNameWrapper
+        opts.retryOnConnReset,
+        opts.apiNameWrapper,
     );
 }

package/src/lib/server/Server.decl.ts

@@ -41,7 +41,7 @@ export type IRouteApiCallback = (response: string | Buffer | Array<string | Buff
 
 export type IRouteLegacyApiCallback = (response: unknown | Shared.TvErrorResponse | Shared.TelevokeError) => void;
 
-export interface IRouter {
+export interface IRouter extends Shared.IEventListener<Shared.IDefaultEvents> {
 
     /**
      * The encoding of the API request/response.
@@ -82,6 +82,8 @@ export interface IRouter {
 export interface IServerEvents extends Shared.IDefaultEvents {
 
     channel(channel: IChannel): void;
+
+    warning(error: unknown, channel?: IChannel): void;
 }
 
 export interface IServer extends Shared.IEventListener<IServerEvents> {

package/src/lib/server/Server.impl.ts

@@ -35,11 +35,19 @@ export class TvServer extends EventEmitter implements dS.IServer, dT.IServer {
         private readonly _streamManagerFactory: Shared.IStreamManagerFactory = Shared.createSharedStreamManagerFactory()
     ) {
         super();
+        this.router.on('error', this._onRouterError);
     }
 
+    private readonly _onRouterError = (e: unknown): void => {
+
+        this.emit('error', e);
+    };
+
     public setRouter(router: dS.IRouter): void {
 
-        this.router = router;
+        this.router?.off('error', this._onRouterError);
+        this.router = router
+            .on('error', this._onRouterError);
     }
 
     public registerChannel(transporter: dT.ITransporter): void {
@@ -60,6 +68,7 @@ export class TvServer extends EventEmitter implements dS.IServer, dT.IServer {
                 });
             })
             .on('error', (err) => this.emit('error', err))
+            .on('warning', (err) => this.emit('warning', err, this._channels[id]))
             .on('close', () => { delete this._channels[id]; });
     }
 

package/src/lib/server/SimpleJsonApiRouter.ts

@@ -17,12 +17,13 @@
 import type * as dS from './Server.decl';
 import * as Shared from '../shared';
 import { buffer2json } from '../shared/Utils';
+import { EventEmitter } from 'node:events';
 
 export type ISimpleJsonApiHandler = (ctx: dS.IRequestContext, ...args: any[]) => unknown;
 
 export type ISimpleJsonMessageHandler = (ctx: dS.IRequestContext, msg: unknown) => unknown;
 
-export class SimpleJsonApiRouter implements dS.IRouter {
+export class SimpleJsonApiRouter extends EventEmitter implements dS.IRouter {
 
     public get encoding(): string {
 
@@ -65,8 +66,18 @@ export class SimpleJsonApiRouter implements dS.IRouter {
             if (result instanceof Promise) {
 
                 result.then(
-                    (data) => { cb(JSON.stringify(data)); },
-                    (e) => { this._processError(cb, e); },
+                    (data) => {
+
+                        try {
+
+                            cb(JSON.stringify(data ?? null));
+                        }
+                        catch (e) {
+
+                            this._processError(cb, e, name);
+                        }
+                    },
+                    (e) => { this._processError(cb, e, name); },
                 );
             }
             else {
@@ -76,11 +87,11 @@ export class SimpleJsonApiRouter implements dS.IRouter {
         }
         catch (e) {
 
-            this._processError(cb, e);
+            this._processError(cb, e, name);
         }
     }
 
-    private _processError(cb: dS.IRouteApiCallback, e: unknown): void {
+    private _processError(cb: dS.IRouteApiCallback, e: unknown, name: string): void {
 
         if (e instanceof Shared.TelevokeError) {
 
@@ -90,11 +101,12 @@ export class SimpleJsonApiRouter implements dS.IRouter {
 
         if (e instanceof Shared.TvErrorResponse) {
 
-            cb(new Shared.errors.app_error(JSON.stringify(e.data)));
+            cb(new Shared.errors.app_error(JSON.stringify(e.data ?? null)));
             return;
         }
 
-        cb(new Shared.errors.app_error('null'));
+        cb(new Shared.errors.server_internal_error());
+        this.emit('error', new Shared.errors.unprocessable_error({ api: name }, e));
     }
 
     public processLegacyApi(
@@ -118,8 +130,8 @@ export class SimpleJsonApiRouter implements dS.IRouter {
             if (result instanceof Promise) {
 
                 result.then(
-                    (data) => { cb(data); },
-                    (e) => { this._processError(cb, e); },
+                    (data) => { cb(data ?? null); },
+                    (e) => { this._processError(cb, e, name); },
                 );
             }
             else {
@@ -129,7 +141,7 @@ export class SimpleJsonApiRouter implements dS.IRouter {
         }
         catch (e) {
 
-            this._processError(cb, e);
+            this._processError(cb, e, name);
         }
     }
 }

package/src/lib/shared/BinaryStream.ts

@@ -20,6 +20,11 @@ import { Readable } from 'node:stream';
 
 export class TvBinaryReadStream extends Readable implements Shared.IBinaryReadStream {
 
+    /**
+     * The index of next chunk to read.
+     */
+    public nextIndex: number = 0;
+
     private _timer: NodeJS.Timeout | null = null;
 
     public constructor(
@@ -87,7 +92,7 @@ export class TvBinaryReadStream extends Readable implements Shared.IBinaryReadSt
         }, this._timeout);
     }
 
-    public push(buf: Buffer | null): boolean {
+    public append(chunkSegments: Buffer[]): void {
 
         if (this.readableEnded) {
 
@@ -99,7 +104,12 @@ export class TvBinaryReadStream extends Readable implements Shared.IBinaryReadSt
             this._resetTimer();
         }
 
-        return super.push(buf);
+        for (const s of chunkSegments) {
+
+            super.push(s);
+        }
+
+        this.nextIndex++;
     }
 
     public close(): void {

package/src/lib/shared/Channel.impl.ts

@@ -438,18 +438,34 @@ export abstract class AbstractTvChannelV2
                     break;
                 }
 
-                const chunks = (packet as v2.IBinaryChunkRequestPacket).ct.body as Buffer[];
+                const chunkSegments = (packet as v2.IBinaryChunkRequestPacket).ct.body as Buffer[];
 
-                if (!chunks[0]?.byteLength) {
+                const chunkIndex = (packet as v2.IBinaryChunkRequestPacket).ct.index;
+
+                if (chunkIndex === 0xFFFFFFFF) {
+
+                    stream.abort();
+                }
+                else if (chunkIndex !== stream.nextIndex) {
+
+                    this._reply({
+                        'cmd': v2.ECommand.BINARY_CHUNK,
+                        'typ': v2.EPacketType.ERROR_RESPONSE,
+                        'seq': packet.seq,
+                        'ct': new E.errors.stream_index_mismatch({
+                            'sid': (packet as v2.IBinaryChunkRequestPacket).ct.streamId,
+                            'chId': this.id,
+                        }),
+                    });
+                    break;
+                }
+                else if (!chunkSegments[0]?.byteLength) {
 
                     stream.close();
                 }
                 else {
 
-                    for (const chunk of chunks) {
-
-                        stream.push(chunk);
-                    }
+                    stream.append(chunkSegments);
                 }
 
                 this._reply({
@@ -546,7 +562,7 @@ export abstract class AbstractTvChannelV2
         });
     }
 
-    public sendBinaryChunk(streamId: number, chunk: Buffer | null): Promise<void> {
+    public sendBinaryChunk(streamId: number, index: number | false, chunk: Buffer | null): Promise<void> {
 
         if (!this.writable) {
 
@@ -561,6 +577,7 @@ export abstract class AbstractTvChannelV2
             'seq': seq,
             'ct': {
                 streamId,
+                'index': index === false ? 0xFFFFFFFF : index,
                 'body': chunk ?? [],
             }
         } satisfies v2.IBinaryChunkRequestPacket));

package/src/lib/shared/Encodings/v2/DecoderV2.ts

@@ -234,7 +234,7 @@ class TvPushMessageRequestDecoder implements IPacketDecoder {
             'cmd': CSv2.ECommand.PUSH_MESSAGE,
             'typ': CSv2.EPacketType.REQUEST,
             'seq': ctx.seq,
-            'ct': readVarBuffer16(ctx)
+            'ct': readVarBuffer(ctx)
         } satisfies dEnc2.IPushMessageRequestPacket;
     }
 }
@@ -244,12 +244,14 @@ class TvBinaryChunkRequestDecoder implements IPacketDecoder {
     public decode(ctx: IDecodeContext): dEnc2.ICommandPacket {
 
         const streamId = readSmallBytes(4, B4, ctx).readUInt32LE(0);
+        const chunkIndex = readSmallBytes(4, B4, ctx).readUInt32LE(0);
         return {
             'cmd': CSv2.ECommand.BINARY_CHUNK,
             'typ': CSv2.EPacketType.REQUEST,
             'seq': ctx.seq,
             'ct': {
                 'streamId': streamId,
+                'index': chunkIndex,
                 'body': readVarBuffer(ctx),
             }
         } satisfies dEnc2.IBinaryChunkRequestPacket;

package/src/lib/shared/Encodings/v2/EncoderV2.ts

@@ -104,10 +104,11 @@ class BinaryChunkRequestEncoder implements IPacketEncoder {
 
     public encode(packet: dEnc2.IBinaryChunkRequestPacket): v2.IDataChunkArray {
 
-        const leadSeg = Buffer.allocUnsafe(CS.HEADER_SIZE + 4 + 4);
+        const leadSeg = Buffer.allocUnsafe(CS.HEADER_SIZE + 12);
 
         writePacketHeader(leadSeg, packet.cmd, packet.typ, packet.seq);
         leadSeg.writeUInt32LE(packet.ct.streamId, CS.HEADER_SIZE);
+        leadSeg.writeUInt32LE(packet.ct.index, CS.HEADER_SIZE + 4);
 
         if (Array.isArray(packet.ct.body)) {
 
@@ -118,12 +119,12 @@ class BinaryChunkRequestEncoder implements IPacketEncoder {
                 bodyLen += Buffer.byteLength(p);
             }
 
-            leadSeg.writeUInt32LE(bodyLen, CS.HEADER_SIZE + 4);
+            leadSeg.writeUInt32LE(bodyLen, CS.HEADER_SIZE + 8);
 
             return [leadSeg, ...packet.ct.body];
         }
 
-        leadSeg.writeUInt32LE(Buffer.byteLength(packet.ct.body), CS.HEADER_SIZE + 4);
+        leadSeg.writeUInt32LE(Buffer.byteLength(packet.ct.body), CS.HEADER_SIZE + 8);
 
         return [leadSeg, packet.ct.body];
     }
@@ -173,7 +174,7 @@ class PushMessageRequestEncoder implements IPacketEncoder {
 
     public encode(packet: dEnc2.IPushMessageRequestPacket): v2.IDataChunkArray {
 
-        const leadSeg = Buffer.allocUnsafe(CS.HEADER_SIZE + 2);
+        const leadSeg = Buffer.allocUnsafe(CS.HEADER_SIZE + 4);
 
         writePacketHeader(leadSeg, packet.cmd, packet.typ, packet.seq);
 
@@ -186,12 +187,12 @@ class PushMessageRequestEncoder implements IPacketEncoder {
                 bodyLen += Buffer.byteLength(p);
             }
 
-            leadSeg.writeUInt16LE(bodyLen, CS.HEADER_SIZE);
+            leadSeg.writeUInt32LE(bodyLen, CS.HEADER_SIZE);
 
             return [leadSeg, ...packet.ct];
         }
 
-        leadSeg.writeUInt16LE(Buffer.byteLength(packet.ct), CS.HEADER_SIZE);
+        leadSeg.writeUInt32LE(Buffer.byteLength(packet.ct), CS.HEADER_SIZE);
 
         return [leadSeg, packet.ct];
     }

package/src/lib/shared/Encodings/v2/Encoding.v2.decl.ts

@@ -111,6 +111,11 @@ export interface IBinaryChunkRequestPacket extends IRequestPacket {
          */
         readonly streamId: number;
 
+        /**
+         * The index of this chunk in the stream.
+         */
+        readonly index: number;
+
         /**
          * The chunk data.
          */

package/src/lib/shared/Errors.ts

@@ -73,9 +73,12 @@ const errorCtors = {
     ...defineProtocolError('stream_not_found'),
     ...defineProtocolError('stream_aborted'),
     ...defineProtocolError('stream_closed'),
+    ...defineProtocolError('stream_index_mismatch'),
     ...defineProtocolError('system_busy'),
+    ...defineProtocolError('server_internal_error'),
     ...defineProtocolError('timeout'),
     ...defineProtocolError('unknown'),
+    ...defineProtocolError('unprocessable_error'),
 
     ['app_error']: class AppError extends TelevokeError {
 

package/src/lib/shared/Shared.decl.ts

@@ -197,13 +197,28 @@ export interface ITransporter {
     getAllProperties(): Record<string, unknown>;
 }
 
-export interface IBinaryReadStream extends Readable {
+export interface IBinaryReadStream extends Omit<Readable, 'push'> {
 
     /**
      * The unique id of binary stream.
      */
     readonly id: number;
 
+    /**
+     * The expected index of next chunk to read.
+     */
+    readonly nextIndex: number;
+
+    /**
+     * Append a binary data chunk to this binary stream, with the given index.
+     *
+     * @param chunk     The binary data chunk to be appended.
+     * @param index     The index of the chunk in the stream.
+     *
+     * @returns Whether the chunk is appended successfully.
+     */
+    append(chunk: Buffer[]): void;
+
     /**
      * Abort the binary stream before it's completed, and release the resource.
      *
@@ -332,13 +347,17 @@ export interface IChannelBase<TEvents extends IDefaultEvents> extends IEventList
     /**
      * Send a binary data chunk to an opened binary stream on the remote side.
      *
-     * > **NOTE: It is not recommended to send a large binary data chunk at once. A large binary chunk should be split**
-     * > **into several small chunks, and then send them one by one, in order.**
+     * > **NOTE**
+     * > - It is not recommended to send a large binary data chunk at once. A large binary chunk should be split
+     * >   into several small chunks, and then send them one by one, in order.
+     * > - Set the `index` to `false` to close the binary stream by aborting.
+     * > - Set the `chunk` to `null` to close the binary stream by finishing.
      *
      * @param id        The `id` field in `IBinaryReadStream`, opened by remote side.
+     * @param index     The index of this chunk in the stream.
      * @param chunks    The binary data chunks to be sent.
      */
-    sendBinaryChunk(id: number, chunk: Buffer | null): Promise<void>;
+    sendBinaryChunk(id: number, index: number | false, chunk: Buffer | null): Promise<void>;
 
     /**
      * Close the channel.

package/src/lib/transporters/http-listener/HttpListener.ts

@@ -74,6 +74,7 @@ class HttpListener extends AbstractHttpListener {
         }
 
         const gateway = this._gateway;
+        this._gateway = null;
 
         return new Promise<void>((resolve, reject) => {
 

package/src/lib/transporters/legacy-http/LegacyHttp.Server.ts

@@ -27,7 +27,7 @@ const encoder = new v1.TvEncoderV1();
 const INVALID_REQUEST_RESPONSE = Buffer.from(encoder.encodeApiErrorResponse(
     'null',
     Shared.Encodings.v1.EResponseCode.MALFORMED_ARGUMENTS,
-    'INVALID REQUEST',
+    '"INVALID REQUEST"',
     0
 ));
 
@@ -76,6 +76,19 @@ class LegacyHttpGateway extends EventEmitter implements dT.IGateway {
             .setLegacyApiProcessor(this._onRequest);
     }
 
+    private _sendResponse(resp: Http.ServerResponse, data: string): void {
+
+        try {
+
+            resp.setHeader('content-length', Buffer.byteLength(data));
+            resp.end(data);
+        }
+        catch (e) {
+
+            this.emit('error', e);
+        }
+    }
+
     public get running(): boolean {
 
         return this._listener.running;
@@ -159,7 +172,6 @@ class LegacyHttpGateway extends EventEmitter implements dT.IGateway {
                     refuseBadRequest(resp);
                     this.emit('error', new Shared.errors.invalid_packet({
                         reason: 'invalid_json',
-                        data: buf,
                     }, e));
                     return;
                 }
@@ -169,7 +181,6 @@ class LegacyHttpGateway extends EventEmitter implements dT.IGateway {
                     refuseBadRequest(resp);
                     this.emit('error', new Shared.errors.invalid_packet({
                         reason: 'malformed_json',
-                        data: input,
                     }));
                     return;
                 }
@@ -185,48 +196,54 @@ class LegacyHttpGateway extends EventEmitter implements dT.IGateway {
 
                         if (result instanceof Shared.errors.app_error) {
 
-                            const data = encoder.encodeApiErrorResponse(
+                            this._sendResponse(resp, encoder.encodeApiErrorResponse(
                                 input.rid,
                                 v1.EResponseCode.FAILURE,
                                 result.message,
                                 recvAt
-                            );
-
-                            resp.setHeader('content-length', Buffer.byteLength(data));
-                            resp.end(data);
+                            ));
                         }
                         else if (result instanceof Shared.errors.api_not_found) {
 
-                            const data = encoder.encodeApiErrorResponse(
+                            this._sendResponse(resp, encoder.encodeApiErrorResponse(
                                 input.rid,
                                 v1.EResponseCode.API_NOT_FOUND,
                                 'null',
                                 recvAt
-                            );
-
-                            resp.setHeader('content-length', Buffer.byteLength(data));
-                            resp.end(data);
+                            ));
                         }
                         else {
 
-                            const data = encoder.encodeApiErrorResponse(
+                            this._sendResponse(resp, encoder.encodeApiErrorResponse(
                                 input.rid,
                                 v1.EResponseCode.SYSTEM_ERROR,
                                 'null',
                                 recvAt
-                            );
-
-                            resp.setHeader('content-length', Buffer.byteLength(data));
-                            resp.end(data);
+                            ));
                         }
 
                         return;
                     }
 
-                    const data = encoder.encodeApiOkResponse(input.rid, result ?? null, recvAt);
+                    let data: string;
+
+                    try {
+
+                        data = encoder.encodeApiOkResponse(input.rid, result ?? null, recvAt);
+                    }
+                    catch (e) {
+
+                        data = encoder.encodeApiErrorResponse(
+                            input.rid,
+                            v1.EResponseCode.SYSTEM_ERROR,
+                            'null',
+                            recvAt
+                        );
+
+                        this.emit('error', new Shared.errors.unprocessable_error({ api: input.api }, e));
+                    }
 
-                    resp.setHeader('content-length', Buffer.byteLength(data));
-                    resp.end(data);
+                    this._sendResponse(resp, data);
 
                 }, input.api, input.args, new LegacyHttpTransporter(req));
             });