@procedures/client 0.2.2 → 0.3.0

package/src/client/middleware/retry.ts

@@ -5,9 +5,14 @@
  * Works with any transport!
  */
 
-import type { ClientRunner, ClientContext, ResponseItem, TypedClientMiddleware } from "../types.js";
+import type { ClientRunner, ClientContext, Method, ResponseItem, TypedClientMiddleware } from "../types.js";
 import type { RetryContext } from "./contexts.js";
-import { abortedItem, sleep, thrownItem } from "./items.js";
+import { abortedItem, deliveryOf, retryAfterOf, sleep, thrownItem } from "./items.js";
+import { realClock, type Clock } from "../../clock.js";
+import { backoffDelay } from "@mark1russell7/service/backoff";
+import { IDEMPOTENCY_KEY_METADATA, idempotencyKeyOf, newIdempotencyKey } from "../../procedures/idempotency.js";
+import { isDuration, optionalMs, type Duration } from "../../duration.js";
+import { TIMER_DEFAULTS } from "../../timers.js";
 
 /**
  * Retry middleware options.
@@ -20,11 +25,17 @@ export interface RetryOptions {
   maxRetries?: number;
 
   /**
-   * Base delay in milliseconds for exponential backoff.
+   * The clock of the backoff and of the budget (roadmap R35). The default is the clock of the
+   * platform. A test gives a fake clock.
+   */
+  clock?: Clock;
+
+  /**
+   * Base delay for exponential backoff, for example `ms(500)`.
    * Actual delay will be: baseDelay * 2^attempt + jitter
-   * @default 1000
+   * @default 1 second
    */
-  retryDelay?: number;
+  retryDelay?: Duration;
 
   /**
    * The factor of the delay from one attempt to the next.
@@ -33,21 +44,47 @@ export interface RetryOptions {
   backoffMultiplier?: number;
 
   /**
-   * The longest delay between two attempts, in milliseconds.
+   * The longest delay between two attempts.
    * @default no limit
    */
-  maxDelay?: number;
+  maxDelay?: Duration;
 
   /**
-   * Maximum jitter as a fraction of the delay (0-1).
-   * Adds randomness to prevent thundering herd.
-   * @default 0.1 (10% jitter)
+   * The random part of each delay, from 0 to 1. With 1 (full jitter), the delay is a random time
+   * from 0 to the backoff, so the clients that failed together do not retry together. 0 gives the
+   * backoff exactly.
+   * @default 1 (full jitter; roadmap R12: before, 0.1 gave a delay within 10 percent of the backoff)
    */
   jitter?: number;
 
