@procedures/client 0.2.3 → 0.4.0

package/src/client/middleware/lru.ts

@@ -63,4 +63,16 @@ export class LruMap<K, V> {
   clear(): void {
     this.entries.clear();
   }
+
+  /** Delete each key whose value matches. This does not count as a use. The number deleted. */
+  deleteWhere(matches: (value: V, key: K) => boolean): number {
+    let deleted = 0;
+    for (const [key, value] of this.entries) {
+      if (matches(value, key)) {
+        this.entries.delete(key);
+        deleted++;
+      }
+    }
+    return deleted;
+  }
 }

package/src/client/middleware/rate-limit.ts

@@ -10,6 +10,8 @@
 import type { ClientMiddleware, ClientRunner, ClientContext, TypedClientMiddleware } from "../types.js";
 import type { RateLimitContext } from "./contexts.js";
 import { abortedItem } from "./items.js";
+import { optionalMs, type Duration } from "../../duration.js";
+import { TIMER_DEFAULTS } from "../../timers.js";
 
 /**
  * Rate limiting options.
@@ -25,7 +27,7 @@ export interface RateLimitOptions {
    * Time window in milliseconds.
    * @default 60000 (1 minute)
    */
-  window?: number;
+  window?: Duration;
 
   /**
    * Behavior when rate limit is exceeded.
@@ -81,7 +83,6 @@ export class RateLimitError extends Error {
  */
 interface QueuedRequest {
   resolve: () => void;
-  reject: (error: Error) => void;
   timestamp: number;
 }
 
