@sachitv/avro-typescript 0.4.0

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

@@ -0,0 +1,110 @@
+import type { ReadableTap } from "../../../serialization/tap.js";
+import { type MetadataInit, type MetadataMap } from "./metadata.js";
+/**
+ * Represents the match status between client and server protocols in the Avro RPC handshake.
+ * - "BOTH": Both client and server protocols match.
+ * - "CLIENT": Only the client protocol is compatible.
+ * - "NONE": Neither protocol matches.
+ */
+export type HandshakeMatch = "BOTH" | "CLIENT" | "NONE";
+/**
+ * Initialization interface for a handshake request in the Avro RPC protocol.
+ * Used to construct the initial handshake message sent by the client.
+ */
+export interface HandshakeRequestInit {
+    /** MD5 hash of the client's Avro protocol schema. */
+    clientHash: Uint8Array;
+    /** Optional string representation of the client's Avro protocol schema. */
+    clientProtocol?: string | null;
+    /** MD5 hash of the server's Avro protocol schema that the client expects. */
+    serverHash: Uint8Array;
+    /** Optional metadata map for additional handshake information. */
+    meta?: MetadataInit | null;
+}
+/**
+ * The processed handshake request message in the Avro RPC protocol.
+ * Contains the resolved fields after decoding or reading from a stream.
+ */
+export interface HandshakeRequestMessage {
+    /** MD5 hash of the client's Avro protocol schema. */
+    clientHash: Uint8Array;
+    /** String representation of the client's Avro protocol schema, or null if not provided. */
+    clientProtocol: string | null;
+    /** MD5 hash of the server's Avro protocol schema that the client expects. */
+    serverHash: Uint8Array;
+    /** Metadata map for additional handshake information, or null if not provided. */
+    meta: MetadataMap | null;
+}
+/**
+ * Initialization interface for a handshake response in the Avro RPC protocol.
+ * Used to construct the response message sent by the server.
+ */
+export interface HandshakeResponseInit {
+    /** The match status indicating compatibility between client and server protocols. */
+    match: HandshakeMatch;
+    /** Optional string representation of the server's Avro protocol schema. */
+    serverProtocol?: string | null;
+    /** Optional MD5 hash of the server's Avro protocol schema. */
+    serverHash?: Uint8Array | null;
+    /** Optional metadata map for additional handshake information. */
+    meta?: MetadataInit | null;
+}
+/**
+ * The processed handshake response message in the Avro RPC protocol.
+ * Contains the resolved fields after decoding or reading from a stream.
+ */
+export interface HandshakeResponseMessage {
+    /** The match status indicating compatibility between client and server protocols. */
+    match: HandshakeMatch;
+    /** String representation of the server's Avro protocol schema, or null if not provided. */
+    serverProtocol: string | null;
+    /** MD5 hash of the server's Avro protocol schema, or null if not provided. */
+    serverHash: Uint8Array | null;
+    /** Metadata map for additional handshake information, or null if not provided. */
+    meta: MetadataMap | null;
+}
+/**
+ * Extracts an optional string value from an Avro union type in handshake messages.
+ * Handles the union of null and string, returning the string if present or null.
+ */
+export declare function _extractOptionalString(unionValue: null | Record<string, string>): string | null;
+/**
+ * Extracts an optional metadata map from an Avro union type in handshake messages.
+ * Handles the union of null and map, returning a cloned metadata map if present or null.
+ */
+export declare function _extractOptionalMetadata(unionValue: null | Record<string, MetadataMap>): MetadataMap | null;
+/**
+ * Extracts an optional MD5 hash from an Avro union type in handshake messages.
+ * Handles the union of null and MD5 fixed type, returning cloned bytes if present or null.
+ */
+export declare function _extractOptionalMd5(unionValue: null | Record<string, Uint8Array>): Uint8Array | null;
+/**
+ * Encodes a handshake request message into a byte buffer for transmission in the Avro RPC protocol.
+ * Serializes the request using the predefined Avro schema for handshake requests.
+ */
+export declare function encodeHandshakeRequest(message: HandshakeRequestInit): Promise<Uint8Array>;
+/**
+ * Decodes a byte buffer into a handshake request message in the Avro RPC protocol.
+ * Deserializes the buffer using the predefined Avro schema for handshake requests.
+ */
+export declare function decodeHandshakeRequest(buffer: ArrayBuffer): Promise<HandshakeRequestMessage>;
+/**
+ * Reads a handshake request message from a readable tap stream in the Avro RPC protocol.
+ * Deserializes the data from the stream using the predefined Avro schema for handshake requests.
+ */
+export declare function readHandshakeRequestFromTap(tap: ReadableTap): Promise<HandshakeRequestMessage>;
+/**
+ * Encodes a handshake response message into a byte buffer for transmission in the Avro RPC protocol.
+ * Serializes the response using the predefined Avro schema for handshake responses.
+ */
+export declare function encodeHandshakeResponse(message: HandshakeResponseInit): Promise<Uint8Array>;
+/**
+ * Decodes a byte buffer into a handshake response message in the Avro RPC protocol.
+ * Deserializes the buffer using the predefined Avro schema for handshake responses.
+ */
+export declare function decodeHandshakeResponse(buffer: ArrayBuffer): Promise<HandshakeResponseMessage>;
+/**
+ * Reads a handshake response message from a readable tap stream in the Avro RPC protocol.
+ * Deserializes the data from the stream using the predefined Avro schema for handshake responses.
+ */
+export declare function readHandshakeResponseFromTap(tap: ReadableTap): Promise<HandshakeResponseMessage>;

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

