@sachitv/avro-typescript 0.4.0

package/esm/rpc/protocol/wire_format/messages.js

@@ -0,0 +1,175 @@
+import { createType } from "../../../type/create_type.js";
+import { ReadableTap } from "../../../serialization/tap.js";
+import { concatUint8Arrays } from "../../../internal/collections/array_utils.js";
+import { cloneMetadataMap, toRequiredMetadataMap, } from "./metadata.js";
+import { encodeHandshakeRequest, encodeHandshakeResponse, readHandshakeRequestFromTap, readHandshakeResponseFromTap, } from "./handshake.js";
+const MAP_OF_BYTES_TYPE = createType({
+    type: "map",
+    values: "bytes",
+});
+const STRING_TYPE = createType("string");
+const BOOLEAN_TYPE = createType("boolean");
+async function readOptionalHandshake(buffer, reader, expectHandshake) {
+    const tap = new ReadableTap(buffer);
+    if (expectHandshake) {
+        const handshake = await reader(tap);
+        return { handshake, tap };
+    }
+    const initialPos = tap.getPos();
+    try {
+        const handshake = await reader(tap);
+        return { handshake, tap };
+    }
+    catch {
+        return { tap: new ReadableTap(buffer, initialPos) };
+    }
+}
+/**
+ * Encodes a call request message into a binary format for transmission.
+ *
+ * The encoded message includes optional handshake data, metadata, message name,
+ * and the request payload. The format follows the Avro RPC wire protocol.
+ *
+ * @param init - The call request initialization object containing handshake,
+ *               metadata, message name, request data, and request type.
+ * @returns A promise that resolves to the encoded message as a Uint8Array.
+ */
+export async function encodeCallRequest(init) {
+    const parts = [];
+    if (init.handshake) {
+        parts.push(await encodeHandshakeRequest(init.handshake));
+    }
+    const metadata = toRequiredMetadataMap(init.metadata);
+    parts.push(new Uint8Array(await MAP_OF_BYTES_TYPE.toBuffer(metadata)));
+    parts.push(new Uint8Array(await STRING_TYPE.toBuffer(init.messageName)));
+    parts.push(new Uint8Array(await init.requestType.toBuffer(init.request)));
+    return concatUint8Arrays(parts);
+}
+/**
+ * Decodes a binary call request message into a structured object.
+ *
+ * This function parses the complete message including handshake (if expected),
+ * metadata, message name, and request payload.
+ *
+ * @param buffer - The binary data containing the encoded call request.
+ * @param options - Decoding options including the request type and whether
+ *                  to expect handshake data.
+ * @returns A promise that resolves to the decoded call request message.
+ */
+export async function decodeCallRequest(buffer, options) {
+    const { requestType, expectHandshake = false } = options;
+    const envelope = await decodeCallRequestEnvelope(buffer, {
+        expectHandshake,
+    });
+    const request = await requestType.read(envelope.bodyTap);
+    return {
+        handshake: envelope.handshake,
+        metadata: envelope.metadata,
+        messageName: envelope.messageName,
+        request,
+    };
+}
+/**
+ * Decodes the envelope of a call request message without parsing the request payload.
+ *
+ * This function is useful for inspecting message metadata and headers before
+ * deciding whether to parse the full request payload. The request data remains
+ * in the bodyTap for later reading.
+ *
+ * @param buffer - The binary data containing the encoded call request.
+ * @param options - Options specifying whether to expect handshake data.
+ * @returns A promise that resolves to the call request envelope.
+ */
+export async function decodeCallRequestEnvelope(buffer, options = {}) {
+    const { expectHandshake = false } = options;
+    const { handshake: handshakeResult, tap: handshakeTap } = await readOptionalHandshake(buffer, readHandshakeRequestFromTap, expectHandshake);
+    const handshake = handshakeResult;
+    const tap = handshakeTap;
+    const metadataMap = await MAP_OF_BYTES_TYPE.read(tap);
+    const metadata = cloneMetadataMap(metadataMap);
+    const messageName = await STRING_TYPE.read(tap);
+    return {
+        handshake,
+        metadata,
+        messageName,
+        bodyTap: tap,
+    };
+}
+/**
+ * Encodes a call response message into a binary format for transmission.
+ *
+ * The encoded message includes optional handshake data, metadata, error flag,
+ * and either the response payload or error payload based on the isError flag.
+ *
+ * @param init - The call response initialization object containing handshake,
+ *               metadata, error flag, payload, and response/error types.
+ * @returns A promise that resolves to the encoded message as a Uint8Array.
+ */
+export async function encodeCallResponse(init) {
+    const parts = [];
+    if (init.handshake) {
+        parts.push(await encodeHandshakeResponse(init.handshake));
+    }
+    const metadata = toRequiredMetadataMap(init.metadata);
+    parts.push(new Uint8Array(await MAP_OF_BYTES_TYPE.toBuffer(metadata)));
+    parts.push(new Uint8Array(await BOOLEAN_TYPE.toBuffer(init.isError)));
+    if (init.isError) {
+        parts.push(new Uint8Array(await init.errorType.toBuffer(init.payload)));
+    }
+    else {
+        parts.push(new Uint8Array(await init.responseType.toBuffer(init.payload)));
+    }
+    return concatUint8Arrays(parts);
+}
+/**
+ * Decodes a binary call response message into a structured object.
+ *
+ * This function parses the complete message including handshake (if expected),
+ * metadata, error flag, and response or error payload based on the error flag.
+ *
+ * @param buffer - The binary data containing the encoded call response.
+ * @param options - Decoding options including response and error types, and
+ *                  whether to expect handshake data.
+ * @returns A promise that resolves to the decoded call response message.
+ */
+export async function decodeCallResponse(buffer, options) {
+    const { responseType, errorType, expectHandshake = false } = options;
+    const envelope = await decodeCallResponseEnvelope(buffer, {
+        expectHandshake,
+    });
+    const payload = envelope.isError
+        ? await errorType.read(envelope.bodyTap)
+        : await responseType.read(envelope.bodyTap);
+    return {
+        handshake: envelope.handshake,
+        metadata: envelope.metadata,
+        isError: envelope.isError,
+        payload,
+    };
+}
+/**
+ * Decodes the envelope of a call response message without parsing the response payload.
+ *
+ * This function is useful for inspecting message metadata and error status before
+ * deciding whether to parse the full response or error payload. The payload data
+ * remains in the bodyTap for later reading.
+ *
+ * @param buffer - The binary data containing the encoded call response.
+ * @param options - Options specifying whether to expect handshake data.
+ * @returns A promise that resolves to the call response envelope.
+ */
+export async function decodeCallResponseEnvelope(buffer, options = {}) {
+    const { expectHandshake = false } = options;
+    const { handshake: handshakeResult, tap: handshakeTap } = await readOptionalHandshake(buffer, readHandshakeResponseFromTap, expectHandshake);
+    const handshake = handshakeResult;
+    const tap = handshakeTap;
+    const metadataMap = await MAP_OF_BYTES_TYPE.read(tap);
+    const metadata = cloneMetadataMap(metadataMap);
+    const isError = await BOOLEAN_TYPE.read(tap);
+    return {
+        handshake,
+        metadata,
+        isError,
+        bodyTap: tap,
+    };
+}

