@zudojs/rpc 0.1.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @zudojs/rpc
 
-Type-safe RPC — define procedures, apply middleware, dispatch calls, and serve over HTTP or your own transport.
+Type-safe RPC — define procedures, apply middleware, dispatch calls, and serve them over your own transport.
 
 ## When to use
 
@@ -8,9 +8,14 @@ Import this when you need:
 
 - a typed RPC layer between services (gateway ↔ microservice, frontend ↔ backend)
 - procedure-level middleware (auth, tracing, rate limit)
-- a dispatcher that picks the right transport
+- a server that validates frames and maps every failure to a wire code
 - structured RPC errors
 
+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.
+
 For request/response inside one process, prefer `@zudojs/api`.
 
 ## Installation
@@ -24,8 +29,11 @@ npm install @zudojs/rpc
 ```typescript
 import {
   createRPCProcedure,
-  RPCDispatcher,
+  createRPCRequest,
   RPCServer,
+  RPCClient,
+  RPCDispatcher,
+  RPCProcedureRegistry,
   RPCMiddlewareStack,
   createRPCContext,
   type RPCContext,
@@ -33,24 +41,108 @@ import {
   type RPCProcedure,
   type RPCRequest,
   type RPCResponse,
+  type RPCTransport,
   type RPCErrorOptions,
 } from "@zudojs/rpc";
 ```
 
 ## Usage
 
+A procedure is `createRPCProcedure(name, handler, options?)`. Names are
+dot-separated identifiers (`"math.sum"`); the handler is positional,
+`(input, context)`; `options.input` / `options.output` are `@zudojs/schema`
+schemas (anything with `safeParse`) the payload and result are checked
+against.
+
 ```typescript
-import { createRPCProcedure, RPCDispatcher } from "@zudojs/rpc";
+import { createRPCProcedure, createRPCRequest, RPCServer } from "@zudojs/rpc";
+import { schema } from "@zudojs/schema";
 
-const sum = createRPCProcedure({
-  name: "sum",
-  input: { a: "number", b: "number" },
-  handler: ({ input }) => input.a + input.b,
-});
+const sum = createRPCProcedure(
+  "math.sum",
+  async (input: { a: number; b: number }) => input.a + input.b,
+  { input: schema.object({ a: schema.number(), b: schema.number() }) },
+);
+
+const server = new RPCServer();
+server.register(sum);
+
+const response = await server.handle(
+  createRPCRequest({ id: "req-1", procedure: "math.sum", payload: { a: 1, b: 2 } }),
+);
+// { id: "req-1", success: true, result: 3 }
+```
 
-const dispatcher = new RPCDispatcher();
-dispatcher.register(sum);
-const result = await dispatcher.call("sum", { a: 1, b: 2 });
+`handle` never throws for a bad request: a malformed frame, an unknown
+procedure, a payload the input schema rejects, a timeout or a handler error
+each come back as `{ success: false, error: { code, message, details? } }`.
+The frame's `metadata` is optional.
+
+### Calling through a transport
+
+`RPCClient` needs 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:
+
+```typescript
+import { RPCClient, type RPCTransport } from "@zudojs/rpc";
+
+const transport: RPCTransport = { send: (request) => server.handle(request) };
+const client = new RPCClient(transport, { timeout: 5_000 });
+
+const total = await client.call<{ a: number; b: number }, number>("math.sum", { a: 1, b: 2 });
+// 3
+```
+
+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`).
+
+### Middleware
+
+```typescript
+import { RPCMiddlewareStack, RPCAuthenticationError } from "@zudojs/rpc";
+
+const stack = new RPCMiddlewareStack([
+  async (context, next) => {
+    if (context.metadata.userId === undefined) {
+      throw new RPCAuthenticationError("Sign in first.");
+    }
+    return next();
+  },
+]);
+
+const server = new RPCServer(undefined, stack);
+```
+
+Each middleware may call `next()` once. Input validation runs before the
+stack, so middleware sees a payload the procedure's schema has accepted.
+
+## Errors
+
+Every error class from `@zudojs/errors`' RPC family is re-exported. The
+server maps them to wire codes (`RPC_PROCEDURE_NOT_FOUND`,
+`RPC_VALIDATION_ERROR`, `RPC_UNAUTHENTICATED`, `RPC_FORBIDDEN`,
+`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
+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
+caller's.
+
+```typescript
+const server = new RPCServer(undefined, undefined, {
+  limits: { maxPayloadBytes: 256 * 1024 },
+  dispatch: { defaultTimeout: 10_000 },
+  onInternalError: (error, requestId) => logger.error({ requestId, error }),
+});
 ```
 
 ## License

