@zudojs/rpc 1.4.2 → 1.5.0

package/README.md

@@ -206,6 +206,14 @@ 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.
 
+`retry(operation, { attempts, delay, backoff, jitter, retryIf, signal })`
+counts **calls**, not retries: `attempts: 3` runs the operation up to three
+times (one call plus two retries) and `attempts: 1` never retries. This is
+the opposite of `@zudojs/lifecycle`, whose `attempts` counts the retries after
+the first call. `delay` is the base backoff in milliseconds (`"fixed"` by
+default; `"linear"` and `"exponential"` scale it per attempt, capped by
+`maxDelay`), and `jitter` defaults to `"full"`.
+
 ### Middleware and trusted identity
 
 Everything in a frame, `metadata` included, is written by the caller: any
@@ -274,6 +282,20 @@ generic message. To send a custom code, build the error with `expose: true`. A h
 `output` schema is treated the same way: it is the server's fault, not the
 caller's.
 
+A failure of something the handler *called* is reported as
+`RPC_UNAVAILABLE`, not as an internal error and not as this procedure's own
+timeout: an `RPCTransportError`, or an `RPCTimeoutError` naming another
+procedure, thrown inside a handler or middleware — what an `RPCClient`
+raises when a downstream service cannot be reached or does not answer — is
+wrapped in an `RPCUnavailableError` (the original as `cause`) and answered
+with `{ code: "RPC_UNAVAILABLE", message: UNAVAILABLE_ERROR_MESSAGE }`, so
+the caller can retry while the downstream error's own text stays out of the
+response; the wrapped error is handed to `onInternalError` for logging. A
+timeout about the procedure itself still goes out as `RPC_TIMEOUT`: the
+dispatcher's own (including when a cooperative handler rethrows
+`context.signal.reason`) and one a handler throws under its own procedure
+name.
+
 ```typescript
 const server = new RPCServer(undefined, undefined, {
   limits: { maxPayloadBytes: 256 * 1024, maxRequestIdLength: 128 },

package/dist/index.d.ts

@@ -27,7 +27,7 @@
  */
 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_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 { 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, UNAVAILABLE_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";
@@ -50,4 +50,3 @@ export type { RPCInterceptor } from "./rpc/interceptor/index.js";
 export { createNoopRPCInterceptor } from "./rpc/interceptor/index.js";
 export type { RPCStreamingHandler, RPCStreamingProcedure, } from "./rpc/streaming/index.js";
 export { createRPCStreamingProcedure } from "./rpc/streaming/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -27,7 +27,7 @@
  */
 export { createRPCMetadata, createRPCRequest, createRPCResponse, createRPCErrorResponse, } from "./rpc/types/index.js";
 // Constants
-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 { 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, UNAVAILABLE_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";
@@ -44,4 +44,3 @@ 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 { createNoopRPCInterceptor } from "./rpc/interceptor/index.js";
 export { createRPCStreamingProcedure } from "./rpc/streaming/index.js";
-//# sourceMappingURL=index.js.map

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

@@ -5,4 +5,3 @@
 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

@@ -4,4 +4,3 @@
  */
 export { RPCClient } from "./rpcClient.core.js";
 export { rpcErrorFromWire } from "./rpcWireError.helper.js";
-//# sourceMappingURL=index.js.map

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

@@ -76,4 +76,3 @@ export declare class RPCClient {
      */
     private toCancellation;
 }
-//# sourceMappingURL=rpcClient.core.d.ts.map

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

@@ -200,4 +200,3 @@ function withWireCode(error) {
     }
     return error;
 }
-//# sourceMappingURL=rpcClient.core.js.map

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

@@ -10,4 +10,3 @@ import { RPCError } from "../errors/rpc.errors.js";
  * `"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

@@ -68,4 +68,3 @@ function withWire(error, code, details) {
     }
     return error;
 }
-//# sourceMappingURL=rpcWireError.helper.js.map

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

@@ -3,5 +3,4 @@
  * 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