@@ -0,0 +1,239 @@
+import { createType } from "../../../type/create_type.js";
+import { cloneBytes, cloneMetadataMap, toOptionalMetadataMap, } from "./metadata.js";
+const handshakeRegistry = new Map();
+const HANDSHAKE_REQUEST_TYPE = createType({
+    namespace: "org.apache.avro.ipc",
+    name: "HandshakeRequest",
+    type: "record",
+    fields: [
+        {
+            name: "clientHash",
+            type: { name: "MD5", type: "fixed", size: 16 },
+        },
+        {
+            name: "clientProtocol",
+            type: ["null", "string"],
+            default: null,
+        },
+        {
+            name: "serverHash",
+            type: "org.apache.avro.ipc.MD5",
+        },
+        {
+            name: "meta",
+            type: ["null", { type: "map", values: "bytes" }],
+            default: null,
+        },
+    ],
+}, { registry: handshakeRegistry });
+const HANDSHAKE_RESPONSE_TYPE = createType({
+    namespace: "org.apache.avro.ipc",
+    name: "HandshakeResponse",
+    type: "record",
+    fields: [
+        {
+            name: "match",
+            type: {
+                name: "HandshakeMatch",
+                type: "enum",
+                symbols: ["BOTH", "CLIENT", "NONE"],
+            },
+        },
+        {
+            name: "serverProtocol",
+            type: ["null", "string"],
+            default: null,
+        },
+        {
+            name: "serverHash",
+            type: [
+                "null",
+                "org.apache.avro.ipc.MD5",
+            ],
+            default: null,
+        },
+        {
+            name: "meta",
+            type: ["null", { type: "map", values: "bytes" }],
+            default: null,
+        },
+    ],
+}, { registry: handshakeRegistry });
+const STRING_BRANCH = "string";
+const MAP_BRANCH = "map";
+const MD5_BRANCH = "org.apache.avro.ipc.MD5";
+// @internal
+function _assertMd5Size(value, field) {
+    if (value.length !== 16) {
+        throw new RangeError(`${field} must contain exactly 16 bytes.`);
+    }
+}
+// @internal
+function _wrapUnion(branch, value) {
+    return { [branch]: value };
+}
+// @internal
+function _createHandshakeRequestRecord(message) {
+    const clientHash = cloneBytes(message.clientHash, "clientHash");
+    _assertMd5Size(clientHash, "clientHash");
+    const serverHash = cloneBytes(message.serverHash, "serverHash");
+    _assertMd5Size(serverHash, "serverHash");
+    const clientProtocol = message.clientProtocol ?? null;
+    let clientProtocolUnion;
+    if (clientProtocol === null) {
+        clientProtocolUnion = null;
+    }
+    else if (typeof clientProtocol === "string") {
+        clientProtocolUnion = _wrapUnion(STRING_BRANCH, clientProtocol);
+    }
+    else {
+        throw new TypeError("clientProtocol must be a string or null.");
+    }
+    const meta = toOptionalMetadataMap(message.meta);
+    const metaUnion = meta === null ? null : _wrapUnion(MAP_BRANCH, meta);
+    return {
+        clientHash,
+        clientProtocol: clientProtocolUnion,
+        serverHash,
+        meta: metaUnion,
+    };
+}
+// @internal
+function _createHandshakeResponseRecord(message) {
+    const serverHash = message.serverHash ?? null;
+    let serverHashUnion;
+    if (serverHash === null) {
+        serverHashUnion = null;
+    }
+    else {
+        const hashBytes = cloneBytes(serverHash, "serverHash");
+        _assertMd5Size(hashBytes, "serverHash");
+        serverHashUnion = _wrapUnion(MD5_BRANCH, hashBytes);
+    }
+    const serverProtocol = message.serverProtocol ?? null;
+    let serverProtocolUnion;
+    if (serverProtocol === null) {
+        serverProtocolUnion = null;
+    }
+    else if (typeof serverProtocol === "string") {
+        serverProtocolUnion = _wrapUnion(STRING_BRANCH, serverProtocol);
+    }
+    else {
+        throw new TypeError("serverProtocol must be a string or null.");
+    }
+    const meta = toOptionalMetadataMap(message.meta);
+    const metaUnion = meta === null ? null : _wrapUnion(MAP_BRANCH, meta);
+    return {
+        match: message.match,
+        serverProtocol: serverProtocolUnion,
+        serverHash: serverHashUnion,
+        meta: metaUnion,
+    };
+}
+/**
+ * Extracts an optional string value from an Avro union type in handshake messages.
+ * Handles the union of null and string, returning the string if present or null.
+ */
+export function _extractOptionalString(unionValue) {
+    if (unionValue === null) {
+        return null;
+    }
+    if (unionValue[STRING_BRANCH] !== undefined) {
+        return unionValue[STRING_BRANCH];
+    }
+    throw new Error("Unexpected union value for string branch.");
+}
+/**
+ * Extracts an optional metadata map from an Avro union type in handshake messages.
+ * Handles the union of null and map, returning a cloned metadata map if present or null.
+ */
+export function _extractOptionalMetadata(unionValue) {
+    if (unionValue === null) {
+        return null;
+    }
+    const map = unionValue[MAP_BRANCH];
+    if (map === undefined) {
+        throw new Error("Unexpected union value for metadata branch.");
+    }
+    return cloneMetadataMap(map);
+}
+/**
+ * Extracts an optional MD5 hash from an Avro union type in handshake messages.
+ * Handles the union of null and MD5 fixed type, returning cloned bytes if present or null.
+ */
+export function _extractOptionalMd5(unionValue) {
+    if (unionValue === null) {
+        return null;
+    }
+    const value = unionValue[MD5_BRANCH];
+    if (value === undefined) {
+        throw new Error("Unexpected union value for MD5 branch.");
+    }
+    return cloneBytes(value, "serverHash");
+}
+// @internal
+function _toHandshakeRequestMessage(record) {
+    return {
+        clientHash: cloneBytes(record.clientHash, "clientHash"),
+        clientProtocol: _extractOptionalString(record.clientProtocol),
+        serverHash: cloneBytes(record.serverHash, "serverHash"),
+        meta: _extractOptionalMetadata(record.meta),
+    };
+}
+// @internal
+function _toHandshakeResponseMessage(record) {
+    return {
+        match: record.match,
+        serverProtocol: _extractOptionalString(record.serverProtocol),
+        serverHash: _extractOptionalMd5(record.serverHash),
+        meta: _extractOptionalMetadata(record.meta),
+    };
+}
+/**
+ * Encodes a handshake request message into a byte buffer for transmission in the Avro RPC protocol.
+ * Serializes the request using the predefined Avro schema for handshake requests.
+ */
+export async function encodeHandshakeRequest(message) {
+    const record = _createHandshakeRequestRecord(message);
+    return new Uint8Array(await HANDSHAKE_REQUEST_TYPE.toBuffer(record));
+}
+/**
+ * Decodes a byte buffer into a handshake request message in the Avro RPC protocol.
+ * Deserializes the buffer using the predefined Avro schema for handshake requests.
+ */
+export async function decodeHandshakeRequest(buffer) {
+    const record = await HANDSHAKE_REQUEST_TYPE.fromBuffer(buffer);
+    return _toHandshakeRequestMessage(record);
+}
+/**
+ * Reads a handshake request message from a readable tap stream in the Avro RPC protocol.
+ * Deserializes the data from the stream using the predefined Avro schema for handshake requests.
+ */
+export async function readHandshakeRequestFromTap(tap) {
+    const record = await HANDSHAKE_REQUEST_TYPE.read(tap);
+    return _toHandshakeRequestMessage(record);
+}
+/**
+ * Encodes a handshake response message into a byte buffer for transmission in the Avro RPC protocol.
+ * Serializes the response using the predefined Avro schema for handshake responses.
+ */
+export async function encodeHandshakeResponse(message) {
+    const record = _createHandshakeResponseRecord(message);
+    return new Uint8Array(await HANDSHAKE_RESPONSE_TYPE.toBuffer(record));
+}
+/**
+ * Decodes a byte buffer into a handshake response message in the Avro RPC protocol.
+ * Deserializes the buffer using the predefined Avro schema for handshake responses.
+ */
+export async function decodeHandshakeResponse(buffer) {
+    const record = await HANDSHAKE_RESPONSE_TYPE.fromBuffer(buffer);
+    return _toHandshakeResponseMessage(record);
+}
+/**
+ * Reads a handshake response message from a readable tap stream in the Avro RPC protocol.
+ * Deserializes the data from the stream using the predefined Avro schema for handshake responses.
+ */
+export async function readHandshakeResponseFromTap(tap) {
+    const record = await HANDSHAKE_RESPONSE_TYPE.read(tap);
+    return _toHandshakeResponseMessage(record);
+}

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

