@procedures/client 0.0.0-stage → 0.1.0

package/src/client/middleware/items.ts

@@ -0,0 +1,114 @@
+/**
+ * Helpers that the client middlewares share.
+ *
+ * The transports report a failure as an error item, not as a thrown error. The middlewares use
+ * the same style: a timeout, an abort or a refused retry is an error item, and `Client` throws
+ * it when `throwOnError` is on (deep dive TRN-7: before, the timeout middleware waited for a
+ * thrown error that the transports never threw).
+ */
+
+import type { ResponseItem } from "../types.js";
+
+/** This function makes an error item. */
+export function errorItem<TRes>(id: string, code: string, message: string, retryable: boolean): ResponseItem<TRes> {
+  return { id, status: { type: "error", code, message, retryable }, payload: null as TRes, metadata: {} };
+}
+
+/** The error item of a request that its caller aborted. A retry does not repeat it. */
+export function abortedItem<TRes>(id: string): ResponseItem<TRes> {
+  return errorItem<TRes>(id, "ABORTED", "Request was aborted", false);
+}
+
+const NETWORK_CODES = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ECONNABORTED",
+  "EPIPE",
+  "ETIMEDOUT",
+  "ENETUNREACH",
+  "EHOSTUNREACH",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "UND_ERR_SOCKET",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "NETWORK_ERROR",
+  "CONNECTION_REFUSED",
+]);
+
+/**
+ * This function tells if a thrown error is a network failure: the connection failed or broke.
+ * A retry can repair a network failure. A validation error, an open circuit breaker or a rate
+ * limit cannot be repaired by a retry (deep dive TRN-8).
+ */
+export function isNetworkError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const code = (error as { code?: unknown }).code;
+  if (typeof code === "string" && NETWORK_CODES.has(code)) return true;
+  const cause = (error as { cause?: unknown }).cause;
+  if (cause !== undefined && cause !== error && isNetworkError(cause)) return true;
+  // fetch() rejects with TypeError("fetch failed") when the connection fails
+  if (error.name === "TypeError" && /fetch failed|network/i.test(error.message)) return true;
+  // The WebSocket transport fails the requests of a connection that closed or never opened
+  return /WebSocket (connection closed|disconnected)|Connection timeout/.test(error.message);
+}
+
+/**
+ * The item that stands for a thrown error, so that `shouldRetry` can decide about it. It is
+ * retryable only when the error is a network failure.
+ */
+export function thrownItem<TRes>(id: string, error: unknown): ResponseItem<TRes> {
+  const code = (error as { code?: unknown } | undefined)?.code;
+  return errorItem<TRes>(
+    id,
+    typeof code === "string" ? code : "THROWN",
+    error instanceof Error ? error.message : String(error),
+    isNetworkError(error),
+  );
+}
+
+/**
+ * This function waits `ms` milliseconds. It returns false at once when the signal aborts (deep
+ * dive TRN-8: before, the backoff of the retry middleware ignored the signal).
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<boolean> {
+  if (signal?.aborted) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      resolve(false);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve(true);
+    }, Math.max(0, ms));
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** The value that `nextOrAbort` gives when the signal aborts first. */
+export const ABORTED_FIRST: unique symbol = Symbol("aborted first");
+
+/**
+ * The next result of an iterator, or `ABORTED_FIRST` when the signal aborts first. A transport
+ * that ignores the signal cannot keep the caller waiting past its timeout.
+ */
+export function nextOrAbort<T>(
+  iterator: AsyncIterator<T>,
+  signal: AbortSignal,
+): Promise<IteratorResult<T> | typeof ABORTED_FIRST> {
+  if (signal.aborted) return Promise.resolve(ABORTED_FIRST);
+  return new Promise((resolve, reject) => {
+    const onAbort = (): void => resolve(ABORTED_FIRST);
+    signal.addEventListener("abort", onAbort, { once: true });
+    iterator.next().then(
+      (result) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(result);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}

package/src/client/middleware/lru.ts

@@ -0,0 +1,66 @@
+/**
+ * A map with a capacity, for the cache middleware.
+ *
+ * A JavaScript `Map` keeps its keys in the order of insertion. A read moves its key to the end,
+ * so the first key is always the least recently used one. A write that goes over the capacity
+ * removes the first key. The core has this small map itself, so it does not depend on
+ * `@procedures/collections` (roadmap 3.3: before, the cache composed `lruMap` and
+ * `hashMap` of that package).
+ */
+export class LruMap<K, V> {
+  private readonly entries = new Map<K, V>();
+
+  /**
+   * @param capacity - The largest number of keys. A positive whole number.
+   * @param onEvict - Called for each key that a write removes to keep the capacity.
+   */
+  constructor(
+    private readonly capacity: number,
+    private readonly onEvict?: (key: K, value: V) => void
+  ) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      throw new RangeError(`The capacity of an LRU map must be a positive whole number, not ${capacity}`);
+    }
+  }
+
+  /** The number of keys. */
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /** True when the map has the key. This does not count as a use. */
+  has(key: K): boolean {
+    return this.entries.has(key);
+  }
+
+  /** The value of the key, or undefined. A read makes the key the most recently used one. */
+  get(key: K): V | undefined {
+    if (!this.entries.has(key)) return undefined;
+    const value = this.entries.get(key) as V;
+    this.entries.delete(key);
+    this.entries.set(key, value);
+    return value;
+  }
+
+  /** Set the value of a key, as the most recently used one. Over the capacity, the oldest key goes. */
+  set(key: K, value: V): void {
+    this.entries.delete(key);
+    this.entries.set(key, value);
+    while (this.entries.size > this.capacity) {
+      const oldest = this.entries.keys().next().value as K;
+      const evicted = this.entries.get(oldest) as V;
+      this.entries.delete(oldest);
+      this.onEvict?.(oldest, evicted);
+    }
+  }
+
+  /** Delete a key. True when it existed. */
+  delete(key: K): boolean {
+    return this.entries.delete(key);
+  }
+
+  /** Delete every key. */
+  clear(): void {
+    this.entries.clear();
+  }
+}

package/src/client/middleware/pagination.ts

@@ -0,0 +1,213 @@
+/**
+ * Universal Pagination Middleware
+ *
+ * Protocol-agnostic pagination handling.
+ * Works with any transport!
+ */
+
+import type { ClientRunner, ClientContext, TypedClientMiddleware } from "../types.js";
+import type { PaginationContext } from "./contexts.js";
+
+/**
+ * Pagination middleware options.
+ */
+export interface PaginationOptions {
+  /**
+   * Default page size
+   * @default 50
+   */
+  defaultLimit?: number;
+
+  /**
+   * Maximum page size (prevents abuse)
+   * @default 1000
+   */
+  maxLimit?: number;
+
+  /**
+   * Page parameter name in metadata
+   * @default "page"
+   */
+  pageKey?: string;
+
+  /**
+   * Limit parameter name in metadata
+   * @default "limit"
+   */
+  limitKey?: string;
+
+  /**
+   * Offset parameter name in metadata (alternative to page)
+   * @default "offset"
+   */
+  offsetKey?: string;
+
+  /**
+   * Whether to use offset-based pagination instead of page-based
+   * @default false
+   */
+  useOffset?: boolean;
+}
+
+/**
+ * Create pagination middleware.
+ *
+ * Automatically handles pagination parameters in request metadata:
+ * - Applies default limit if not specified
+ * - Enforces maximum limit to prevent abuse
+ * - Supports both page-based and offset-based pagination
+ *
+ * @param options - Pagination configuration
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * // Page-based pagination
+ * client.use(createPaginationMiddleware({
+ *   defaultLimit: 50,
+ *   maxLimit: 1000
+ * }));
+ *
+ * await client.call(
+ *   { service: "users", operation: "list" },
+ *   {},
+ *   { page: 2, limit: 100 } // Metadata
+ * );
+ *
+ * // Offset-based pagination
+ * client.use(createPaginationMiddleware({
+ *   useOffset: true,
+ *   defaultLimit: 50
+ * }));
+ *
+ * await client.call(
+ *   { service: "users", operation: "list" },
+ *   {},
+ *   { offset: 100, limit: 50 } // Metadata
+ * );
+ * ```
+ */
+export function createPaginationMiddleware(
+  options: PaginationOptions = {}
+): TypedClientMiddleware<PaginationContext, {}> {
+  const {
+    defaultLimit = 50,
+    maxLimit = 1000,
+    pageKey = "page",
+    limitKey = "limit",
+    offsetKey = "offset",
+    useOffset = false,
+  } = options;
+
+  return <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
+    return async function* (context: ClientContext<TReq>) {
+      const { metadata } = context.message;
+
+      // Extract pagination params
+      let page = metadata[pageKey] as number | undefined;
+      let limit = metadata[limitKey] as number | undefined;
+      let offset = metadata[offsetKey] as number | undefined;
+
+      // Apply defaults and limits
+      if (limit === undefined) {
+        limit = defaultLimit;
+      } else {
+        // Enforce maximum limit
+        limit = Math.min(Math.max(1, limit), maxLimit);
+      }
+
+      if (useOffset) {
+        // Offset-based pagination
+        if (offset === undefined) {
+          offset = 0;
+        } else {
+          offset = Math.max(0, offset);
+        }
+
+        // Update message metadata, with the state as one object (PaginationContext)
+        context.message.metadata = {
+          ...metadata,
+          [offsetKey]: offset,
+          [limitKey]: limit,
+          pagination: { offset, limit },
+        };
+      } else {
+        // Page-based pagination
+        if (page === undefined) {
+          page = 1;
+        } else {
+          page = Math.max(1, page);
+        }
+
+        // Update message metadata, with the state as one object (PaginationContext)
+        context.message.metadata = {
+          ...metadata,
+          [pageKey]: page,
+          [limitKey]: limit,
+          pagination: { page, limit },
+        };
+
+        // Optionally compute offset for backends that need it
+        const computedOffset = (page - 1) * limit;
+        if (metadata["includeOffset"]) {
+          context.message.metadata[offsetKey] = computedOffset;
+          context.message.metadata["pagination"] = { page, offset: computedOffset, limit };
+        }
+      }
+
+      // Execute request
+      yield* next(context);
+    };
+  };
+}
+
+/**
+ * Helper to create an async iterator for paginated results.
+ *
+ * Automatically fetches all pages and yields items as they arrive.
+ *
+ * @param client - The client instance
+ * @param method - Method to call
+ * @param payload - Request payload
+ * @param options - Pagination options
+ * @returns Async iterable of all items across all pages
+ *
+ * @example
+ * ```typescript
+ * // Fetch all users across all pages
+ * for await (const user of paginateAll(client, { service: "users", operation: "list" }, {})) {
+ *   console.log(user);
+ * }
+ * ```
+ */
+export async function* paginateAll<TReq, TRes extends { items: any[]; hasMore?: boolean; total?: number }>(
+  client: { call: (method: any, payload: TReq, metadata?: any) => Promise<TRes> },
+  method: any,
+  payload: TReq,
+  options: { limit?: number; maxPages?: number } = {}
+): AsyncIterable<TRes extends { items: (infer U)[] } ? U : never> {
+  const { limit = 50, maxPages = Infinity } = options;
+  let page = 1;
+  let hasMore = true;
+
+  while (hasMore && page <= maxPages) {
+    const response = await client.call(method, payload, { page, limit });
+
+    // Yield all items from this page
+    for (const item of response.items) {
+      yield item;
+    }
+
+    // Check if there are more pages
+    if (response.hasMore !== undefined) {
+      hasMore = response.hasMore;
+    } else if (response.total !== undefined) {
+      hasMore = page * limit < response.total;
+    } else {
+      // If no pagination metadata, check if we got a full page
+      hasMore = response.items.length === limit;
+    }
+
+    page++;
+  }
+}

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

