@litert/televoke 0.4.7 → 1.0.0-0

package/src/lib/shared/Encodings/v1/EncoderV1.ts

@@ -0,0 +1,66 @@
+/**
+* Copyright 2023 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.
+* You may obtain a copy of the License at
+*
+*   https://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+import * as dEncV1 from './Protocol.v1.decls';
+
+export class TvEncoderV1 {
+
+    public encodeApiRequest(
+        rid: string | number,
+        name: string,
+        args: unknown,
+        timeout: number,
+    ): string {
+
+        return JSON.stringify({
+            ttl: timeout,
+            rid,
+            api: name,
+            args,
+            cst: Date.now(),
+        } satisfies dEncV1.IRequestPayloadV1);
+    }
+
+    public encodeApiOkResponse(
+        rid: string | number,
+        body: unknown,
+        recvAt: number
+    ): string {
+
+        return JSON.stringify({
+            rid,
+            body,
+            sst: Date.now(),
+            srt: recvAt,
+            code: dEncV1.EResponseCode.OK,
+        } satisfies dEncV1.IResponsePayloadV1);
+    }
+
+    public encodeApiErrorResponse(
+        rid: string | number,
+        errorCode: dEncV1.EResponseCode,
+        body: string,
+        recvAt: number
+    ): string {
+
+        if (typeof rid === 'string') {
+
+            rid = JSON.stringify(rid);
+        }
+
+        return `{"rid":${rid},"body":${body},"sst":${Date.now()},"srt":${recvAt},"code":${errorCode}}`;
+    }
+}

package/src/lib/shared/Encodings/v1/Protocol.v1.decls.ts

@@ -0,0 +1,96 @@
+/**
+* Copyright 2023 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.
+* You may obtain a copy of the License at
+*
+*   https://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+export enum EResponseCode {
+
+    /**
+     * API was called succeed
+     */
+    OK,
+    /**
+     * The invoked API does not exist on the remote server.
+     */
+    API_NOT_FOUND,
+    /**
+     * Some unexpected error happened.
+     */
+    SYSTEM_ERROR,
+    /**
+     * Logical error happened inside the API handler.
+     */
+    FAILURE,
+    /**
+     * The arguments inside the request is malformed.
+     */
+    MALFORMED_ARGUMENTS
+}
+
+export interface IRequestPayloadV1 {
+
+    ttl: number;
+
+    api: string;
+
+    args: unknown;
+
+    cst: number;
+
+    rid: string | number;
+}
+
+export interface IResponsePayloadV1 {
+
+    /**
+     * The time when server sent the response.
+     */
+    sst: number;
+
+    /**
+     * The time when server received the request.
+     */
+    srt: number;
+
+    /**
+     * The identity of the request.
+     */
+    rid: string | number;
+
+    /**
+     * The protocol status code of the response.
+     */
+    code: number;
+
+    /**
+     * The content of API response.
+     */
+    body: unknown;
+}
+
+/**
+ * The default port for HTTP.
+ */
+export const DEFAULT_INSECURE_PORT = 80;
+
+/**
+ * The default port for HTTPS.
+ */
+export const DEFAULT_SECURE_PORT = 443;
+
+export const DEFAULT_BACKLOG = 511;
+
+export const DEFAULT_HOSTNAME = 'localhost';
+
+export const MAX_PACKET_SIZE = 64 * 1024 * 1024;

package/src/lib/shared/Encodings/v1/index.ts

