@procedures/client 0.2.2 → 0.3.0

package/src/adapters/websocket/server/types.ts

@@ -8,6 +8,7 @@ import type { IncomingMessage } from "http";
 import type { Server as HttpServer } from "http";
 import type { WebSocket } from "ws";
 import type { BrowserGuardOptions } from "../../../server/browser-guard.js";
+import type { Duration } from "../../../duration.js";
 
 /**
  * WebSocket authentication handler.
@@ -75,6 +76,21 @@ export interface WebSocketServerTransportOptions extends Omit<BrowserGuardOption
    * @default 1 MiB
    */
   highWaterMark?: number;
+
+  /**
+   * The heartbeat of the server: a WebSocket ping to each connection at each interval. A
+   * connection that misses `misses` pongs one after the other is closed, so the server finds a
+   * client that went silent (roadmap R3: before, only the client sent pings). Browsers and the
+   * `ws` client answer a ping without code. `false` turns it off.
+   * @default { interval: seconds(15), misses: 2 } (`TIMER_DEFAULTS.webSocketServer`)
+   */
+  heartbeat?: { interval?: Duration; misses?: number } | false;
+
+  /**
+   * The time until the first frame of a call that the server sends to a client (roadmap R24).
+   * @default seconds(30)
+   */
+  reverseRequestTimeout?: Duration;
 }
 
 /**
@@ -85,7 +101,10 @@ export interface WebSocketMessage<TReq = unknown> {
   id: string;
 
   /** Message type */