+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, UNAVAILABLE_ERROR_MESSAGE, DEFAULT_RPC_HTTP_MAX_BODY_BYTES, MAX_RPC_FRAME_DEPTH, } from "./rpcConstants.core.js";

package/dist/rpc/constants/index.js

@@ -3,5 +3,4 @@
  * 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
+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, UNAVAILABLE_ERROR_MESSAGE, DEFAULT_RPC_HTTP_MAX_BODY_BYTES, MAX_RPC_FRAME_DEPTH, } from "./rpcConstants.core.js";

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

@@ -54,6 +54,13 @@ 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.";
+/**
+ * Message sent with `RPC_UNAVAILABLE` when a handler failed because a
+ * service it called — over RPC or otherwise — could not be reached or
+ * timed out. The downstream error's own text (hosts, paths, timeouts) is
+ * server detail and goes to `onInternalError` instead.
+ */
+export declare const UNAVAILABLE_ERROR_MESSAGE = "A service this request depends on is temporarily unavailable.";
 /**
  * Default limit, in bytes, on an HTTP request or response body carrying
  * one RPC frame: the payload limit plus headroom for the frame envelope
@@ -65,4 +72,3 @@ export declare const DEFAULT_RPC_HTTP_MAX_BODY_BYTES: number;
  * 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

@@ -54,6 +54,13 @@ 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.";
+/**
+ * Message sent with `RPC_UNAVAILABLE` when a handler failed because a
+ * service it called — over RPC or otherwise — could not be reached or
+ * timed out. The downstream error's own text (hosts, paths, timeouts) is
+ * server detail and goes to `onInternalError` instead.
+ */
+export const UNAVAILABLE_ERROR_MESSAGE = "A service this request depends on is temporarily unavailable.";
 /**
  * Default limit, in bytes, on an HTTP request or response body carrying
  * one RPC frame: the payload limit plus headroom for the frame envelope
@@ -65,4 +72,3 @@ export const DEFAULT_RPC_HTTP_MAX_BODY_BYTES = MAX_RPC_PAYLOAD_SIZE + 64 * 1024;
  * 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/index.d.ts

@@ -4,4 +4,3 @@
  */
 export type { RPCAuthContext, RPCContext, RPCContextOptions, } from "./rpcContext.type.js";
 export { createRPCContext } from "./rpcContext.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/rpc/context/index.js

@@ -3,4 +3,3 @@
  * metadata, the transport's trusted `auth`, and the validated `input`.
  */
 export { createRPCContext } from "./rpcContext.type.js";
-//# sourceMappingURL=index.js.map

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

@@ -61,4 +61,3 @@ export declare function bindRPCContextInput(context: RPCContext, input: unknown)
  * Creates a new RPC context.
  */
 export declare function createRPCContext(request: RPCRequest, signal: AbortSignal, options?: RPCContextOptions): RPCContext;
-//# sourceMappingURL=rpcContext.type.d.ts.map

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

@@ -32,4 +32,3 @@ export function createRPCContext(request, signal, options = {}) {
     };
     return Object.freeze(context);
 }
-//# sourceMappingURL=rpcContext.type.js.map

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

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

package/dist/rpc/dispatcher/index.js

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

package/dist/rpc/dispatcher/rpcDispatcher.core.d.ts

@@ -68,4 +68,3 @@ export declare class RPCDispatcher {
      */
     private resolveTimeout;
 }
-//# sourceMappingURL=rpcDispatcher.core.d.ts.map

package/dist/rpc/dispatcher/rpcDispatcher.core.js

@@ -5,6 +5,7 @@ import { DEFAULT_RPC_TIMEOUT } from "../constants/rpcConstants.core.js";
 import { parseInput, parseOutput } from "../validation/rpcValidation.core.js";
 import { readDeadline, throwIfDeadlineExceeded, } from "../reliability/deadline/rpcDeadline.helper.js";
 import { createTimeout } from "../reliability/timeout/rpcTimeout.helper.js";