@@ -96,14 +97,14 @@ interface QueuedRequest {
  * // Reject strategy (default)
  * client.use(createRateLimitMiddleware({
  *   maxRequests: 100,    // 100 requests
- *   window: 60000,       // per minute
+ *   window: minutes(1),
  *   strategy: "reject"   // Throw error when exceeded
  * }));
  *
  * // Queue strategy
  * client.use(createRateLimitMiddleware({
  *   maxRequests: 10,
- *   window: 1000,
+ *   window: seconds(1),
  *   strategy: "queue",   // Queue requests when exceeded
  *   maxQueueSize: 50
  * }));
@@ -114,12 +115,12 @@ export function createRateLimitMiddleware(
 ): TypedClientMiddleware<RateLimitContext, {}> {
   const {
     maxRequests = 100,
-    window = 60000,
     strategy = "reject",
     maxQueueSize = 100,
     message = "Rate limit exceeded",
     onRateLimitExceeded,
   } = options;
+  const window = optionalMs(options.window, "window") ?? TIMER_DEFAULTS.rateLimit.windowMs;
 
   // Token bucket state
   let tokens = maxRequests;
@@ -206,7 +207,6 @@ export function createRateLimitMiddleware(
           signal?.removeEventListener("abort", onAbort);
           resolve(true);
         },
-        reject: () => resolve(false),
         timestamp: Date.now(),
       };
       // A queued request whose caller aborts leaves the queue (before, it kept its place)
@@ -273,9 +273,9 @@ export function createRateLimitMiddleware(
  * @example
  * ```typescript
  * client.use(createPerServiceRateLimiter({
- *   users: { maxRequests: 100, window: 60000 },
- *   orders: { maxRequests: 50, window: 60000 },
- *   default: { maxRequests: 200, window: 60000 }
+ *   users: { maxRequests: 100, window: minutes(1) },
+ *   orders: { maxRequests: 50, window: minutes(1) },
+ *   default: { maxRequests: 200, window: minutes(1) }
  * }));
  * ```
  */

package/src/client/middleware/resilience.ts

@@ -0,0 +1,81 @@
+/**
+ * The resilience preset (roadmap R10): the timeouts, the cache, the retry, the circuit breaker and
+ * the rate limit of a client, in the one order that works.
+ *
+ * The first layer is the outermost one:
+ *
+ * 1. The overall timeout: it covers the whole call, retries included.
+ * 2. The cache: a hit makes no request, so no try and no slot of the rate limit.
+ * 3. The retry: it starts each try.
+ * 4. The circuit breaker: it counts each try, and an open breaker stops a retry loop.
+ * 5. The rate limit: each try takes a slot.
+ * 6. The timeout of one try: inside the retry, so the retry can start the next try.
+ *
+ * Each order pitfall of a hand-made stack is impossible here: an overall timeout inside the
+ * retry, a per-try timeout outside it, or a rate limit outside the retry. The deadline of the
+ * call goes to the server as `procedure-timeout` with each try (`client/deadline.ts`).
+ */
+
+import type { ClientMiddleware, ClientRunner, TypedClientMiddleware } from "../types.js";
+import type { CacheContext, CircuitBreakerContext, RateLimitContext, RetryContext, TimeoutContext } from "./contexts.js";
+import { createCacheMiddleware, type CacheOptions } from "./cache.js";
+import { createCircuitBreakerMiddleware, type CircuitBreakerOptions } from "./circuit-breaker.js";
+import { createRateLimitMiddleware, type RateLimitOptions } from "./rate-limit.js";
+import { createRetryMiddleware, type RetryOptions } from "./retry.js";
+import { createOverallTimeoutMiddleware, createTimeoutMiddleware } from "./timeout.js";
+import type { Duration } from "../../duration.js";
+
+/** The parts of the preset. An absent part is not in the stack. */
+export interface ResilienceOptions {
+  /** The time of the whole call, retries included. */
+  overall?: Duration | undefined;
+  /** The time of one try. It is at most the remaining time of the call. */
+  perAttempt?: Duration | undefined;
+  /** The retry. Its `idempotent` option decides which calls go again after an indeterminate try. */
+  retry?: RetryOptions | undefined;
+  /** The circuit breaker. */
+  breaker?: CircuitBreakerOptions | undefined;
+  /** The cache of the reads that opt in. */
+  cache?: CacheOptions | undefined;
+  /** The rate limit of the tries. */
+  rateLimit?: RateLimitOptions | undefined;
+  /** The message of a timeout error. */
+  message?: string | undefined;
+}
+
+/** The context that the preset gives: the context of each part that it can have. */
+export type ResilienceContext = TimeoutContext & Partial<RetryContext & CacheContext & CircuitBreakerContext & RateLimitContext>;
+
+/**
+ * This function gives one middleware with the parts of `options` in the correct order (see the
+ * file comment). Add it with one `use()`.
+ *
+ * @example
+ * ```typescript
+ * const client = new Client(transport).use(
+ *   resilience({
+ *     overall: seconds(10),
+ *     perAttempt: seconds(3),
+ *     retry: { maxRetries: 2, idempotent: idempotentIn(registry) },
+ *     breaker: { failureThreshold: 5 },
+ *   }),
+ * );
+ * ```
+ */
+export function resilience(options: ResilienceOptions): TypedClientMiddleware<ResilienceContext, {}> {
+  const layers: ClientMiddleware[] = [];
+  const message = options.message;
+  if (options.overall) {
+    layers.push(createOverallTimeoutMiddleware({ overall: options.overall, ...(message ? { message: `${message} (overall)` } : {}) }) as ClientMiddleware);
+  }
+  if (options.cache) layers.push(createCacheMiddleware(options.cache) as ClientMiddleware);
+  if (options.retry) layers.push(createRetryMiddleware(options.retry) as ClientMiddleware);
+  if (options.breaker) layers.push(createCircuitBreakerMiddleware(options.breaker) as ClientMiddleware);
+  if (options.rateLimit) layers.push(createRateLimitMiddleware(options.rateLimit) as ClientMiddleware);
+  if (options.perAttempt) {
+    layers.push(createTimeoutMiddleware({ perAttempt: options.perAttempt, ...(message ? { message: `${message} (per-attempt)` } : {}) }) as ClientMiddleware);
+  }
+  const composed = <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> =>
+    layers.reduceRight<ClientRunner<TReq, TRes>>((inner, layer) => (layer as ClientMiddleware<TReq, TRes>)(inner), next);
+  return composed as TypedClientMiddleware<ResilienceContext, {}>;
+}

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;
         }