package/esm/rpc/protocol/wire_format/metadata.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Represents a metadata value as a byte array in Avro RPC metadata.
+ */
+export type MetadataValue = Uint8Array;
+/**
+ * Initialization types for Avro RPC metadata, allowing various input formats
+ * that can be converted to a MetadataMap.
+ */
+export type MetadataInit = Map<string, MetadataValue> | Iterable<[string, MetadataValue]> | Record<string, MetadataValue>;
+/**
+ * A map of string keys to MetadataValue byte arrays, representing the standard
+ * form of Avro RPC metadata.
+ */
+export type MetadataMap = Map<string, MetadataValue>;
+/**
+ * Checks if the given value is an iterable metadata initialization type,
+ * useful for distinguishing between Map and Record inputs in Avro RPC metadata.
+ */
+export declare function isIterableMetadata(value: MetadataInit | undefined | null): value is Iterable<[string, MetadataValue]>;
+/**
+ * Clones a Uint8Array to ensure immutability of metadata values in Avro RPC.
+ * Throws if the value is not a Uint8Array.
+ */
+export declare function cloneBytes(value: Uint8Array, field: string): Uint8Array;
+/**
+ * Converts a MetadataInit to a MetadataMap, cloning all byte values for
+ * immutability in Avro RPC metadata handling.
+ */
+export declare function toMetadataMap(init: MetadataInit): MetadataMap;
+/**
+ * Converts an optional MetadataInit to a MetadataMap or null, used for
+ * optional metadata fields in Avro RPC messages.
+ */
+export declare function toOptionalMetadataMap(init: MetadataInit | undefined | null): MetadataMap | null;
+/**
+ * Converts an optional MetadataInit to a MetadataMap, defaulting to an empty
+ * map if null or undefined, for required metadata in Avro RPC.
+ */
+export declare function toRequiredMetadataMap(init: MetadataInit | undefined | null): MetadataMap;
+/**
+ * Creates a deep clone of a MetadataMap, cloning all byte values to ensure
+ * immutability in Avro RPC metadata operations.
+ */
+export declare function cloneMetadataMap(map: MetadataMap): MetadataMap;

