@sachitv/avro-typescript 0.4.0

package/esm/rpc/message_endpoint/helpers.d.ts

@@ -0,0 +1,37 @@
+import type { BinaryReadable } from "../protocol/transports/transport_helpers.js";
+import type { CallRequestEnvelope, CallResponseEnvelope } from "../protocol/wire_format/messages.js";
+import type { Message } from "../definitions/message_definition.js";
+import type { ResolverEntry } from "../definitions/protocol_definitions.js";
+/**
+ * Reads a single framed message from a binary readable stream in the context of message endpoints.
+ * Uses a FrameAssembler to accumulate chunks until a complete message is formed.
+ * @param readable The binary readable stream to read from.
+ * @returns A promise that resolves to the Uint8Array of the framed message.
+ * @throws Error if no framed message is received.
+ */
+export declare function readSingleMessage(readable: BinaryReadable): Promise<Uint8Array>;
+/**
+ * Drains a binary readable stream by consuming all remaining bytes in the context of message endpoints.
+ * Useful for clearing the stream after processing.
+ * @param readable The binary readable stream to drain.
+ * @returns A promise that resolves when the stream is fully drained.
+ */
+export declare function drainReadable(readable: BinaryReadable): Promise<void>;
+/**
+ * Reads the payload from a call response envelope in the context of message endpoints.
+ * Handles error responses and uses a resolver for schema resolution if provided.
+ * @param envelope The call response envelope containing the body tap.
+ * @param message The message definition for type information.
+ * @param resolver Optional resolver entry for custom schema resolution.
+ * @returns A promise that resolves to the deserialized response payload.
+ */
+export declare function readResponsePayload(envelope: CallResponseEnvelope, message: Message, resolver?: ResolverEntry): Promise<unknown>;
+/**
+ * Reads the payload from a call request envelope in the context of message endpoints.
+ * Uses a resolver for schema resolution if provided, otherwise falls back to message types.
+ * @param envelope The call request envelope containing the body tap.
+ * @param message The message definition for type information.
+ * @param resolver Optional resolver entry for custom schema resolution.
+ * @returns A promise that resolves to the deserialized request payload.
+ */
+export declare function readRequestPayload(envelope: CallRequestEnvelope, message: Message, resolver?: ResolverEntry): Promise<unknown>;

package/esm/rpc/message_endpoint/helpers.js

@@ -0,0 +1,68 @@
+import { FrameAssembler } from "../protocol/frame_assembler.js";
+/**
+ * Reads a single framed message from a binary readable stream in the context of message endpoints.
+ * Uses a FrameAssembler to accumulate chunks until a complete message is formed.
+ * @param readable The binary readable stream to read from.
+ * @returns A promise that resolves to the Uint8Array of the framed message.
+ * @throws Error if no framed message is received.
+ */
+export async function readSingleMessage(readable) {
+    const assembler = new FrameAssembler();
+    while (true) {
+        const chunk = await readable.read();
+        if (chunk === null) {
+            break;
+        }
+        const messages = assembler.push(chunk);
+        if (messages.length) {
+            return messages[0];
+        }
+    }
+    throw new Error("no framed message received");
+}
+/**
+ * Drains a binary readable stream by consuming all remaining bytes in the context of message endpoints.
+ * Useful for clearing the stream after processing.
+ * @param readable The binary readable stream to drain.
+ * @returns A promise that resolves when the stream is fully drained.
+ */
+export async function drainReadable(readable) {
+    while ((await readable.read()) !== null) {
+        // consume remaining bytes
+    }
+}
+/**
+ * Reads the payload from a call response envelope in the context of message endpoints.
+ * Handles error responses and uses a resolver for schema resolution if provided.
+ * @param envelope The call response envelope containing the body tap.
+ * @param message The message definition for type information.
+ * @param resolver Optional resolver entry for custom schema resolution.
+ * @returns A promise that resolves to the deserialized response payload.
+ */
+export async function readResponsePayload(envelope, message, resolver) {
+    const tap = envelope.bodyTap;
+    if (envelope.isError) {
+        if (resolver?.error) {
+            return await resolver.error.read(tap);
+        }
+        return await message.errorType.read(tap);
+    }
+    if (resolver?.response) {
+        return await resolver.response.read(tap);
+    }
+    return await message.responseType.read(tap);
+}
+/**
+ * Reads the payload from a call request envelope in the context of message endpoints.
+ * Uses a resolver for schema resolution if provided, otherwise falls back to message types.
+ * @param envelope The call request envelope containing the body tap.
+ * @param message The message definition for type information.
+ * @param resolver Optional resolver entry for custom schema resolution.
+ * @returns A promise that resolves to the deserialized request payload.
+ */
+export async function readRequestPayload(envelope, message, resolver) {
+    if (resolver?.request) {
+        return await resolver.request.read(envelope.bodyTap);
+    }
+    return await message.requestType.read(envelope.bodyTap);
+}