+import { toUpstreamError } from "./rpcDispatcher.downstream.js";
 import { abortReasonToRPCError, raceAbort, } from "../reliability/cancellation/rpcAbort.helper.js";
 /**
  * Dispatches RPC requests to registered procedures.
@@ -66,9 +67,15 @@ export class RPCDispatcher {
                     ? parseInput(procedure.options.input, request.payload, request.procedure)
                     : request.payload;
                 bindRPCContextInput(context, input);
-                const result = await this.middleware.execute(context, async () => {
-                    return procedure.handler(input, context);
-                });
+                let result;
+                try {
+                    result = await this.middleware.execute(context, async () => {
+                        return procedure.handler(input, context);
+                    });
+                }
+                catch (error) {
+                    throw toUpstreamError(error, request.procedure, controller.signal);
+                }
                 return procedure.options?.output
                     ? parseOutput(procedure.options.output, result, request.procedure)
                     : result;
@@ -148,4 +155,3 @@ export class RPCDispatcher {
         return configured;
     }
 }
-//# sourceMappingURL=rpcDispatcher.core.js.map

package/dist/rpc/dispatcher/rpcDispatcher.downstream.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Translation of downstream failures raised inside a handler.
+ *
+ * A handler that calls another service over RPC gets that client's errors:
+ * an `RPCTransportError` when the peer could not be reached, an
+ * `RPCTimeoutError` when it did not answer in time. Rethrown as they are,
+ * the transport error went out as `RPC_INTERNAL_ERROR` (its code is not
+ * public vocabulary) and the timeout as `RPC_TIMEOUT` — which told the
+ * caller *this* procedure had timed out, when it was a dependency that had.
+ * Both are one condition from the caller's point of view: the service is
+ * unavailable right now, and the call may be retried.
+ */
+/**
+ * Returns the error a handler's failure should propagate as.
+ *
+ * A downstream failure becomes an `RPCUnavailableError` with the original
+ * as `cause`; the server maps it to `RPC_UNAVAILABLE` and hands the cause
+ * to `onInternalError`. Downstream means an `RPCTransportError` (only a
+ * transport raises one) or an `RPCTimeoutError` that names a procedure
+ * other than this one — an `RPCClient` stamps the procedure it was calling
+ * on every timeout it raises. A timeout about this procedure — the
+ * dispatcher's own, which a cooperative handler rethrows from
+ * `context.signal.reason`, or one a handler throws under its own name —
+ * stays `RPC_TIMEOUT`, as does everything else.
+ */
+export declare function toUpstreamError(error: unknown, procedureName: string, signal: AbortSignal): unknown;

package/dist/rpc/dispatcher/rpcDispatcher.downstream.js

@@ -0,0 +1,41 @@
+/**
+ * Translation of downstream failures raised inside a handler.
+ *
+ * A handler that calls another service over RPC gets that client's errors:
+ * an `RPCTransportError` when the peer could not be reached, an
+ * `RPCTimeoutError` when it did not answer in time. Rethrown as they are,
+ * the transport error went out as `RPC_INTERNAL_ERROR` (its code is not
+ * public vocabulary) and the timeout as `RPC_TIMEOUT` — which told the
+ * caller *this* procedure had timed out, when it was a dependency that had.
+ * Both are one condition from the caller's point of view: the service is
+ * unavailable right now, and the call may be retried.
+ */
+import { RPCTimeoutError, RPCTransportError, RPCUnavailableError, } from "../errors/rpc.errors.js";
+import { withCause } from "../errors/rpcErrorCause.helper.js";
+import { UNAVAILABLE_ERROR_MESSAGE } from "../constants/rpcConstants.core.js";
+/**
+ * Returns the error a handler's failure should propagate as.
+ *
+ * A downstream failure becomes an `RPCUnavailableError` with the original
+ * as `cause`; the server maps it to `RPC_UNAVAILABLE` and hands the cause
+ * to `onInternalError`. Downstream means an `RPCTransportError` (only a
+ * transport raises one) or an `RPCTimeoutError` that names a procedure
+ * other than this one — an `RPCClient` stamps the procedure it was calling
+ * on every timeout it raises. A timeout about this procedure — the
+ * dispatcher's own, which a cooperative handler rethrows from
+ * `context.signal.reason`, or one a handler throws under its own name —
+ * stays `RPC_TIMEOUT`, as does everything else.
+ */
+export function toUpstreamError(error, procedureName, signal) {
+    if (signal.aborted && error === signal.reason) {
+        return error;
+    }
+    const downstream = error instanceof RPCTransportError ||
+        (error instanceof RPCTimeoutError &&
+            error.procedureName !== undefined &&
+            error.procedureName !== procedureName);
+    if (downstream) {
+        return withCause(new RPCUnavailableError(UNAVAILABLE_ERROR_MESSAGE, procedureName), error);
+    }
+    return error;
+}

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