@@ -0,0 +1,315 @@
+/**
+ * Rate Limiting Middleware
+ *
+ * Throttles requests using token bucket algorithm.
+ * Prevents overwhelming services with too many requests.
+ *
+ * Works with both client and server!
+ */
+
+import type { ClientMiddleware, ClientRunner, ClientContext, TypedClientMiddleware } from "../types.js";
+import type { RateLimitContext } from "./contexts.js";
+import { abortedItem } from "./items.js";
+
+/**
+ * Rate limiting options.
+ */
+export interface RateLimitOptions {
+  /**
+   * Maximum number of requests per time window.
+   * @default 100
+   */
+  maxRequests?: number;
+
+  /**
+   * Time window in milliseconds.
+   * @default 60000 (1 minute)
+   */
+  window?: number;
+
+  /**
+   * Behavior when rate limit is exceeded.
+   * - "reject": Throw error immediately
+   * - "queue": Queue requests and process when capacity available
+   * @default "reject"
+   */
+  strategy?: "reject" | "queue";
+
+  /**
+   * Maximum queue size (only for "queue" strategy).
+   * @default 100
+   */
+  maxQueueSize?: number;
+
+  /**
+   * Custom error message.
+   */
+  message?: string;
+
+  /**
+   * Callback when rate limit is exceeded.
+   */
+  onRateLimitExceeded?: (stats: RateLimitStats) => void;
+}
+
+/**
+ * Rate limit statistics.
+ */
+export interface RateLimitStats {
+  tokensAvailable: number;
+  maxTokens: number;
+  queueSize: number;
+  totalRequests: number;
+  rejectedRequests: number;
+}
+
+/**
+ * Rate limit error thrown when limit exceeded.
+ */
+export class RateLimitError extends Error {
+  constructor(
+    message: string,
+    public readonly stats: RateLimitStats
+  ) {
+    super(message);
+    this.name = "RateLimitError";
+  }
+}
+
+/**
+ * Queued request for "queue" strategy.
+ */
+interface QueuedRequest {
+  resolve: () => void;
+  reject: (error: Error) => void;
+  timestamp: number;
+}
+
+/**
+ * Create rate limiting middleware using token bucket algorithm.
+ *
+ * @param options - Rate limiting configuration
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * // Reject strategy (default)
+ * client.use(createRateLimitMiddleware({
+ *   maxRequests: 100,    // 100 requests
+ *   window: 60000,       // per minute
+ *   strategy: "reject"   // Throw error when exceeded
+ * }));
+ *
+ * // Queue strategy
+ * client.use(createRateLimitMiddleware({
+ *   maxRequests: 10,
+ *   window: 1000,
+ *   strategy: "queue",   // Queue requests when exceeded
+ *   maxQueueSize: 50
+ * }));
+ * ```
+ */
+export function createRateLimitMiddleware(
+  options: RateLimitOptions = {}
+): TypedClientMiddleware<RateLimitContext, {}> {
+  const {
+    maxRequests = 100,
+    window = 60000,
+    strategy = "reject",
+    maxQueueSize = 100,
+    message = "Rate limit exceeded",
+    onRateLimitExceeded,
+  } = options;
+
+  // Token bucket state
+  let tokens = maxRequests;
+  let lastRefill = Date.now();
+  let totalRequests = 0;
+  let rejectedRequests = 0;
+
+  // Queue for "queue" strategy
+  const queue: QueuedRequest[] = [];
+  let drainTimer: ReturnType<typeof setTimeout> | undefined;
+
+  /**
+   * Refill tokens based on elapsed time.
+   */
+  function refillTokens(): void {
+    const now = Date.now();
+    const elapsed = now - lastRefill;
+
+    if (elapsed >= window) {
+      // Full refill
+      tokens = maxRequests;
+      lastRefill = now;
+    } else {
+      // Partial refill (tokens per millisecond * elapsed time)
+      const tokensToAdd = (maxRequests / window) * elapsed;
+      tokens = Math.min(maxRequests, tokens + tokensToAdd);
+      lastRefill = now;
+    }
+  }
+
+  /**
+   * Get current statistics.
+   */
+  function getStats(): RateLimitStats {
+    return {
+      tokensAvailable: Math.floor(tokens),
+      maxTokens: maxRequests,
+      queueSize: queue.length,
+      totalRequests,
+      rejectedRequests,
+    };
+  }
+
+  /**
+   * Acquire a token (blocking for queue strategy). Returns false when the signal aborted the
+   * wait. A new request waits behind the queued requests, also when a token is free: before,
+   * an arrival could take the token of a queued request (deep dive TRN-12).
+   */
+  async function acquireToken(signal?: AbortSignal): Promise<boolean> {
+    refillTokens();
+
+    if (queue.length === 0 && tokens >= 1) {
+      // Token available
+      tokens -= 1;
+      return true;
+    }
+
+    // No tokens available
+    const stats = getStats();
+
+    if (strategy === "reject") {
+      // Reject immediately
+      rejectedRequests++;
+      if (onRateLimitExceeded) {
+        onRateLimitExceeded(stats);
+      }
+      throw new RateLimitError(message, stats);
+    }
+
+    // Queue strategy - wait for token
+    if (queue.length >= maxQueueSize) {
+      rejectedRequests++;
+      if (onRateLimitExceeded) {
+        onRateLimitExceeded(stats);
+      }
+      throw new RateLimitError(`${message} (queue full)`, stats);
+    }
+
+    if (signal?.aborted) return false;
+
+    return new Promise<boolean>((resolve) => {
+      const request: QueuedRequest = {
+        resolve: () => {
+          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)
+      const onAbort = (): void => {
+        const index = queue.indexOf(request);
+        if (index >= 0) queue.splice(index, 1);
+        resolve(false);
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      queue.push(request);
+      scheduleDrain();
+    });
+  }
+
+  /**
+   * Give tokens to the queued requests, in order, and wait for the next token while the queue
+   * is not empty. The timer keeps the process alive while requests wait: before, an unref'd
+   * timer let the process exit with queued requests that never ran (deep dive TRN-12).
+   */
+  function scheduleDrain(): void {
+    if (drainTimer !== undefined) return;
+    refillTokens();
+    while (queue.length > 0 && tokens >= 1) {
+      tokens -= 1;
+      queue.shift()!.resolve();
+    }
+    if (queue.length === 0) return;
+    // The time until the next whole token
+    const wait = Math.max(1, Math.ceil(((1 - tokens) * window) / maxRequests));
+    drainTimer = setTimeout(() => {
+      drainTimer = undefined;
+      scheduleDrain();
+    }, wait);
+  }
+
+  const middleware = <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
+    return async function* (context: ClientContext<TReq>) {
+      totalRequests++;
+
+      // Acquire token (may throw or wait)
+      if (!(await acquireToken(context.message.signal))) {
+        yield abortedItem<TRes>(context.message.id);
+        return;
+      }
+      // The state for the other middlewares (RateLimitContext)
+      context.message.metadata["rateLimit"] = {
+        tokensAvailable: Math.floor(tokens),
+        maxTokens: maxRequests,
+        queueSize: queue.length,
+      };
+
+      // Execute request
+      yield* next(context);
+    };
+  };
+  return middleware;
+}
+
+/**
+ * Create per-service rate limiter.
+ *
+ * Applies different rate limits based on service name.
+ *
+ * @example
+ * ```typescript
+ * client.use(createPerServiceRateLimiter({
+ *   users: { maxRequests: 100, window: 60000 },
+ *   orders: { maxRequests: 50, window: 60000 },
+ *   default: { maxRequests: 200, window: 60000 }
+ * }));
+ * ```
+ */
+export function createPerServiceRateLimiter(
+  limits: Record<string, RateLimitOptions> & { default?: RateLimitOptions }
+): ClientMiddleware {
+  // Create rate limiter for each service
+  const limiters = new Map<string, ClientMiddleware>();
+
+  for (const [service, options] of Object.entries(limits)) {
+    limiters.set(service, createRateLimitMiddleware(options));
+  }
+
+  const defaultLimiter = limits.default
+    ? createRateLimitMiddleware(limits.default)
+    : null;
+
+  return <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
+    return async function* (context: ClientContext<TReq>) {
+      // Get service name from context
+      const service = context.message.method.service;
+
+      // Get appropriate limiter
+      const limiter = limiters.get(service) ?? defaultLimiter;
+
+      if (limiter) {
+        // Apply service-specific rate limit
+        const typedLimiter = limiter as ClientMiddleware<TReq, TRes>;
+        const limitedNext = typedLimiter(next);
+        yield* limitedNext(context);
+      } else {
+        // No rate limit for this service
+        yield* next(context);
+      }
+    };
+  };
+}