package/esm/rpc/message_endpoint/listener.d.ts

@@ -0,0 +1,37 @@
+import type { BinaryDuplexLike } from "../protocol/transports/transport_helpers.js";
+import { MessageEndpoint } from "./base.js";
+import type { MessageTransportOptions, ProtocolFactory, ProtocolLike } from "../definitions/protocol_definitions.js";
+/**
+ * Abstract base class for message listeners.
+ * Listens for incoming RPC requests and dispatches them to handlers.
+ */
+export declare abstract class MessageListener extends MessageEndpoint {
+    /**
+     * Destroys the listener, stopping it from accepting new requests.
+     * @param noWait If true, does not wait for pending requests to complete (if applicable).
+     */
+    abstract destroy(noWait?: boolean): void;
+}
+/**
+ * Stateless implementation of MessageListener.
+ * Handles one request per connection, common in HTTP-based transports.
+ */
+export declare class StatelessListener extends MessageListener {
+    #private;
+    /**
+     * Creates a new StatelessListener.
+     * @param protocol The protocol definition.
+     * @param transport The binary transport to read from/write to.
+     * @param opts Configuration options.
+     * @param protocolFactory Factory for creating protocol instances from schema.
+     */
+    constructor(protocol: ProtocolLike, transport: BinaryDuplexLike, opts: MessageTransportOptions, protocolFactory: ProtocolFactory);
+    /**
+     * Destroys the listener.
+     */
+    destroy(): void;
+    /**
+     * Waits for the listener's main loop to exit.
+     */
+    waitForClose(): Promise<void>;
+}

package/esm/rpc/message_endpoint/listener.js