@@ -1,3 +1,2 @@
 export { RPCError, RPCProcedureNotFoundError, RPCInvalidRequestError, RPCValidationError, RPCAuthenticationError, RPCForbiddenError, RPCTimeoutError, RPCCancelledError, RPCInternalError, RPCTransportError, RPCSerializationError, RPCDeserializationError, RPCUnavailableError, RPCRateLimitedError, RPCDeadlineExceededError, RPCDuplicateProcedureError, createRPCError, isRPCError, } from "./rpc.errors.js";
 export type { RPCErrorOptions } from "./rpc.errors.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/rpc/errors/index.js

@@ -1,2 +1 @@
 export { RPCError, RPCProcedureNotFoundError, RPCInvalidRequestError, RPCValidationError, RPCAuthenticationError, RPCForbiddenError, RPCTimeoutError, RPCCancelledError, RPCInternalError, RPCTransportError, RPCSerializationError, RPCDeserializationError, RPCUnavailableError, RPCRateLimitedError, RPCDeadlineExceededError, RPCDuplicateProcedureError, createRPCError, isRPCError, } from "./rpc.errors.js";
-//# sourceMappingURL=index.js.map

package/dist/rpc/errors/rpc.errors.d.ts

@@ -1,3 +1,2 @@
 export { RPCError, RPCProcedureNotFoundError, RPCInvalidRequestError, RPCValidationError, RPCAuthenticationError, RPCForbiddenError, RPCTimeoutError, RPCCancelledError, RPCInternalError, RPCTransportError, RPCSerializationError, RPCDeserializationError, RPCUnavailableError, RPCRateLimitedError, RPCDeadlineExceededError, RPCDuplicateProcedureError, createRPCError, isRPCError, } from "@zudojs/errors";
 export type { RPCErrorOptions } from "@zudojs/errors";
-//# sourceMappingURL=rpc.errors.d.ts.map

package/dist/rpc/errors/rpc.errors.js

@@ -1,2 +1 @@
 export { RPCError, RPCProcedureNotFoundError, RPCInvalidRequestError, RPCValidationError, RPCAuthenticationError, RPCForbiddenError, RPCTimeoutError, RPCCancelledError, RPCInternalError, RPCTransportError, RPCSerializationError, RPCDeserializationError, RPCUnavailableError, RPCRateLimitedError, RPCDeadlineExceededError, RPCDuplicateProcedureError, createRPCError, isRPCError, } from "@zudojs/errors";
-//# sourceMappingURL=rpc.errors.js.map

package/dist/rpc/errors/rpcErrorCause.helper.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Attaches a cause to an error whose constructor takes none.
+ *
+ * The `@zudojs/errors` RPC classes fix their options in the constructor, so
+ * an error that wraps another (a transport failure wrapping a fetch error,
+ * an unavailable error wrapping a downstream timeout) gets its `cause` set
+ * afterwards. Non-enumerable, like the platform's own `Error.cause`, so it
+ * is not serialized by accident.
+ */
+export declare function withCause<T extends Error>(error: T, cause: unknown): T;

package/dist/rpc/errors/rpcErrorCause.helper.js