package/dist/index.d.ts

@@ -21,7 +21,9 @@
  */
 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, PROCEDURE_NAME_PATTERN, } from "./rpc/constants/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 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";
 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 type { RPCHandler, RPCProcedure, RPCProcedureOptions, } from "./rpc/procedure/index.js";
@@ -31,13 +33,15 @@ export type { RPCContext } from "./rpc/context/index.js";
 export { createRPCContext } from "./rpc/context/index.js";
 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 } from "./rpc/client/index.js";
+export type { RPCCallOptions, RPCClientOptions } from "./rpc/client/index.js";
 export { RPCClient } from "./rpc/client/index.js";
-export { createTimeout, withTimeout, getRemainingTime, isDeadlineExceeded, throwIfDeadlineExceeded, createCancellableSignal, cancelSignal, DEFAULT_RETRY_OPTIONS, calculateRetryDelay, retry, } from "./rpc/reliability/index.js";
-export type { RPCBackoff, RPCRetryOptions } from "./rpc/reliability/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";
 export { createNoopRPCInterceptor } from "./rpc/interceptor/index.js";
 export type { RPCStreamingHandler, RPCStreamingProcedure, } from "./rpc/streaming/index.js";

package/dist/index.js

@@ -21,19 +21,18 @@
  */
 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, PROCEDURE_NAME_PATTERN, } from "./rpc/constants/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 { 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";
 export { RPCProcedureRegistry, RPCProcedureRouter, } from "./rpc/procedure/index.js";
 export { createRPCContext } from "./rpc/context/index.js";
 export { RPCMiddlewareStack } from "./rpc/middleware/index.js";
-// Dispatcher
 export { RPCDispatcher } from "./rpc/dispatcher/index.js";
-// Server
 export { RPCServer } from "./rpc/server/index.js";
 export { RPCClient } from "./rpc/client/index.js";
 // Reliability
-export { createTimeout, withTimeout, getRemainingTime, isDeadlineExceeded, throwIfDeadlineExceeded, createCancellableSignal, cancelSignal, DEFAULT_RETRY_OPTIONS, calculateRetryDelay, retry, } from "./rpc/reliability/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 { createNoopRPCInterceptor } from "./rpc/interceptor/index.js";
 export { createRPCStreamingProcedure } from "./rpc/streaming/index.js";
 //# sourceMappingURL=index.js.map

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

@@ -1,3 +1,3 @@
-export type { RPCCallOptions } from "./rpcClient.core.js";
+export type { RPCCallOptions, RPCClientOptions } from "./rpcClient.core.js";
 export { RPCClient } from "./rpcClient.core.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -4,23 +4,77 @@ import type { RPCTransport } from "../transport/rpcTransport.type.js";
  */
 export interface RPCCallOptions {
     readonly timeout?: number;
+    /** Cancels the call. An already-aborted signal fails immediately. */
     readonly signal?: AbortSignal;
     readonly metadata?: Record<string, string | number | boolean | undefined>;
 }
