@procedures/client 0.0.0-stage → 0.1.0

package/dist/client/middleware/rate-limit.js

@@ -0,0 +1,222 @@
+/**
+ * Rate Limiting Middleware
+ *
+ * Throttles requests using token bucket algorithm.
+ * Prevents overwhelming services with too many requests.
+ *
+ * Works with both client and server!
+ */
+import { abortedItem } from "./items.js";
+/**
+ * Rate limit error thrown when limit exceeded.
+ */
+export class RateLimitError extends Error {
+    stats;
+    constructor(message, stats) {
+        super(message);
+        this.stats = stats;
+        this.name = "RateLimitError";
+    }
+}
+/**
+ * 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 = {}) {
+    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 = [];
+    let drainTimer;
+    /**
+     * Refill tokens based on elapsed time.
+     */
+    function refillTokens() {
+        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() {
+        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) {
+        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((resolve) => {
+            const request = {
+                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 = () => {
+                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() {
+        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 = (next) => {
+        return async function* (context) {
+            totalRequests++;
+            // Acquire token (may throw or wait)
+            if (!(await acquireToken(context.message.signal))) {
+                yield abortedItem(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) {
+    // Create rate limiter for each service
+    const limiters = new Map();
+    for (const [service, options] of Object.entries(limits)) {
+        limiters.set(service, createRateLimitMiddleware(options));
+    }
+    const defaultLimiter = limits.default
+        ? createRateLimitMiddleware(limits.default)
+        : null;
+    return (next) => {
+        return async function* (context) {
+            // 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;
+                const limitedNext = typedLimiter(next);
+                yield* limitedNext(context);
+            }
+            else {
+                // No rate limit for this service
+                yield* next(context);
+            }
+        };
+    };
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/client/middleware/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../../src/client/middleware/rate-limit.ts"],"names":[],"mappings":"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"}

package/dist/client/middleware/retry.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Universal Retry Middleware
+ *
+ * Protocol-agnostic retry with exponential backoff and jitter.
+ * Works with any transport!
+ */
+import type { ResponseItem, TypedClientMiddleware } from "../types.js";
+import type { RetryContext } from "./contexts.js";
+/**
+ * Retry middleware options.
+ */
+export interface RetryOptions {
+    /**
+     * Maximum number of retry attempts.
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Base delay in milliseconds for exponential backoff.
+     * Actual delay will be: baseDelay * 2^attempt + jitter
+     * @default 1000
+     */
+    retryDelay?: number;
+    /**
+     * The factor of the delay from one attempt to the next.
+     * @default 2
+     */
+    backoffMultiplier?: number;
+    /**
+     * The longest delay between two attempts, in milliseconds.
+     * @default no limit
+     */
+    maxDelay?: number;
+    /**
+     * Maximum jitter as a fraction of the delay (0-1).
+     * Adds randomness to prevent thundering herd.
+     * @default 0.1 (10% jitter)
+     */
+    jitter?: number;
+    /**
+     * Custom function to determine if a request should be retried.
+     * Takes precedence over Status.retryable flag.
+     *
+     * @param item - The response item
+     * @param attempt - Current attempt number (0-indexed)
+     * @returns true if the request should be retried
+     */
+    shouldRetry?: (item: ResponseItem<unknown>, attempt: number) => boolean;
+    /**
+     * Hook called before each retry attempt.
+     * Can modify delay or abort retry.
+     *
+     * @param item - The response item that triggered retry
+     * @param attempt - Current attempt number (0-indexed)
+     * @returns Object with shouldRetry and optional delayMs override
+     */
+    onBeforeRetry?: (item: ResponseItem<unknown>, attempt: number) => Promise<{
+        shouldRetry: boolean;
+        delayMs?: number;
+    }> | {
+        shouldRetry: boolean;
+        delayMs?: number;
+    };
+    /**
+     * Hook called after each retry completes (success or failure).
+     *
+     * @param success - Whether the retry succeeded
+     * @param attempt - Attempt number that just completed
+     */
+    onAfterRetry?: (success: boolean, attempt: number) => Promise<void> | void;
+}
+/**
+ * Create retry middleware with exponential backoff and jitter.
+ *
+ * Features:
+ * - Protocol-agnostic: Works with HTTP, gRPC, WebSocket, local
+ * - Uses Status.retryable flag (no protocol-specific knowledge)
+ * - Exponential backoff with jitter
+ * - Custom retry predicates
+ * - Before/after retry hooks
+ * - Respects AbortSignal
+ * - **Context override**: Values from metadata.retry take precedence over options:
+ *   `maxAttempts`, `delay`, `backoffMultiplier` and `maxDelay` (the `route()` overrides)
+ *
+ * @param options - Retry configuration (defaults, can be overridden per-call)
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * // Create middleware with defaults
+ * client.use(createRetryMiddleware({ maxRetries: 3 }));
+ *
+ * // Override per-call via context
+ * await client.call(method, payload, {
+ *   context: { retry: { maxAttempts: 5 } }
+ * });
+ * ```
+ */
+export declare function createRetryMiddleware(options?: RetryOptions): TypedClientMiddleware<RetryContext, {}>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/client/middleware/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/client/middleware/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAA+B,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAExE;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CACd,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,EAC3B,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAEtG;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,YAAiB,GAAG,qBAAqB,CAAC,YAAY,EAAE,EAAE,CAAC,CAiIzG"}

package/dist/client/middleware/retry.js

@@ -0,0 +1,150 @@
+/**
+ * Universal Retry Middleware
+ *
+ * Protocol-agnostic retry with exponential backoff and jitter.
+ * Works with any transport!
+ */
+import { abortedItem, sleep, thrownItem } from "./items.js";
+/**
+ * Create retry middleware with exponential backoff and jitter.
+ *
+ * Features:
+ * - Protocol-agnostic: Works with HTTP, gRPC, WebSocket, local
+ * - Uses Status.retryable flag (no protocol-specific knowledge)
+ * - Exponential backoff with jitter
+ * - Custom retry predicates
+ * - Before/after retry hooks
+ * - Respects AbortSignal
+ * - **Context override**: Values from metadata.retry take precedence over options:
+ *   `maxAttempts`, `delay`, `backoffMultiplier` and `maxDelay` (the `route()` overrides)
+ *
+ * @param options - Retry configuration (defaults, can be overridden per-call)
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * // Create middleware with defaults
+ * client.use(createRetryMiddleware({ maxRetries: 3 }));
+ *
+ * // Override per-call via context
+ * await client.call(method, payload, {
+ *   context: { retry: { maxAttempts: 5 } }
+ * });
+ * ```
+ */
+export function createRetryMiddleware(options = {}) {
+    const { retryDelay: defaultRetryDelay = 1000, jitter: defaultJitter = 0.1, shouldRetry: customShouldRetry, onBeforeRetry, onAfterRetry, } = options;
+    const defaultMaxRetries = options.maxRetries ?? 3;
+    const defaultMultiplier = options.backoffMultiplier ?? 2;
+    const defaultMaxDelay = options.maxDelay ?? Number.POSITIVE_INFINITY;
+    /** The overrides of one call (`retry: { ... }` in its context). Before, only maxAttempts was read. */
+    const overridesOf = (value) => {
+        if (typeof value !== "object" || value === null)
+            return {};
+        const out = {};
+        for (const key of ["maxAttempts", "delay", "backoffMultiplier", "maxDelay"]) {
+            const field = value[key];
+            if (typeof field === "number" && Number.isFinite(field) && field >= 0)
+                out[key] = field;
+        }
+        return out;
+    };
+    /** The backoff delay of an attempt: exponential, with jitter, at most the maximum delay */
+    const backoffDelay = (attempt, overrides) => {
+        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));
+    };
+    return (next) => {
+        return async function* (context) {
+            // 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, attempt) => customShouldRetry
+                ? customShouldRetry(item, attempt)
+                : item.status.type === "error" && item.status.retryable;
+            const signal = context.message.signal;
+            const baseId = context.message.id;
+            let attempt = 0;
+            for (;;) {
+                // Update retry metadata with current state
+                context.message.metadata.retry = {
+                    ...overrides,
+                    attempt,
+                    maxAttempts: maxRetries,
+                };
+                // 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).
+                context.message.id = attempt === 0 ? baseId : `${baseId}.retry${attempt}`;
+                // Check if cancelled before attempt
+                if (signal?.aborted) {
+                    yield abortedItem(context.message.id);
+                    return;
+                }
+                // The items pass through as they arrive (BUGS-2026-07 M2: before, the middleware
+                // collected the whole stream first). A retry is possible only while no item has
+                // reached the reader: the first item is a retryable error, or the attempt throws
+                // before its first item. After that, a retry would repeat items.
+                let started = false;
+                let lastItem;
+                let retryItem;
+                try {
+                    for await (const item of next(context)) {
+                        if (!started && attempt < maxRetries && shouldRetryItem(item, attempt)) {
+                            retryItem = item;
+                            break;
+                        }
+                        started = true;
+                        lastItem = item;
+                        yield item;
+                    }
+                }
+                catch (error) {
+                    const isAborted = signal?.aborted || (error instanceof Error && error.name === "AbortError");
+                    if (started || isAborted || attempt >= maxRetries) {
+                        throw error;
+                    }
+                    // A thrown error is retried only when it is a network failure, or when shouldRetry
+                    // says so. Before, every thrown error was retried: a validation error, an open
+                    // circuit breaker, a rate limit (deep dive TRN-8).
+                    const item = thrownItem(context.message.id, error);
+                    if (!shouldRetryItem(item, attempt)) {
+                        throw error;
+                    }
+                    retryItem = item;
+                }
+                if (retryItem === undefined) {
+                    // Success, a non-retryable error, or the last attempt
+                    if (onAfterRetry) {
+                        await onAfterRetry(lastItem?.status.type === "success", attempt);
+                    }
+                    return;
+                }
+                let delay = backoffDelay(attempt, overrides);
+                // Before retry hook
+                if (onBeforeRetry) {
+                    const hookResult = await onBeforeRetry(retryItem, attempt);
+                    if (!hookResult.shouldRetry) {
+                        // Hook decided not to retry - yield the error and return
+                        yield retryItem;
+                        if (onAfterRetry) {
+                            await onAfterRetry(false, attempt);
+                        }
+                        return;
+                    }
+                    // Use custom delay if provided by hook
+                    if (hookResult.delayMs !== undefined) {
+                        delay = hookResult.delayMs;
+                    }
+                }
+                // The backoff stops at once when the caller aborts (deep dive TRN-8)
+                if (!(await sleep(delay, signal))) {
+                    yield abortedItem(context.message.id);
+                    return;
+                }
+                attempt++;
+            }
+        };
+    };
+}
+//# sourceMappingURL=retry.js.map

package/dist/client/middleware/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/client/middleware/retry.ts"],"names":[],"mappings":"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"}

package/dist/client/middleware/timeout.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Universal Timeout Middleware
+ *
+ * Protocol-agnostic timeout handling with per-request and overall timeouts.
+ * Works with any transport!
+ */
+import type { TypedClientMiddleware } from "../types.js";
+import type { TimeoutContext } from "./contexts.js";
+/**
+ * Timeout middleware options.
+ */
+export interface TimeoutOptions {
+    /**
+     * Timeout in milliseconds for the entire request (including retries).
+     * @default undefined (no overall timeout)
+     */
+    overall?: number;
+    /**
+     * Timeout in milliseconds for each individual attempt.
+     * Useful with retry middleware for per-attempt timeouts.
+     * @default undefined (no per-attempt timeout)
+     */
+    perAttempt?: number;
+    /**
+     * Custom timeout error message.
+     * @default "Request timeout"
+     */
+    message?: string;
+}
+/**
+ * Create overall timeout middleware.
+ *
+ * Applies timeout to the entire request, including all retry attempts.
+ * If timeout is exceeded, the request is aborted.
+ *
+ * **Context Override**: metadata.timeout.overall takes precedence over options.
+ *
+ * @param options - Timeout configuration (defaults, can be overridden per-call)
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * // Create middleware with default timeout
+ * client.use(createOverallTimeoutMiddleware({ overall: 5000 }));
+ *
+ * // Override per-call via context
+ * await client.call(method, payload, {
+ *   context: { timeout: { overall: 10000 } }
+ * });
+ * ```
+ */
+export declare function createOverallTimeoutMiddleware(options: Pick<TimeoutOptions, "overall" | "message">): TypedClientMiddleware<TimeoutContext, {}>;
+/**
+ * Create per-attempt timeout middleware.
+ *
+ * Applies timeout to each individual attempt (useful with retry middleware).
+ * Each retry gets a fresh timeout.
+ *
+ * **Context Override**: metadata.timeout.perAttempt takes precedence over options.
+ *
+ * @param options - Timeout configuration (defaults, can be overridden per-call)
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * // Create middleware with default timeout
+ * client.use(createTimeoutMiddleware({ perAttempt: 1000 }));
+ *
+ * // Override per-call via context
+ * await client.call(method, payload, {
+ *   context: { timeout: { perAttempt: 2000 } }
+ * });
+ * ```
+ */
+export declare function createTimeoutMiddleware(options: Pick<TimeoutOptions, "perAttempt" | "message">): TypedClientMiddleware<TimeoutContext, {}>;
+/**
+ * Create combined timeout middleware with both overall and per-attempt timeouts.
+ *
+ * @param options - Timeout configuration
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * client.use(createCombinedTimeoutMiddleware({
+ *   overall: 5000,     // 5 seconds total
+ *   perAttempt: 1000   // 1 second per attempt
+ * }));
+ * ```
+ */
+export declare function createCombinedTimeoutMiddleware(options: TimeoutOptions): TypedClientMiddleware<TimeoutContext, {}>;
+//# sourceMappingURL=timeout.d.ts.map

package/dist/client/middleware/timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../../src/client/middleware/timeout.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAA+D,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEtH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA2JD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,SAAS,CAAC,GAAG,qBAAqB,CAAC,cAAc,EAAE,EAAE,CAAC,CAmB9I;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,GAAG,SAAS,CAAC,GAAG,qBAAqB,CAAC,cAAc,EAAE,EAAE,CAAC,CAmB1I;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,cAAc,GAAG,qBAAqB,CAAC,cAAc,EAAE,EAAE,CAAC,CAmBlH"}