@@ -0,0 +1,18 @@
+/**
+ * Attaches a cause to an error whose constructor takes none.
+ *
+ * The `@zudojs/errors` RPC classes fix their options in the constructor, so
+ * an error that wraps another (a transport failure wrapping a fetch error,
+ * an unavailable error wrapping a downstream timeout) gets its `cause` set
+ * afterwards. Non-enumerable, like the platform's own `Error.cause`, so it
+ * is not serialized by accident.
+ */
+export function withCause(error, cause) {
+    Object.defineProperty(error, "cause", {
+        value: cause,
+        enumerable: false,
+        configurable: true,
+        writable: true,
+    });
+    return error;
+}

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

@@ -1,3 +1,2 @@
 export type { RPCInterceptor } from "./rpcInterceptor.type.js";
 export { createNoopRPCInterceptor } from "./rpcInterceptor.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/rpc/interceptor/index.js

@@ -1,2 +1 @@
 export { createNoopRPCInterceptor } from "./rpcInterceptor.type.js";
-//# sourceMappingURL=index.js.map

package/dist/rpc/interceptor/rpcInterceptor.type.d.ts

@@ -9,4 +9,3 @@ export interface RPCInterceptor {
  * Creates a no-op interceptor.
  */
 export declare function createNoopRPCInterceptor(): RPCInterceptor;
-//# sourceMappingURL=rpcInterceptor.type.d.ts.map

package/dist/rpc/interceptor/rpcInterceptor.type.js

@@ -8,4 +8,3 @@ export function createNoopRPCInterceptor() {
         },
     };
 }
-//# sourceMappingURL=rpcInterceptor.type.js.map

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

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

package/dist/rpc/middleware/index.js

@@ -1,2 +1 @@
 export { RPCMiddlewareStack } from "./rpcMiddleware.core.js";
-//# sourceMappingURL=index.js.map

package/dist/rpc/middleware/rpcMiddleware.core.d.ts

@@ -26,4 +26,3 @@ export declare class RPCMiddlewareStack {
      */
     execute(context: RPCContext, handler: () => Promise<unknown>): Promise<unknown>;
 }
-//# sourceMappingURL=rpcMiddleware.core.d.ts.map

package/dist/rpc/middleware/rpcMiddleware.core.js

@@ -49,4 +49,3 @@ export class RPCMiddlewareStack {
         return runAt(0);
     }
 }
-//# sourceMappingURL=rpcMiddleware.core.js.map

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

@@ -2,4 +2,3 @@ export type { RPCHandler, RPCProcedure, RPCProcedureOptions, } from "./rpcProced
 export { createRPCProcedure } from "./rpcProcedure.type.js";
 export { RPCProcedureRegistry } from "./rpcProcedureRegistry.core.js";
 export { RPCProcedureRouter } from "./rpcProcedureRouter.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/rpc/procedure/index.js

@@ -1,4 +1,3 @@
 export { createRPCProcedure } from "./rpcProcedure.type.js";
 export { RPCProcedureRegistry } from "./rpcProcedureRegistry.core.js";
 export { RPCProcedureRouter } from "./rpcProcedureRouter.core.js";
-//# sourceMappingURL=index.js.map

package/dist/rpc/procedure/rpcProcedure.type.d.ts

@@ -46,4 +46,3 @@ export interface RPCProcedure<TInput = unknown, TOutput = unknown> {
  * Creates a new RPC procedure.
  */
 export declare function createRPCProcedure<TInput = unknown, TOutput = unknown>(name: RPCProcedureName, handler: RPCHandler<TInput, TOutput>, options?: RPCProcedureOptions<TInput, TOutput>): RPCProcedure<TInput, TOutput>;
-//# sourceMappingURL=rpcProcedure.type.d.ts.map

package/dist/rpc/procedure/rpcProcedure.type.js

@@ -17,4 +17,3 @@ export function createRPCProcedure(name, handler, options = {}) {
         options: Object.freeze(options),
     });
 }
-//# sourceMappingURL=rpcProcedure.type.js.map

package/dist/rpc/procedure/rpcProcedureRegistry.core.d.ts

@@ -51,4 +51,3 @@ export declare class RPCProcedureRegistry {
      */
     clear(): void;
 }
-//# sourceMappingURL=rpcProcedureRegistry.core.d.ts.map

