@zudojs/rpc 0.0.1 → 1.0.0

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

@@ -3,15 +3,38 @@
  *
  * Retry utilities for RPC operations.
  */
+import { RPCCancelledError } from "../../errors/rpc.errors.js";
+import { MAX_TIMER_DELAY } from "../../constants/rpcConstants.core.js";
 /**
  * Default retry options.
  */
-export const DEFAULT_RETRY_OPTIONS = {
+export const DEFAULT_RETRY_OPTIONS = Object.freeze({
     attempts: 1,
     delay: 0,
-};
+});
+/**
+ * Applies the configured jitter strategy to a delay.
+ */
+function applyJitter(delay, jitter) {
+    if (delay <= 0) {
+        return 0;
+    }
+    switch (jitter) {
+        case "full":
+            return Math.round(Math.random() * delay);
+        case "equal":
+            return Math.round(delay / 2 + Math.random() * (delay / 2));
+        default:
+            return delay;
+    }
+}
 /**
  * Calculates the delay for a retry attempt.
+ *
+ * The result is finite, non-negative, and no greater than a timer can
+ * represent. Jitter defaults to `"none"` here so the calculation stays
+ * predictable for callers that compose it; {@link retry} opts into
+ * `"full"` jitter by default.
  */
 export function calculateRetryDelay(attempt, options) {
     const backoff = options.backoff ?? "fixed";
@@ -21,30 +44,79 @@ export function calculateRetryDelay(attempt, options) {
         delay = options.delay * attempt;
     }
     else if (backoff === "exponential") {
-        delay = options.delay * 2 ** (attempt - 1);
+        delay = options.delay * 2 ** Math.max(0, attempt - 1);
+    }
+    if (!Number.isFinite(delay) || delay < 0) {
+        delay = 0;
+    }
+    const capped = Math.min(delay, maxDelay, MAX_TIMER_DELAY);
+    return Math.min(applyJitter(capped, options.jitter ?? "none"), MAX_TIMER_DELAY);
+}
+/**
+ * Sleeps for a duration, rejecting early if the signal aborts.
+ */
+function sleep(ms, signal) {
+    if (ms <= 0) {
+        return Promise.resolve();
     }
-    return Math.min(delay, maxDelay);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        timer.unref?.();
+        function onAbort() {
+            clearTimeout(timer);
+            reject(signal?.reason instanceof Error
+                ? signal.reason
+                : new RPCCancelledError("Retry cancelled."));
+        }
+        if (signal) {
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+    });
 }
 /**
  * Retries an asynchronous operation.
+ *
+ * Jitter defaults to `"full"` so concurrent callers retrying the same
+ * failing dependency do not synchronise into a retry wave.
  */
 export async function retry(operation, options) {
-    const attempts = Math.max(1, options.attempts);
+    const attempts = Math.max(1, Math.floor(options.attempts));
+    const jittered = {
+        ...options,
+        jitter: options.jitter ?? "full",
+    };
+    let lastError;
     for (let attempt = 0; attempt < attempts; attempt += 1) {
+        if (options.signal?.aborted) {
+            throw options.signal.reason instanceof Error
+                ? options.signal.reason
+                : new RPCCancelledError("Retry cancelled.");
+        }
         try {
             return await operation();
         }
         catch (error) {
+            lastError = error;
             if (attempt >= attempts - 1) {
                 throw error;
             }
             if (options.retryIf && !options.retryIf(error)) {
                 throw error;
             }
-            const delay = calculateRetryDelay(attempt + 1, options);
-            await new Promise((resolve) => setTimeout(resolve, delay));
+            const delay = calculateRetryDelay(attempt + 1, jittered);
+            options.onRetry?.(error, attempt + 1, delay);
+            await sleep(delay, options.signal);
         }
     }
-    throw new Error("Retry loop exited unexpectedly.");
+    // Unreachable while `attempts >= 1`, but throwing the last observed
+    // error beats inventing a new one if that ever changes.
+    throw lastError ?? new Error("Retry loop exited without running.");
 }
 //# sourceMappingURL=rpcRetry.helper.js.map

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

