@zudojs/rpc 1.3.0 → 1.4.0

package/dist/rpc/reliability/cancellation/rpcAbort.helper.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @zudojs/rpc/reliability/cancellation
+ *
+ * Abort helpers used by transports to turn a signal into a typed error.
+ */
+import type { RPCError } from "../../errors/rpc.errors.js";
+/**
+ * Converts an aborted signal's reason into a typed RPC error: an RPC
+ * error reason (such as the client's `RPCTimeoutError`) passes through,
+ * anything else becomes an `RPCCancelledError`.
+ */
+export declare function abortReasonToRPCError(signal: AbortSignal, procedureName?: string): RPCError;
+/**
+ * Settles with `promise`, or rejects as soon as `signal` aborts.
+ */
+export declare function raceAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined, procedureName?: string): Promise<T>;
+//# sourceMappingURL=rpcAbort.helper.d.ts.map

package/dist/rpc/reliability/cancellation/rpcAbort.helper.js

@@ -0,0 +1,40 @@
+/**
+ * @zudojs/rpc/reliability/cancellation
+ *
+ * Abort helpers used by transports to turn a signal into a typed error.
+ */
+import { isRPCError, RPCCancelledError } from "../../errors/rpc.errors.js";
+/**
+ * Converts an aborted signal's reason into a typed RPC error: an RPC
+ * error reason (such as the client's `RPCTimeoutError`) passes through,
+ * anything else becomes an `RPCCancelledError`.
+ */
+export function abortReasonToRPCError(signal, procedureName) {
+    const reason = signal.reason;
+    return isRPCError(reason)
+        ? reason
+        : new RPCCancelledError("Call cancelled by caller.", procedureName);
+}
+/**
+ * Settles with `promise`, or rejects as soon as `signal` aborts.
+ */
+export function raceAbort(promise, signal, procedureName) {
+    if (signal === undefined) {
+        return promise;
+    }
+    if (signal.aborted) {
+        return Promise.reject(abortReasonToRPCError(signal, procedureName));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortReasonToRPCError(signal, procedureName));
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+//# sourceMappingURL=rpcAbort.helper.js.map

package/dist/rpc/reliability/retry/rpcRetry.helper.js

@@ -54,6 +54,9 @@ export function calculateRetryDelay(attempt, options) {
 }
 /**
  * Sleeps for a duration, rejecting early if the signal aborts.
+ *
+ * The timer stays ref'd: a pending retry is work the caller is awaiting,
+ * and an unref'd backoff let a script exit before the next attempt.
  */
 function sleep(ms, signal) {
     if (ms <= 0) {
@@ -64,7 +67,6 @@ function sleep(ms, signal) {
             signal?.removeEventListener("abort", onAbort);
             resolve();
         }, ms);
-        timer.unref?.();
         function onAbort() {
             clearTimeout(timer);
             reject(signal?.reason instanceof Error

package/dist/rpc/reliability/timeout/rpcTimeout.helper.d.ts

@@ -6,9 +6,11 @@
 /**
  * Creates a timeout promise that rejects after the given duration.
  *
- * The returned `cancel` clears the underlying timer. A timeout promise
- * whose timer is never cleared keeps the event loop alive for its full
- * duration even after the work it guarded has finished.
+ * The returned `cancel` clears the underlying timer, and every caller in
+ * this package cancels it as soon as the guarded work settles. The timer
+ * is deliberately *not* unref'd: it guards pending work, and in a script
+ * with no other handle an unref'd deadline let Node exit (code 13,
+ * "unsettled top-level await") before the timeout could reject.
  */
 export declare function createTimeout(duration: number, procedureName?: string): {
     readonly promise: Promise<never>;

package/dist/rpc/reliability/timeout/rpcTimeout.helper.js

@@ -8,9 +8,11 @@ import { MAX_TIMER_DELAY } from "../../constants/rpcConstants.core.js";
 /**
  * Creates a timeout promise that rejects after the given duration.
  *
- * The returned `cancel` clears the underlying timer. A timeout promise
- * whose timer is never cleared keeps the event loop alive for its full
- * duration even after the work it guarded has finished.
+ * The returned `cancel` clears the underlying timer, and every caller in
+ * this package cancels it as soon as the guarded work settles. The timer
+ * is deliberately *not* unref'd: it guards pending work, and in a script
+ * with no other handle an unref'd deadline let Node exit (code 13,
+ * "unsettled top-level await") before the timeout could reject.
  */
 export function createTimeout(duration, procedureName) {
     const delay = Math.min(Math.max(0, duration), MAX_TIMER_DELAY);
@@ -19,7 +21,6 @@ export function createTimeout(duration, procedureName) {
         timer = setTimeout(() => {
             reject(new RPCTimeoutError(duration, procedureName));
         }, delay);
-        timer.unref?.();
     });
     return {
         promise,

package/dist/rpc/server/index.d.ts

@@ -1,3 +1,9 @@
+/**
+ * RPC server: validates incoming frames, dispatches them to registered
+ * procedures, and maps every failure onto a wire-safe error payload.
+ */
 export type { RPCServerOptions } from "./rpcServer.core.js";
 export { RPCServer } from "./rpcServer.core.js";
+export type { RPCMappedError } from "./rpcErrorMapping.helper.js";
+export { mapRPCError } from "./rpcErrorMapping.helper.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/rpc/server/index.js

@@ -1,2 +1,7 @@
+/**
+ * RPC server: validates incoming frames, dispatches them to registered
+ * procedures, and maps every failure onto a wire-safe error payload.
+ */
 export { RPCServer } from "./rpcServer.core.js";
+export { mapRPCError } from "./rpcErrorMapping.helper.js";
 //# sourceMappingURL=index.js.map

package/dist/rpc/server/rpcBaseErrorMapping.helper.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Wire mapping for exposable `@zudojs/errors` errors that are not RPC
+ * errors — a `NotFoundError` or `ConflictError` thrown by domain code a
+ * procedure calls.
+ */
+import type { RPCErrorPayload } from "../types/rpcResponse.type.js";
+/**
+ * Maps a `@zudojs/errors` error built with `expose: true` onto a wire
+ * payload: its status picks the RPC code (404 → `RPC_NOT_FOUND`, 409 →
+ * `RPC_CONFLICT`, 401, 403, 422, 429 …; a `ValidationError` is always
+ * `RPC_VALIDATION_ERROR`), and an unlisted status keeps the error's own
+ * code. The message is the error's own, which `expose: true` declares
+ * safe. Returns `undefined` for anything else, which stays internal.
+ */
+export declare function mapExposedBaseError(error: unknown): RPCErrorPayload | undefined;
+//# sourceMappingURL=rpcBaseErrorMapping.helper.d.ts.map

package/dist/rpc/server/rpcBaseErrorMapping.helper.js

@@ -0,0 +1,57 @@
+/**
+ * Wire mapping for exposable `@zudojs/errors` errors that are not RPC
+ * errors — a `NotFoundError` or `ConflictError` thrown by domain code a
+ * procedure calls.
+ */
+import { isBaseError, RateLimitError, ValidationError } from "@zudojs/errors";
+/** Wire code for each HTTP-style status an exposable error can carry. */
+const STATUS_WIRE_CODES = new Map([
+    [400, "RPC_VALIDATION_ERROR"],
+    [401, "RPC_UNAUTHENTICATED"],
+    [403, "RPC_FORBIDDEN"],
+    [404, "RPC_NOT_FOUND"],
+    [408, "RPC_TIMEOUT"],
+    [409, "RPC_CONFLICT"],
+    [422, "RPC_VALIDATION_ERROR"],
+    [429, "RPC_RATE_LIMITED"],
+    [503, "RPC_UNAVAILABLE"],
+    [504, "RPC_TIMEOUT"],
+]);
+function validationDetails(error) {
+    if (error.issues.length === 0) {
+        return undefined;
+    }
+    // The received `value` is dropped: a response never echoes caller input.
+    return error.issues.map((issue) => ({
+        path: (issue.path ?? (issue.field !== undefined ? [issue.field] : [])).map(String).join("."),
+        code: issue.code ?? "invalid",
+        message: issue.message,
+    }));
+}
+/**
+ * Maps a `@zudojs/errors` error built with `expose: true` onto a wire
+ * payload: its status picks the RPC code (404 → `RPC_NOT_FOUND`, 409 →
+ * `RPC_CONFLICT`, 401, 403, 422, 429 …; a `ValidationError` is always
+ * `RPC_VALIDATION_ERROR`), and an unlisted status keeps the error's own
+ * code. The message is the error's own, which `expose: true` declares
+ * safe. Returns `undefined` for anything else, which stays internal.
+ */
+export function mapExposedBaseError(error) {
+    if (!isBaseError(error) || error.expose !== true) {
+        return undefined;
+    }
+    const code = error instanceof ValidationError
+        ? "RPC_VALIDATION_ERROR"
+        : (STATUS_WIRE_CODES.get(error.statusCode) ?? String(error.code));
+    const details = error instanceof ValidationError
+        ? validationDetails(error)
+        : error instanceof RateLimitError && error.retryAfterSeconds !== undefined
+            ? { retryAfter: error.retryAfterSeconds }
+            : undefined;
+    return {
+        code,
+        message: error.message,
+        ...(details !== undefined ? { details } : {}),
+    };
+}
+//# sourceMappingURL=rpcBaseErrorMapping.helper.js.map

package/dist/rpc/server/rpcErrorMapping.helper.d.ts

@@ -0,0 +1,35 @@
+import type { RPCErrorPayload } from "../types/rpcResponse.type.js";
+/**
+ * An error mapped onto the wire.
+ *
+ * `internal` is `true` when the original error carried server detail that
+ * was withheld from `payload`; transports hand the original error to their
+ * `onInternalError` hook in that case so the failure stays diagnosable.
+ */
+export interface RPCMappedError {
+    readonly payload: RPCErrorPayload;
+    readonly internal: boolean;
+}
+/**
+ * Maps any thrown value onto a wire-safe error payload.
+ *
+ * Typed RPC errors keep their wire code (and, for validation and rate
+ * limiting, their `details`). A `@zudojs/errors` error built with
+ * `expose: true` — `NotFoundError`, `ConflictError`, `ValidationError` … —
+ * travels with its own message under the matching code (`RPC_NOT_FOUND`,
+ * `RPC_CONFLICT`, `RPC_VALIDATION_ERROR` …). Anything not built to be
+ * exposed — an `RPCInternalError`, a non-exposed custom `RPCError` or
+ * `BaseError`, or any other error — is answered with
+ * {@link INTERNAL_ERROR_MESSAGE}, so exception text, stack traces and
+ * causes never reach the remote side.
+ */
+export declare function mapRPCError(error: unknown): RPCMappedError;
+/**
+ * The wire code of a typed RPC error — `RPC_TIMEOUT` for an
+ * `RPCTimeoutError`, and so on — or `undefined` for anything without one.
+ * The client stamps it on every error it rejects with, so a caller
+ * compares `error.code` against the same strings whether the failure was
+ * reported by the server or raised locally (its own deadline, a cancel).
+ */
+export declare function rpcWireCodeOf(error: unknown): string | undefined;
+//# sourceMappingURL=rpcErrorMapping.helper.d.ts.map

package/dist/rpc/server/rpcErrorMapping.helper.js

@@ -0,0 +1,101 @@
+import { isRPCError, RPCAuthenticationError, RPCCancelledError, RPCDeadlineExceededError, RPCDeserializationError, RPCForbiddenError, RPCInternalError, RPCInvalidRequestError, RPCProcedureNotFoundError, RPCRateLimitedError, RPCSerializationError, RPCTimeoutError, RPCTransportError, RPCUnavailableError, RPCValidationError, } from "../errors/rpc.errors.js";
+import { INTERNAL_ERROR_MESSAGE } from "../constants/rpcConstants.core.js";
+import { mapExposedBaseError } from "./rpcBaseErrorMapping.helper.js";
+/**
+ * Wire codes for the error types the server maps.
+ *
+ * Ordered most specific first; every entry is a type a caller can act
+ * on, which is why they must not be collapsed into a generic internal
+ * error. The third element marks a typed error whose message is server
+ * detail: its code travels, its message goes to `onInternalError`.
+ */
+const ERROR_CODES = [
+    [RPCProcedureNotFoundError, "RPC_PROCEDURE_NOT_FOUND"],
+    [RPCValidationError, "RPC_VALIDATION_ERROR"],
+    [RPCInvalidRequestError, "RPC_INVALID_REQUEST"],
+    [RPCAuthenticationError, "RPC_UNAUTHENTICATED"],
+    [RPCForbiddenError, "RPC_FORBIDDEN"],
+    [RPCRateLimitedError, "RPC_RATE_LIMITED"],
+    [RPCDeadlineExceededError, "RPC_DEADLINE_EXCEEDED"],
+    [RPCTimeoutError, "RPC_TIMEOUT"],
+    [RPCCancelledError, "RPC_CANCELLED"],
+    [RPCUnavailableError, "RPC_UNAVAILABLE"],
+    [RPCSerializationError, "RPC_SERIALIZATION_ERROR", true],
+    [RPCDeserializationError, "RPC_DESERIALIZATION_ERROR"],
+];
+/**
+ * Maps any thrown value onto a wire-safe error payload.
+ *
+ * Typed RPC errors keep their wire code (and, for validation and rate
+ * limiting, their `details`). A `@zudojs/errors` error built with
+ * `expose: true` — `NotFoundError`, `ConflictError`, `ValidationError` … —
+ * travels with its own message under the matching code (`RPC_NOT_FOUND`,
+ * `RPC_CONFLICT`, `RPC_VALIDATION_ERROR` …). Anything not built to be
+ * exposed — an `RPCInternalError`, a non-exposed custom `RPCError` or
+ * `BaseError`, or any other error — is answered with
+ * {@link INTERNAL_ERROR_MESSAGE}, so exception text, stack traces and
+ * causes never reach the remote side.
+ */
+export function mapRPCError(error) {
+    if (error instanceof RPCInternalError || !(error instanceof Error)) {
+        return internalFailure("RPC_INTERNAL_ERROR");
+    }
+    for (const [type, code, internal] of ERROR_CODES) {
+        if (error instanceof type) {
+            return internal === true
+                ? internalFailure(code)
+                : exposed(code, error.message, detailsOf(error));
+        }
+    }
+    if (isRPCError(error)) {
+        return error.expose === false
+            ? internalFailure(error.code)
+            : exposed(error.code, error.message, undefined);
+    }
+    const base = mapExposedBaseError(error);
+    if (base !== undefined) {
+        return { payload: base, internal: false };
+    }
+    return internalFailure("RPC_INTERNAL_ERROR");
+}
+/**
+ * The wire code of a typed RPC error — `RPC_TIMEOUT` for an
+ * `RPCTimeoutError`, and so on — or `undefined` for anything without one.
+ * The client stamps it on every error it rejects with, so a caller
+ * compares `error.code` against the same strings whether the failure was
+ * reported by the server or raised locally (its own deadline, a cancel).
+ */
+export function rpcWireCodeOf(error) {
+    if (error instanceof RPCInternalError) {
+        return "RPC_INTERNAL_ERROR";
+    }
+    if (error instanceof RPCTransportError) {
+        return "RPC_TRANSPORT_ERROR";
+    }
+    return ERROR_CODES.find(([type]) => error instanceof type)?.[1];
+}
+function detailsOf(error) {
+    if (error instanceof RPCValidationError &&
+        error.issues !== undefined &&
+        error.issues.length > 0) {
+        return error.issues;
+    }
+    if (error instanceof RPCRateLimitedError && error.retryAfter !== undefined) {
+        return { retryAfter: error.retryAfter };
+    }
+    return undefined;
+}
+function exposed(code, message, details) {
+    return {
+        payload: {
+            code,
+            message,
+            ...(details !== undefined ? { details } : {}),
+        },
+        internal: false,
+    };
+}
+function internalFailure(code) {
+    return { payload: { code, message: INTERNAL_ERROR_MESSAGE }, internal: true };
+}
+//# sourceMappingURL=rpcErrorMapping.helper.js.map

package/dist/rpc/server/rpcServer.core.d.ts

@@ -61,12 +61,5 @@ export declare class RPCServer {
      * Returns the procedure registry.
      */
     getRegistry(): RPCProcedureRegistry;
-    /**
-     * Maps a known error onto a wire payload.
-     *
-     * Returns `undefined` for anything unrecognised, which the caller
-     * answers with a generic internal error.
-     */
-    private mapError;
 }
 //# sourceMappingURL=rpcServer.core.d.ts.map

package/dist/rpc/server/rpcServer.core.js

@@ -2,33 +2,9 @@ import { RPCProcedureRegistry } from "../procedure/rpcProcedureRegistry.core.js"
 import { RPCMiddlewareStack } from "../middleware/rpcMiddleware.core.js";
 import { RPCDispatcher } from "../dispatcher/rpcDispatcher.core.js";
 import { createRPCErrorResponse } from "../types/rpcResponse.type.js";
-import { isRPCError, RPCAuthenticationError, RPCCancelledError, RPCDeadlineExceededError, RPCDeserializationError, RPCForbiddenError, RPCInternalError, RPCInvalidRequestError, RPCProcedureNotFoundError, RPCRateLimitedError, RPCSerializationError, RPCTimeoutError, RPCUnavailableError, RPCValidationError, } from "../errors/rpc.errors.js";
-import { INTERNAL_ERROR_MESSAGE, MAX_RPC_REQUEST_ID_LENGTH, } from "../constants/rpcConstants.core.js";
+import { MAX_RPC_REQUEST_ID_LENGTH } from "../constants/rpcConstants.core.js";
 import { assertValidRequest } from "../validation/rpcValidation.core.js";
-/**
- * Wire codes for the error types the server maps.
- *
- * Ordered most specific first; every entry is a type a caller can act
- * on, which is why they must not be collapsed into a generic internal
- * error.
- */
-const ERROR_CODES = [
-    [RPCProcedureNotFoundError, "RPC_PROCEDURE_NOT_FOUND"],
-    [RPCValidationError, "RPC_VALIDATION_ERROR"],
-    [RPCInvalidRequestError, "RPC_INVALID_REQUEST"],
-    [RPCAuthenticationError, "RPC_UNAUTHENTICATED"],
-    [RPCForbiddenError, "RPC_FORBIDDEN"],
-    [RPCRateLimitedError, "RPC_RATE_LIMITED"],
-    [RPCDeadlineExceededError, "RPC_DEADLINE_EXCEEDED"],
-    [RPCTimeoutError, "RPC_TIMEOUT"],
-    [RPCCancelledError, "RPC_CANCELLED"],
-    [RPCUnavailableError, "RPC_UNAVAILABLE"],
-    // A serialization failure is a server fault (500, `expose: false`) whose
-    // message names what could not be encoded; the code travels, the
-    // message goes to `onInternalError`.
-    [RPCSerializationError, "RPC_SERIALIZATION_ERROR", true],
-    [RPCDeserializationError, "RPC_DESERIALIZATION_ERROR"],
-];
+import { mapRPCError } from "./rpcErrorMapping.helper.js";
 /**
  * RPC server that receives and dispatches requests.
  */
@@ -91,29 +67,14 @@ export class RPCServer {
             return await this.dispatcher.dispatch(frame, trusted);
         }
         catch (error) {
-            const mapped = this.mapError(error);
-            if (mapped === undefined) {
-                this.options.onInternalError?.(error, requestId);
-                return createRPCErrorResponse(requestId, {
-                    code: "RPC_INTERNAL_ERROR",
-                    message: INTERNAL_ERROR_MESSAGE,
-                });
-            }
+            const mapped = mapRPCError(error);
             if (mapped.internal) {
-                // The error is typed, so the caller keeps its code, but it was
-                // constructed with `expose: false`: its message is server detail
-                // and goes to the log, not the wire.
+                // Internal detail goes to the log, never the wire: the caller is
+                // an untrusted peer and exception text can name hosts, paths,
+                // credentials or queries.
                 this.options.onInternalError?.(error, requestId);
-                return createRPCErrorResponse(requestId, {
-                    code: mapped.code,
-                    message: INTERNAL_ERROR_MESSAGE,
-                });
             }
-            return createRPCErrorResponse(requestId, {
-                code: mapped.code,
-                message: mapped.message,
-                ...(mapped.details !== undefined ? { details: mapped.details } : {}),
-            });
+            return createRPCErrorResponse(requestId, mapped.payload);
         }
     }
     /**
@@ -122,50 +83,5 @@ export class RPCServer {
     getRegistry() {
         return this.registry;
     }
-    /**
-     * Maps a known error onto a wire payload.
-     *
-     * Returns `undefined` for anything unrecognised, which the caller
-     * answers with a generic internal error.
-     */
-    mapError(error) {
-        // An RPCInternalError *is* the generic internal failure: it carries
-        // `expose: false` and a message written for the log. Mapping it like
-        // any other RPCError put that message on the wire.
-        if (error instanceof RPCInternalError) {
-            return undefined;
-        }
-        for (const [type, code, internal] of ERROR_CODES) {
-            if (error instanceof type) {
-                const payload = {
-                    code,
-                    message: error.message,
-                    ...(internal ? { internal: true } : {}),
-                };
-                if (error instanceof RPCValidationError &&
-                    error.issues !== undefined &&
-                    error.issues.length > 0) {
-                    payload.details = error.issues;
-                }
-                if (error instanceof RPCRateLimitedError &&
-                    error.retryAfter !== undefined) {
-                    payload.details = { retryAfter: error.retryAfter };
-                }
-                return payload;
-            }
-        }
-        // A custom RPCError subclass is still a deliberate, caller-facing
-        // error; honour its own code rather than hiding it. Its message only
-        // travels when the error was built to be exposed — `RPCError`
-        // defaults to `expose: false`.
-        if (isRPCError(error)) {
-            return {
-                code: error.code,
-                message: error.message,
-                internal: error.expose === false,
-            };
-        }
-        return undefined;
-    }
 }
 //# sourceMappingURL=rpcServer.core.js.map

package/dist/rpc/transport/codec/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Wire encoding shared by the built-in transports: the frame serializer
+ * (`@zudojs/serialization` JSON with size and depth limits), a response
+ * frame shape guard, and a bounded Fetch API body reader.
+ */
+export type { RPCFrameSerializer, RPCJsonSerializerOptions, } from "./rpcCodec.helper.js";
+export { createRPCJsonSerializer, isRPCResponseFrame } from "./rpcCodec.helper.js";
+export type { RPCBodyReadResult, RPCBodySource } from "./rpcBody.helper.js";
+export { readBoundedBody } from "./rpcBody.helper.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/rpc/transport/codec/index.js

@@ -0,0 +1,8 @@
+/**
+ * Wire encoding shared by the built-in transports: the frame serializer
+ * (`@zudojs/serialization` JSON with size and depth limits), a response
+ * frame shape guard, and a bounded Fetch API body reader.
+ */
+export { createRPCJsonSerializer, isRPCResponseFrame } from "./rpcCodec.helper.js";
+export { readBoundedBody } from "./rpcBody.helper.js";
+//# sourceMappingURL=index.js.map

package/dist/rpc/transport/codec/rpcBody.helper.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Outcome of {@link readBoundedBody}.
+ *
+ * `too-large` means the body exceeded the limit (by its declared
+ * `Content-Length` or while streaming); `unreadable` means the stream
+ * failed, was aborted, or was not valid UTF-8.
+ */
+export type RPCBodyReadResult = {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly reason: "too-large" | "unreadable";
+};
+/**
+ * The part of a Fetch API `Request` or `Response` a body read needs.
+ */
+export interface RPCBodySource {
+    readonly body: ReadableStream<Uint8Array> | null;
+    readonly headers: Headers;
+}
+/**
+ * Reads a Fetch API body as UTF-8 text without ever buffering more than
+ * `maxBytes`.
+ *
+ * `request.text()` buffers the whole body before anything can check its
+ * size, so a peer could make the server hold an arbitrarily large body in
+ * memory. This checks the declared `Content-Length` first, then counts
+ * bytes as they stream and cancels the stream the moment the limit is
+ * crossed. Transport-neutral: `@zudojs/api`'s fetch binding reads request
+ * bodies through it too.
+ *
+ * @param maxBytes Limit in bytes; `0` or less disables the limit.
+ */
+export declare function readBoundedBody(source: RPCBodySource, maxBytes: number): Promise<RPCBodyReadResult>;
+//# sourceMappingURL=rpcBody.helper.d.ts.map

package/dist/rpc/transport/codec/rpcBody.helper.js

@@ -0,0 +1,64 @@
+/**
+ * Reads a Fetch API body as UTF-8 text without ever buffering more than
+ * `maxBytes`.
+ *
+ * `request.text()` buffers the whole body before anything can check its
+ * size, so a peer could make the server hold an arbitrarily large body in
+ * memory. This checks the declared `Content-Length` first, then counts
+ * bytes as they stream and cancels the stream the moment the limit is
+ * crossed. Transport-neutral: `@zudojs/api`'s fetch binding reads request
+ * bodies through it too.
+ *
+ * @param maxBytes Limit in bytes; `0` or less disables the limit.
+ */
+export async function readBoundedBody(source, maxBytes) {
+    const limited = maxBytes > 0;
+    const declared = Number(source.headers.get("content-length") ?? Number.NaN);
+    if (limited && Number.isFinite(declared) && declared > maxBytes) {
+        await source.body?.cancel().catch(() => undefined);
+        return { ok: false, reason: "too-large" };
+    }
+    if (source.body === null) {
+        return { ok: true, text: "" };
+    }
+    const reader = source.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            total += value.byteLength;
+            if (limited && total > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                return { ok: false, reason: "too-large" };
+            }
+            chunks.push(value);
+        }
+    }
+    catch {
+        return { ok: false, reason: "unreadable" };
+    }
+    finally {
+        reader.releaseLock();
+    }
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(concat(chunks, total));
+        return { ok: true, text };
+    }
+    catch {
+        return { ok: false, reason: "unreadable" };
+    }
+}
+function concat(chunks, total) {
+    const joined = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return joined;
+}
+//# sourceMappingURL=rpcBody.helper.js.map

package/dist/rpc/transport/codec/rpcCodec.helper.d.ts

@@ -0,0 +1,41 @@
+import type { Serializer } from "@zudojs/serialization";
+import type { RPCResponse } from "../../types/rpcResponse.type.js";
+/**
+ * Serializer that turns RPC frames into wire text and back.
+ *
+ * Any `@zudojs/serialization` string serializer fits. Both ends of a
+ * connection must use compatible serializers: a server created with
+ * `preserveTypes: true` should be called by a client that uses it too.
+ */
+export type RPCFrameSerializer = Serializer<unknown, string>;
+/**
+ * Options for {@link createRPCJsonSerializer}.
+ */
+export interface RPCJsonSerializerOptions {
+    /** Largest accepted encoded frame, in bytes. */
+    readonly maxSize?: number;
+    /** Deepest accepted nesting. Defaults to {@link MAX_RPC_FRAME_DEPTH}. */
+    readonly maxDepth?: number;
+    /**
+     * Tag `Date`, `BigInt`, `Map`, `Set` and friends so they survive the
+     * trip. Defaults to `false` (plain JSON), which any HTTP client can
+     * speak.
+     */
+    readonly preserveTypes?: boolean;
+}
+/**
+ * Creates the default frame serializer: `@zudojs/serialization` JSON with
+ * size and depth limits, so decoding an untrusted frame is bounded.
+ */
+export declare function createRPCJsonSerializer(options?: RPCJsonSerializerOptions): RPCFrameSerializer;
+/**
+ * Determines whether a decoded value has the shape of an
+ * {@link RPCResponse}: a string `id`, a boolean `success`, and — when
+ * present — an `error` with string `code` and `message`.
+ *
+ * Transports check this before handing a peer's reply to the client, so
+ * a proxy's HTML error page or a truncated body is reported as a
+ * transport failure instead of being read as a result.
+ */
+export declare function isRPCResponseFrame(value: unknown): value is RPCResponse;
+//# sourceMappingURL=rpcCodec.helper.d.ts.map