package/dist/rpc/procedure/rpcProcedureRegistry.core.js

@@ -88,4 +88,3 @@ export class RPCProcedureRegistry {
         this.procedures.clear();
     }
 }
-//# sourceMappingURL=rpcProcedureRegistry.core.js.map

package/dist/rpc/procedure/rpcProcedureRouter.core.d.ts

@@ -34,4 +34,3 @@ export declare class RPCProcedureRouter {
      */
     clear(): void;
 }
-//# sourceMappingURL=rpcProcedureRouter.core.d.ts.map

package/dist/rpc/procedure/rpcProcedureRouter.core.js

@@ -61,4 +61,3 @@ export class RPCProcedureRouter {
         this.routes.clear();
     }
 }
-//# sourceMappingURL=rpcProcedureRouter.core.js.map

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

@@ -14,4 +14,3 @@ export declare function abortReasonToRPCError(signal: AbortSignal, procedureName
  * 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

@@ -37,4 +37,3 @@ export function raceAbort(promise, signal, procedureName) {
         });
     });
 }
-//# sourceMappingURL=rpcAbort.helper.js.map

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

@@ -38,4 +38,3 @@ export declare function combineSignals(...signals: readonly (AbortSignal | undef
     readonly signal: AbortSignal;
     dispose(): void;
 };
-//# sourceMappingURL=rpcCancellation.helper.d.ts.map

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

@@ -74,4 +74,3 @@ export function combineSignals(...signals) {
         },
     };
 }
-//# sourceMappingURL=rpcCancellation.helper.js.map

package/dist/rpc/reliability/deadline/rpcDeadline.helper.d.ts

@@ -28,4 +28,3 @@ export declare function throwIfDeadlineExceeded(deadline: number, procedureName?
 export declare function readDeadline(metadata: {
     readonly deadline?: unknown;
 }): number | undefined;
-//# sourceMappingURL=rpcDeadline.helper.d.ts.map

package/dist/rpc/reliability/deadline/rpcDeadline.helper.js

@@ -45,4 +45,3 @@ export function readDeadline(metadata) {
     }
     return deadline;
 }
-//# sourceMappingURL=rpcDeadline.helper.js.map

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

@@ -4,4 +4,3 @@ export type { CancellableSignal } from "./cancellation/rpcCancellation.helper.js
 export { createCancellableSignal, cancelSignal, throwIfCancelled, combineSignals, } from "./cancellation/rpcCancellation.helper.js";
 export type { RPCBackoff, RPCJitter, RPCRetryOptions, } from "./retry/rpcRetry.helper.js";
 export { DEFAULT_RETRY_OPTIONS, calculateRetryDelay, retry, } from "./retry/rpcRetry.helper.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/rpc/reliability/index.js

@@ -2,4 +2,3 @@ export { createTimeout, withTimeout, runWithTimeout, } from "./timeout/rpcTimeou
 export { getRemainingTime, isDeadlineExceeded, throwIfDeadlineExceeded, readDeadline, } from "./deadline/rpcDeadline.helper.js";
 export { createCancellableSignal, cancelSignal, throwIfCancelled, combineSignals, } from "./cancellation/rpcCancellation.helper.js";
 export { DEFAULT_RETRY_OPTIONS, calculateRetryDelay, retry, } from "./retry/rpcRetry.helper.js";
-//# sourceMappingURL=index.js.map

package/dist/rpc/reliability/retry/rpcRetry.helper.d.ts

