@zudojs/rpc 1.2.0 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @zudojs/rpc
 
-Type-safe RPC — define procedures, apply middleware, dispatch calls, and serve them over your own transport.
+Type-safe RPC — define procedures, apply middleware, dispatch calls, and serve them in-process or over HTTP with the built-in transports, or over your own.
 
 <!-- zudo-docs:start -->
 
@@ -19,10 +19,13 @@ Import this when you need:
 
 The package is transport-agnostic: `RPCServer.handle` takes a request frame
 and returns a response frame, and `RPCClient` sends through any object
-implementing `RPCTransport`. It ships no HTTP or WebSocket transport of its
-own.
+implementing `RPCTransport`. Two transports ship with it: an in-memory one
+(`createRPCMemoryTransport`) and HTTP on the web-standard Fetch API
+(`createRPCHttpTransport` for the client, `createRPCFetchHandler` for the
+server). There is no WebSocket transport.
 
-For request/response inside one process, prefer `@zudojs/api`.
+To expose `@zudojs/api` operations as procedures, use
+`registerApiRpcProcedures` from `@zudojs/api`.
 
 ## Installation
 
@@ -49,6 +52,20 @@ import {
   type RPCResponse,
   type RPCTransport,
   type RPCErrorOptions,
+  // transports
+  createRPCMemoryTransport,
+  createRPCHttpTransport,
+  createRPCFetchHandler,
+  createRPCJsonSerializer,
+  readBoundedBody,
+  isRPCResponseFrame,
+  RPC_HTTP_STATUS,
+  rpcHttpStatus,
+  // errors on the wire
+  mapRPCError,
+  rpcErrorFromWire,
+  DEFAULT_RPC_HTTP_MAX_BODY_BYTES,
+  MAX_RPC_FRAME_DEPTH,
 } from "@zudojs/rpc";
 ```
 
@@ -74,7 +91,11 @@ const server = new RPCServer();
 server.register(sum);
 
 const response = await server.handle(
-  createRPCRequest({ id: "req-1", procedure: "math.sum", payload: { a: 1, b: 2 } }),
+  createRPCRequest({
+    id: "req-1",
+    procedure: "math.sum",
+    payload: { a: 1, b: 2 },
+  }),
 );
 // { id: "req-1", success: true, result: 3 }
 ```
@@ -86,25 +107,104 @@ The frame's `metadata` is optional.
 
 ### Calling through a transport
 
-`RPCClient` needs an `RPCTransport` — an object whose `send(request, options)`
+`RPCClient` sends through an `RPCTransport`: an object whose `send(request, options)`
 delivers the frame and resolves with the response. `options.signal` aborts the
-call and `options.timeout` is the deadline in milliseconds, so a transport can
-set its own socket timeout. The in-process transport below is the smallest
-possible one:
+call and `options.timeout` is the deadline in milliseconds.
+
+**In memory**, for tests and modular monoliths:
 
 ```typescript
-import { RPCClient, type RPCTransport } from "@zudojs/rpc";
+import { RPCClient, createRPCMemoryTransport } from "@zudojs/rpc";
 
-const transport: RPCTransport = { send: (request) => server.handle(request) };
-const client = new RPCClient(transport, { timeout: 5_000 });
+const client = new RPCClient(
+  createRPCMemoryTransport(server, { auth: { userId: "u1" } }),
+  { timeout: 5_000 },
+);
 
-const total = await client.call<{ a: number; b: number }, number>("math.sum", { a: 1, b: 2 });
+const total = await client.call<{ a: number; b: number }, number>("math.sum", {
+  a: 1,
+  b: 2,
+});
 // 3
 ```
 