@@ -5,10 +5,26 @@
  */
 /**
  * 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.
  */
-export declare function createTimeout(duration: number): Promise<never>;
+export declare function createTimeout(duration: number, procedureName?: string): {
+    readonly promise: Promise<never>;
+    cancel(): void;
+};
 /**
  * Wraps a promise with a timeout.
+ *
+ * The timer is always cleared once the race settles, whichever side won.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, duration: number, procedureName?: string): Promise<T>;
+/**
+ * Runs an operation under a timeout, aborting it when the timeout wins.
+ *
+ * Unlike {@link withTimeout}, this gives the operation a signal so it can
+ * stop its own work rather than continuing unobserved.
  */
-export declare function withTimeout<T>(promise: Promise<T>, duration: number): Promise<T>;
+export declare function runWithTimeout<T>(operation: (signal: AbortSignal) => Promise<T>, duration: number, procedureName?: string, parentSignal?: AbortSignal): Promise<T>;
 //# sourceMappingURL=rpcTimeout.helper.d.ts.map

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

@@ -3,20 +3,84 @@
  *
  * Timeout utilities for RPC operations.
  */
+import { RPCTimeoutError } from "../../errors/rpc.errors.js";
+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.
  */
-export function createTimeout(duration) {
-    return new Promise((_, reject) => {
-        setTimeout(() => {
-            reject(new Error(`Operation timed out after ${duration}ms.`));
-        }, duration);
+export function createTimeout(duration, procedureName) {
+    const delay = Math.min(Math.max(0, duration), MAX_TIMER_DELAY);
+    let timer;
+    const promise = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new RPCTimeoutError(duration, procedureName));
+        }, delay);
+        timer.unref?.();
     });
+    return {
+        promise,
+        cancel() {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+    };
 }
 /**
  * Wraps a promise with a timeout.
+ *
+ * The timer is always cleared once the race settles, whichever side won.
+ */
+export async function withTimeout(promise, duration, procedureName) {
+    const timeout = createTimeout(duration, procedureName);
+    try {
+        return await Promise.race([promise, timeout.promise]);
+    }
+    finally {
+        timeout.cancel();
+    }
+}
+/**
+ * Runs an operation under a timeout, aborting it when the timeout wins.
+ *
+ * Unlike {@link withTimeout}, this gives the operation a signal so it can
+ * stop its own work rather than continuing unobserved.
  */