-  type: "request" | "response" | "error" | "stream" | "cancel" | "credit" | "ping" | "pong" | "server-request" | "server-response" | "event";
+  type: "hello" | "request" | "response" | "error" | "stream" | "cancel" | "credit" | "ping" | "pong" | "server-request" | "server-response" | "event";
+
+  /** The protocol version of a `hello` frame (roadmap R25). */
+  protocol?: number;
 
   /** RPC method (for requests) */
   method?: {

package/src/adapters/websocket/shared/rpc.ts

@@ -0,0 +1,453 @@
+/**
+ * The calls over one WebSocket in the two directions (roadmap R24).
+ *
+ * A WebSocket connection carries the calls of each side to the other side, with the same frames:
+ * a `request`, then a `response`, an `error`, or `stream` frames that end with `stream.done`. The
+ * reader of a stream gives `credit`, and the caller can `cancel`. `OutgoingCalls` is the side that
+ * sends calls. `IncomingCalls` is the side that serves them with a `RequestHandler`, so a call runs
+ * through `invokeProcedure` (validation, the expose rule, the capability, the deadline of
+ * `procedure-timeout`). The server serves the calls of the client, and the client can serve the
+ * calls of the server: before, the reverse calls had frames of their own (`server-request`,
+ * `server-response`), with one value, no stream, no cancel and no signal.
+ */
+
+import type { Message, ResponseItem } from "../../../client/types.js";
+import type { RequestHandler, ServerRequest } from "../../../server/types.js";
+import type { WebSocketMessage } from "../server/types.js";
+import { withoutInternalKeys } from "../../metadata.js";
+import { DELIVERY_METADATA_KEY } from "../../../client/middleware/items.js";
+
+/**
+ * A queue of response items that one reader takes in order: push, then end or fail. The reader
+ * waits for the next item without polling.
+ */
+export class ItemQueue<T> {
+  private items: T[] = [];
+  private ended = false;
+  private failure: { error: Error } | undefined;
+  private wake: (() => void) | undefined;
+
+  push(item: T): void {
+    this.items.push(item);
+    this.notify();
+  }
+
+  end(): void {
+    this.ended = true;
+    this.notify();
+  }
+
+  fail(error: Error): void {
+    this.failure = { error };
+    this.notify();
+  }
+
+  private notify(): void {
+    const wake = this.wake;
+    this.wake = undefined;
+    wake?.();
+  }
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<T, void, undefined> {
+    for (;;) {
+      if (this.items.length > 0) {
+        yield this.items.shift()!;
+        continue;
+      }
+      if (this.failure) throw this.failure.error;
+      if (this.ended) return;
+      await new Promise<void>((resolve) => {
+        this.wake = resolve;
+      });
+    }
+  }
+}
+
+/**
+ * The credit of a stream (deep dive TRN-3): the number of items that the reader has room for.
+ * The stream takes one for each item that it sends, and waits when it has none.
+ */
+export class StreamCredit {
+  private wake: (() => void) | undefined;
+
+  constructor(private credit: number) {}
+
+  grant(n: number): void {
+    this.credit += n;
+    const wake = this.wake;
+    this.wake = undefined;
+    wake?.();
+  }
+
+  /** Take one item of credit. Returns false when the signal aborted the wait. */
+  async take(signal: AbortSignal): Promise<boolean> {
+    while (this.credit <= 0) {
+      if (signal.aborted) return false;
+      await new Promise<void>((resolve) => {
+        const onAbort = (): void => resolve();
+        signal.addEventListener("abort", onAbort, { once: true });
+        this.wake = () => {
+          signal.removeEventListener("abort", onAbort);
+          resolve();
+        };
+      });
+    }
+    if (signal.aborted) return false;
+    this.credit--;
+    return true;
+  }
+}
+
+/** The error of a failed stream or handler: its code (a string) and its retryable flag. */
+export function errorStatus(error: unknown): { type: "error"; code: string; message: string; retryable: boolean } {
+  const code = (error as { code?: unknown } | undefined)?.code;
+  const retryable = (error as { retryable?: unknown } | undefined)?.retryable;
+  return {
+    type: "error",
+    code: typeof code === "string" ? code : "HANDLER_ERROR",
+    message: error instanceof Error ? error.message : String(error),
+    // Before, every stream error lost its retryable flag (deep dive TRN-7)
+    retryable: typeof retryable === "boolean" ? retryable : false,
+  };
+}
+
+/** A text of an error message of a frame: a string, or the JSON of another value. */
+function textOf(value: unknown): string {
+  if (typeof value === "string") return value;
+  return value === undefined ? "Unknown error" : JSON.stringify(value);
+}
+
+/** The response item of a `response` or an `error` frame, for the caller's message id. */
+export function itemOfFrame(frame: WebSocketMessage, messageId: string): ResponseItem<unknown> {
+  let status: ResponseItem<unknown>["status"];
+  if (frame.status && frame.status.type === "error") {
+    status = { type: "error", code: String(frame.status.code), message: textOf(frame.status.message), retryable: frame.status.retryable || false };
+  } else if (frame.status && frame.status.type === "success") {
+    status = { type: "success", code: Number(frame.status.code) };
+  } else if (frame.type === "error") {
+    status = {
+      type: "error",
+      code: String(frame.error?.code || "UNKNOWN_ERROR"),
+      message: textOf(frame.error?.message),
+      retryable: frame.error?.retryable || false,
+    };
+  } else {
+    status = { type: "success", code: 200 };
+  }
+  return { id: messageId, status, payload: frame.payload, metadata: frame.metadata || {} };
+}
+
+/** A call that this side sent and that waits for frames. */
+interface PendingCall {
+  /** The id of the caller's message: the response items carry it */
+  messageId: string;
+  /** The response items of the call, in order */
+  queue: ItemQueue<ResponseItem<unknown>>;
+  /** The time limit until the first frame */
+  timeout?: ReturnType<typeof setTimeout> | undefined;
+}
+
+/** The options of `OutgoingCalls`. */
+export interface OutgoingCallsOptions {
+  /** This function sends a frame on the socket. */
+  send: (frame: WebSocketMessage) => void;
+  /** True while the socket is open. */
+  isOpen: () => boolean;
+  /** The time until the first frame of a call, in milliseconds. 0 or less: no limit. */
+  requestTimeoutMs: number;
+  /** The number of stream items that the reader can hold. */
+  streamWindow: number;
+  /** The start of the wire id of each call: the two sides use different ones. */
+  idPrefix: string;
+}
+
+/** The calls that this side sends on one socket. */
+export class OutgoingCalls {
+  private readonly pending = new Map<string, PendingCall>();
+  private seq = 0;
+
+  constructor(private readonly options: OutgoingCallsOptions) {}
+
+  /** The number of calls that wait for their frames. */
+  get size(): number {
+    return this.pending.size;
+  }
+
+  /** This function sends a call, and gives its response items. */
+  async *call<TReq, TRes>(message: Message<TReq>): AsyncGenerator<ResponseItem<TRes>, void, undefined> {
+    if (message.signal?.aborted) {
+      yield abortedItem<TRes>(message.id);
+      return;
+    }
+    if (!this.options.isOpen()) {
+      // The call did not leave: a retry can send it
+      yield {
+        id: message.id,
+        status: { type: "error", code: "CONNECTION_CLOSED", message: "The connection is closed", retryable: true },
+        payload: null as TRes,
+        metadata: { [DELIVERY_METADATA_KEY]: "not-sent" },
+      };
+      return;
+    }
+    const wireId = `${this.options.idPrefix}${message.id}~${++this.seq}`;
+    const window = this.options.streamWindow;
+    const queue = new ItemQueue<ResponseItem<unknown>>();
+    const pending: PendingCall = { messageId: message.id, queue };
+    const limited = Number.isFinite(this.options.requestTimeoutMs) && this.options.requestTimeoutMs > 0;
+    if (limited) pending.timeout = setTimeout(() => {
+      if (this.pending.get(wireId) !== pending) return;
+      this.pending.delete(wireId);
+      this.sendCancel(wireId);
+      queue.push({
+        id: message.id,
+        status: { type: "error", code: "TIMEOUT", message: `Request timeout after ${this.options.requestTimeoutMs}ms`, retryable: false },
+        payload: null,
+        metadata: { [DELIVERY_METADATA_KEY]: "indeterminate" },
+      });
+      queue.end();
+    }, this.options.requestTimeoutMs);
+    this.pending.set(wireId, pending);
+
+    const onAbort = (): void => {
+      if (this.pending.get(wireId) !== pending) return;
+      this.pending.delete(wireId);
+      if (pending.timeout) clearTimeout(pending.timeout);
+      this.sendCancel(wireId);
+      queue.push(abortedItem(message.id));
+      queue.end();
+    };
+    message.signal?.addEventListener("abort", onAbort, { once: true });
+
+    try {
+      this.options.send({
+        id: wireId,
+        type: "request",
+        method: message.method,
+        payload: message.payload,
+        // The internal metadata keys stay in this process (deep dive TRN-11)
+        metadata: withoutInternalKeys(message.metadata),
+        credit: window,
+      });
+      let taken = 0;
+      for await (const item of queue) {
+        yield item as ResponseItem<TRes>;
+        // The reader took the item: give the other side credit, in batches of half the window
+        if (++taken >= window / 2 && this.pending.get(wireId) === pending) {
+          this.sendCredit(wireId, taken);
+          taken = 0;
+        }
+      }
+    } finally {
+      message.signal?.removeEventListener("abort", onAbort);
+      if (pending.timeout) clearTimeout(pending.timeout);
+      if (this.pending.get(wireId) === pending) {
+        // The reader stopped before the end: the other side stops the stream
+        this.pending.delete(wireId);
+        this.sendCancel(wireId);
+      }
+    }
+  }
+
+  /**
+   * This function takes a `response`, `error` or `stream` frame of a call that this side sent.
+   * It gives false for another frame.
+   */
+  receive(frame: WebSocketMessage): boolean {
+    if (frame.type !== "response" && frame.type !== "error" && frame.type !== "stream") return false;
+    const pending = this.pending.get(frame.id);
+    if (!pending) return false;
+    // The first frame arrived: the time limit ends. A stream can stay open longer.
+    if (pending.timeout) {
+      clearTimeout(pending.timeout);
+      pending.timeout = undefined;
+    }
+    if (frame.type === "stream" && !frame.status) {
+      if (frame.stream?.done) {
+        this.pending.delete(frame.id);
+        pending.queue.end();
+        return true;
+      }
+      pending.queue.push({ id: pending.messageId, status: { type: "success", code: 200 }, payload: frame.payload, metadata: frame.metadata || {} });
+      return true;
+    }
+    this.pending.delete(frame.id);
+    pending.queue.push(itemOfFrame(frame, pending.messageId));
+    pending.queue.end();
+    return true;
+  }
+
+  /**
+   * This function fails each call that waits: the socket closed. The other side can have run
+   * them, so their outcome is indeterminate (R1).
+   */
+  failAll(reason: string): void {
+    for (const pending of this.pending.values()) {
+      if (pending.timeout) clearTimeout(pending.timeout);
+      pending.queue.fail(new Error(reason));
+    }
+    this.pending.clear();
+  }
+
+  private sendCancel(id: string): void {
+    if (this.options.isOpen()) this.options.send({ id, type: "cancel" });
+  }
+
+  private sendCredit(id: string, credit: number): void {
+    if (this.options.isOpen()) this.options.send({ id, type: "credit", credit });
+  }
+}
+
+/** The options of `IncomingCalls`. */
+export interface IncomingCallsOptions {
+  /** The handler that serves each call: a `ProcedureServer`, a `Server`, or a function object. */
+  handler: RequestHandler;
+  /** This function sends a frame on the socket. */
+  send: (frame: WebSocketMessage) => void;
+  /** This function sends a frame and waits while the send buffer of the socket is full. */
+  sendWithBackpressure?: ((frame: WebSocketMessage, signal: AbortSignal) => Promise<void>) | undefined;
+  /** True while the socket is open. */
+  isOpen: () => boolean;
+  /** This function makes the server request of a `request` frame: the metadata, the credentials. */
+  requestOf: (frame: WebSocketMessage, signal: AbortSignal) => ServerRequest;
+}
+
+/** The calls that the other side sends on one socket, served by a handler. */
+export class IncomingCalls {
+  /** The calls that run, by wire id: a cancel frame or a closed socket aborts them */
+  private readonly inflight = new Map<string, AbortController>();
+  /** The flow control of the streams that run, by wire id */
+  private readonly credits = new Map<string, StreamCredit>();
+
+  constructor(private readonly options: IncomingCallsOptions) {}
+
+  /** The number of calls that run. */
+  get size(): number {
+    return this.inflight.size;
+  }
+
+  /**
+   * This function takes a `request`, `cancel` or `credit` frame of the other side. It gives false
+   * for another frame.
+   */
+  receive(frame: WebSocketMessage): boolean {
+    if (frame.type === "cancel") {
+      this.inflight.get(frame.id)?.abort();
+      this.inflight.delete(frame.id);
+      return true;
+    }
+    if (frame.type === "credit") {
+      if (typeof frame.credit === "number" && frame.credit > 0) this.credits.get(frame.id)?.grant(frame.credit);
+      return true;
+    }
+    if (frame.type !== "request") return false;
+    if (!frame.id || !frame.method) {
+      this.sendError(frame.id || "unknown", "Invalid message format", "INVALID_REQUEST");
+      return true;
+    }
+    // A request id names one request while it runs. A second request with the id would take the
+    // first one's controller: its stream could not be cancelled (deep dive TRN-9).
+    if (this.inflight.has(frame.id)) {
+      this.sendError(frame.id, "A request with this id is still running", "DUPLICATE_REQUEST");
+      return true;
+    }
+    void this.serve(frame);
+    return true;
+  }
+
+  /** This function aborts each call that runs: the socket closed, or the side stops. */
+  abortAll(): void {
+    for (const controller of this.inflight.values()) controller.abort();
+    this.inflight.clear();
+    this.credits.clear();
+  }
+
+  private async serve(frame: WebSocketMessage): Promise<void> {
+    const controller = new AbortController();
+    this.inflight.set(frame.id, controller);
+    try {
+      const response = await this.options.handler.handle(this.options.requestOf(frame, controller.signal));
+      if (response.stream) {
+        const credit = typeof frame.credit === "number" && frame.credit > 0 ? new StreamCredit(frame.credit) : undefined;
+        if (credit) this.credits.set(frame.id, credit);
+        await this.sendStream(frame.id, response.stream, controller.signal, credit);
+      } else {
+        const out: WebSocketMessage = {
+          id: frame.id,
+          type: response.status.type === "success" ? "response" : "error",
+          payload: response.payload,
+          metadata: response.metadata,
+          status: response.status,
+        };
+        if (response.status.type === "error") {
+          out.error = { code: response.status.code, message: response.status.message || "Unknown error", retryable: response.status.retryable };
+        }
+        this.send(out);
+      }
+    } catch (error) {
+      this.sendError(frame.id, error instanceof Error ? error.message : "Internal server error", "INTERNAL_ERROR");
+    } finally {
+      // Delete only this request's entries (deep dive TRN-9)
+      if (this.inflight.get(frame.id) === controller) this.inflight.delete(frame.id);
+      this.credits.delete(frame.id);
+    }
+  }
+
+  /**
+   * Send a stream (BUGS-2026-07 H5): one `stream` frame for each item, then a frame with
+   * `stream.done`. An error of the stream ends it with an `error` frame. When the signal aborts
+   * (a cancel frame, a closed socket), the loop stops, and the handler of the stream gets
+   * return(). The stream takes its next item only when the reader has credit for it.
+   */
+  private async sendStream(id: string, stream: AsyncIterable<unknown>, signal: AbortSignal, credit: StreamCredit | undefined): Promise<void> {
+    const iterator = stream[Symbol.asyncIterator]();
+    let done = false;
+    try {
+      for (;;) {
+        if (credit && !(await credit.take(signal))) return;
+        if (signal.aborted || !this.options.isOpen()) return;
+        const result = await iterator.next();
+        if (result.done) {
+          done = true;
+          break;
+        }
+        if (signal.aborted || !this.options.isOpen()) return;
+        const item: WebSocketMessage = { id, type: "stream", payload: result.value, stream: { done: false } };
+        if (this.options.sendWithBackpressure) await this.options.sendWithBackpressure(item, signal);
+        else this.send(item);
+      }
+      this.send({ id, type: "stream", stream: { done: true } });
+    } catch (error) {
+      done = true;
+      if (signal.aborted) return;
+      const status = errorStatus(error);
+      this.send({
+        id,
+        type: "error",
+        status,
+        error: { code: status.code, message: status.message, retryable: status.retryable },
+        stream: { done: true },
+      });
+    } finally {
+      // The loop stopped before the end: the handler gets return()
+      if (!done) await iterator.return?.();
+    }
+  }
+
+  private send(frame: WebSocketMessage): void {
+    if (this.options.isOpen()) this.options.send(frame);
+  }
+
+  private sendError(id: string, message: string, code: string): void {
+    this.send({
+      id,
+      type: "error",
+      status: { type: "error", code, message, retryable: false },
+      error: { code, message, retryable: false },
+    });
+  }
+}
+
+/** The error item of a call that its caller aborted. A retry does not repeat it. */
+function abortedItem<TRes>(id: string): ResponseItem<TRes> {
+  return { id, status: { type: "error", code: "ABORTED", message: "Request was aborted", retryable: false }, payload: null as TRes, metadata: {} };
+}

package/src/browser.ts

@@ -75,8 +75,13 @@ export {
 // ============================================================================
 export { Server } from "./server/server.js";
 export type { ServerOptions } from "./server/server.js";
-export { ProcedureServer, createProcedureServer } from "./server/procedure-server.js";
-export type { ProcedureServerOptions, StorageConfig } from "./server/procedure-server.js";
+export { ProcedureServer, createProcedureServer, STREAM_METADATA_KEY, isUnboundedStream, tokenMatches } from "./server/procedure-server.js";
+// The credentials of a network request (roadmap R18)
+export { credentialsOf, bearerOf, withoutSecretHeaders } from "./server/request-auth.js";
+// The procedures of a host: host.health, host.info, host.metrics (roadmap R19)
+export { hostProcedures } from "./server/host-procedures.js";
+export type { HostSource } from "./server/host-procedures.js";
+export type { ProcedureServerOptions, StorageConfig, StopOptions, UseStorageOptions } from "./server/procedure-server.js";
 export {
   HandlerNotFoundError,
   ServerError,
@@ -85,6 +90,9 @@ export { pathToMethod, methodToPath } from "./server/method.js";
 export type {
   ServerRequest,
   ServerResponse,
+  RequestHandler,
+  Credentials,
+  Principal,
   ServerHandler,
   ServerMiddleware,
   ServerContext,
@@ -191,6 +199,7 @@ export {
   // Meta-procedures for runtime definition
   defineProcedureProcedure,
   getProcedureProcedure,
+  manifestProcedure,
   listProceduresProcedure,
   deleteProcedureProcedure,
   metaProcedures,
@@ -222,6 +231,7 @@ export type {
   ProcedureError,
   RepositoryProvider,
   CollectionStorage,
+  StorageChanges,
   StorageMetadata,
   ProcedureModule,
   ModuleInput,
@@ -271,6 +281,7 @@ export type {
   InvokeOptions,
   ProcedureOutput,
   InvocationErrorCode,
+  ForbiddenReason,
   Invocation,
   InvocationChanges,
   InvocationNext,
@@ -294,7 +305,44 @@ export {
   explainInvocation,
   checkEffects,
 } from "./procedures/capability.js";
-export { PURE_EFFECTS, REGISTRY_READ_EFFECTS, withEffects } from "./procedures/effects.js";
+export { PURE_EFFECTS, REGISTRY_READ_EFFECTS, withEffects, INFERRED_EFFECTS_METADATA_KEY, inferredEffectsOf, effectsValue } from "./procedures/effects.js";
+// The clock of the timers, and the state machines as data (roadmap R35)
+export { realClock } from "./clock.js";
+export type { Cancel, Clock } from "./clock.js";
+export { WEBSOCKET_CONNECTION_MACHINE, CIRCUIT_BREAKER_MACHINE, replayTransitions } from "./machines.js";
+export type { MachineDocument, MachineTransition, MachineTransitionDef, MachineTimer, MachineDuration } from "./machines.js";
+// The default times of the core, as data (roadmap R34)
+export { TIMER_DEFAULTS } from "./timers.js";
+export type { TimerDefaults } from "./timers.js";
+// The transport over a message port: a Web Worker, a MessageChannel (roadmap R27)
+export { PortTransport } from "./adapters/port/transport.js";
+export type { PortLike, PortTransportOptions } from "./adapters/port/transport.js";
+// The W3C trace context: one trace from the client to the handler (roadmap R16)
+export { TRACEPARENT_METADATA_KEY, formatTraceparent, parseTraceparent, newTraceId, newSpanId, isW3cIds } from "./tracing/traceparent.js";
+export type { TraceContext } from "./tracing/traceparent.js";
+// Wire protocol v1: the version and the one list of error codes (roadmap R25)
+export { PROTOCOL_VERSION, PROTOCOL_HEADER, ERROR_CODES, isProtocolErrorCode, httpStatusOf, protocolVersionOf } from "./protocol.js";
+export type { ProtocolErrorCode, ErrorCodeInfo } from "./protocol.js";
+// The deadline of a call: the remaining time goes as procedure-timeout (roadmap R10)
+export { TIMEOUT_METADATA_KEY, DEADLINE_METADATA_KEY } from "./client/deadline.js";
+// Typed durations: each public option that is a time takes a Duration (roadmap R11)
+export { ms, seconds, minutes, hours, toMs, optionalMs, isDuration } from "./duration.js";
+export type { Duration, TimeUnit } from "./duration.js";
+// One manifest type (roadmap R17)
+export { MANIFEST_FORMAT, describeProcedure as describeProcedureEntry, describeRegistry, exposedProcedures, hashOf } from "./procedures/manifest.js";
+export type { ProcedureEntry, ProcedureManifest, CliDescription, DescribeOptions, DescribeRegistryOptions } from "./procedures/manifest.js";
+// Idempotency of calls (roadmap R1)
+export {
+  IDEMPOTENCY_KEY_METADATA,
+  MAX_IDEMPOTENCY_KEY_LENGTH,
+  IdempotencyCache,
+  idempotencyKeyOf,
+  idempotentIn,
+  effectsIn,
+  isRepeatable,
+  newIdempotencyKey,
+} from "./procedures/idempotency.js";
+export type { IdempotencyOptions } from "./procedures/idempotency.js";
 export type { ToolHints, CapabilityRefusal, CapabilityRefusalReason, InvocationExplanation, EffectsViolation } from "./procedures/capability.js";
 export type { CallPolicy, CallRefusal, HiddenCall } from "./procedures/policy.js";
 export { timeoutInterceptor, tracingInterceptor, metricsInterceptor } from "./procedures/interceptors.js";

package/src/client/call-types.ts

@@ -6,6 +6,7 @@
  */
 
 import type { ProcedurePath } from "../procedures/types.js";
+import type { Duration } from "../duration.js";
 import type { RouteLeaf, OutputConfig } from "./consumption.js";
 import { isRouteLeafWithConfig, extractInput, extractOutputConfig } from "./consumption.js";
 
@@ -22,30 +23,30 @@ export { isRouteLeafWithConfig, extractInput, extractOutputConfig } from "./cons
 export interface RetryOverride {
   /** Maximum number of retry attempts */
   attempts?: number;
-  /** Delay between retries in milliseconds */
-  delay?: number;
+  /** Delay between retries */
+  delay?: Duration;
   /** Exponential backoff multiplier */
   backoffMultiplier?: number;
   /** Maximum delay between retries */
-  maxDelay?: number;
+  maxDelay?: Duration;
 }
 
 /**
  * Per-call timeout configuration override.
  */
 export interface TimeoutOverride {
-  /** Overall request timeout in milliseconds */
-  ms?: number;
+  /** The overall timeout of the request */
+  overall?: Duration;
   /** Per-attempt timeout for retries */
-  perAttempt?: number;
+  perAttempt?: Duration;
 }
 
 /**
  * Per-call cache configuration override.
  */
 export interface CacheOverride {
-  /** Time-to-live in milliseconds */
-  ttl?: number;
+  /** Time-to-live */
+  ttl?: Duration;
   /** Skip cache for this request */
   bypass?: boolean;
   /** Force cache refresh */
@@ -66,8 +67,7 @@ export interface MiddlewareOverrides {
 
 /**
  * This function converts the overrides of a route call to the context keys that the middleware
- * reads: `retry.attempts` becomes `retry.maxAttempts`, and `timeout.ms` becomes
- * `timeout.overall`. The other keys pass unchanged. (Before, the documented keys had no
+ * reads: `retry.attempts` becomes `retry.maxAttempts`. The other keys pass unchanged. (Before, the documented keys had no
  * effect: deep dive CORE-14.)
  *
  * @param overrides - The `middlewares` of a route call
@@ -84,10 +84,6 @@ export function toMiddlewareContext(overrides: MiddlewareOverrides | undefined):
     const { attempts, ...rest } = overrides.retry;
     context["retry"] = attempts === undefined ? rest : { ...rest, maxAttempts: attempts };
   }
-  if (overrides.timeout) {
-    const { ms, ...rest } = overrides.timeout;
-    context["timeout"] = ms === undefined ? rest : { ...rest, overall: ms };
-  }
   return context;
 }