+  /**
+   * The retry budget of this middleware: each call adds `ratio` of a retry to the budget, and each
+   * retry takes one. When the budget is empty, an error goes to the caller without a retry, so a
+   * failing service gets at most `ratio` more requests, not `maxRetries` times more. Besides the
+   * budget, `minPerSecond` retries a second are always allowed. `false` turns the budget off.
+   * @default { ratio: 0.2, minPerSecond: 10 }
+   */
+  budget?: { ratio?: number; minPerSecond?: number } | false;
+
+  /**
+   * The calls that the middleware can send again after a try with an indeterminate outcome: the
+   * request left, and no answer came (a reset, a closed connection, the timeout of one try). The
+   * server can have run such a call, so only an idempotent call goes again (roadmap R1).
+   *
+   * - a function: true for an idempotent method. `idempotentIn(registry)` reads the effects of
+   *   the procedures that the client knows.
+   * - `true`: every call. Use it only with a server that removes duplicate calls by their
+   *   idempotency key (`ProcedureServer` does).
+   * - absent: only a call with `retry: { idempotent: true }` in its context.
+   *
+   * A try that did not leave the client (a refused connection) and an error that the server
+   * marks retryable go again in each case.
+   */
+  idempotent?: boolean | ((method: Method) => boolean | undefined);
+
   /**
    * Custom function to determine if a request should be retried.
-   * Takes precedence over Status.retryable flag.
+   * Takes precedence over Status.retryable flag. The rule of `idempotent` still applies.
    *
    * @param item - The response item
    * @param attempt - Current attempt number (0-indexed)
@@ -96,7 +133,7 @@ export interface RetryOptions {
  * @example
  * ```typescript
  * // Create middleware with defaults
- * client.use(createRetryMiddleware({ maxRetries: 3 }));
+ * client.use(createRetryMiddleware({ maxRetries: 3, retryDelay: ms(500) }));
  *
  * // Override per-call via context
  * await client.call(method, payload, {
@@ -105,54 +142,121 @@ export interface RetryOptions {
  * ```
  */
 export function createRetryMiddleware(options: RetryOptions = {}): TypedClientMiddleware<RetryContext, {}> {
+  const defaultRetryDelay = optionalMs(options.retryDelay, "retryDelay") ?? TIMER_DEFAULTS.retry.retryDelayMs;
   const {
-    retryDelay: defaultRetryDelay = 1000,
-    jitter: defaultJitter = 0.1,
+    jitter: defaultJitter = 1,
     shouldRetry: customShouldRetry,
     onBeforeRetry,
     onAfterRetry,
+    idempotent: idempotentOption,
   } = options;
-  const defaultMaxRetries = options.maxRetries ?? 3;
-  const defaultMultiplier = options.backoffMultiplier ?? 2;
-  const defaultMaxDelay = options.maxDelay ?? Number.POSITIVE_INFINITY;
+  const defaultMaxRetries = options.maxRetries ?? TIMER_DEFAULTS.retry.maxRetries;
+  const defaultMultiplier = options.backoffMultiplier ?? TIMER_DEFAULTS.retry.backoffMultiplier;
+  const defaultMaxDelay = optionalMs(options.maxDelay, "maxDelay") ?? TIMER_DEFAULTS.retry.maxDelayMs;
 
-  /** The overrides of one call (`retry: { ... }` in its context). Before, only maxAttempts was read. */
-  const overridesOf = (value: unknown): Partial<Pick<RetryContext["retry"], "maxAttempts" | "delay" | "backoffMultiplier" | "maxDelay">> => {
+  /**
+   * The overrides of one call (`retry: { ... }` in its context), with the delays in milliseconds.
+   * Before, only maxAttempts was read.
+   */
+  const overridesOf = (value: unknown): { maxAttempts?: number; delay?: number; backoffMultiplier?: number; maxDelay?: number } => {
     if (typeof value !== "object" || value === null) return {};
-    const out: Partial<Pick<RetryContext["retry"], "maxAttempts" | "delay" | "backoffMultiplier" | "maxDelay">> = {};
-    for (const key of ["maxAttempts", "delay", "backoffMultiplier", "maxDelay"] as const) {
+    const out: { maxAttempts?: number; delay?: number; backoffMultiplier?: number; maxDelay?: number } = {};
+    for (const key of ["maxAttempts", "backoffMultiplier"] as const) {
       const field = (value as Record<string, unknown>)[key];
       if (typeof field === "number" && Number.isFinite(field) && field >= 0) out[key] = field;
     }
+    for (const key of ["delay", "maxDelay"] as const) {
+      const field = (value as Record<string, unknown>)[key];
+      if (field !== undefined) {
+        if (!isDuration(field)) throw new TypeError(`retry.${key} must be a duration such as ms(500) (roadmap R11)`);
+        out[key] = optionalMs(field, `retry.${key}`)!;
+      }
+    }
     return out;
   };
 
-  /** The backoff delay of an attempt: exponential, with jitter, at most the maximum delay */
-  const backoffDelay = (attempt: number, overrides: ReturnType<typeof overridesOf>): number => {
-    const baseDelay = (overrides.delay ?? defaultRetryDelay) * Math.pow(overrides.backoffMultiplier ?? defaultMultiplier, attempt);
-    const jitterAmount = defaultJitter * baseDelay * (Math.random() * 2 - 1);
-    return Math.max(0, Math.min(overrides.maxDelay ?? defaultMaxDelay, baseDelay + jitterAmount));
+  /**
+   * The backoff delay of an attempt (from 0): exponential, at most the maximum delay, with the
+   * random part of `jitter` (full jitter by default). The backoff is `backoffDelay` of
+   * `@mark1russell7/service/backoff` (roadmap R37), whose tries start at 1.
+   */
+  const retryDelayOf = (attempt: number, overrides: ReturnType<typeof overridesOf>): number =>
+    backoffDelay(
+      {
+        base: overrides.delay ?? defaultRetryDelay,
+        factor: overrides.backoffMultiplier ?? defaultMultiplier,
+        cap: overrides.maxDelay ?? defaultMaxDelay,
+        jitter: { kind: "subtract", fraction: Math.min(1, Math.max(0, defaultJitter)) },
+      },
+      attempt + 1,
+    );
+
+  // The retry budget (R12): a balance of retries that each call fills by `ratio`
+  const budget = options.budget === false ? undefined : { ratio: options.budget?.ratio ?? 0.2, minPerSecond: options.budget?.minPerSecond ?? 10 };
+  const budgetCap = budget ? Math.max(1, budget.ratio * 100) : 0;
+  let balance = budgetCap;
+  const clock = options.clock ?? realClock;
+  let secondStart = clock.now();
+  let retriesThisSecond = 0;
+  /** This function takes one retry from the budget, or gives false when the budget is empty. */
+  const takeRetry = (): boolean => {
+    if (!budget) return true;
+    if (balance >= 1) {
+      balance -= 1;
+      return true;
+    }
+    const now = clock.now();
+    if (now - secondStart >= 1000) {
+      secondStart = now;
+      retriesThisSecond = 0;
+    }
+    if (retriesThisSecond < budget.minPerSecond) {
+      retriesThisSecond++;
+      return true;
+    }
+    return false;
+  };
+
+  /** True when the call can go again after an indeterminate try: the call says so, or the option. */
+  const isIdempotent = (method: Method, value: unknown): boolean => {
+    const own = typeof value === "object" && value !== null ? (value as { idempotent?: unknown }).idempotent : undefined;
+    if (typeof own === "boolean") return own;
+    if (typeof idempotentOption === "function") return idempotentOption(method) === true;
+    return idempotentOption === true;
   };
 
   return <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
     return async function* (context: ClientContext<TReq>) {
       // Read from metadata first (user-provided context), then fall back to options
-      const overrides = overridesOf(context.message.metadata.retry);
-      const maxRetries = overrides.maxAttempts ?? defaultMaxRetries;
-      const shouldRetryItem = (item: ResponseItem<TRes>, attempt: number): boolean =>
-        customShouldRetry
+      const given = context.message.metadata.retry;
+      const overrides = overridesOf(given);
+      // maxAttempts counts the attempts: the first try and the retries (R12: before, the override
+      // was used as the number of retries, against its name and its documentation)
+      const maxRetries = overrides.maxAttempts !== undefined ? Math.max(0, overrides.maxAttempts - 1) : defaultMaxRetries;
+      if (budget) balance = Math.min(budgetCap, balance + budget.ratio);
+      const idempotent = isIdempotent(context.message.method, context.message.metadata.retry);
+      const shouldRetryItem = (item: ResponseItem<TRes>, attempt: number): boolean => {
+        const wanted = customShouldRetry
           ? customShouldRetry(item, attempt)
           : item.status.type === "error" && item.status.retryable;
+        // A request that can have run goes again only when the call is idempotent (R1). Before,
+        // a reset or a timeout of one try sent a write again.
+        return wanted && (deliveryOf(item) !== "indeterminate" || idempotent);
+      };
       const signal = context.message.signal;
       const baseId = context.message.id;
+      // One key for all the tries of the call: a server that removes duplicates runs it one time
+      const idempotencyKey = idempotencyKeyOf(context.message.metadata) ?? newIdempotencyKey();
+      context.message.metadata[IDEMPOTENCY_KEY_METADATA] = idempotencyKey;
 
       let attempt = 0;
       for (;;) {
         // Update retry metadata with current state
         context.message.metadata.retry = {
-          ...overrides,
+          ...(typeof given === "object" && given !== null ? (given as object) : {}),
           attempt,
-          maxAttempts: maxRetries,
+          maxAttempts: maxRetries + 1,
+          idempotent,
         };
         // Each attempt gets its own request id. The id correlates the frames of one attempt
         // on the wire: a cancelled attempt can still answer under its id (deep dive TRN-8/9).
@@ -204,7 +308,15 @@ export function createRetryMiddleware(options: RetryOptions = {}): TypedClientMi
           return;
         }
 
-        let delay = backoffDelay(attempt, overrides);
+        // The budget is empty: the error goes to the caller (R12)
+        if (!takeRetry()) {
+          yield retryItem;
+          if (onAfterRetry) await onAfterRetry(false, attempt);
+          return;
+        }
+
+        // A server that asks for a wait (Retry-After) gets at least that wait (R12)
+        let delay = Math.max(retryDelayOf(attempt, overrides), retryAfterOf(retryItem) ?? 0);
 
         // Before retry hook
         if (onBeforeRetry) {
@@ -225,7 +337,7 @@ export function createRetryMiddleware(options: RetryOptions = {}): TypedClientMi
         }
 
         // The backoff stops at once when the caller aborts (deep dive TRN-8)
-        if (!(await sleep(delay, signal))) {
+        if (!(await sleep(delay, signal, clock))) {
           yield abortedItem<TRes>(context.message.id);
           return;
         }

package/src/client/middleware/timeout.ts

@@ -5,26 +5,29 @@
  * Works with any transport!
  */
 
-import type { ClientMiddleware, ClientRunner, ClientContext, ResponseItem, TypedClientMiddleware } from "../types.js";
-import { ABORTED_FIRST, errorItem, nextOrAbort } from "./items.js";
+import type { ClientRunner, ClientContext, ResponseItem, TypedClientMiddleware } from "../types.js";
+import { ABORTED_FIRST, abortedItem, errorItem, nextOrAbort, withDelivery } from "./items.js";
 import type { TimeoutContext } from "./contexts.js";
+import { deadlineOf, narrowDeadline, restoreDeadline } from "../deadline.js";
+import { resilience } from "./resilience.js";
+import { optionalMs, type Duration } from "../../duration.js";
 
 /**
  * Timeout middleware options.
  */
 export interface TimeoutOptions {
   /**
-   * Timeout in milliseconds for the entire request (including retries).
+   * The time of the entire request (including retries), for example `seconds(10)`.
    * @default undefined (no overall timeout)
    */
-  overall?: number;
+  overall?: Duration | undefined;
 
   /**
-   * Timeout in milliseconds for each individual attempt.
+   * The time of each individual attempt, for example `seconds(2)`.
    * Useful with retry middleware for per-attempt timeouts.
    * @default undefined (no per-attempt timeout)
    */
-  perAttempt?: number;
+  perAttempt?: Duration | undefined;
 
   /**
    * Custom timeout error message.
@@ -89,17 +92,18 @@ function composeAbortSignals(...signals: (AbortSignal | undefined)[]): {
     }
   }
 
-  // Fallback: Manual composition for older environments
+  // Fallback: Manual composition for older environments. The composed signal keeps the reason of
+  // the signal that aborted, as with AbortSignal.any() (before, it got a new AbortError).
   const controller = new AbortController();
   const abortListeners: Array<() => void> = [];
 
   for (const signal of validSignals) {
     if (signal.aborted) {
-      controller.abort();
+      controller.abort(signal.reason);
       break;
     }
 
-    const listener = () => controller.abort();
+    const listener = () => controller.abort(signal.reason);
     signal.addEventListener("abort", listener, { once: true });
     abortListeners.push(() => signal.removeEventListener("abort", listener));
   }
@@ -116,7 +120,8 @@ function composeAbortSignals(...signals: (AbortSignal | undefined)[]): {
 /**
  * Run `next` with a timeout. When the time runs out, the request's signal aborts, and the
  * reader gets one TIMEOUT error item in place of the transport's ABORTED item or thrown error.
- * The middleware does not wait for a transport that ignores the signal.
+ * The middleware does not wait for a transport that ignores the signal: not after the timeout,
+ * and not after an abort of the caller, which gives an ABORTED item.
  *
  * Before, the middleware waited for a thrown error, but the transports yield error items: the
  * reader got "ABORTED" (not retryable), so a per-attempt timeout with retry never retried, and
@@ -131,25 +136,34 @@ async function* runWithTimeout<TReq, TRes>(
 ): AsyncGenerator<ResponseItem<TRes>, void, undefined> {
   const timeoutController = new AbortController();
   const timeoutId = setTimeout(() => timeoutController.abort(), ms);
+  // The overall timeout is the deadline of the call: the transport sends its remaining time to
+  // the server (roadmap R10). The timeout of one try is not: the server keeps a keyed write
+  // until the next try can get its result, and the request signal stops another call.
+  const deadlineBefore = retryable ? deadlineOf(context.message.metadata) : narrowDeadline(context.message.metadata, Date.now() + ms);
 
   // Compose with existing signal
   const originalSignal = context.message.signal;
   const { controller: composedController, cleanup } = composeAbortSignals(originalSignal, timeoutController.signal);
   context.message.signal = composedController.signal;
   const timedOut = (): boolean => timeoutController.signal.aborted && !originalSignal?.aborted;
-  const timeoutItem = (): ResponseItem<TRes> => errorItem<TRes>(context.message.id, "TIMEOUT", message, retryable);
+  // The request left before the time ran out: the server can still run it (R1)
+  const timeoutItem = (): ResponseItem<TRes> =>
+    withDelivery(errorItem<TRes>(context.message.id, "TIMEOUT", message, retryable), "indeterminate");
 
   const iterator = next(context)[Symbol.asyncIterator]();
   // "running": a next() may be pending; "done": the iterator ended; "abandoned": the timeout won
   let phase: "running" | "done" | "abandoned" = "running";
   try {
     for (;;) {
-      const result = await nextOrAbort(iterator, timeoutController.signal);
+      // The timeout and the abort of the caller both end the wait (roadmap R30: before, the wait
+      // ignored the abort of the caller, so a transport that ignored the signal kept the caller
+      // waiting until the timeout, and the caller got TIMEOUT for its own abort)
+      const result = await nextOrAbort(iterator, composedController.signal);
       if (result === ABORTED_FIRST) {
         phase = "abandoned";
-        // The transport did not stop in time: end it in the background, and give the timeout
+        // The transport did not stop in time: end it in the background, and give the timeout or the abort
         void Promise.resolve(iterator.return?.()).catch(() => undefined);
-        yield timeoutItem();
+        yield timedOut() ? timeoutItem() : abortedItem<TRes>(context.message.id);
         return;
       }
       if (result.done) {
@@ -172,6 +186,7 @@ async function* runWithTimeout<TReq, TRes>(
     throw error;
   } finally {
     clearTimeout(timeoutId);
+    restoreDeadline(context.message.metadata, deadlineBefore);
     cleanup();
     // Restore the caller's original signal; we only swapped in the composed signal for this
     // attempt. Leaving the (possibly aborted) composed signal in place poisons subsequent
@@ -200,22 +215,24 @@ async function* runWithTimeout<TReq, TRes>(
  * @example
  * ```typescript
  * // Create middleware with default timeout
- * client.use(createOverallTimeoutMiddleware({ overall: 5000 }));
+ * client.use(createOverallTimeoutMiddleware({ overall: seconds(5) }));
  *
  * // Override per-call via context
  * await client.call(method, payload, {
- *   context: { timeout: { overall: 10000 } }
+ *   context: { timeout: { overall: seconds(10) } }
  * });
  * ```
  */
 export function createOverallTimeoutMiddleware(options: Pick<TimeoutOptions, "overall" | "message">): TypedClientMiddleware<TimeoutContext, {}> {
-  const { overall: defaultOverall, message = "Overall request timeout" } = options;
+  const { message = "Overall request timeout" } = options;
+  const defaultOverall = optionalMs(options.overall, "overall");
 
   return <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
     return async function* (context: ClientContext<TReq>) {
       // Read from metadata first (user-provided context), then fall back to options
-      const overall = (context.message.metadata.timeout as TimeoutContext["timeout"] | undefined)?.overall
-        ?? defaultOverall;
+      const overall =
+        optionalMs((context.message.metadata.timeout as TimeoutContext["timeout"] | undefined)?.overall, "timeout.overall") ??
+        defaultOverall;
 
       if (!overall) {
         // No timeout - passthrough
@@ -243,22 +260,24 @@ export function createOverallTimeoutMiddleware(options: Pick<TimeoutOptions, "ov
  * @example
  * ```typescript
  * // Create middleware with default timeout
- * client.use(createTimeoutMiddleware({ perAttempt: 1000 }));
+ * client.use(createTimeoutMiddleware({ perAttempt: seconds(1) }));
  *
  * // Override per-call via context
  * await client.call(method, payload, {
- *   context: { timeout: { perAttempt: 2000 } }
+ *   context: { timeout: { perAttempt: seconds(2) } }
  * });
  * ```
  */
 export function createTimeoutMiddleware(options: Pick<TimeoutOptions, "perAttempt" | "message">): TypedClientMiddleware<TimeoutContext, {}> {
-  const { perAttempt: defaultPerAttempt, message = "Request timeout" } = options;
+  const { message = "Request timeout" } = options;
+  const defaultPerAttempt = optionalMs(options.perAttempt, "perAttempt");
 
   return <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
     return async function* (context: ClientContext<TReq>) {
       // Read from metadata first (user-provided context), then fall back to options
-      const perAttempt = (context.message.metadata.timeout as TimeoutContext["timeout"] | undefined)?.perAttempt
-        ?? defaultPerAttempt;
+      const perAttempt =
+        optionalMs((context.message.metadata.timeout as TimeoutContext["timeout"] | undefined)?.perAttempt, "timeout.perAttempt") ??
+        defaultPerAttempt;
 
       if (!perAttempt) {
         // No timeout - passthrough
@@ -266,8 +285,12 @@ export function createTimeoutMiddleware(options: Pick<TimeoutOptions, "perAttemp
         return;
       }
 
+      // The limit of one try is at most the remaining time of the call (roadmap R10)
+      const deadline = deadlineOf(context.message.metadata);
+      const limit = deadline === undefined ? perAttempt : Math.max(0, Math.min(perAttempt, deadline - Date.now()));
+
       // A retry middleware outside this one can start a new attempt
-      yield* runWithTimeout(next, context, perAttempt, message, true);
+      yield* runWithTimeout(next, context, limit, message, true);
     };
   };
 }
@@ -275,34 +298,20 @@ export function createTimeoutMiddleware(options: Pick<TimeoutOptions, "perAttemp
 /**
  * Create combined timeout middleware with both overall and per-attempt timeouts.
  *
+ * @deprecated Use `resilience({ overall, perAttempt, retry })`. This function puts the two
+ * timeouts in one slot, so a retry middleware that you add with another `use()` cannot sit
+ * between them: the retry is outside both, or inside both. `resilience` puts the retry between
+ * them (roadmap R10).
+ *
  * @param options - Timeout configuration
  * @returns Middleware function
  *
  * @example
  * ```typescript
- * client.use(createCombinedTimeoutMiddleware({
- *   overall: 5000,     // 5 seconds total
- *   perAttempt: 1000   // 1 second per attempt
- * }));
+ * client.use(resilience({ overall: seconds(5), perAttempt: seconds(1), retry: { maxRetries: 2 } }));
  * ```
  */
 export function createCombinedTimeoutMiddleware(options: TimeoutOptions): TypedClientMiddleware<TimeoutContext, {}> {
   const { overall, perAttempt, message = "Request timeout" } = options;
-
-  return <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
-    // Compose both timeout middlewares
-    let composed: ClientRunner<TReq, TRes> = next;
-
-    if (perAttempt) {
-      const perAttemptMiddleware = createTimeoutMiddleware({ perAttempt, message: `${message} (per-attempt)` }) as ClientMiddleware<TReq, TRes>;
-      composed = perAttemptMiddleware(composed);
-    }
-
-    if (overall) {
-      const overallMiddleware = createOverallTimeoutMiddleware({ overall, message: `${message} (overall)` }) as ClientMiddleware<TReq, TRes>;
-      composed = overallMiddleware(composed);
-    }
-
-    return composed;
-  };
+  return resilience({ overall, perAttempt, message }) as TypedClientMiddleware<TimeoutContext, {}>;
 }

package/src/client/middleware/tracing.ts

@@ -14,6 +14,7 @@
 
 import type { TypedClientMiddleware } from "../types.js";
 import type { TracingContext } from "./contexts.js";
+import { TRACEPARENT_METADATA_KEY, formatTraceparent, isW3cIds, newSpanId, newTraceId, parseTraceparent } from "../../tracing/traceparent.js";
 
 /**
  * Tracing Configuration
@@ -98,9 +99,10 @@ function generateId(): string {
 export function createTracingMiddleware(
   options: TracingOptions = {}
 ): TypedClientMiddleware<TracingContext, {}> {
+  // W3C ids by default, so the server continues the trace (roadmap R16)
   const {
-    generateTraceId = generateId,
-    generateSpanId = generateId,
+    generateTraceId = newTraceId,
+    generateSpanId = newSpanId,
     getCurrentTrace,
     serviceName,
   } = options;
@@ -108,8 +110,9 @@ export function createTracingMiddleware(
   return (next) => async function* (context) {
     // Check if there's already tracing metadata
     if (!context.message.metadata.tracing) {
-      // Try to get current trace context
-      const currentTrace = getCurrentTrace?.();
+      // Try to get current trace context: the function of the options, or the trace context of
+      // the caller (a call that a handler makes on a server carries the span of that handler)
+      const currentTrace = getCurrentTrace?.() ?? parseTraceparent(context.message.metadata[TRACEPARENT_METADATA_KEY]) ?? null;
 
       if (currentTrace) {
         // Continue existing trace (create child span)
@@ -132,6 +135,12 @@ export function createTracingMiddleware(
       }
     }
 
+    // The W3C trace context of the call: the server continues this trace (R16)
+    const tracing = context.message.metadata.tracing;
+    if (tracing && isW3cIds(tracing.traceId, tracing.spanId)) {
+      context.message.metadata[TRACEPARENT_METADATA_KEY] = formatTraceparent(tracing.traceId, tracing.spanId);
+    }
+
     // Continue middleware chain
     yield* next(context);
   };

package/src/client/types.ts

@@ -26,7 +26,13 @@ export interface Method {
   /** Operation name (e.g., "get", "create", "update", "delete", "watch") */
   operation: string;
 
-  /** Optional version (e.g., "v1", "v2") */
+  /**
+   * Optional version (e.g., "v1", "v2").
+   *
+   * @deprecated The wire protocol (v1, roadmap R25) has no version of a procedure: the server
+   * ignores this field. A URL strategy can put it in the path. Use a new path for a procedure
+   * that changes in a way that is not compatible.
+   */
   version?: string;
 }
 
@@ -66,6 +72,8 @@ export interface Metadata {
   retry?: {
     attempt: number;
     maxAttempts: number;
+    /** True: a second run of the call changes nothing more, so a retry is safe */
+    idempotent?: boolean;
   };
 
   /** Extensible for custom fields */

package/src/clock.ts

@@ -0,0 +1,21 @@
+/**
+ * The clock of the core (roadmap R35). The retry, the circuit breaker and the WebSocket client
+ * read the time and start their timers only through a clock. Thus a test gives a fake clock, and
+ * the timing is exact and repeatable.
+ *
+ * The clock comes from `@mark1russell7/service/clock` (roadmap R37). The entry imports nothing
+ * else, and it has 228 bytes of gzip. The `fakeClock` of `@mark1russell7/service/testing` fits here.
+ * A `Cancel` of the platform also has `unref`. The circuit breaker uses it for its reset: a breaker
+ * must not keep a process alive for its reset time (BUGS-2026-07 M4).
+ */
+
+import { platformClock, type Cancel, type Clock } from "@mark1russell7/service/clock";
+
+export type { Cancel, Clock };
+
+/**
+ * The clock of the platform: `performance.now()` and `setTimeout`. Its timers keep a Node process
+ * alive, as `setTimeout` does: a script that waits for a retry does not end during the wait. The
+ * `realClock` of the service package is different: its timers do not keep a process alive.
+ */
+export const realClock: Clock = platformClock();

package/src/duration.ts

@@ -0,0 +1,56 @@
+/**
+ * Typed durations (roadmap R11).
+ *
+ * Each public option of this package that is a time takes a `Duration`: a quantity of
+ * `@mark1russell7/quantity` with a time unit. A plain number is a type error, so `timeout: 5`
+ * cannot mean five milliseconds in one place and five seconds in another. The wire keeps
+ * milliseconds (`procedure-timeout`), and the internals convert each duration one time, when an
+ * option is read.
+ *
+ * `@mark1russell7/quantity` has no `Duration` type yet. This alias narrows its `Quantity` to the
+ * time units, so the type also refuses `{ value: 5, unit: "kg" }`.
+ */
+
+import { quantity, valueIn, type Quantity } from "@mark1russell7/quantity";
+
+/** The canonical time units of `@mark1russell7/quantity` that a duration of this package uses. */
+export type TimeUnit = "ns" | "us" | "ms" | "s" | "min" | "h" | "d";
+
+/** A time: a quantity with a time unit. */
+export type Duration = Quantity & { readonly unit: TimeUnit };
+
+const TIME_UNITS: ReadonlySet<string> = new Set<TimeUnit>(["ns", "us", "ms", "s", "min", "h", "d"]);
+
+/** This function makes a duration of milliseconds. */
+export const ms = (value: number): Duration => quantity(value, "ms") as Duration;
+/** This function makes a duration of seconds. */
+export const seconds = (value: number): Duration => quantity(value, "s") as Duration;
+/** This function makes a duration of minutes. */
+export const minutes = (value: number): Duration => quantity(value, "min") as Duration;
+/** This function makes a duration of hours. */
+export const hours = (value: number): Duration => quantity(value, "h") as Duration;
+
+/** True when a value is a duration: a finite number with a time unit. */
+export function isDuration(value: unknown): value is Duration {
+  if (value === null || typeof value !== "object") return false;
+  const { value: amount, unit } = value as { value?: unknown; unit?: unknown };
+  return typeof amount === "number" && Number.isFinite(amount) && typeof unit === "string" && TIME_UNITS.has(unit);
+}
+
+/**
+ * The number of milliseconds of a duration. A value that is not a duration (a plain number, or
+ * a quantity of another kind) throws a `TypeError` that names the option.
+ */
+export function toMs(duration: Duration, option = "duration"): number {
+  if (!isDuration(duration)) {
+    throw new TypeError(
+      `${option} must be a duration such as ms(500) or seconds(2), got ${JSON.stringify(duration)}. Plain numbers are not durations (roadmap R11).`,
+    );
+  }
+  return valueIn(duration, "ms");
+}
+
+/** The milliseconds of an optional duration, or undefined. */
+export function optionalMs(duration: Duration | undefined, option?: string): number | undefined {
+  return duration === undefined ? undefined : toMs(duration, option);
+}