-export async function withTimeout(promise, duration) {
-    return Promise.race([promise, createTimeout(duration)]);
+export async function runWithTimeout(operation, duration, procedureName, parentSignal) {
+    const controller = new AbortController();
+    const timeout = createTimeout(duration, procedureName);
+    const onParentAbort = () => {
+        if (!controller.signal.aborted) {
+            controller.abort(parentSignal?.reason);
+        }
+    };
+    if (parentSignal) {
+        if (parentSignal.aborted) {
+            onParentAbort();
+        }
+        else {
+            parentSignal.addEventListener("abort", onParentAbort, { once: true });
+        }
+    }
+    try {
+        return await Promise.race([
+            operation(controller.signal),
+            timeout.promise.catch((error) => {
+                if (!controller.signal.aborted) {
+                    controller.abort(error);
+                }
+                throw error;
+            }),
+        ]);
+    }
+    finally {
+        timeout.cancel();
+        parentSignal?.removeEventListener("abort", onParentAbort);
+    }
 }
 //# sourceMappingURL=rpcTimeout.helper.js.map

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

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

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

@@ -3,6 +3,24 @@ import type { RPCResponse } from "../types/rpcResponse.type.js";
 import type { RPCProcedure } from "../procedure/rpcProcedure.type.js";
 import { RPCProcedureRegistry } from "../procedure/rpcProcedureRegistry.core.js";
 import { RPCMiddlewareStack } from "../middleware/rpcMiddleware.core.js";
+import type { RPCDispatcherOptions } from "../dispatcher/rpcDispatcher.core.js";
+import type { RPCRequestLimits } from "../validation/rpcValidation.core.js";
+/**
+ * Options for an RPC server.
+ */
+export interface RPCServerOptions {
+    /** Limits applied to every incoming request before dispatch. */
+    readonly limits?: RPCRequestLimits;
+    /** Dispatch behaviour: default timeout and deadline handling. */
+    readonly dispatch?: RPCDispatcherOptions;
+    /**
+     * Receives errors that produced an internal error response, together
+     * with the request id the caller was given. Internal error detail is
+     * never returned over the wire, so this is where it must be recorded
+     * for the failure to be diagnosable.
+     */
+    readonly onInternalError?: (error: unknown, requestId: string) => void;
+}
 /**
  * RPC server that receives and dispatches requests.
  */
@@ -10,18 +28,39 @@ export declare class RPCServer {
     private readonly registry;
     private readonly middleware;
     private readonly dispatcher;
-    constructor(registry?: RPCProcedureRegistry, middleware?: RPCMiddlewareStack);
+    private readonly options;
+    constructor(registry?: RPCProcedureRegistry, middleware?: RPCMiddlewareStack, options?: RPCServerOptions);
     /**
      * Registers a procedure.
+     *
+     * Generic over the procedure's input and output so a procedure built
+     * with `createRPCProcedure<TInput, TOutput>` can be registered
+     * directly. `RPCProcedure` is contravariant in `TInput` (its handler
+     * accepts that input), so a typed procedure is NOT assignable to
+     * `RPCProcedure<unknown>` and a non-generic signature would reject
+     * every typed procedure. Decoding stays a runtime concern.
      */
-    register(procedure: RPCProcedure): this;
+    register<TInput = unknown, TOutput = unknown>(procedure: RPCProcedure<TInput, TOutput>): this;
     /**
      * Handles an incoming RPC request.
+     *
+     * The frame is validated before dispatch, and every failure is mapped
+     * to a typed wire code. Unexpected errors are reported to
+     * `onInternalError` and answered with a fixed message: internal
+     * exception text can name hosts, paths, credentials or queries, and
+     * the caller is an untrusted peer.
      */
     handle(request: RPCRequest): Promise<RPCResponse>;
     /**
      * 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,7 +2,30 @@ 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 { RPCInternalError, RPCProcedureNotFoundError, RPCValidationError, } from "../errors/rpc.errors.js";
+import { isRPCError, RPCAuthenticationError, RPCCancelledError, RPCDeadlineExceededError, RPCDeserializationError, RPCForbiddenError, RPCInvalidRequestError, RPCProcedureNotFoundError, RPCRateLimitedError, RPCSerializationError, RPCTimeoutError, RPCUnavailableError, RPCValidationError, } from "../errors/rpc.errors.js";
+import { INTERNAL_ERROR_MESSAGE } 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"],
+    [RPCSerializationError, "RPC_SERIALIZATION_ERROR"],
+    [RPCDeserializationError, "RPC_DESERIALIZATION_ERROR"],
+];
 /**
  * RPC server that receives and dispatches requests.
  */
@@ -10,13 +33,22 @@ export class RPCServer {
     registry;
     middleware;
     dispatcher;
-    constructor(registry, middleware) {
+    options;
+    constructor(registry, middleware, options = {}) {
         this.registry = registry ?? new RPCProcedureRegistry();
         this.middleware = middleware ?? new RPCMiddlewareStack();
-        this.dispatcher = new RPCDispatcher(this.registry, this.middleware);
+        this.options = options;
+        this.dispatcher = new RPCDispatcher(this.registry, this.middleware, options.dispatch ?? {});
     }
     /**
      * Registers a procedure.
+     *
+     * Generic over the procedure's input and output so a procedure built
+     * with `createRPCProcedure<TInput, TOutput>` can be registered
+     * directly. `RPCProcedure` is contravariant in `TInput` (its handler
+     * accepts that input), so a typed procedure is NOT assignable to
+     * `RPCProcedure<unknown>` and a non-generic signature would reject
+     * every typed procedure. Decoding stays a runtime concern.
      */
     register(procedure) {
         this.registry.register(procedure);
@@ -24,29 +56,31 @@ export class RPCServer {
     }
     /**
      * Handles an incoming RPC request.
+     *
+     * The frame is validated before dispatch, and every failure is mapped
+     * to a typed wire code. Unexpected errors are reported to
+     * `onInternalError` and answered with a fixed message: internal
+     * exception text can name hosts, paths, credentials or queries, and
+     * the caller is an untrusted peer.
      */
     async handle(request) {
+        const requestId = typeof request?.id === "string"
+            ? request.id
+            : "";
         try {
+            assertValidRequest(request, this.options.limits);
             return await this.dispatcher.dispatch(request);
         }
         catch (error) {
-            if (error instanceof RPCProcedureNotFoundError) {
-                return createRPCErrorResponse(request.id, {
-                    code: "RPC_PROCEDURE_NOT_FOUND",
-                    message: error.message,
+            const mapped = this.mapError(error);
+            if (mapped === undefined) {
+                this.options.onInternalError?.(error, requestId);
+                return createRPCErrorResponse(requestId, {
+                    code: "RPC_INTERNAL_ERROR",
+                    message: INTERNAL_ERROR_MESSAGE,
                 });
             }
-            if (error instanceof RPCValidationError) {
-                return createRPCErrorResponse(request.id, {
-                    code: "RPC_VALIDATION_ERROR",
-                    message: error.message,
-                    details: error.issues,
-                });
-            }
-            return createRPCErrorResponse(request.id, {
-                code: "RPC_INTERNAL_ERROR",
-                message: error instanceof Error ? error.message : "Unknown error",
-            });
+            return createRPCErrorResponse(requestId, mapped);
         }
     }
     /**
@@ -55,5 +89,35 @@ 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) {
+        for (const [type, code] of ERROR_CODES) {
+            if (error instanceof type) {
+                const payload = {
+                    code,
+                    message: error.message,
+                };
+                if (error instanceof RPCValidationError && error.issues !== undefined) {
+                    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.
+        if (isRPCError(error)) {
+            return { code: error.code, message: error.message };
+        }
+        return undefined;
+    }
 }
 //# sourceMappingURL=rpcServer.core.js.map

package/dist/rpc/streaming/rpcStreaming.type.d.ts

@@ -2,6 +2,15 @@
  * @zudojs/rpc/streaming
  *
  * Streaming types for RPC operations.
+ *
+ * @remarks
+ * These types describe a streaming contract but are **not yet
+ * dispatchable**: `RPCProcedureRegistry` and `RPCServer` accept only
+ * `RPCProcedure`, and `RPCTransport.send` resolves with a single
+ * `RPCResponse` rather than a stream. A procedure built with
+ * {@link createRPCStreamingProcedure} therefore cannot be registered or
+ * called over a transport today. Use it to shape a handler ahead of
+ * transport support; do not rely on it to serve traffic.
  */
 /**
  * A streaming RPC procedure handler.

package/dist/rpc/streaming/rpcStreaming.type.js

@@ -2,6 +2,15 @@
  * @zudojs/rpc/streaming
  *
  * Streaming types for RPC operations.
+ *
+ * @remarks
+ * These types describe a streaming contract but are **not yet
+ * dispatchable**: `RPCProcedureRegistry` and `RPCServer` accept only
+ * `RPCProcedure`, and `RPCTransport.send` resolves with a single
+ * `RPCResponse` rather than a stream. A procedure built with
+ * {@link createRPCStreamingProcedure} therefore cannot be registered or
+ * called over a transport today. Use it to shape a handler ahead of
+ * transport support; do not rely on it to serve traffic.
  */
 /**
  * Creates a streaming RPC procedure.

package/dist/rpc/transport/rpcTransport.type.d.ts

@@ -11,7 +11,15 @@ export interface RPCTransportRequestOptions {
  * Transport interface for sending and receiving RPC messages.
  */
 export interface RPCTransport {
-    send(request: RPCRequest): Promise<RPCResponse>;
+    /**
+     * Sends a request and resolves with the peer's response.
+     *
+     * `options.signal` aborts the in-flight send. A transport that ignores
+     * it still works — the client races the signal itself — but the
+     * underlying connection is only released by a transport that honours
+     * it.
+     */
+    send(request: RPCRequest, options?: RPCTransportRequestOptions): Promise<RPCResponse>;
     close?(): Promise<void>;
 }
 //# sourceMappingURL=rpcTransport.type.d.ts.map

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

@@ -0,0 +1,3 @@
+export type { RPCRequestLimits, RPCSchema } from "./rpcValidation.core.js";
+export { assertValidProcedureName, assertValidRequest, measurePayloadBytes, toValidationIssues, parseInput, parseOutput, } from "./rpcValidation.core.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/rpc/validation/index.js

@@ -0,0 +1,2 @@
+export { assertValidProcedureName, assertValidRequest, measurePayloadBytes, toValidationIssues, parseInput, parseOutput, } from "./rpcValidation.core.js";
+//# sourceMappingURL=index.js.map

package/dist/rpc/validation/rpcValidation.core.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @zudojs/rpc/validation
+ *
+ * Request-level checks applied before a payload reaches a handler.
+ *
+ * Requests arrive from an untrusted peer over a transport, so these are
+ * the first checks the server runs, not the last.
+ */
+import type { Schema, SchemaIssue } from "@zudojs/schema";
+import type { RPCRequest } from "../types/rpcRequest.type.js";
+/**
+ * Limits applied to an incoming request.
+ */
+export interface RPCRequestLimits {
+    /**
+     * Maximum encoded payload size in bytes. Defaults to
+     * {@link MAX_RPC_PAYLOAD_SIZE}. Set to `0` to skip the check when the
+     * transport already enforces a frame limit.
+     */
+    readonly maxPayloadBytes?: number;
+    /**
+     * Whether procedure names must match {@link PROCEDURE_NAME_PATTERN}.
+     * Defaults to `true`.
+     */
+    readonly enforceProcedureNamePattern?: boolean;
+}
+/**
+ * Validates a procedure name.
+ *
+ * Length is checked before the pattern so a pathological name cannot
+ * drive regex backtracking.
+ */
+export declare function assertValidProcedureName(name: unknown): asserts name is string;
+/**
+ * Measures the encoded size of a payload in bytes.
+ *
+ * Returns `undefined` for a payload that cannot be encoded, which the
+ * caller reports as an invalid request rather than passing on.
+ */
+export declare function measurePayloadBytes(payload: unknown): number | undefined;
+/**
+ * Validates the shape and size of an incoming request.
+ *
+ * @throws {RPCInvalidRequestError} when the frame is malformed or the
+ * payload exceeds the configured limit.
+ */
+export declare function assertValidRequest(request: unknown, limits?: RPCRequestLimits): asserts request is RPCRequest;
+/**
+ * Converts schema issues into metadata safe to return to a caller.
+ *
+ * Only the path, code and message travel; the received input is dropped
+ * so a validation response cannot echo back data the caller sent.
+ */
+export declare function toValidationIssues(issues: readonly SchemaIssue[]): readonly {
+    path: string;
+    code: string;
+    message: string;
+}[];
+/**
+ * The part of a `@zudojs/schema` Schema this package depends on.
+ *
+ * Structural so any schema-like validator can be supplied, and so the
+ * dependency stays to the parse contract rather than the class.
+ */
+export type RPCSchema<TOutput = unknown> = Pick<Schema<TOutput, never>, "safeParse">;
+/**
+ * Parses caller input against a schema.
+ *
+ * @throws {RPCValidationError} carrying the issues, which are safe to
+ * return: they describe the caller's own input.
+ */
+export declare function parseInput<T>(schema: RPCSchema<T>, value: unknown, procedureName: string): T;
+/**
+ * Parses a handler's result against its output schema.
+ *
+ * An invalid output is a server defect rather than a caller mistake, so
+ * the issues describe internal shape and stay server-side: the thrown
+ * error carries no issue detail.
+ */
+export declare function parseOutput<T>(schema: RPCSchema<T>, value: unknown, procedureName: string): T;
+//# sourceMappingURL=rpcValidation.core.d.ts.map