+Frames are round-tripped through JSON by default, so the server never shares
+objects with the caller, and a value that could not cross a network (a
+`BigInt` result, a cycle) fails in memory too. Pass `serializer: false` to hand
+frames over by reference. `auth` (a value, or a function of the request) is
+handed to the server as the trusted `context.auth`.
+
+**Over HTTP.** Mount the server's fetch handler on any Fetch API server at one
+POST endpoint, and point the client transport at it:
+
+```typescript
+import { createRPCFetchHandler, createRPCHttpTransport } from "@zudojs/rpc";
+
+// Server: (request: Request) => Promise<Response>
+const handle = createRPCFetchHandler(server, {
+  auth: async (request) => verifyBearer(request.headers.get("authorization")),
+  onInternalError: (error, requestId) => logger.error({ requestId, error }),
+});
+Bun.serve({ port: 3000, fetch: handle }); // or Deno.serve, an edge runtime, …
+// On @zudojs/http, no glue code: mountFetchHandler(router, "/rpc", handle);
+
+// Client: uses the global fetch.
+const remote = new RPCClient(
+  createRPCHttpTransport({
+    url: "https://math.internal/rpc",
+    headers: () => ({ authorization: `Bearer ${currentToken()}` }),
+  }),
+  { timeout: 5_000 },
+);
+await remote.call("math.sum", { a: 1, b: 2 });
+```
+
+On `@zudojs/http`, mount it with `mountFetchHandler(router, "/rpc", handle)`. The handler answers every path it is mounted on, so the prefix that `mountFetchHandler` strips does not matter. It reads at most `maxBodyBytes` (default
+`DEFAULT_RPC_HTTP_MAX_BODY_BYTES`, 1 MiB plus envelope headroom) without
+buffering more, and decodes with a size- and depth-limited
+`@zudojs/serialization` JSON serializer. Every reply, including one to a bad
+HTTP request (wrong method, wrong content type, oversized or invalid body), is
+an RPC frame with a status from `RPC_HTTP_STATUS` (404 unknown procedure, 422
+validation, 401, 403, 429, 504 timeout, 500 internal, and so on). The status is
+advisory; `error.code` is authoritative. An `auth` hook that throws an
+`RPCAuthenticationError` refuses the call. Any other error it throws is
+answered as an internal error. The call runs under `request.signal`, so a
+client that disconnects cancels the procedure (`context.signal` aborts); the
+memory transport passes the caller's signal to the server the same way.
+
+The server refuses (`RPC_INVALID_REQUEST`) a frame whose `payload` or
+`metadata` holds a `__proto__`, `constructor` or `prototype` key at any
+depth: `JSON.parse` keeps such a key as an own property, and a handler that
+merges its input into another object would have that object's prototype
+replaced. `limits: { allowUnsafeKeys: true }` turns the check off, and
+`findUnsafeKey(value)` runs it on anything else you decode.
+
+The client transport aborts the underlying `fetch` when the call's signal or
+deadline fires. It reports a network failure, or a reply that is not an RPC
+frame for this request (a proxy's HTML page, a truncated or oversized body), as
+an `RPCTransportError`. An expired deadline is an `RPCTimeoutError`, and a caller
+abort is an `RPCCancelledError`. Use the same serializer on both ends:
+`createRPCJsonSerializer({ preserveTypes: true })` carries `Date`, `BigInt`,
+`Map` and `Set`.
+
 A failed call rejects with a typed error rebuilt from the wire code
-(`RPCTimeoutError`, `RPCCancelledError`, `RPCUnavailableError`, or an
-`RPCError` carrying the server's `code` and `details`).
+(`rpcErrorFromWire`): `RPCProcedureNotFoundError`, `RPCValidationError` (with
+`issues`), `RPCInvalidRequestError`, `RPCAuthenticationError`,
+`RPCForbiddenError`, `RPCRateLimitedError`, `RPCTimeoutError`,
+`RPCCancelledError` or `RPCUnavailableError`, or else an `RPCError`. The
+server's `details` are kept on the error as `error.details`.
+
+`error.code` is always the wire code — `"RPC_TIMEOUT"`, `"RPC_CANCELLED"`,
+`"RPC_UNAVAILABLE"`, `"RPC_VALIDATION_ERROR"`, `"RPC_NOT_FOUND"` … — whether
+the server reported the failure or the client raised it itself (its own
+deadline, a cancelled signal, a closed client, `"RPC_TRANSPORT_ERROR"` for a
+network failure). Branch on `instanceof` or on those strings; the class
+codes (`ErrorCode.RPC_TIMEOUT`, `"ERR_RPC_TIMEOUT"`) are not what a client
+error carries.
+
+A pending call's deadline and a `retry()` backoff hold a normal (ref'd)
+timer, cleared as soon as the call settles, so a plain script awaiting a call
+stays alive until it resolves or times out.
 
 ### Middleware and trusted identity
 
@@ -147,10 +247,20 @@ server maps them to wire codes (`RPC_PROCEDURE_NOT_FOUND`,
 `RPC_RATE_LIMITED`, `RPC_TIMEOUT`, …). A custom `RPCError` subclass keeps its
 own `code`.
 
-What reaches the caller follows the error's `expose` flag. Anything thrown
-with `expose: false` — an `RPCInternalError`, an `RPCSerializationError`, a
-plain `new RPCError(...)` (whose default is `expose: false`), or any
-non-RPC error — is answered with the fixed `INTERNAL_ERROR_MESSAGE`; the
+`mapRPCError(error)` is the mapping the server and the fetch handler share. Use it in a custom transport to produce the same wire payloads.
+
+What reaches the caller follows the error's `expose` flag. A
+`@zudojs/errors` error built with `expose: true` keeps its message and maps
+to the matching code by status: `NotFoundError` → `RPC_NOT_FOUND`,
+`ConflictError` → `RPC_CONFLICT`, `ValidationError` → `RPC_VALIDATION_ERROR`
+(with its issues, minus the received values, as `details`),
+`AuthenticationError` → `RPC_UNAUTHENTICATED`, `AuthorizationError` →
+`RPC_FORBIDDEN`, `RateLimitError` → `RPC_RATE_LIMITED` (with
+`{ retryAfter }`); an unlisted status keeps the error's own code. Anything
+thrown with `expose: false` — an `RPCInternalError`, an
+`RPCSerializationError`, a plain `new RPCError(...)` (whose default is
+`expose: false`), a non-exposed `BaseError`, or any other error — is
+answered with the fixed `INTERNAL_ERROR_MESSAGE`; the
 original error is handed to `onInternalError(error, requestId)` so it can be
 logged against the request id. A handler result that fails the procedure's
 `output` schema is treated the same way: it is the server's fault, not the
@@ -158,12 +268,19 @@ caller's.
 
 ```typescript
 const server = new RPCServer(undefined, undefined, {
-  limits: { maxPayloadBytes: 256 * 1024 },
+  limits: { maxPayloadBytes: 256 * 1024, maxRequestIdLength: 128 },
   dispatch: { defaultTimeout: 10_000 },
   onInternalError: (error, requestId) => logger.error({ requestId, error }),
 });
 ```
 
+`maxPayloadBytes` bounds `payload` and `metadata` together, because both are
+caller-controlled and both reach the handler. `maxRequestIdLength` bounds
+`request.id`, which every response echoes back; an id over the limit is
+refused before a response is built, so it is never reflected. Both default to
+`MAX_RPC_PAYLOAD_SIZE` (1 MiB) and `MAX_RPC_REQUEST_ID_LENGTH` (128), and
+either can be set to `0` when the transport already enforces the limit.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -8,20 +8,26 @@
  *
  * @example
  * ```ts
- * import { RPCServer, RPCClient, createRPCProcedure, RPCMiddlewareStack } from "@zudojs/rpc";
+ * import {
+ *   RPCServer,
+ *   RPCClient,
+ *   createRPCProcedure,
+ *   createRPCMemoryTransport,
+ * } from "@zudojs/rpc";
  *
  * const server = new RPCServer();
  * server.register(createRPCProcedure("users.getUser", async (input) => {
  *   return userService.findById(input.id);
  * }));
  *
- * const client = new RPCClient(memoryTransport);
+ * // In-process; swap for createRPCHttpTransport({ url }) across the network.
+ * const client = new RPCClient(createRPCMemoryTransport(server));
  * const user = await client.call("users.getUser", { id: "123" });
  * ```
  */
 export type { RPCProcedureName, RPCMetadata, RPCMetadataOptions, RPCRequest, RPCRequestOptions, RPCErrorPayload, RPCResponse, } from "./rpc/types/index.js";
 export { createRPCMetadata, createRPCRequest, createRPCResponse, createRPCErrorResponse, } from "./rpc/types/index.js";
-export { DEFAULT_RPC_TIMEOUT, MAX_RPC_PAYLOAD_SIZE, MAX_PENDING_REQUESTS, MAX_MIDDLEWARE, MAX_PROCEDURES, MAX_PROCEDURE_NAME_LENGTH, MAX_TIMER_DELAY, PROCEDURE_NAME_PATTERN, INTERNAL_ERROR_MESSAGE, } from "./rpc/constants/index.js";
+export { DEFAULT_RPC_TIMEOUT, MAX_RPC_PAYLOAD_SIZE, MAX_RPC_REQUEST_ID_LENGTH, MAX_PENDING_REQUESTS, MAX_MIDDLEWARE, MAX_PROCEDURES, MAX_PROCEDURE_NAME_LENGTH, MAX_TIMER_DELAY, PROCEDURE_NAME_PATTERN, INTERNAL_ERROR_MESSAGE, DEFAULT_RPC_HTTP_MAX_BODY_BYTES, MAX_RPC_FRAME_DEPTH, } from "./rpc/constants/index.js";
 export type { RPCRequestLimits, RPCSchema } from "./rpc/validation/index.js";
 export { assertValidProcedureName, assertValidRequest, measurePayloadBytes, toValidationIssues, parseInput, parseOutput, } from "./rpc/validation/index.js";
 export type { RPCErrorOptions } from "./rpc/errors/index.js";
@@ -35,11 +41,9 @@ export type { RPCMiddleware } from "./rpc/middleware/index.js";
 export { RPCMiddlewareStack } from "./rpc/middleware/index.js";
 export type { RPCDispatcherOptions } from "./rpc/dispatcher/index.js";
 export { RPCDispatcher } from "./rpc/dispatcher/index.js";
-export type { RPCServerOptions } from "./rpc/server/index.js";
-export { RPCServer } from "./rpc/server/index.js";
-export type { RPCTransport, RPCTransportRequestOptions, } from "./rpc/transport/index.js";
-export type { RPCCallOptions, RPCClientOptions } from "./rpc/client/index.js";
-export { RPCClient } from "./rpc/client/index.js";
+export * from "./rpc/server/index.js";
+export * from "./rpc/transport/index.js";
+export * from "./rpc/client/index.js";
 export { createTimeout, withTimeout, runWithTimeout, getRemainingTime, isDeadlineExceeded, throwIfDeadlineExceeded, readDeadline, createCancellableSignal, cancelSignal, throwIfCancelled, combineSignals, DEFAULT_RETRY_OPTIONS, calculateRetryDelay, retry, } from "./rpc/reliability/index.js";
 export type { RPCBackoff, RPCJitter, RPCRetryOptions, CancellableSignal, } from "./rpc/reliability/index.js";
 export type { RPCInterceptor } from "./rpc/interceptor/index.js";

package/dist/index.js

@@ -8,20 +8,26 @@
  *
  * @example
  * ```ts
- * import { RPCServer, RPCClient, createRPCProcedure, RPCMiddlewareStack } from "@zudojs/rpc";
+ * import {
+ *   RPCServer,
+ *   RPCClient,
+ *   createRPCProcedure,
+ *   createRPCMemoryTransport,
+ * } from "@zudojs/rpc";
  *
  * const server = new RPCServer();
  * server.register(createRPCProcedure("users.getUser", async (input) => {
  *   return userService.findById(input.id);
  * }));
  *
- * const client = new RPCClient(memoryTransport);
+ * // In-process; swap for createRPCHttpTransport({ url }) across the network.
+ * const client = new RPCClient(createRPCMemoryTransport(server));
  * const user = await client.call("users.getUser", { id: "123" });
  * ```
  */
 export { createRPCMetadata, createRPCRequest, createRPCResponse, createRPCErrorResponse, } from "./rpc/types/index.js";
 // Constants
-export { DEFAULT_RPC_TIMEOUT, MAX_RPC_PAYLOAD_SIZE, MAX_PENDING_REQUESTS, MAX_MIDDLEWARE, MAX_PROCEDURES, MAX_PROCEDURE_NAME_LENGTH, MAX_TIMER_DELAY, PROCEDURE_NAME_PATTERN, INTERNAL_ERROR_MESSAGE, } from "./rpc/constants/index.js";
+export { DEFAULT_RPC_TIMEOUT, MAX_RPC_PAYLOAD_SIZE, MAX_RPC_REQUEST_ID_LENGTH, MAX_PENDING_REQUESTS, MAX_MIDDLEWARE, MAX_PROCEDURES, MAX_PROCEDURE_NAME_LENGTH, MAX_TIMER_DELAY, PROCEDURE_NAME_PATTERN, INTERNAL_ERROR_MESSAGE, DEFAULT_RPC_HTTP_MAX_BODY_BYTES, MAX_RPC_FRAME_DEPTH, } from "./rpc/constants/index.js";
 export { assertValidProcedureName, assertValidRequest, measurePayloadBytes, toValidationIssues, parseInput, parseOutput, } from "./rpc/validation/index.js";
 export { RPCError, RPCProcedureNotFoundError, RPCInvalidRequestError, RPCValidationError, RPCAuthenticationError, RPCForbiddenError, RPCTimeoutError, RPCCancelledError, RPCInternalError, RPCTransportError, RPCSerializationError, RPCDeserializationError, RPCUnavailableError, RPCRateLimitedError, RPCDeadlineExceededError, RPCDuplicateProcedureError, createRPCError, isRPCError, } from "./rpc/errors/index.js";
 export { createRPCProcedure } from "./rpc/procedure/index.js";
@@ -29,8 +35,11 @@ export { RPCProcedureRegistry, RPCProcedureRouter, } from "./rpc/procedure/index
 export { createRPCContext } from "./rpc/context/index.js";
 export { RPCMiddlewareStack } from "./rpc/middleware/index.js";
 export { RPCDispatcher } from "./rpc/dispatcher/index.js";
-export { RPCServer } from "./rpc/server/index.js";
-export { RPCClient } from "./rpc/client/index.js";
+// Server, transports (in-memory and HTTP) and client — every export of
+// these barrels is public.
+export * from "./rpc/server/index.js";
+export * from "./rpc/transport/index.js";
+export * from "./rpc/client/index.js";
 // Reliability
 export { createTimeout, withTimeout, runWithTimeout, getRemainingTime, isDeadlineExceeded, throwIfDeadlineExceeded, readDeadline, createCancellableSignal, cancelSignal, throwIfCancelled, combineSignals, DEFAULT_RETRY_OPTIONS, calculateRetryDelay, retry, } from "./rpc/reliability/index.js";
 export { createNoopRPCInterceptor } from "./rpc/interceptor/index.js";

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

@@ -1,3 +1,8 @@
+/**
+ * RPC client: builds request frames, sends them through an
+ * {@link RPCTransport}, and rebuilds typed errors from error responses.
+ */
 export type { RPCCallOptions, RPCClientOptions } from "./rpcClient.core.js";
 export { RPCClient } from "./rpcClient.core.js";
+export { rpcErrorFromWire } from "./rpcWireError.helper.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/rpc/client/index.js

@@ -1,2 +1,7 @@
+/**
+ * RPC client: builds request frames, sends them through an
+ * {@link RPCTransport}, and rebuilds typed errors from error responses.
+ */
 export { RPCClient } from "./rpcClient.core.js";
+export { rpcErrorFromWire } from "./rpcWireError.helper.js";
 //# sourceMappingURL=index.js.map

package/dist/rpc/client/rpcClient.core.d.ts

@@ -41,8 +41,14 @@ export declare class RPCClient {
     get pendingCount(): number;
     /**
      * Calls a remote procedure.
+     *
+     * Rejects with a typed RPC error whose `code` is the wire code
+     * (`"RPC_TIMEOUT"`, `"RPC_CANCELLED"`, `"RPC_VALIDATION_ERROR"` …)
+     * whether the server reported the failure or the client raised it (its
+     * own deadline, a cancelled signal, a closed client).
      */
     call<TInput = unknown, TOutput = unknown>(procedure: string, input: TInput, options?: RPCCallOptions): Promise<TOutput>;
+    private invoke;
     /**
      * Cancels every in-flight call and stops accepting new ones.
      */
@@ -69,12 +75,5 @@ export declare class RPCClient {
      * error is passed through untouched.
      */
     private toCancellation;
-    /**
-     * Reconstructs a typed error from an error response.
-     *
-     * The wire code drives the type, so a caller can tell an
-     * authentication failure from a timeout without string matching.
-     */
-    private toError;
 }
 //# sourceMappingURL=rpcClient.core.d.ts.map

package/dist/rpc/client/rpcClient.core.js

@@ -1,6 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { createRPCRequest } from "../types/rpcRequest.type.js";
-import { isRPCError, RPCCancelledError, RPCError, RPCTimeoutError, RPCUnavailableError, } from "../errors/rpc.errors.js";
+import { isRPCError, RPCCancelledError, RPCUnavailableError, } from "../errors/rpc.errors.js";
+import { rpcErrorFromWire } from "./rpcWireError.helper.js";
+import { rpcWireCodeOf } from "../server/rpcErrorMapping.helper.js";
 import { DEFAULT_RPC_TIMEOUT, MAX_PENDING_REQUESTS, } from "../constants/rpcConstants.core.js";
 import { createTimeout } from "../reliability/timeout/rpcTimeout.helper.js";
 /**
@@ -28,8 +30,21 @@ export class RPCClient {
     }
     /**
      * Calls a remote procedure.
+     *
+     * Rejects with a typed RPC error whose `code` is the wire code
+     * (`"RPC_TIMEOUT"`, `"RPC_CANCELLED"`, `"RPC_VALIDATION_ERROR"` …)
+     * whether the server reported the failure or the client raised it (its
+     * own deadline, a cancelled signal, a closed client).
      */
     async call(procedure, input, options = {}) {
+        try {
+            return await this.invoke(procedure, input, options);
+        }
+        catch (error) {
+            throw withWireCode(error);
+        }
+    }
+    async invoke(procedure, input, options) {
         if (this.closed) {
             throw new RPCUnavailableError("RPC client has been closed.", procedure);
         }
@@ -84,7 +99,7 @@ export class RPCClient {
             }
             const response = await Promise.race(races);
             if (!response.success) {
-                throw this.toError(response, procedure);
+                throw rpcErrorFromWire(response.error, procedure);
             }
             return response.result;
         }
@@ -166,52 +181,23 @@ export class RPCClient {
         }
         return error;
     }
-    /**
-     * Reconstructs a typed error from an error response.
-     *
-     * The wire code drives the type, so a caller can tell an
-     * authentication failure from a timeout without string matching.
-     */
-    toError(response, procedure) {
-        const message = response.error?.message ?? "RPC call failed.";
-        const code = response.error?.code;
-        switch (code) {
-            case "RPC_TIMEOUT": {
-                // The constructor derives its message from a duration the wire
-                // does not carry; keep the type and restore the server's message
-                // rather than reporting "timed out after 0ms".
-                const timeout = new RPCTimeoutError(0, procedure);
-                Object.defineProperty(timeout, "message", {
-                    value: message,
-                    enumerable: false,
-                    configurable: true,
-                    writable: true,
-                });
-                return timeout;
-            }
-            case "RPC_CANCELLED":
-                return new RPCCancelledError(message, procedure);
-            case "RPC_UNAVAILABLE":
-                return new RPCUnavailableError(message, procedure);
-            default:
-                break;
+}
+/**
+ * Gives a typed RPC error its wire code. An error rebuilt from a response
+ * already has it; one raised locally still carries its class code
+ * (`ERR_RPC_TIMEOUT`), which a caller comparing against `"RPC_TIMEOUT"`
+ * would never match.
+ */
+function withWireCode(error) {
+    const code = isRPCError(error) ? rpcWireCodeOf(error) : undefined;
+    if (code !== undefined && error instanceof Error && error.code !== code) {
+        try {
+            Object.defineProperty(error, "code", { value: code, enumerable: true, configurable: true });
         }
-        const error = new RPCError(message, { procedureName: procedure });
-        // Preserve the server's code and any details for callers that
-        // branch on them.
-        Object.defineProperty(error, "code", {
-            value: code ?? error.code,
-            enumerable: true,
-            configurable: true,
-        });
-        if (response.error?.details !== undefined) {
-            Object.defineProperty(error, "details", {
-                value: response.error.details,
-                enumerable: true,
-                configurable: true,
-            });
+        catch {
+            // A frozen error keeps the code it has.
         }
-        return error;
     }
+    return error;
 }
 //# sourceMappingURL=rpcClient.core.js.map

package/dist/rpc/client/rpcWireError.helper.d.ts

@@ -0,0 +1,13 @@
+import type { RPCErrorPayload } from "../types/rpcResponse.type.js";
+import { RPCError } from "../errors/rpc.errors.js";
+/**
+ * Rebuilds a typed error from an error response's payload.
+ *
+ * The wire code drives the class, so a caller can tell a validation
+ * failure from an authentication failure or a timeout with `instanceof`
+ * rather than string matching. Every rebuilt error carries the server's
+ * wire `code` (`error.code === "RPC_TIMEOUT"`, `"RPC_VALIDATION_ERROR"`,
+ * `"RPC_NOT_FOUND"` …) and its `details`.
+ */
+export declare function rpcErrorFromWire(payload: RPCErrorPayload | undefined, procedure: string): RPCError;
+//# sourceMappingURL=rpcWireError.helper.d.ts.map

package/dist/rpc/client/rpcWireError.helper.js

@@ -0,0 +1,71 @@
+import { RPCAuthenticationError, RPCCancelledError, RPCError, RPCForbiddenError, RPCInvalidRequestError, RPCProcedureNotFoundError, RPCRateLimitedError, RPCTimeoutError, RPCUnavailableError, RPCValidationError, } from "../errors/rpc.errors.js";
+/**
+ * Rebuilds a typed error from an error response's payload.
+ *
+ * The wire code drives the class, so a caller can tell a validation
+ * failure from an authentication failure or a timeout with `instanceof`
+ * rather than string matching. Every rebuilt error carries the server's
+ * wire `code` (`error.code === "RPC_TIMEOUT"`, `"RPC_VALIDATION_ERROR"`,
+ * `"RPC_NOT_FOUND"` …) and its `details`.
+ */
+export function rpcErrorFromWire(payload, procedure) {
+    const message = payload?.message ?? "RPC call failed.";
+    const code = payload?.code;
+    const details = payload?.details;
+    switch (code) {
+        case "RPC_TIMEOUT":
+            return withWire(withMessage(new RPCTimeoutError(0, procedure), message), code, details);
+        case "RPC_CANCELLED":
+            return withWire(new RPCCancelledError(message, procedure), code, details);
+        case "RPC_UNAVAILABLE":
+            return withWire(new RPCUnavailableError(message, procedure), code, details);
+        case "RPC_PROCEDURE_NOT_FOUND":
+            return withWire(withMessage(new RPCProcedureNotFoundError(procedure), message), code, details);
+        case "RPC_VALIDATION_ERROR":
+            return withWire(new RPCValidationError(message, (Array.isArray(details) ? details : []), procedure), code, details);
+        case "RPC_INVALID_REQUEST":
+            return withWire(new RPCInvalidRequestError(message, procedure), code, details);
+        case "RPC_UNAUTHENTICATED":
+            return withWire(new RPCAuthenticationError(message, procedure), code, details);
+        case "RPC_FORBIDDEN":
+            return withWire(new RPCForbiddenError(message, procedure), code, details);
+        case "RPC_RATE_LIMITED":
+            return withWire(new RPCRateLimitedError(message, retryAfterOf(details), procedure), code, details);
+        default:
+            return withWire(new RPCError(message, { procedureName: procedure }), code, details);
+    }
+}
+function retryAfterOf(details) {
+    if (typeof details !== "object" || details === null) {
+        return undefined;
+    }
+    const value = details.retryAfter;
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? value
+        : undefined;
+}
+function withMessage(error, message) {
+    Object.defineProperty(error, "message", {
+        value: message,
+        enumerable: false,
+        configurable: true,
+        writable: true,
+    });
+    return error;
+}
+function withWire(error, code, details) {
+    Object.defineProperty(error, "code", {
+        value: code ?? error.code,
+        enumerable: true,
+        configurable: true,
+    });
+    if (details !== undefined) {
+        Object.defineProperty(error, "details", {
+            value: details,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    return error;
+}
+//# sourceMappingURL=rpcWireError.helper.js.map

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

@@ -1,2 +1,7 @@
-export { DEFAULT_RPC_TIMEOUT, MAX_RPC_PAYLOAD_SIZE, MAX_PENDING_REQUESTS, MAX_MIDDLEWARE, MAX_PROCEDURES, MAX_PROCEDURE_NAME_LENGTH, MAX_TIMER_DELAY, PROCEDURE_NAME_PATTERN, INTERNAL_ERROR_MESSAGE, } from "./rpcConstants.core.js";
+/**
+ * Limits and defaults shared across the RPC package: timeouts, payload
+ * and frame sizes, procedure-name rules, and the fixed internal-error
+ * message returned to remote callers.
+ */
+export { DEFAULT_RPC_TIMEOUT, MAX_RPC_PAYLOAD_SIZE, MAX_RPC_REQUEST_ID_LENGTH, MAX_PENDING_REQUESTS, MAX_MIDDLEWARE, MAX_PROCEDURES, MAX_PROCEDURE_NAME_LENGTH, MAX_TIMER_DELAY, PROCEDURE_NAME_PATTERN, INTERNAL_ERROR_MESSAGE, DEFAULT_RPC_HTTP_MAX_BODY_BYTES, MAX_RPC_FRAME_DEPTH, } from "./rpcConstants.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/rpc/constants/index.js

@@ -1,2 +1,7 @@
-export { DEFAULT_RPC_TIMEOUT, MAX_RPC_PAYLOAD_SIZE, MAX_PENDING_REQUESTS, MAX_MIDDLEWARE, MAX_PROCEDURES, MAX_PROCEDURE_NAME_LENGTH, MAX_TIMER_DELAY, PROCEDURE_NAME_PATTERN, INTERNAL_ERROR_MESSAGE, } from "./rpcConstants.core.js";
+/**
+ * Limits and defaults shared across the RPC package: timeouts, payload
+ * and frame sizes, procedure-name rules, and the fixed internal-error
+ * message returned to remote callers.
+ */
+export { DEFAULT_RPC_TIMEOUT, MAX_RPC_PAYLOAD_SIZE, MAX_RPC_REQUEST_ID_LENGTH, MAX_PENDING_REQUESTS, MAX_MIDDLEWARE, MAX_PROCEDURES, MAX_PROCEDURE_NAME_LENGTH, MAX_TIMER_DELAY, PROCEDURE_NAME_PATTERN, INTERNAL_ERROR_MESSAGE, DEFAULT_RPC_HTTP_MAX_BODY_BYTES, MAX_RPC_FRAME_DEPTH, } from "./rpcConstants.core.js";
 //# sourceMappingURL=index.js.map

package/dist/rpc/constants/rpcConstants.core.d.ts

@@ -11,6 +11,15 @@ export declare const DEFAULT_RPC_TIMEOUT = 30000;
  * Maximum payload size for RPC messages (1MB).
  */
 export declare const MAX_RPC_PAYLOAD_SIZE: number;
+/**
+ * Maximum length of a request id accepted from a peer.
+ *
+ * The id is echoed verbatim into every success and error response, so an
+ * unbounded id is a reflection amplifier: the server writes back whatever
+ * the caller sent, on both paths. 128 characters holds a UUID, a ULID or a
+ * W3C trace id with room to spare.
+ */
+export declare const MAX_RPC_REQUEST_ID_LENGTH = 128;
 /**
  * Maximum number of pending requests allowed in the client.
  */
@@ -45,4 +54,15 @@ export declare const MAX_TIMER_DELAY = 2147483647;
  * request id instead.
  */
 export declare const INTERNAL_ERROR_MESSAGE = "The server encountered an internal error while handling this request.";
+/**
+ * Default limit, in bytes, on an HTTP request or response body carrying
+ * one RPC frame: the payload limit plus headroom for the frame envelope
+ * (`id`, `procedure`, `metadata`, `timestamp`).
+ */
+export declare const DEFAULT_RPC_HTTP_MAX_BODY_BYTES: number;
+/**
+ * Maximum nesting depth accepted when decoding a frame from the wire.
+ * Bounds the work a hostile peer can force with deeply nested JSON.
+ */
+export declare const MAX_RPC_FRAME_DEPTH = 128;
 //# sourceMappingURL=rpcConstants.core.d.ts.map

package/dist/rpc/constants/rpcConstants.core.js

@@ -11,6 +11,15 @@ export const DEFAULT_RPC_TIMEOUT = 30_000;
  * Maximum payload size for RPC messages (1MB).
  */
 export const MAX_RPC_PAYLOAD_SIZE = 1024 * 1024;
+/**
+ * Maximum length of a request id accepted from a peer.
+ *
+ * The id is echoed verbatim into every success and error response, so an
+ * unbounded id is a reflection amplifier: the server writes back whatever
+ * the caller sent, on both paths. 128 characters holds a UUID, a ULID or a
+ * W3C trace id with room to spare.
+ */
+export const MAX_RPC_REQUEST_ID_LENGTH = 128;
 /**
  * Maximum number of pending requests allowed in the client.
  */
@@ -45,4 +54,15 @@ export const MAX_TIMER_DELAY = 2_147_483_647;
  * request id instead.
  */
 export const INTERNAL_ERROR_MESSAGE = "The server encountered an internal error while handling this request.";
+/**
+ * Default limit, in bytes, on an HTTP request or response body carrying
+ * one RPC frame: the payload limit plus headroom for the frame envelope
+ * (`id`, `procedure`, `metadata`, `timestamp`).
+ */
+export const DEFAULT_RPC_HTTP_MAX_BODY_BYTES = MAX_RPC_PAYLOAD_SIZE + 64 * 1024;
+/**
+ * Maximum nesting depth accepted when decoding a frame from the wire.
+ * Bounds the work a hostile peer can force with deeply nested JSON.
+ */
+export const MAX_RPC_FRAME_DEPTH = 128;
 //# sourceMappingURL=rpcConstants.core.js.map

package/dist/rpc/context/rpcContext.type.d.ts

@@ -15,6 +15,13 @@ export type RPCAuthContext = Readonly<Record<string, unknown>>;
 export interface RPCContextOptions {
     /** Trusted, transport-derived identity. See {@link RPCAuthContext}. */
     readonly auth?: RPCAuthContext;
+    /**
+     * Aborts when the caller is gone — the HTTP client disconnected, the
+     * in-process caller cancelled. The dispatch then fails with
+     * `RPC_CANCELLED` and the handler's `context.signal` aborts, so the
+     * server stops work nobody will read.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * Context passed through the RPC execution pipeline.