@@ -0,0 +1,18 @@
+/**
+* Copyright 2023 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.
+* You may obtain a copy of the License at
+*
+*   https://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+export * from './EncoderV1';
+export * from './Protocol.v1.decls';

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

@@ -0,0 +1,31 @@
+/**
+* Copyright 2023 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.
+* You may obtain a copy of the License at
+*
+*   https://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+export enum ECommand {
+    API_CALL = 0x00,
+    PUSH_MESSAGE = 0x01,
+    BINARY_CHUNK = 0x02,
+    PING = 0xFE,
+    CLOSE = 0xFF
+}
+
+export enum EPacketType {
+    REQUEST = 0x00,
+    SUCCESS_RESPONSE = 0x01,
+    ERROR_RESPONSE = 0x02,
+}
+
+export const HEADER_SIZE = 8;

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

@@ -0,0 +1,404 @@
+/**
+* Copyright 2023 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.
+* You may obtain a copy of the License at
+*
+*   https://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+import * as CSv2 from './Constants.v2';
+import * as CS from '../../Constants';
+import { ProtocolError, TelevokeError, errors } from '../../Errors';
+import type * as dEnc2 from './Encoding.v2.decl';
+
+interface IDecodeContext {
+
+    chunks: Buffer[];
+
+    chIndex: number;
+
+    chOffset: number;
+
+    command: CSv2.ECommand;
+
+    type: CSv2.EPacketType;
+
+    seq: number;
+}
+
+const B8 = Buffer.allocUnsafe(8);
+const B4 = Buffer.allocUnsafe(4);
+const B2 = Buffer.allocUnsafe(2);
+
+interface IPacketDecoder {
+
+    decode(ctx: IDecodeContext): dEnc2.ICommandPacket;
+}
+
+function readSmallBytes(bytes: number, buf: Buffer, ctx: IDecodeContext): Buffer {
+
+    let readBytes = 0;
+
+    while (readBytes < bytes) {
+
+        if (ctx.chIndex === ctx.chunks.length) {
+
+            throw new errors.incomplete_packet();
+        }
+
+        const c = ctx.chunks[ctx.chIndex];
+        const cLen = c.byteLength;
+        let cOff = ctx.chOffset;
+
+        do {
+
+            buf[readBytes++] = c[cOff++];
+        }
+        while (cOff < cLen && readBytes < bytes);
+
+        if (cOff === cLen) {
+
+            ctx.chIndex++;
+            ctx.chOffset = 0;
+        }
+        else {
+
+            ctx.chOffset = cOff;
+        }
+
+        if (readBytes === bytes) {
+
+            break;
+        }
+    }
+
+    return buf;
+}
+
+function readLargeBytes(bytes: number, ctx: IDecodeContext): Buffer[] {
+
+    let readBytes = 0;
+    const ret: Buffer[] = [];
+
+    while (readBytes < bytes) {
+
+        if (ctx.chIndex === ctx.chunks.length) {
+
+            throw new errors.incomplete_packet();
+        }
+
+        const c = ctx.chunks[ctx.chIndex];
+        const bytes2Read = Math.min(bytes - readBytes, c.byteLength - ctx.chOffset);
+
+        ret.push(c.subarray(ctx.chOffset, ctx.chOffset + bytes2Read));
+
+        readBytes += bytes2Read;
+        ctx.chOffset += bytes2Read;
+
+        if (ctx.chOffset === c.byteLength) {
+
+            ctx.chIndex++;
+            ctx.chOffset = 0;
+        }
+
+        if (readBytes === bytes) {
+
+            break;
+        }
+    }
+
+    return ret;
+}
+
+function readString(bytes: number, ctx: IDecodeContext): string {
+
+    const td = new TextDecoder('utf8');
+
+    let readBytes = 0;
+    let ret: string = '';
+
+    while (readBytes < bytes) {
+
+        if (ctx.chIndex === ctx.chunks.length) {
+
+            throw new errors.incomplete_packet();
+        }
+
+        const c = ctx.chunks[ctx.chIndex];
+        const bytes2Read = Math.min(bytes - readBytes, c.byteLength - ctx.chOffset);
+
+        ret += td.decode(c.subarray(ctx.chOffset, ctx.chOffset + bytes2Read), { stream: true });
+
+        readBytes += bytes2Read;
+        ctx.chOffset += bytes2Read;
+
+        if (ctx.chOffset === c.byteLength) {
+
+            ctx.chIndex++;
+            ctx.chOffset = 0;
+        }
+
+        if (readBytes === bytes) {
+
+            break;
+        }
+    }
+
+    return ret;
+}
+
+function readVarString(ctx: IDecodeContext): string {
+
+    const len = readSmallBytes(2, B2, ctx).readUInt16LE(0);
+
+    return readString(len, ctx);
+}
+
+function readVarBuffer(ctx: IDecodeContext): Buffer[] {
+
+    const len = readSmallBytes(4, B4, ctx).readUInt32LE(0);
+
+    return readLargeBytes(len, ctx);
+}
+
+function readVarBuffer16(ctx: IDecodeContext): Buffer[] {
+
+    const len = readSmallBytes(2, B4, ctx).readUInt16LE(0);
+
+    return readLargeBytes(len, ctx);
+}
+
+class TvErrorResponseDecoder implements IPacketDecoder {
+
+    public decode(ctx: IDecodeContext): dEnc2.ICommandPacket {
+
+        const len = readSmallBytes(2, B2, ctx).readUInt16LE(0);
+
+        const errorMsg = readString(len, ctx);
+
+        return {
+            'cmd': ctx.command,
+            'typ': CSv2.EPacketType.ERROR_RESPONSE,
+            'seq': ctx.seq,
+            'ct': errorMsg.startsWith(CS.PROTOCOL_ERROR_NAMESPACE) ?
+                new ProtocolError(errorMsg.slice(CS.PROTOCOL_ERROR_NAMESPACE.length + 1), null) :
+                new errors.app_error(errorMsg.slice(CS.APP_ERROR_NAMESPACE.length + 1), null),
+        } satisfies dEnc2.IErrorResponsePacket;
+    }
+}
+
+class TvApiRequestDecoder implements IPacketDecoder {
+
+    public decode(ctx: IDecodeContext): dEnc2.ICommandPacket {
+
+        const name = readVarString(ctx);
+
+        return {
+            'cmd': CSv2.ECommand.API_CALL,
+            'typ': CSv2.EPacketType.REQUEST,
+            'seq': ctx.seq,
+            'ct': {
+                'name': name,
+                'body': readVarBuffer(ctx),
+            }
+        } satisfies dEnc2.IApiRequestPacket;
+    }
+}
+
+class TvPingRequestDecoder implements IPacketDecoder {
+
+    public decode(ctx: IDecodeContext): dEnc2.ICommandPacket {
+
+        return {
+            'cmd': CSv2.ECommand.PING,
+            'typ': CSv2.EPacketType.REQUEST,
+            'seq': ctx.seq,
+            'ct': readVarBuffer16(ctx)
+        } satisfies dEnc2.IPingRequestPacket;
+    }
+}
+
+class TvPushMessageRequestDecoder implements IPacketDecoder {
+
+    public decode(ctx: IDecodeContext): dEnc2.ICommandPacket {
+
+        return {
+            'cmd': CSv2.ECommand.PUSH_MESSAGE,
+            'typ': CSv2.EPacketType.REQUEST,
+            'seq': ctx.seq,
+            'ct': readVarBuffer16(ctx)
+        } satisfies dEnc2.IPushMessageRequestPacket;
+    }
+}
+
+class TvBinaryChunkRequestDecoder implements IPacketDecoder {
+
+    public decode(ctx: IDecodeContext): dEnc2.ICommandPacket {
+
+        const streamId = readSmallBytes(4, B4, ctx).readUInt32LE(0);
+        return {
+            'cmd': CSv2.ECommand.BINARY_CHUNK,
+            'typ': CSv2.EPacketType.REQUEST,
+            'seq': ctx.seq,
+            'ct': {
+                'streamId': streamId,
+                'body': readVarBuffer(ctx),
+            }
+        } satisfies dEnc2.IBinaryChunkRequestPacket;
+    }
+}
+
+class TvCloseRequestDecoder implements IPacketDecoder {
+
+    public decode(ctx: IDecodeContext): dEnc2.ICommandPacket {
+
+        return {
+            'cmd': CSv2.ECommand.CLOSE,
+            'typ': CSv2.EPacketType.REQUEST,
+            'seq': ctx.seq,
+            'ct': null
+        } satisfies dEnc2.ICloseRequestPacket;
+    }
+}
+
+class TvVoidResponseDecoder implements IPacketDecoder {
+
+    public decode(ctx: IDecodeContext): dEnc2.ICommandPacket {
+
+        return {
+            'cmd': ctx.command,
+            'typ': CSv2.EPacketType.SUCCESS_RESPONSE,
+            'seq': ctx.seq,
+            'ct': null
+        } satisfies dEnc2.ISuccessResponsePacket;
+    }
+}
+
+class TvApiResponseDecoder implements IPacketDecoder {
+
+    public decode(ctx: IDecodeContext): dEnc2.ICommandPacket {
+
+        return {
+            'cmd': CSv2.ECommand.API_CALL,
+            'typ': CSv2.EPacketType.SUCCESS_RESPONSE,
+            'seq': ctx.seq,
+            'ct': readVarBuffer(ctx)
+        } satisfies dEnc2.IApiResponsePacket;
+    }
+}
+
+class TvPingResponseDecoder implements IPacketDecoder {
+
+    public decode(ctx: IDecodeContext): dEnc2.ICommandPacket {
+
+        return {
+            'cmd': CSv2.ECommand.PING,
+            'typ': CSv2.EPacketType.SUCCESS_RESPONSE,
+            'seq': ctx.seq,
+            'ct': readVarBuffer16(ctx)
+        } satisfies dEnc2.IPingResponsePacket;
+    }
+}
+
+const packetDecoders: Record<number, IPacketDecoder> = {
+
+    [CSv2.EPacketType.ERROR_RESPONSE + 0x100 * CSv2.ECommand.API_CALL]: new TvErrorResponseDecoder(),
+    [CSv2.EPacketType.ERROR_RESPONSE + 0x100 * CSv2.ECommand.PING]: new TvErrorResponseDecoder(),
+    [CSv2.EPacketType.ERROR_RESPONSE + 0x100 * CSv2.ECommand.BINARY_CHUNK]: new TvErrorResponseDecoder(),
+    [CSv2.EPacketType.ERROR_RESPONSE + 0x100 * CSv2.ECommand.CLOSE]: new TvErrorResponseDecoder(),
+    [CSv2.EPacketType.ERROR_RESPONSE + 0x100 * CSv2.ECommand.PUSH_MESSAGE]: new TvErrorResponseDecoder(),
+
+    [CSv2.EPacketType.REQUEST + 0x100 * CSv2.ECommand.API_CALL]: new TvApiRequestDecoder(),
+    [CSv2.EPacketType.REQUEST + 0x100 * CSv2.ECommand.PING]: new TvPingRequestDecoder(),
+    [CSv2.EPacketType.REQUEST + 0x100 * CSv2.ECommand.PUSH_MESSAGE]: new TvPushMessageRequestDecoder(),
+    [CSv2.EPacketType.REQUEST + 0x100 * CSv2.ECommand.CLOSE]: new TvCloseRequestDecoder(),
+    [CSv2.EPacketType.REQUEST + 0x100 * CSv2.ECommand.BINARY_CHUNK]: new TvBinaryChunkRequestDecoder(),
+
+    [CSv2.EPacketType.SUCCESS_RESPONSE + 0x100 * CSv2.ECommand.PUSH_MESSAGE]: new TvVoidResponseDecoder(),
+    [CSv2.EPacketType.SUCCESS_RESPONSE + 0x100 * CSv2.ECommand.CLOSE]: new TvVoidResponseDecoder(),
+    [CSv2.EPacketType.SUCCESS_RESPONSE + 0x100 * CSv2.ECommand.BINARY_CHUNK]: new TvVoidResponseDecoder(),
+    [CSv2.EPacketType.SUCCESS_RESPONSE + 0x100 * CSv2.ECommand.API_CALL]: new TvApiResponseDecoder(),
+    [CSv2.EPacketType.SUCCESS_RESPONSE + 0x100 * CSv2.ECommand.PING]: new TvPingResponseDecoder(),
+};
+
+export class TvDecoderV2 {
+
+    /**
+     * Pass all chunks of a whole packet to this method, and it will return an array of decoded results.
+     *
+     * @throws {TelevokeError}
+     */
+    public decode(packetChunks: Buffer[]): dEnc2.ICommandPacket {
+
+        const ctx = this._decodeHeader(packetChunks);
+
+        try {
+
+            return packetDecoders[ctx.command * 0x100 + ctx.type].decode(ctx);
+        }
+        catch (e) {
+
+            if (e instanceof TelevokeError) {
+
+                throw e;
+            }
+
+            throw new errors.invalid_packet(null, e);
+        }
+    }
+
+    private _decodeHeader(chunks: Buffer[]): IDecodeContext {
+
+        try {
+
+            const ctx: IDecodeContext = {
+                chunks,
+                chIndex: 0,
+                chOffset: 0,
+                command: 0,
+                type: 0,
+                seq: 0,
+            };
+
+            readSmallBytes(8, B8, ctx);
+
+            ctx.command = B8[0];
+            ctx.type = B8[1];
+
+            if (undefined === CSv2.EPacketType[ctx.type]) {
+
+                throw new errors.invalid_packet({
+                    unknownPacketType: ctx.type,
+                });
+            }
+
+            if (undefined === CSv2.ECommand[ctx.command]) {
+
+                throw new errors.invalid_packet({
+                    unknownCommand: ctx.command,
+                });
+            }
+
+            ctx.seq = B8.readUInt16LE(2)  * 0x1_0000_0000 + B8.readUInt32LE(4);
+
+            return ctx;
+        }
+        catch (e) {
+
+            if (e instanceof TelevokeError) {
+
+                throw e;
+            }
+
+            throw new errors.invalid_packet(null, e);
+        }
+    }
+}