@procedures/client 0.2.3 → 0.4.0

package/src/client/client.ts

@@ -56,7 +56,8 @@ import { RouteResolver, type ResolvedRoute, type RouteResolutionResult } from ".
 import { BatchExecutor, type ExecutionContext } from "./batch-executor.js";
 import type { ProcedureRegistry } from "../procedures/registry.js";
 import type { EventBus } from "../events/types.js";
-import { TIMEOUT_METADATA_KEY, narrowCapability } from "../procedures/capability.js";
+import { narrowCapability } from "../procedures/capability.js";
+import { TIMEOUT_METADATA_KEY, absorbTimeout, writeRemainingTime } from "./deadline.js";
 import type { Capability, ClearanceOrder, NestedCallOptions } from "../procedures/types.js";
 import { PROCEDURE_REGISTRY } from "../procedures/registry.js";
 import { validateSchema } from "../procedures/schema.js";
@@ -147,6 +148,11 @@ interface CallerContext {
 
 /** The options of `exec()` and `execStream()`. */
 export interface ExecOptions {
+  /**
+   * The signal of the program: an abort stops the call that runs, and the calls that did not
+   * start do not start (roadmap R14). Each nested call gets it.
+   */
+  signal?: AbortSignal | undefined;
   /**
    * This function gets the hydration events of this program only: the refs that hydration runs,
    * also inside control flow and runners, with the call that gets each result. A trace uses it.
@@ -155,6 +161,14 @@ export interface ExecOptions {
   onRef?: ((event: HydrationEvent) => void) | undefined;
 }
 
+/** The caller context of `exec()` and `execStream()`: the observer and the signal. */
+function callerOf(options: ExecOptions): CallerContext {
+  const caller: CallerContext = {};
+  if (options.onRef) caller.onRef = options.onRef;
+  if (options.signal) caller.signal = options.signal;
+  return caller;
+}
+
 /**
  * Generate a unique message ID.
  */
@@ -357,7 +371,7 @@ export class Client<TContext = {}> {
    * ```typescript
    * // Type accumulation example
    * const client = new Client(transport)
-   *   .use(createTimeoutMiddleware({ overall: 5000 }))  // Client<TimeoutContext>
+   *   .use(createOverallTimeoutMiddleware({ overall: 5000 }))  // Client<TimeoutContext>
    *   .use(createRetryMiddleware())                     // Client<TimeoutContext & RetryContext>
    *   .use(createCacheMiddleware({ methods: ["users.get"] }));                    // Client<... & CacheContext>
    *
@@ -478,7 +492,7 @@ export class Client<TContext = {}> {
     input?: unknown,
     options: ExecOptions = {}
   ): Promise<TOutput> {
-    const caller: CallerContext = options.onRef ? { onRef: options.onRef } : {};
+    const caller: CallerContext = callerOf(options);
     const { path, input: hydratedInput } = await this.prepareRef(refOrPath, input, caller);
     return this.execInternal<TOutput>(path, hydratedInput, caller);
   }
@@ -501,7 +515,7 @@ export class Client<TContext = {}> {
     options: ExecOptions = {}
   ): AsyncIterable<TOutput> {
     const self = this;
-    const caller: CallerContext = options.onRef ? { onRef: options.onRef } : {};
+    const caller: CallerContext = callerOf(options);
     return (async function* () {
       const { path, input: hydratedInput } = await self.prepareRef(refOrPath, input, caller);
       yield* self.execStreamInternal<TOutput>(path, hydratedInput, caller);
@@ -744,6 +758,10 @@ export class Client<TContext = {}> {
       (message.metadata as any).__schema = opts.schema;
     }
 
+    // The remaining time of the caller becomes the deadline of the call: the client sends the
+    // remaining time again for each try (roadmap R10)
+    absorbTimeout(message.metadata);
+
     // Compose middleware chain
     const runner = this.composeMiddleware<TReq, TRes>();
 
@@ -771,6 +789,9 @@ export class Client<TContext = {}> {
     // Innermost function: call transport
     const self = this;
     const transportRunner: ClientRunner<TReq, TRes> = async function* (context: ClientContext<TReq>) {
+      // The remaining time of the deadline goes with each try, so the server stops the handler
+      // when this client stops waiting (roadmap R10)
+      writeRemainingTime(context.message.metadata);
       yield* self.transport.send<TReq, TRes>(context.message);
     };
 
@@ -1163,11 +1184,9 @@ export class Client<TContext = {}> {
         yield* outputItems(await invokeProcedure(procedure, input, options));
         return;
       }
-      const callOptions: CallOptions<TContext> = { context: context.metadata as ClientContextInput<TContext> };
-      if (context.signal) {
-        callOptions.signal = context.signal;
-      }
-      yield* self.stream(self.pathToMethod(path), input, callOptions);
+      // The deadline of the capability goes with the call, as for exec() (roadmap R14: before, a
+      // remote leaf of route() sent the signal, not the deadline)
+      yield* self.stream(self.pathToMethod(path), input, self.remoteCallOptions({ metadata: context.metadata, signal: context.signal }));
     })();
   }
 

package/src/client/deadline.ts

@@ -0,0 +1,64 @@
+/**
+ * One deadline for a call (roadmap R10).
+ *
+ * A call has one absolute deadline in its metadata (`__deadline`, a time of `Date.now()`). The
+ * key starts with `__`, so it stays in this process. Each part of the client can only make it
+ * earlier: the remaining time that the caller sends, the overall timeout and the timeout of each
+ * try. Just before the transport sends a try, the client writes the remaining time into
+ * `procedure-timeout`. The server uses it to make its own deadline earlier, so a handler stops
+ * when its caller stops waiting.
+ *
+ * Before, the overall timeout and the timeout of each try did not reach the server, and a
+ * client could also send `X-Timeout`, which the server ignored.
+ */
+
+import type { Metadata } from "./types.js";
+
+/**
+ * The metadata key of the remaining time of a remote call, in milliseconds. A server uses it
+ * only to make its deadline earlier.
+ */
+export const TIMEOUT_METADATA_KEY = "procedure-timeout";
+
+/** The metadata key of the absolute deadline of a call. It stays in this process. */
+export const DEADLINE_METADATA_KEY = "__deadline";
+
+/** The deadline of a call, or undefined. */
+export function deadlineOf(metadata: Metadata): number | undefined {
+  const deadline = metadata[DEADLINE_METADATA_KEY];
+  return typeof deadline === "number" && Number.isFinite(deadline) ? deadline : undefined;
+}
+
+/**
+ * This function makes the deadline of a call earlier: the earlier of its deadline and `at`. It
+ * gives the deadline from before, to put back with `restoreDeadline`.
+ */
+export function narrowDeadline(metadata: Metadata, at: number): number | undefined {
+  const before = deadlineOf(metadata);
+  metadata[DEADLINE_METADATA_KEY] = before === undefined ? at : Math.min(before, at);
+  return before;
+}
+
+/** This function puts back the deadline from before a `narrowDeadline`. */
+export function restoreDeadline(metadata: Metadata, before: number | undefined): void {
+  if (before === undefined) delete metadata[DEADLINE_METADATA_KEY];
+  else metadata[DEADLINE_METADATA_KEY] = before;
+}
+
+/**
+ * The remaining time that the caller gives in `procedure-timeout` becomes the deadline of the
+ * call, when the call starts. The client then writes the remaining time again for each try.
+ */
+export function absorbTimeout(metadata: Metadata, now: number = Date.now()): void {
+  const timeoutMs = metadata[TIMEOUT_METADATA_KEY];
+  if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs < 0) return;
+  delete metadata[TIMEOUT_METADATA_KEY];
+  narrowDeadline(metadata, now + timeoutMs);
+}
+
+/** This function writes the remaining time of the deadline into `procedure-timeout`, for one try. */
+export function writeRemainingTime(metadata: Metadata, now: number = Date.now()): void {
+  const deadline = deadlineOf(metadata);
+  if (deadline === undefined) return;
+  metadata[TIMEOUT_METADATA_KEY] = Math.max(0, Math.floor(deadline - now));
+}

package/src/client/errors/README.md

@@ -213,6 +213,8 @@ console.error(formatError(error, true)); // include stack trace
 2. Add metadata to `ERROR_REGISTRY` in `registry.ts` or `HTTP_ERROR_REGISTRY` in `http-errors.ts`
 3. If HTTP-related, add to `HTTP_STATUS_ERROR_MAP` in `http-errors.ts`
 
+`ERROR_CODES` of the wire protocol (`src/protocol.ts`, `WIRE-PROTOCOL.md`) is the source of the codes of the protocol. `ERROR_REGISTRY` has an entry for each of them, and that entry takes its HTTP status and its retry flag from `ERROR_CODES`. To add a code of the protocol, add it to `ERROR_CODES`. A code without texts in `registry.ts` gets the meaning of the protocol as its texts. `defineProtocolError` gives a code of the protocol its own texts.
+
 Example:
 ```typescript
 // 1. Add to ErrorCode enum

package/src/client/errors/factory.ts

@@ -94,8 +94,10 @@ export type ErrorPattern = {
 const ERROR_PATTERNS : ErrorPattern[] = [
   {
     code: ErrorCode.ABORTED,
+    // The reason of AbortSignal.timeout() is a TimeoutError with the message "The operation was
+    // aborted due to timeout": it is a timeout (roadmap R30: before, it was ABORTED)
     detect: (name: string, message: string) =>
-      name === "aborterror" || message.includes("abort"),
+      name === "aborterror" || (name !== "timeouterror" && message.includes("abort")),
   },
   {
     code: ErrorCode.TIMEOUT,
@@ -124,13 +126,8 @@ const ERROR_PATTERNS : ErrorPattern[] = [
       message.includes("network") ||
       message.includes("connection"),
   },
-  {
-    code: ErrorCode.PARSE_ERROR,
-    detect: (_name: string, message: string) =>
-      message.includes("parse") ||
-      message.includes("json") ||
-      message.includes("unexpected token"),
-  },
+  // Before the parse errors: "Converting circular structure to JSON" names JSON too (roadmap R30:
+  // before, it was PARSE_ERROR)
   {
     code: ErrorCode.SERIALIZE_ERROR,
     detect: (_name: string, message: string) =>
@@ -138,6 +135,13 @@ const ERROR_PATTERNS : ErrorPattern[] = [
       message.includes("stringify") ||
       message.includes("circular"),
   },
+  {
+    code: ErrorCode.PARSE_ERROR,
+    detect: (_name: string, message: string) =>
+      message.includes("parse") ||
+      message.includes("json") ||
+      message.includes("unexpected token"),
+  },
 ] as const satisfies ErrorPattern[];
 
 /**

package/src/client/errors/http-errors.ts

@@ -8,6 +8,7 @@
 import { ErrorCategory, ErrorSeverity, type ErrorMetadata } from "./types.js";
 import { ErrorCode } from "./codes.js";
 import { HTTPStatus } from "./http-status.js";
+import { httpStatusOf } from "../../protocol.js";
 
 /**
  * Helper to create HTTP error metadata.
@@ -595,6 +596,10 @@ export function httpStatusToErrorCode(status: number): ErrorCode {
  * ```
  */
 export function errorCodeToHTTPStatus(code: ErrorCode): HTTPStatus {
+  // A code of the wire protocol has the status of ERROR_CODES: before, TIMEOUT gave 408 here and
+  // 504 on the wire
+  const protocolStatus = httpStatusOf(code);
+  if (protocolStatus !== undefined) return protocolStatus as HTTPStatus;
   // Build map from HTTP_STATUS_ERROR_MAP
   const entry = HTTP_STATUS_ERROR_MAP.find(([, errorCode]) => errorCode === code);
   return entry?.[0] ?? HTTPStatus.INTERNAL_SERVER_ERROR;

package/src/client/errors/index.ts

@@ -20,7 +20,7 @@
  * console.log(error.metadata.userMessage);  // User-friendly message
  * console.log(error.metadata.devMessage);   // Developer diagnostic
  * console.log(error.metadata.suggestions);  // Suggested actions
- * console.log(error.metadata.retryable);    // true
+ * console.log(error.metadata.retryable);    // false (ERROR_CODES of the protocol)
  *
  * // Format for logging
  * console.log(formatError(error));

package/src/client/errors/registry.ts

@@ -15,6 +15,7 @@ import {
 } from "./types.js";
 import { HTTP_ERROR_REGISTRY } from "./http-errors.js";
 import { ErrorCode } from "./codes.js";
+import { ERROR_CODES, type ProtocolErrorCode } from "../../protocol.js";
 
 /**
  * Create error metadata with defaults.
@@ -47,12 +48,71 @@ function defineError(
   return result;
 }
 
+/** The texts of an entry. For a code of the protocol, `ERROR_CODES` gives the status and the retry flag. */
+type ProtocolErrorTexts = Omit<ErrorMetadata, "code" | "httpStatus" | "retryable">;
+
 /**
- * Universal Error Registry
- *
- * Protocol-agnostic error codes with rich metadata.
+ * This function makes the entry of a code of the wire protocol. The HTTP status and the retry
+ * flag come from `ERROR_CODES` (`protocol.ts`, `WIRE-PROTOCOL.md`), the source of these facts.
+ */
+function defineProtocolError(code: ProtocolErrorCode, texts: ProtocolErrorTexts): ErrorMetadata {
+  const info = ERROR_CODES[code];
+  return defineError(code, { ...texts, httpStatus: info.http, retryable: info.retryable });
+}
+
+/** The category of each code of the protocol, for a code that the registry does not describe. */
+const PROTOCOL_CATEGORIES: Readonly<Record<ProtocolErrorCode, ErrorCategory>> = {
+  NOT_FOUND: ErrorCategory.CLIENT,
+  NO_HANDLER: ErrorCategory.SERVER,
+  NOT_EXPOSED: ErrorCategory.AUTH,
+  NOT_DECLARED: ErrorCategory.AUTH,
+  FORBIDDEN: ErrorCategory.AUTH,
+  UNAUTHORIZED: ErrorCategory.AUTH,
+  VALIDATION_ERROR: ErrorCategory.CLIENT,
+  INVALID_REQUEST: ErrorCategory.PROTOCOL,
+  PROTOCOL_VERSION: ErrorCategory.PROTOCOL,
+  OUTPUT_VALIDATION_ERROR: ErrorCategory.SERVER,
+  NO_OUTPUT: ErrorCategory.SERVER,
+  HANDLER_ERROR: ErrorCategory.SERVER,
+  INTERNAL_ERROR: ErrorCategory.SERVER,
+  NOT_ACCEPTABLE: ErrorCategory.CLIENT,
+  DUPLICATE: ErrorCategory.CLIENT,
+  DUPLICATE_REQUEST: ErrorCategory.CLIENT,
+  ABORTED: ErrorCategory.CANCELLED,
+  TIMEOUT: ErrorCategory.TIMEOUT,
+  UNAVAILABLE: ErrorCategory.SERVER,
+  CONNECTION_CLOSED: ErrorCategory.NETWORK,
+  CONNECTION_NOT_FOUND: ErrorCategory.CLIENT,
+};
+
+/**
+ * This function gives the registry with one entry for each code of the protocol. The status and
+ * the retry flag of such an entry come from `ERROR_CODES`, so the two lists agree (before, the
+ * registry gave `TIMEOUT` the status 408 and two codes another retry flag). A code without texts
+ * here gets the meaning of the protocol as its texts.
+ */
+function withProtocolCodes(described: ErrorRegistry): ErrorRegistry {
+  const registry: ErrorRegistry = { ...described };
+  for (const code of Object.keys(ERROR_CODES) as ProtocolErrorCode[]) {
+    const info = ERROR_CODES[code];
+    const meaning = `${info.meaning}.`;
+    const texts: ProtocolErrorTexts = described[code] ?? {
+      summary: info.meaning,
+      detail: meaning,
+      category: PROTOCOL_CATEGORIES[code],
+      severity: info.retryable ? ErrorSeverity.WARNING : ErrorSeverity.ERROR,
+      userMessage: meaning,
+      devMessage: meaning,
+    };
+    registry[code] = { ...texts, code, httpStatus: info.http, retryable: info.retryable };
+  }
+  return registry;
+}
+
+/**
+ * The entries with their own texts. `ERROR_REGISTRY` adds the codes of the protocol.
  */
-export const ERROR_REGISTRY: ErrorRegistry = {
+const DESCRIBED_ERRORS = {
   //
   // ═══ Network Errors ═══
   //
@@ -108,16 +168,14 @@ export const ERROR_REGISTRY: ErrorRegistry = {
   // ═══ Timeout Errors ═══
   //
 
-  TIMEOUT: defineError(ErrorCode.TIMEOUT, {
+  TIMEOUT: defineProtocolError("TIMEOUT", {
     summary: "Request timed out",
     detail:
       "The request exceeded the configured timeout duration. This may indicate slow server response, network congestion, or overly aggressive timeout settings.",
     category: ErrorCategory.TIMEOUT,
-    retryable: true,
     severity: ErrorSeverity.WARNING,
     userMessage: "The request took too long to complete. Please try again.",
     devMessage: "Request exceeded timeout threshold. Consider increasing timeout or optimizing server response time.",
-    httpStatus: 408,
     suggestions: [
       "Try again with a longer timeout",
       "Check server performance",
@@ -159,11 +217,10 @@ export const ERROR_REGISTRY: ErrorRegistry = {
   // ═══ Cancellation Errors ═══
   //
 
-  ABORTED: defineError(ErrorCode.ABORTED, {
+  ABORTED: defineProtocolError("ABORTED", {
     summary: "Request was aborted",
     detail: "The request was explicitly cancelled by the client via AbortSignal. This is user-initiated.",
     category: ErrorCategory.CANCELLED,
-    retryable: false,
     severity: ErrorSeverity.INFO,
     userMessage: "The request was cancelled.",
     devMessage: "Request aborted via AbortSignal. This is expected and not an error condition.",
@@ -269,15 +326,13 @@ export const ERROR_REGISTRY: ErrorRegistry = {
     ],
   }),
 
-  UNAUTHORIZED: defineError(ErrorCode.UNAUTHORIZED, {
+  UNAUTHORIZED: defineProtocolError("UNAUTHORIZED", {
     summary: "Unauthorized",
     detail: "Authentication is required but was not provided or is invalid.",
     category: ErrorCategory.AUTH,
-    retryable: false,
     severity: ErrorSeverity.ERROR,
     userMessage: "Authentication required. Please sign in.",
     devMessage: "Missing or invalid authentication credentials. Check auth token/API key.",
-    httpStatus: 401,
     suggestions: [
       "Provide valid authentication credentials",
       "Check token hasn't expired",
@@ -285,15 +340,13 @@ export const ERROR_REGISTRY: ErrorRegistry = {
     ],
   }),
 
-  FORBIDDEN: defineError(ErrorCode.FORBIDDEN, {
+  FORBIDDEN: defineProtocolError("FORBIDDEN", {
     summary: "Forbidden",
     detail: "The authenticated user doesn't have permission to access this resource.",
     category: ErrorCategory.AUTH,
-    retryable: false,
     severity: ErrorSeverity.ERROR,
     userMessage: "You don't have permission to access this resource.",
     devMessage: "Insufficient permissions. Check user roles and resource ACLs.",
-    httpStatus: 403,
     suggestions: [
       "Verify user has required permissions",
       "Check resource access control lists",
@@ -301,15 +354,13 @@ export const ERROR_REGISTRY: ErrorRegistry = {
     ],
   }),
 
-  NOT_FOUND: defineError(ErrorCode.NOT_FOUND, {
+  NOT_FOUND: defineProtocolError("NOT_FOUND", {
     summary: "Not found",
     detail: "The requested resource does not exist.",
     category: ErrorCategory.CLIENT,
-    retryable: false,
     severity: ErrorSeverity.ERROR,
     userMessage: "The requested item was not found.",
     devMessage: "Resource not found. Verify ID/path is correct and resource exists.",
-    httpStatus: 404,
     suggestions: [
       "Verify the resource ID is correct",
       "Check the resource hasn't been deleted",
@@ -402,17 +453,15 @@ export const ERROR_REGISTRY: ErrorRegistry = {
   // ═══ Server Errors (5xx) ═══
   //
 
-  INTERNAL_ERROR: defineError(ErrorCode.INTERNAL_ERROR, {
+  INTERNAL_ERROR: defineProtocolError("INTERNAL_ERROR", {
     summary: "Internal server error",
     detail: "The server encountered an unexpected condition. This is a server-side bug.",
     category: ErrorCategory.SERVER,
-    retryable: true,
     severity: ErrorSeverity.CRITICAL,
     userMessage: "Server error occurred. Please try again later.",
     devMessage: "Internal server error. Check server logs for details.",
-    httpStatus: 500,
+    // The protocol says that a retry does not help (ERROR_CODES: retryable false)
     suggestions: [
-      "Retry the request",
       "Check server logs",
       "Contact server team",
     ],
@@ -554,6 +603,14 @@ export const ERROR_REGISTRY: ErrorRegistry = {
   ...HTTP_ERROR_REGISTRY,
 } as const satisfies ErrorRegistry;
 
+/**
+ * Universal Error Registry
+ *
+ * Protocol-agnostic error codes with rich metadata. Each code of the wire protocol has an entry,
+ * and `ERROR_CODES` gives its HTTP status and its retry flag.
+ */
+export const ERROR_REGISTRY: ErrorRegistry = withProtocolCodes(DESCRIBED_ERRORS);
+
 /**
  * Get error metadata by code.
  *

package/src/client/index.ts

@@ -29,7 +29,7 @@ export { LocalTransport } from "../adapters/local/client/index.js";
 export type { LocalTransportOptions, Handler } from "../adapters/local/client/index.js";
 
 export { WebSocketTransport } from "../adapters/websocket/client/index.js";
-export type { WebSocketTransportOptions } from "../adapters/websocket/client/index.js";
+export type { WebSocketTransportOptions, WebSocketClass } from "../adapters/websocket/client/index.js";
 // WebSocketState is a runtime enum — export as a value (not type-only) so consumers can compare
 // transport.getState() === WebSocketState.CONNECTED. See documentation/BUGS-2026-07.md (L1).
 export { WebSocketState } from "../adapters/websocket/client/index.js";
@@ -43,10 +43,13 @@ export type {
 } from "../adapters/mock/client//index.js";
 
 // Middleware
-export { createRetryMiddleware } from "./middleware/retry.js";``
+export { createRetryMiddleware } from "./middleware/retry.js";
+// The delivery of a failed try: it did not leave, or its outcome is indeterminate (roadmap R1)
+export { DELIVERY_METADATA_KEY, deliveryOf, isNotSentError } from "./middleware/items.js";
+export type { Delivery } from "./middleware/items.js";
 export type { RetryOptions } from "./middleware/retry.js";
 
-export { createCacheMiddleware } from "./middleware/cache.js";
+export { createCacheMiddleware, invalidateCache } from "./middleware/cache.js";
 export type { CacheOptions, CacheStats } from "./middleware/cache.js";
 
 export {
@@ -55,6 +58,21 @@ export {
   createCombinedTimeoutMiddleware,
 } from "./middleware/timeout.js";
 export type { TimeoutOptions } from "./middleware/timeout.js";
+// Typed durations (roadmap R11)
+export { ms, seconds, minutes, hours, toMs, isDuration } from "../duration.js";
+export type { Duration } from "../duration.js";
+// The resilience preset and the deadline of a call (roadmap R10)
+export { resilience } from "./middleware/resilience.js";
+export type { ResilienceOptions, ResilienceContext } from "./middleware/resilience.js";
+export {
+  TIMEOUT_METADATA_KEY,
+  DEADLINE_METADATA_KEY,
+  deadlineOf,
+  narrowDeadline,
+  restoreDeadline,
+  absorbTimeout,
+  writeRemainingTime,
+} from "./deadline.js";
 
 export { createPaginationMiddleware, paginateAll } from "./middleware/pagination.js";
 export type { PaginationOptions } from "./middleware/pagination.js";