+/**
+ * Options for constructing an RPC client.
+ */
+export interface RPCClientOptions {
+    /** Default timeout for calls that do not specify one. */
+    readonly timeout?: number;
+    /**
+     * Maximum number of calls in flight at once. Defaults to
+     * {@link MAX_PENDING_REQUESTS}. Additional calls fail fast rather than
+     * queueing without bound.
+     */
+    readonly maxPending?: number;
+}
 /**
  * RPC client for invoking remote procedures.
+ *
+ * Every call is tracked while it is genuinely in flight and removed the
+ * moment it settles, so the concurrency limit reflects real in-flight
+ * work rather than accumulating entries from calls that already
+ * succeeded.
  */
 export declare class RPCClient {
     private readonly transport;
+    private readonly options;
     private readonly pending;
-    constructor(transport: RPCTransport);
+    private closed;
+    constructor(transport: RPCTransport, options?: RPCClientOptions);
+    /**
+     * Number of calls currently in flight.
+     */
+    get pendingCount(): number;
     /**
      * Calls a remote procedure.
      */
     call<TInput = unknown, TOutput = unknown>(procedure: string, input: TInput, options?: RPCCallOptions): Promise<TOutput>;
     /**
-     * Creates a timeout promise for an RPC call.
+     * Cancels every in-flight call and stops accepting new ones.
+     */
+    close(reason?: string): Promise<void>;
+    /**
+     * Describes the calls currently in flight, for diagnostics.
+     */
+    inspectPending(): readonly {
+        procedure: string;
+        elapsedMs: number;
+    }[];
+    /**
+     * A promise that rejects when the signal aborts.
+     */
+    private abortPromise;
+    private abortReason;
+    private cancellationError;
+    /**
+     * Normalises an abort reason into an `RPCCancelledError`.
+     *
+     * A bare `controller.abort()` yields a `DOMException`, so callers that
+     * branch on error type would never see a cancellation. The original
+     * reason is preserved as `cause`; a reason that is already an RPC
+     * 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 createTimeout;
+    private toError;
 }
 //# sourceMappingURL=rpcClient.core.d.ts.map

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

@@ -1,60 +1,217 @@
+import { randomUUID } from "node:crypto";
 import { createRPCRequest } from "../types/rpcRequest.type.js";
-import { RPCProcedureNotFoundError } from "../errors/rpc.errors.js";
+import { isRPCError, RPCCancelledError, RPCError, RPCTimeoutError, RPCUnavailableError, } from "../errors/rpc.errors.js";
 import { DEFAULT_RPC_TIMEOUT, MAX_PENDING_REQUESTS, } from "../constants/rpcConstants.core.js";
+import { createTimeout } from "../reliability/timeout/rpcTimeout.helper.js";
 /**
  * RPC client for invoking remote procedures.
+ *
+ * Every call is tracked while it is genuinely in flight and removed the
+ * moment it settles, so the concurrency limit reflects real in-flight
+ * work rather than accumulating entries from calls that already
+ * succeeded.
  */
 export class RPCClient {
     transport;
+    options;
     pending = new Map();
-    constructor(transport) {
+    closed = false;
+    constructor(transport, options = {}) {
         this.transport = transport;
+        this.options = options;
+    }
+    /**
+     * Number of calls currently in flight.
+     */
+    get pendingCount() {
+        return this.pending.size;
     }
     /**
      * Calls a remote procedure.
      */
     async call(procedure, input, options = {}) {
-        const id = crypto.randomUUID();
-        const timeout = options.timeout ?? DEFAULT_RPC_TIMEOUT;
-        if (this.pending.size >= MAX_PENDING_REQUESTS) {
-            throw new Error("Too many pending RPC requests.");
+        if (this.closed) {
+            throw new RPCUnavailableError("RPC client has been closed.", procedure);
+        }
+        const maxPending = this.options.maxPending ?? MAX_PENDING_REQUESTS;
+        if (this.pending.size >= maxPending) {
+            throw new RPCUnavailableError(`Too many RPC requests in flight (${this.pending.size}/${maxPending}).`, procedure);
         }
-        const response = await Promise.race([
-            this.transport.send(createRPCRequest({
+        if (options.signal?.aborted) {
+            throw this.cancellationError(options.signal, procedure);
+        }
+        const id = randomUUID();
+        const timeoutMs = options.timeout ?? this.options.timeout ?? DEFAULT_RPC_TIMEOUT;
+        const controller = new AbortController();
+        const timeout = timeoutMs > 0 ? createTimeout(timeoutMs, procedure) : undefined;
+        const onCallerAbort = () => {
+            controller.abort(this.cancellationError(options.signal, procedure));
+        };
+        options.signal?.addEventListener("abort", onCallerAbort, { once: true });
+        this.pending.set(id, {
+            procedure,
+            startedAt: Date.now(),
+            cancel: (reason) => {
+                if (!controller.signal.aborted) {
+                    controller.abort(reason);
+                }
+            },
+        });
+        try {
+            const request = createRPCRequest({
                 id,
                 procedure,
                 payload: input,
                 metadata: options.metadata,
-            })),
-            this.createTimeout(id, timeout),
-        ]);
-        if (!response.success) {
-            const error = new Error(response.error?.message ?? "RPC call failed.");
-            error.code = response.error?.code;
-            throw error;
+            });
+            // The transport is told the deadline as well as given the signal:
+            // `RPCTransportRequestOptions.timeout` exists so a transport can set
+            // its own socket or request timeout, and it was never populated.
+            const races = [
+                this.transport.send(request, {
+                    signal: controller.signal,
+                    ...(timeoutMs > 0 ? { timeout: timeoutMs } : {}),
+                }),
+                this.abortPromise(controller.signal, procedure),
+            ];
+            if (timeout) {
+                races.push(timeout.promise.catch((error) => {
+                    if (!controller.signal.aborted) {
+                        controller.abort(error);
+                    }
+                    throw error;
+                }));
+            }
+            const response = await Promise.race(races);
+            if (!response.success) {
+                throw this.toError(response, procedure);
+            }
+            return response.result;
+        }
+        finally {
+            // Removing the entry here — rather than leaving it for a timer to
+            // reap — is what keeps `pendingCount` equal to the number of calls
+            // actually in flight.
+            this.pending.delete(id);
+            timeout?.cancel();
+            options.signal?.removeEventListener("abort", onCallerAbort);
+            if (!controller.signal.aborted) {
+                controller.abort(new RPCCancelledError("Call settled.", procedure));
+            }
         }
-        return response.result;
     }
     /**
-     * Creates a timeout promise for an RPC call.
+     * Cancels every in-flight call and stops accepting new ones.
+     */
+    async close(reason) {
+        this.closed = true;
+        const error = new RPCCancelledError(reason ?? "RPC client closed.");
+        for (const call of this.pending.values()) {
+            call.cancel(error);
+        }
+        this.pending.clear();
+        await this.transport.close?.();
+    }
+    /**
+     * Describes the calls currently in flight, for diagnostics.
+     */
+    inspectPending() {
+        const now = Date.now();
+        return [...this.pending.values()].map((call) => ({
+            procedure: call.procedure,
+            elapsedMs: now - call.startedAt,
+        }));
+    }
+    /**
+     * A promise that rejects when the signal aborts.
      */
-    createTimeout(id, timeout) {
-        return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                this.pending.delete(id);
-                reject(new Error(`RPC call timed out after ${timeout}ms.`));
-            }, timeout);
-            this.pending.set(id, {
-                resolve: (response) => {
-                    clearTimeout(timer);
-                    resolve(response);
-                },
-                reject: (error) => {
-                    clearTimeout(timer);
-                    reject(error);
-                },
+    abortPromise(signal, procedure) {
+        return new Promise((_, reject) => {
+            if (signal.aborted) {
+                reject(this.abortReason(signal, procedure));
+                return;
+            }
+            signal.addEventListener("abort", () => reject(this.abortReason(signal, procedure)), { once: true });
+        });
+    }
+    abortReason(signal, procedure) {
+        return this.toCancellation(signal.reason, procedure);
+    }
+    cancellationError(signal, procedure) {
+        return this.toCancellation(signal?.reason, procedure);
+    }
+    /**
+     * Normalises an abort reason into an `RPCCancelledError`.
+     *
+     * A bare `controller.abort()` yields a `DOMException`, so callers that
+     * branch on error type would never see a cancellation. The original
+     * reason is preserved as `cause`; a reason that is already an RPC
+     * error is passed through untouched.
+     */
+    toCancellation(reason, procedure) {
+        if (isRPCError(reason)) {
+            return reason;
+        }
+        const message = reason instanceof Error && reason.name !== "AbortError"
+            ? reason.message
+            : "Call cancelled by caller.";
+        const error = new RPCCancelledError(message, procedure);
+        if (reason !== undefined) {
+            Object.defineProperty(error, "cause", {
+                value: reason,
+                enumerable: false,
+                configurable: true,
+                writable: true,
             });
+        }
+        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;
+        }
+        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,
+            });
+        }
+        return error;
     }
 }
 //# sourceMappingURL=rpcClient.core.js.map

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

@@ -1,2 +1,2 @@
-export { DEFAULT_RPC_TIMEOUT, MAX_RPC_PAYLOAD_SIZE, MAX_PENDING_REQUESTS, MAX_MIDDLEWARE, MAX_PROCEDURES, PROCEDURE_NAME_PATTERN, } from "./rpcConstants.core.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 "./rpcConstants.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/rpc/constants/index.js

@@ -1,2 +1,2 @@
-export { DEFAULT_RPC_TIMEOUT, MAX_RPC_PAYLOAD_SIZE, MAX_PENDING_REQUESTS, MAX_MIDDLEWARE, MAX_PROCEDURES, PROCEDURE_NAME_PATTERN, } from "./rpcConstants.core.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 "./rpcConstants.core.js";
 //# sourceMappingURL=index.js.map

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

@@ -27,4 +27,22 @@ export declare const MAX_PROCEDURES = 4096;
  * Procedure name pattern: dot-separated lowercase identifiers.
  */
 export declare const PROCEDURE_NAME_PATTERN: RegExp;
+/**
+ * Maximum length of a procedure name, checked before the pattern so a
+ * pathological name cannot drive regex backtracking.
+ */
+export declare const MAX_PROCEDURE_NAME_LENGTH = 256;
+/**
+ * Largest delay Node's timer subsystem accepts. A larger delay overflows
+ * a signed 32-bit integer and is silently clamped to `1`.
+ */
+export declare const MAX_TIMER_DELAY = 2147483647;
+/**
+ * Message returned to callers for an unexpected server-side failure.
+ *
+ * Internal exception text may name hosts, paths, credentials or queries,
+ * so it is logged rather than returned. Callers correlate with the
+ * request id instead.
+ */
+export declare const INTERNAL_ERROR_MESSAGE = "The server encountered an internal error while handling this request.";
 //# sourceMappingURL=rpcConstants.core.d.ts.map

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

@@ -27,4 +27,22 @@ export const MAX_PROCEDURES = 4096;
  * Procedure name pattern: dot-separated lowercase identifiers.
  */
 export const PROCEDURE_NAME_PATTERN = /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$/;
+/**
+ * Maximum length of a procedure name, checked before the pattern so a
+ * pathological name cannot drive regex backtracking.
+ */
+export const MAX_PROCEDURE_NAME_LENGTH = 256;
+/**
+ * Largest delay Node's timer subsystem accepts. A larger delay overflows
+ * a signed 32-bit integer and is silently clamped to `1`.
+ */
+export const MAX_TIMER_DELAY = 2_147_483_647;
+/**
+ * Message returned to callers for an unexpected server-side failure.
+ *
+ * Internal exception text may name hosts, paths, credentials or queries,
+ * so it is logged rather than returned. Callers correlate with the
+ * request id instead.
+ */
+export const INTERNAL_ERROR_MESSAGE = "The server encountered an internal error while handling this request.";
 //# sourceMappingURL=rpcConstants.core.js.map

package/dist/rpc/context/rpcContext.type.js

@@ -5,7 +5,9 @@ export function createRPCContext(request, signal) {
     const state = new Map();
     const context = {
         request,
-        metadata: request.metadata,
+        // A frame decoded from JSON may omit `metadata`; middleware reads
+        // `context.metadata.userId` and the like without guarding.
+        metadata: request.metadata ?? {},
         signal,
         state,
         get(key) {

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

@@ -1,2 +1,3 @@
+export type { RPCDispatcherOptions } from "./rpcDispatcher.core.js";
 export { RPCDispatcher } from "./rpcDispatcher.core.js";
 //# sourceMappingURL=index.d.ts.map