package/esm/rpc/protocol/wire_format/metadata.js

@@ -0,0 +1,74 @@
+/**
+ * Checks if the given value is an iterable metadata initialization type,
+ * useful for distinguishing between Map and Record inputs in Avro RPC metadata.
+ */
+export function isIterableMetadata(value) {
+    if (value === undefined || value === null) {
+        return false;
+    }
+    if (value instanceof Map) {
+        return true;
+    }
+    return typeof value[Symbol.iterator] === "function";
+}
+/**
+ * Clones a Uint8Array to ensure immutability of metadata values in Avro RPC.
+ * Throws if the value is not a Uint8Array.
+ */
+export function cloneBytes(value, field) {
+    if (!(value instanceof Uint8Array)) {
+        throw new TypeError(`${field} must be a Uint8Array.`);
+    }
+    return new Uint8Array(value);
+}
+/**
+ * Converts a MetadataInit to a MetadataMap, cloning all byte values for
+ * immutability in Avro RPC metadata handling.
+ */
+export function toMetadataMap(init) {
+    const map = new Map();
+    if (isIterableMetadata(init)) {
+        for (const [key, value] of init) {
+            if (typeof key !== "string") {
+                throw new TypeError("Metadata keys must be strings.");
+            }
+            map.set(key, cloneBytes(value, `Metadata value for '${key}'`));
+        }
+        return map;
+    }
+    for (const [key, value] of Object.entries(init)) {
+        map.set(key, cloneBytes(value, `Metadata value for '${key}'`));
+    }
+    return map;
+}
+/**
+ * Converts an optional MetadataInit to a MetadataMap or null, used for
+ * optional metadata fields in Avro RPC messages.
+ */
+export function toOptionalMetadataMap(init) {
+    if (init === undefined || init === null) {
+        return null;
+    }
+    return toMetadataMap(init);
+}
+/**
+ * Converts an optional MetadataInit to a MetadataMap, defaulting to an empty
+ * map if null or undefined, for required metadata in Avro RPC.
+ */
+export function toRequiredMetadataMap(init) {
+    if (init === undefined || init === null) {
+        return new Map();
+    }
+    return toMetadataMap(init);
+}
+/**
+ * Creates a deep clone of a MetadataMap, cloning all byte values to ensure
+ * immutability in Avro RPC metadata operations.
+ */
+export function cloneMetadataMap(map) {
+    const clone = new Map();
+    for (const [key, value] of map.entries()) {
+        clone.set(key, cloneBytes(value, `Metadata value for '${key}'`));
+    }
+    return clone;
+}

package/esm/rpc/protocol_core.d.ts