@@ -0,0 +1,192 @@
+import type { Type } from "../../../schemas/type.js";
+import { ReadableTap } from "../../../serialization/tap.js";
+import { type MetadataInit, type MetadataMap } from "./metadata.js";
+import { type HandshakeRequestInit, type HandshakeRequestMessage, type HandshakeResponseInit, type HandshakeResponseMessage } from "./handshake.js";
+/**
+ * Initialization object for encoding a call request in the Avro RPC wire format.
+ * Contains the data needed to construct a call request message, including optional handshake,
+ * metadata, message name, request payload, and the Avro type of the request.
+ */
+export interface CallRequestInit<T> {
+    /** Optional handshake request data for protocol negotiation in the Avro RPC wire format. */
+    handshake?: HandshakeRequestInit | HandshakeRequestMessage;
+    /** Optional metadata map or initialization object for additional message metadata. */
+    metadata?: MetadataInit | null;
+    /** The name of the RPC message being called. */
+    messageName: string;
+    /** The request payload data to be sent. */
+    request: T;
+    /** The Avro type definition for the request payload. */
+    requestType: Type<T>;
+}
+/**
+ * Represents a decoded call request message in the Avro RPC wire format.
+ * Contains the parsed handshake (if present), metadata, message name, and request payload.
+ */
+export interface CallRequestMessage<T> {
+    /** Optional decoded handshake request message for protocol negotiation. */
+    handshake?: HandshakeRequestMessage;
+    /** Metadata map containing additional message information. */
+    metadata: MetadataMap;
+    /** The name of the RPC message being called. */
+    messageName: string;
+    /** The decoded request payload data. */
+    request: T;
+}
+/**
+ * Options for decoding a call request message from the Avro RPC wire format.
+ * Specifies the expected request type and whether a handshake is expected.
+ */
+export interface DecodeCallRequestOptions<T> {
+    /** The Avro type definition for the request payload. */
+    requestType: Type<T>;
+    /** Whether to expect and parse handshake data in the message. */
+    expectHandshake?: boolean;
+}
+/**
+ * Envelope for a call request message in the Avro RPC wire format.
+ * Contains the handshake (if present), metadata, message name, and a tap for reading the request body.
+ */
+export interface CallRequestEnvelope {
+    /** Optional decoded handshake request message. */
+    handshake?: HandshakeRequestMessage;
+    /** Metadata map with message metadata. */
+    metadata: MetadataMap;
+    /** The name of the RPC message. */
+    messageName: string;
+    /** Readable tap positioned at the start of the request payload for lazy reading. */
+    bodyTap: ReadableTap;
+}
+/**
+ * Initialization object for encoding a call response in the Avro RPC wire format.
+ * Contains the data needed to construct a call response message, including optional handshake,
+ * metadata, error flag, payload, and the Avro types for response and error.
+ */
+export interface CallResponseInit<TResponse, TError> {
+    /** Optional handshake response data for protocol negotiation. */
+    handshake?: HandshakeResponseInit | HandshakeResponseMessage;
+    /** Optional metadata map or initialization object. */
+    metadata?: MetadataInit | null;
+    /** Flag indicating whether this response represents an error. */
+    isError: boolean;
+    /** The response or error payload data. */
+    payload: TResponse | TError;
+    /** The Avro type definition for the response payload. */
+    responseType: Type<TResponse>;
+    /** The Avro type definition for the error payload. */
+    errorType: Type<TError>;
+}
+/**
+ * Represents a decoded call response message in the Avro RPC wire format.
+ * Contains the parsed handshake (if present), metadata, error flag, and payload.
+ */
+export interface CallResponseMessage<TResponse, TError> {
+    /** Optional decoded handshake response message. */
+    handshake?: HandshakeResponseMessage;
+    /** Metadata map containing additional message information. */
+    metadata: MetadataMap;
+    /** Flag indicating whether this response represents an error. */
+    isError: boolean;
+    /** The decoded response or error payload data. */
+    payload: TResponse | TError;
+}
+/**
+ * Options for decoding a call response message from the Avro RPC wire format.
+ * Specifies the expected response and error types, and whether a handshake is expected.
+ */
+export interface DecodeCallResponseOptions<TResponse, TError> {
+    /** The Avro type definition for the response payload. */
+    responseType: Type<TResponse>;
+    /** The Avro type definition for the error payload. */
+    errorType: Type<TError>;
+    /** Whether to expect and parse handshake data in the message. */
+    expectHandshake?: boolean;
+}
+/**
+ * Envelope for a call response message in the Avro RPC wire format.
+ * Contains the handshake (if present), metadata, error flag, and a tap for reading the response body.
+ */
+export interface CallResponseEnvelope {
+    /** Optional decoded handshake response message. */
+    handshake?: HandshakeResponseMessage;
+    /** Metadata map with message metadata. */
+    metadata: MetadataMap;
+    /** Flag indicating whether this response represents an error. */
+    isError: boolean;
+    /** Readable tap positioned at the start of the response or error payload for lazy reading. */
+    bodyTap: ReadableTap;
+}
+/**
+ * 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 declare function encodeCallRequest<T>(init: CallRequestInit<T>): Promise<Uint8Array>;
+/**
+ * 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 declare function decodeCallRequest<T>(buffer: ArrayBuffer, options: DecodeCallRequestOptions<T>): Promise<CallRequestMessage<T>>;
+/**
+ * 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 declare function decodeCallRequestEnvelope(buffer: ArrayBuffer, options?: {
+    expectHandshake?: boolean;
+}): Promise<CallRequestEnvelope>;
+/**
+ * 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 declare function encodeCallResponse<TResponse, TError>(init: CallResponseInit<TResponse, TError>): Promise<Uint8Array>;
+/**
+ * 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 declare function decodeCallResponse<TResponse, TError>(buffer: ArrayBuffer, options: DecodeCallResponseOptions<TResponse, TError>): Promise<CallResponseMessage<TResponse, TError>>;
+/**
+ * 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 declare function decodeCallResponseEnvelope(buffer: ArrayBuffer, options?: {
+    expectHandshake?: boolean;
+}): Promise<CallResponseEnvelope>;