@@ -0,0 +1,212 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _StatelessListener_instances, _StatelessListener_transport, _StatelessListener_destroyed, _StatelessListener_protocolFactory, _StatelessListener_requestDecoder, _StatelessListener_runPromise, _StatelessListener_exposeProtocol, _StatelessListener_maxRequestSize, _StatelessListener_requestTimeout, _StatelessListener_run, _StatelessListener_handleRequest, _StatelessListener_validateHandshake;
+import { encodeCallResponse } from "../protocol/wire_format/messages.js";
+import { frameMessage } from "../protocol/wire_format/framing.js";
+import { bytesEqual, bytesToHex, errorToPayload, textEncoder, toArrayBuffer, } from "../protocol/protocol_helpers.js";
+import { createType } from "../../type/create_type.js";
+import { toBinaryDuplex } from "../protocol/transports/transport_helpers.js";
+import { MessageEndpoint } from "./base.js";
+import { decodeCallRequestEnvelope } from "../protocol/wire_format/messages.js";
+import { readRequestPayload } from "./helpers.js";
+import { FrameAssembler } from "../protocol/frame_assembler.js";
+/**
+ * Abstract base class for message listeners.
+ * Listens for incoming RPC requests and dispatches them to handlers.
+ */
+export class MessageListener extends MessageEndpoint {
+}
+/**
+ * Stateless implementation of MessageListener.
+ * Handles one request per connection, common in HTTP-based transports.
+ */
+export class StatelessListener extends MessageListener {
+    /**
+     * Creates a new StatelessListener.
+     * @param protocol The protocol definition.
+     * @param transport The binary transport to read from/write to.
+     * @param opts Configuration options.
+     * @param protocolFactory Factory for creating protocol instances from schema.
+     */
+    constructor(protocol, transport, opts, protocolFactory) {
+        super(protocol, opts);
+        _StatelessListener_instances.add(this);
+        _StatelessListener_transport.set(this, void 0);
+        _StatelessListener_destroyed.set(this, false);
+        _StatelessListener_protocolFactory.set(this, void 0);
+        _StatelessListener_requestDecoder.set(this, void 0);
+        _StatelessListener_runPromise.set(this, void 0);
+        _StatelessListener_exposeProtocol.set(this, void 0);
+        _StatelessListener_maxRequestSize.set(this, void 0);
+        _StatelessListener_requestTimeout.set(this, void 0);
+        __classPrivateFieldSet(this, _StatelessListener_transport, transport, "f");
+        __classPrivateFieldSet(this, _StatelessListener_protocolFactory, protocolFactory, "f");
+        __classPrivateFieldSet(this, _StatelessListener_requestDecoder, opts.requestDecoder ?? decodeCallRequestEnvelope, "f");
+        __classPrivateFieldSet(this, _StatelessListener_exposeProtocol, opts.exposeProtocol ?? false, "f");
+        // Security: limit request size to prevent DoS (default 10MB)
+        __classPrivateFieldSet(this, _StatelessListener_maxRequestSize, opts.maxRequestSize ?? 10 * 1024 * 1024, "f");
+        // Security: timeout to prevent hanging requests (default 30 seconds)
+        __classPrivateFieldSet(this, _StatelessListener_requestTimeout, opts.requestTimeout ?? 30000, "f");
+        __classPrivateFieldSet(this, _StatelessListener_runPromise, __classPrivateFieldGet(this, _StatelessListener_instances, "m", _StatelessListener_run).call(this), "f");
+    }
+    /**
+     * Destroys the listener.
+     */
+    destroy() {
+        if (!__classPrivateFieldGet(this, _StatelessListener_destroyed, "f")) {
+            __classPrivateFieldSet(this, _StatelessListener_destroyed, true, "f");
+            this.dispatchEot(0);
+        }
+    }
+    /**
+     * Waits for the listener's main loop to exit.
+     */
+    waitForClose() {
+        return __classPrivateFieldGet(this, _StatelessListener_runPromise, "f");
+    }
+}
+_StatelessListener_transport = new WeakMap(), _StatelessListener_destroyed = new WeakMap(), _StatelessListener_protocolFactory = new WeakMap(), _StatelessListener_requestDecoder = new WeakMap(), _StatelessListener_runPromise = new WeakMap(), _StatelessListener_exposeProtocol = new WeakMap(), _StatelessListener_maxRequestSize = new WeakMap(), _StatelessListener_requestTimeout = new WeakMap(), _StatelessListener_instances = new WeakSet(), _StatelessListener_run = async function _StatelessListener_run() {
+    const duplex = toBinaryDuplex(__classPrivateFieldGet(this, _StatelessListener_transport, "f"));
+    const assembler = new FrameAssembler();
+    let totalSize = 0;
+    try {
+        // Set up timeout for the entire request processing
+        const timeoutController = new AbortController();
+        const timeoutId = setTimeout(() => {
+            timeoutController.abort();
+        }, __classPrivateFieldGet(this, _StatelessListener_requestTimeout, "f"));
+        try {
+            while (!timeoutController.signal.aborted) {
+                const chunk = await duplex.readable.read();
+                if (chunk === null) {
+                    break;
+                }
+                // Security: check size limit to prevent DoS
+                totalSize += chunk.length;
+                if (totalSize > __classPrivateFieldGet(this, _StatelessListener_maxRequestSize, "f")) {
+                    throw new Error(`request too large: ${totalSize} bytes (max: ${__classPrivateFieldGet(this, _StatelessListener_maxRequestSize, "f")})`);
+                }
+                const messages = assembler.push(chunk);
+                if (messages.length > 0) {
+                    // Process the first complete message
+                    await __classPrivateFieldGet(this, _StatelessListener_instances, "m", _StatelessListener_handleRequest).call(this, messages[0], duplex);
+                    return; // Only process one request per connection in stateless mode
+                }
+            }
+            if (timeoutController.signal.aborted) {
+                throw new Error("request timeout");
+            }
+            throw new Error("no request payload");
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    catch (err) {
+        this.dispatchError(err);
+    }
+    finally {
+        await duplex.writable.close();
+        this.destroy();
+    }
+}, _StatelessListener_handleRequest = async function _StatelessListener_handleRequest(payload, duplex) {
+    const envelope = await __classPrivateFieldGet(this, _StatelessListener_requestDecoder, "f").call(this, toArrayBuffer(payload), { expectHandshake: true });
+    if (!envelope.handshake) {
+        throw new Error("missing handshake request");
+    }
+    const { response: handshakeResponse, requestResolverKey, } = await __classPrivateFieldGet(this, _StatelessListener_instances, "m", _StatelessListener_validateHandshake).call(this, envelope.handshake);
+    let message;
+    let result;
+    let isError = false;
+    let errorPayload;
+    try {
+        message = this.protocol.getMessages().get(envelope.messageName);
+        if (!message) {
+            throw new Error(`unsupported message: ${envelope.messageName}`);
+        }
+        const resolver = this.protocol.getListenerResolvers(requestResolverKey, message.name);
+        const requestValue = await readRequestPayload(envelope, message, resolver);
+        const handler = this.protocol.getHandler(message.name);
+        if (!handler) {
+            throw new Error(`unsupported message: ${message.name}`);
+        }
+        result = await handler(requestValue, this, {
+            metadata: envelope.metadata,
+        });
+    }
+    catch (err) {
+        isError = true;
+        errorPayload = errorToPayload(err);
+    }
+    const responsePayload = await encodeCallResponse({
+        handshake: handshakeResponse,
+        metadata: envelope.metadata,
+        isError,
+        payload: isError ? errorPayload : result,
+        responseType: message ? message.responseType : createType("null"),
+        errorType: message ? message.errorType : createType(["string"]),
+    });
+    const framed = frameMessage(responsePayload, { frameSize: this.frameSize });
+    await duplex.writable.write(framed);
+}, _StatelessListener_validateHandshake = 
+// deno-lint-ignore require-await
+async function _StatelessListener_validateHandshake(handshake) {
+    let validationError = null;
+    let resolverError = null;
+    const clientHashKey = bytesToHex(handshake.clientHash);
+    const needsResolver = clientHashKey !== this.protocol.hashKey;
+    if (needsResolver && !this.protocol.hasListenerResolvers(clientHashKey)) {
+        if (handshake.clientProtocol) {
+            // Security: validate JSON before parsing
+            if (typeof handshake.clientProtocol !== "string" ||
+                handshake.clientProtocol.length > 1024 * 1024) { // 1MB limit
+                validationError = new Error("invalid client protocol: too large or not a string");
+            }
+            else {
+                try {
+                    // Basic JSON validation
+                    const parsedProtocol = JSON.parse(handshake.clientProtocol);
+                    const emitterProtocol = __classPrivateFieldGet(this, _StatelessListener_protocolFactory, "f").call(this, parsedProtocol);
+                    this.protocol.ensureListenerResolvers(clientHashKey, emitterProtocol);
+                }
+                catch (err) {
+                    validationError = err instanceof Error
+                        ? err
+                        : new Error("invalid client protocol JSON");
+                }
+            }
+        }
+        else {
+            resolverError = new Error("unknown client protocol hash");
+        }
+    }
+    const handshakeIssue = validationError ?? resolverError;
+    const serverMatch = bytesEqual(handshake.serverHash, this.protocol.getHashBytes());
+    // Protocol exposure logic:
+    // - Expose when server hash doesn't match AND client hash is known (normal schema evolution)
+    // - Expose when exposeProtocol is true (explicit discovery mode)
+    // - Never expose when there are validation errors (malformed input)
+    const clientHashKnown = !needsResolver;
+    const shouldExposeProtocol = ((!serverMatch && clientHashKnown) ||
+        __classPrivateFieldGet(this, _StatelessListener_exposeProtocol, "f")) && !validationError;
+    const response = {
+        match: handshakeIssue ? "NONE" : serverMatch ? "BOTH" : "CLIENT",
+        serverProtocol: shouldExposeProtocol ? this.protocol.toString() : null,
+        serverHash: serverMatch ? null : this.protocol.getHashBytes(),
+        meta: validationError
+            ? new Map([["error", textEncoder.encode(String(validationError))]])
+            : resolverError
+                ? new Map([["error", textEncoder.encode(String(resolverError))]])
+                : null,
+    };
+    return { response, requestResolverKey: clientHashKey };
+};

package/esm/rpc/protocol/frame_assembler.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Incrementally collects framed Avro messages from arbitrary binary chunks.
+ * Counterpart to the `frameMessage` function in `framing.ts`, which frames messages for sending.
+ */
+export declare class FrameAssembler {
+    #private;
+    /** Pushes a chunk and returns complete frames */
+    push(chunk: Uint8Array): Uint8Array[];
+    /** Resets the assembler */
+    reset(): void;
+}

package/esm/rpc/protocol/frame_assembler.js

@@ -0,0 +1,77 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _FrameAssembler_instances, _FrameAssembler_buffer, _FrameAssembler_frames, _FrameAssembler_flushFrames, _FrameAssembler_readUint32BE;
+import { concatUint8Arrays } from "../../internal/collections/array_utils.js";
+/**
+ * Incrementally collects framed Avro messages from arbitrary binary chunks.
+ * Counterpart to the `frameMessage` function in `framing.ts`, which frames messages for sending.
+ */
+export class FrameAssembler {
+    constructor() {
+        _FrameAssembler_instances.add(this);
+        _FrameAssembler_buffer.set(this, new Uint8Array(0));
+        _FrameAssembler_frames.set(this, []);
+    }
+    /** Pushes a chunk and returns complete frames */
+    push(chunk) {
+        if (!chunk.length) {
+            return [];
+        }
+        if (!__classPrivateFieldGet(this, _FrameAssembler_buffer, "f").length) {
+            __classPrivateFieldSet(this, _FrameAssembler_buffer, chunk.slice(), "f");
+        }
+        else {
+            const combined = new Uint8Array(__classPrivateFieldGet(this, _FrameAssembler_buffer, "f").length + chunk.length);
+            combined.set(__classPrivateFieldGet(this, _FrameAssembler_buffer, "f"), 0);
+            combined.set(chunk, __classPrivateFieldGet(this, _FrameAssembler_buffer, "f").length);
+            __classPrivateFieldSet(this, _FrameAssembler_buffer, combined, "f");
+        }
+        const output = [];
+        let offset = 0;
+        while (__classPrivateFieldGet(this, _FrameAssembler_buffer, "f").length - offset >= 4) {
+            const frameLength = __classPrivateFieldGet(this, _FrameAssembler_instances, "m", _FrameAssembler_readUint32BE).call(this, offset);
+            offset += 4;
+            if (frameLength === 0) {
+                output.push(__classPrivateFieldGet(this, _FrameAssembler_instances, "m", _FrameAssembler_flushFrames).call(this));
+                continue;
+            }
+            if (offset + frameLength > __classPrivateFieldGet(this, _FrameAssembler_buffer, "f").length) {
+                offset -= 4; // rewind header, wait for more data
+                break;
+            }
+            __classPrivateFieldGet(this, _FrameAssembler_frames, "f").push(__classPrivateFieldGet(this, _FrameAssembler_buffer, "f").subarray(offset, offset + frameLength));
+            offset += frameLength;
+        }
+        if (offset > 0) {
+            __classPrivateFieldSet(this, _FrameAssembler_buffer, __classPrivateFieldGet(this, _FrameAssembler_buffer, "f").subarray(offset), "f");
+        }
+        return output;
+    }
+    /** Resets the assembler */
+    reset() {
+        __classPrivateFieldSet(this, _FrameAssembler_buffer, new Uint8Array(0), "f");
+        __classPrivateFieldSet(this, _FrameAssembler_frames, [], "f");
+    }
+}
+_FrameAssembler_buffer = new WeakMap(), _FrameAssembler_frames = new WeakMap(), _FrameAssembler_instances = new WeakSet(), _FrameAssembler_flushFrames = function _FrameAssembler_flushFrames() {
+    if (!__classPrivateFieldGet(this, _FrameAssembler_frames, "f").length) {
+        return new Uint8Array(0);
+    }
+    const payload = __classPrivateFieldGet(this, _FrameAssembler_frames, "f").length === 1
+        ? __classPrivateFieldGet(this, _FrameAssembler_frames, "f")[0]
+        : concatUint8Arrays(__classPrivateFieldGet(this, _FrameAssembler_frames, "f"));
+    __classPrivateFieldSet(this, _FrameAssembler_frames, [], "f");
+    return payload;
+}, _FrameAssembler_readUint32BE = function _FrameAssembler_readUint32BE(offset) {
+    const view = new DataView(__classPrivateFieldGet(this, _FrameAssembler_buffer, "f").buffer, __classPrivateFieldGet(this, _FrameAssembler_buffer, "f").byteOffset + offset, 4);
+    return view.getUint32(0, false); // big-endian
+};

package/esm/rpc/protocol/protocol_helpers.d.ts

@@ -0,0 +1,59 @@
+import type { ProtocolLike } from "../definitions/protocol_definitions.js";
+import type { MetadataInit } from "./wire_format/metadata.js";
+/** TextEncoder instance for encoding strings to UTF-8 bytes. */
+export declare const textEncoder: TextEncoder;
+/** TextDecoder instance for decoding UTF-8 bytes to strings. */
+export declare const textDecoder: TextDecoder;
+/**
+ * Normalizes a protocol name by prepending the namespace if the name does not already contain a dot.
+ * @param name The protocol name.
+ * @param namespace Optional namespace to prepend.
+ * @returns The normalized protocol name.
+ */
+export declare function normalizeProtocolName(name: string, namespace?: string): string;
+/**
+ * Serializes a protocol to a JSON string containing the protocol name, types, and messages.
+ * @param protocol The protocol to stringify.
+ * @returns The JSON string representation of the protocol.
+ */
+export declare function stringifyProtocol(protocol: ProtocolLike): string;
+/**
+ * Creates metadata with a given ID, optionally copying from a base metadata.
+ * @param id The ID to set in the metadata.
+ * @param base Optional base metadata to copy from.
+ * @returns The new metadata with the ID.
+ */
+export declare function metadataWithId(id: number, base?: MetadataInit | null): MetadataInit;
+/**
+ * Converts a 32-bit integer to a Uint8Array of 4 bytes in big-endian order.
+ * @param value The integer value to convert.
+ * @returns The Uint8Array representation of the integer.
+ */
+export declare function int32ToBytes(value: number): Uint8Array;
+/**
+ * Converts a Uint8Array to a hexadecimal string representation.
+ * @param bytes The bytes to convert.
+ * @returns The hexadecimal string.
+ */
+export declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * Checks if two Uint8Arrays are equal by comparing their lengths and contents.
+ * @param a The first Uint8Array.
+ * @param b The second Uint8Array.
+ * @returns True if the arrays are equal, false otherwise.
+ */
+export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Converts a Uint8Array to an ArrayBuffer by slicing the underlying buffer.
+ * @param bytes The Uint8Array to convert.
+ * @returns The corresponding ArrayBuffer.
+ */
+export declare function toArrayBuffer(bytes: Uint8Array): ArrayBuffer;
+/**
+ * Converts an error or unknown value to a payload object with a string property.
+ * @param err The error or value to convert.
+ * @returns An object with a 'string' property containing the error message or string representation.
+ */
+export declare function errorToPayload(err: unknown): {
+    string: string;
+};

package/esm/rpc/protocol/protocol_helpers.js

@@ -0,0 +1,123 @@
+/** TextEncoder instance for encoding strings to UTF-8 bytes. */
+export const textEncoder = new TextEncoder();
+/** TextDecoder instance for decoding UTF-8 bytes to strings. */
+export const textDecoder = new TextDecoder();
+/**
+ * Normalizes a protocol name by prepending the namespace if the name does not already contain a dot.
+ * @param name The protocol name.
+ * @param namespace Optional namespace to prepend.
+ * @returns The normalized protocol name.
+ */
+export function normalizeProtocolName(name, namespace) {
+    if (!name) {
+        throw new Error("missing protocol name");
+    }
+    if (namespace && !name.includes(".")) {
+        return `${namespace}.${name}`;
+    }
+    return name;
+}
+/**
+ * Serializes a protocol to a JSON string containing the protocol name, types, and messages.
+ * @param protocol The protocol to stringify.
+ * @returns The JSON string representation of the protocol.
+ */
+export function stringifyProtocol(protocol) {
+    const namedTypes = protocol.getNamedTypes();
+    const messages = {};
+    for (const [name, message] of protocol.getMessages()) {
+        messages[name] = message;
+    }
+    // The types/messages already implement toJSON, so JSON.stringify will invoke
+    // their serialization helpers automatically.
+    return JSON.stringify({
+        protocol: protocol.getName(),
+        types: namedTypes.length ? namedTypes : undefined,
+        messages,
+    });
+}
+/**
+ * Creates metadata with a given ID, optionally copying from a base metadata.
+ * @param id The ID to set in the metadata.
+ * @param base Optional base metadata to copy from.
+ * @returns The new metadata with the ID.
+ */
+export function metadataWithId(id, base) {
+    const map = new Map();
+    if (base instanceof Map) {
+        for (const [key, value] of base) {
+            map.set(key, value.slice());
+        }
+    }
+    else if (Array.isArray(base)) {
+        for (const [key, value] of base) {
+            map.set(key, value.slice());
+        }
+    }
+    else if (base && typeof base === "object") {
+        for (const [key, value] of Object.entries(base)) {
+            map.set(key, value.slice());
+        }
+    }
+    map.set("id", int32ToBytes(id));
+    return map;
+}
+/**
+ * Converts a 32-bit integer to a Uint8Array of 4 bytes in big-endian order.
+ * @param value The integer value to convert.
+ * @returns The Uint8Array representation of the integer.
+ */
+export function int32ToBytes(value) {
+    const buffer = new ArrayBuffer(4);
+    new DataView(buffer).setInt32(0, value, false);
+    return new Uint8Array(buffer);
+}
+/**
+ * Converts a Uint8Array to a hexadecimal string representation.
+ * @param bytes The bytes to convert.
+ * @returns The hexadecimal string.
+ */
+export function bytesToHex(bytes) {
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Checks if two Uint8Arrays are equal by comparing their lengths and contents.
+ * @param a The first Uint8Array.
+ * @param b The second Uint8Array.
+ * @returns True if the arrays are equal, false otherwise.
+ */
+export function bytesEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Converts a Uint8Array to an ArrayBuffer by slicing the underlying buffer.
+ * @param bytes The Uint8Array to convert.
+ * @returns The corresponding ArrayBuffer.
+ */
+export function toArrayBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+/**
+ * Converts an error or unknown value to a payload object with a string property.
+ * @param err The error or value to convert.
+ * @returns An object with a 'string' property containing the error message or string representation.
+ */
+export function errorToPayload(err) {
+    if (err instanceof Error) {
+        return { string: err.message };
+    }
+    if (typeof err === "string") {
+        return { string: err };
+    }
+    return { string: String(err) };
+}

package/esm/rpc/protocol/transports/fetch.d.ts

@@ -0,0 +1,9 @@
+import type { FetchTransportOptions, StatelessTransportFactory } from "./transport_helpers.js";
+/**
+ * Creates a stateless transport factory using the Fetch API.
+ *
+ * @param endpoint The URL to send requests to.
+ * @param options Configuration options for the fetch transport.
+ * @returns A factory function that creates a new transport for each request.
+ */
+export declare function createFetchTransport(endpoint: string | URL, options?: FetchTransportOptions): StatelessTransportFactory;

package/esm/rpc/protocol/transports/fetch.js

@@ -0,0 +1,30 @@
+/**
+ * Creates a stateless transport factory using the Fetch API.
+ *
+ * @param endpoint The URL to send requests to.
+ * @param options Configuration options for the fetch transport.
+ * @returns A factory function that creates a new transport for each request.
+ */
+export function createFetchTransport(endpoint, options = {}) {
+    const url = typeof endpoint === "string" ? endpoint : endpoint.toString();
+    return async () => {
+        const stream = new TransformStream();
+        const fetchFn = options.fetch ?? fetch;
+        const init = { ...(options.init ?? {}) };
+        const headers = new Headers(init.headers ?? options.headers);
+        if (!headers.has("content-type")) {
+            headers.set("content-type", "avro/binary");
+        }
+        init.method = options.method ?? init.method ?? "POST";
+        init.headers = headers;
+        init.body = stream.readable;
+        const response = await fetchFn(url, init);
+        if (!response.body) {
+            throw new Error("Fetch response has no body.");
+        }
+        return {
+            readable: response.body,
+            writable: stream.writable,
+        };
+    };
+}