@@ -0,0 +1,121 @@
+import type { Type } from "../schemas/type.js";
+import { Message } from "./definitions/message_definition.js";
+import type { MessageDefinition, MessageHandler, MessageTransportOptions, ProtocolDefinition, ProtocolLike, ProtocolOptions, ResolverEntry } from "./definitions/protocol_definitions.js";
+import type { MessageListener } from "./message_endpoint/listener.js";
+import type { MessageEmitter } from "./message_endpoint/emitter.js";
+import type { BinaryDuplexLike, StatelessTransportFactory } from "./protocol/transports/transport_helpers.js";
+/**
+ * Core Avro RPC protocol representation that validates schemas, hashes the
+ * protocol definition, and coordinates message handlers and transports.
+ */
+export declare class Protocol implements ProtocolLike {
+    #private;
+    private constructor();
+    /**
+     * Creates a new Protocol instance from a definition.
+     * @param attrs The protocol definition object.
+     * @param opts Protocol creation options.
+     * @returns A new Protocol instance.
+     */
+    static create(attrs: ProtocolDefinition, opts?: ProtocolOptions): Protocol;
+    /**
+     * Creates a subprotocol sharing the same context but without a parent reference.
+     * @returns A new Protocol instance.
+     */
+    subprotocol(): Protocol;
+    /**
+     * Gets the protocol name.
+     */
+    getName(): string;
+    /**
+     * Returns the string representation of the protocol (JSON).
+     */
+    toString(): string;
+    /**
+     * Gets the MD5 hash of the protocol as a hex string.
+     */
+    get hashKey(): string;
+    /**
+     * Gets the MD5 hash of the protocol as bytes.
+     */
+    getHashBytes(): Uint8Array;
+    /**
+     * Gets all messages defined in the protocol.
+     */
+    getMessages(): Map<string, Message>;
+    /**
+     * Gets all named types defined in the protocol.
+     */
+    getNamedTypes(): Type[];
+    /**
+     * Gets a specific message by name.
+     */
+    getMessage(name: string): Message | undefined;
+    /**
+     * Gets the names of all messages in the protocol.
+     */
+    getMessageNames(): readonly string[];
+    /**
+     * Gets the definition of a specific message.
+     */
+    getMessageDefinition(name: string): MessageDefinition | undefined;
+    /**
+     * Gets summary information about the protocol.
+     */
+    getProtocolInfo(): import("./definitions/protocol_definitions.js").ProtocolInfo;
+    /**
+     * Gets a type definition by name.
+     */
+    getType(name: string): Type | undefined;
+    /**
+     * Registers a message handler for a specific message name.
+     */
+    on(name: string, handler: MessageHandler): this;
+    /**
+     * Emits a message using the provided emitter.
+     * @param name The name of the message to emit.
+     * @param request The request payload.
+     * @param emitter The emitter to use.
+     */
+    emit(name: string, request: unknown, emitter: MessageEmitter): Promise<unknown>;
+    /**
+     * Creates a new message emitter for this protocol.
+     * @param transport The transport factory or instance.
+     * @param opts Transport options.
+     */
+    createEmitter(transport: BinaryDuplexLike | StatelessTransportFactory, opts?: MessageTransportOptions): MessageEmitter;
+    /**
+     * Creates a new message listener for this protocol.
+     * @param transport The transport instance.
+     * @param opts Transport options.
+     */
+    createListener(transport: BinaryDuplexLike, opts?: MessageTransportOptions): MessageListener;
+    /**
+     * Gets the handler registered for a specific message.
+     */
+    getHandler(name: string): MessageHandler | undefined;
+    /**
+     * Gets schema resolvers for an emitter (client) given a server hash.
+     */
+    getEmitterResolvers(hashKey: string, messageName: string): ResolverEntry | undefined;
+    /**
+     * Gets schema resolvers for a listener (server) given a client hash.
+     */
+    getListenerResolvers(hashKey: string, messageName: string): ResolverEntry | undefined;
+    /**
+     * Checks if resolvers exist for a given client hash.
+     */
+    hasListenerResolvers(hashKey: string): boolean;
+    /**
+     * Checks if resolvers exist for a given server hash.
+     */
+    hasEmitterResolvers(hashKey: string): boolean;
+    /**
+     * Ensures resolvers exist for communicating with a remote protocol (client-side).
+     */
+    ensureEmitterResolvers(hashKey: string, remote: ProtocolLike): void;
+    /**
+     * Ensures resolvers exist for communicating with a remote protocol (server-side).
+     */
+    ensureListenerResolvers(hashKey: string, emitterProtocol: ProtocolLike): void;
+}