@@ -15,7 +15,16 @@ export type RPCJitter = "none" | "full" | "equal";
  * Retry options.
  */
 export interface RPCRetryOptions {
+    /**
+     * Total number of calls, not the number of retries: `attempts: 3` calls
+     * the operation up to three times (one call plus two retries), and
+     * `attempts: 1` never retries. Values below 1 are treated as 1.
+     *
+     * Note that `@zudojs/lifecycle` counts the other way — its `attempts`
+     * is the number of retries after the first call.
+     */
     readonly attempts: number;
+    /** Base delay before a retry, in milliseconds; see `backoff`. */
     readonly delay: number;
     readonly maxDelay?: number;
     readonly backoff?: RPCBackoff;
@@ -51,4 +60,3 @@ export declare function calculateRetryDelay(attempt: number, options: RPCRetryOp
  * failing dependency do not synchronise into a retry wave.
  */
 export declare function retry<T>(operation: () => Promise<T>, options: RPCRetryOptions): Promise<T>;
-//# sourceMappingURL=rpcRetry.helper.d.ts.map

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

@@ -121,4 +121,3 @@ export async function retry(operation, options) {
     // 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

@@ -29,4 +29,3 @@ export declare function withTimeout<T>(promise: Promise<T>, duration: number, pr
  * stop its own work rather than continuing unobserved.
  */
 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

@@ -84,4 +84,3 @@ export async function runWithTimeout(operation, duration, procedureName, parentS
         parentSignal?.removeEventListener("abort", onParentAbort);
     }
 }
-//# sourceMappingURL=rpcTimeout.helper.js.map

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

@@ -6,4 +6,3 @@ 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

@@ -4,4 +4,3 @@
  */
 export { RPCServer } from "./rpcServer.core.js";
 export { mapRPCError } from "./rpcErrorMapping.helper.js";
-//# sourceMappingURL=index.js.map

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

@@ -23,4 +23,3 @@ export declare function mapExposedBaseError(error: unknown): RPCErrorPayload | u
  * `RPC_INTERNAL_ERROR`.
  */
 export declare function withheldRPCErrorCode(code: string): string;
-//# sourceMappingURL=rpcBaseErrorMapping.helper.d.ts.map

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

@@ -67,4 +67,3 @@ export function mapExposedBaseError(error) {
 export function withheldRPCErrorCode(code) {
     return Object.hasOwn(RPC_HTTP_STATUS, code) ? code : "RPC_INTERNAL_ERROR";
 }
-//# sourceMappingURL=rpcBaseErrorMapping.helper.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * Wire mapping for failures of something the server itself called.
+ *
+ * A transport failure inside a handler is a dependency the server could not
+ * reach, not a fault of the request: `RPC_UNAVAILABLE`, so the caller may
+ * retry, with the transport's own text (hosts, paths) withheld. An
+ * `RPCUnavailableError` carrying a `cause` is the dispatcher's wrap of such
+ * a failure; its cause is worth logging, so it is reported as internal too.
+ */
+import type { RPCMappedError } from "./rpcErrorMapping.helper.js";
+/**
+ * Maps a downstream failure onto `RPC_UNAVAILABLE`, marked internal so the
+ * original reaches `onInternalError`; `undefined` for anything else.
+ */
+export declare function mapDownstreamError(error: Error): RPCMappedError | undefined;

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

@@ -0,0 +1,27 @@
+/**
+ * Wire mapping for failures of something the server itself called.
+ *
+ * A transport failure inside a handler is a dependency the server could not
+ * reach, not a fault of the request: `RPC_UNAVAILABLE`, so the caller may
+ * retry, with the transport's own text (hosts, paths) withheld. An
+ * `RPCUnavailableError` carrying a `cause` is the dispatcher's wrap of such
+ * a failure; its cause is worth logging, so it is reported as internal too.
+ */
+import { RPCTransportError, RPCUnavailableError, } from "../errors/rpc.errors.js";
+import { UNAVAILABLE_ERROR_MESSAGE } from "../constants/rpcConstants.core.js";
+/**
+ * Maps a downstream failure onto `RPC_UNAVAILABLE`, marked internal so the
+ * original reaches `onInternalError`; `undefined` for anything else.
+ */
+export function mapDownstreamError(error) {
+    if (error instanceof RPCTransportError) {
+        return unavailable(UNAVAILABLE_ERROR_MESSAGE);
+    }
+    if (error instanceof RPCUnavailableError && error.cause !== undefined) {
+        return unavailable(error.message);
+    }
+    return undefined;
+}
+function unavailable(message) {
+    return { payload: { code: "RPC_UNAVAILABLE", message }, internal: true };
+}