@procedures/client 0.0.0-stage → 0.2.0

package/dist/client/middleware/timeout.js

@@ -0,0 +1,253 @@
+/**
+ * Universal Timeout Middleware
+ *
+ * Protocol-agnostic timeout handling with per-request and overall timeouts.
+ * Works with any transport!
+ */
+import { ABORTED_FIRST, errorItem, nextOrAbort } from "./items.js";
+/**
+ * Compose multiple AbortSignals into one.
+ *
+ * Uses AbortSignal.any() if available (Node 20+, modern browsers),
+ * otherwise falls back to manual composition with cleanup.
+ *
+ * Returns a controller whose signal aborts when ANY of the input signals abort.
+ *
+ * @param signals - Array of signals to compose (undefined values filtered out)
+ * @returns Object with controller and cleanup function
+ */
+function composeAbortSignals(...signals) {
+    const validSignals = signals.filter((s) => s !== undefined);
+    if (validSignals.length === 0) {
+        return {
+            controller: new AbortController(),
+            cleanup: () => { },
+        };
+    }
+    if (validSignals.length === 1) {
+        // Single signal - no composition needed
+        const signal = validSignals[0];
+        // Type guard: signal is guaranteed to be defined since validSignals[0] exists
+        if (!signal) {
+            return { controller: new AbortController(), cleanup: () => { } };
+        }
+        if (signal.aborted) {
+            const controller = new AbortController();
+            controller.abort();
+            return { controller, cleanup: () => { } };
+        }
+        return {
+            controller: { signal },
+            cleanup: () => { },
+        };
+    }
+    // Use AbortSignal.any() if available (Node 20+, modern browsers)
+    // This is more efficient and handles cleanup automatically
+    if ("any" in AbortSignal && typeof AbortSignal.any === "function") {
+        try {
+            const composedSignal = AbortSignal.any(validSignals);
+            return {
+                controller: { signal: composedSignal },
+                cleanup: () => { }, // AbortSignal.any() handles cleanup internally
+            };
+        }
+        catch {
+            // Fall through to manual composition if AbortSignal.any() fails
+        }
+    }
+    // Fallback: Manual composition for older environments
+    const controller = new AbortController();
+    const abortListeners = [];
+    for (const signal of validSignals) {
+        if (signal.aborted) {
+            controller.abort();
+            break;
+        }
+        const listener = () => controller.abort();
+        signal.addEventListener("abort", listener, { once: true });
+        abortListeners.push(() => signal.removeEventListener("abort", listener));
+    }
+    const cleanup = () => {
+        for (const remove of abortListeners) {
+            remove();
+        }
+    };
+    return { controller, cleanup };
+}
+/**
+ * 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.
+ *
+ * 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
+ * a transport that ignored the signal kept the caller waiting (deep dive TRN-7).
+ */
+async function* runWithTimeout(next, context, ms, message, retryable) {
+    const timeoutController = new AbortController();
+    const timeoutId = setTimeout(() => timeoutController.abort(), 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 = () => timeoutController.signal.aborted && !originalSignal?.aborted;
+    const timeoutItem = () => errorItem(context.message.id, "TIMEOUT", message, retryable);
+    const iterator = next(context)[Symbol.asyncIterator]();
+    // "running": a next() may be pending; "done": the iterator ended; "abandoned": the timeout won
+    let phase = "running";
+    try {
+        for (;;) {
+            const result = await nextOrAbort(iterator, timeoutController.signal);
+            if (result === ABORTED_FIRST) {
+                phase = "abandoned";
+                // The transport did not stop in time: end it in the background, and give the timeout
+                void Promise.resolve(iterator.return?.()).catch(() => undefined);
+                yield timeoutItem();
+                return;
+            }
+            if (result.done) {
+                phase = "done";
+                return;
+            }
+            if (result.value.status.type === "error" && timedOut()) {
+                // The transport saw the aborted signal and reported ABORTED: it is a timeout
+                yield timeoutItem();
+                return;
+            }
+            yield result.value;
+        }
+    }
+    catch (error) {
+        phase = "done";
+        if (timedOut()) {
+            yield timeoutItem();
+            return;
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutId);
+        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
+        // retry attempts with instant aborts. See documentation/BUGS-2026-07.md (H10).
+        if (originalSignal) {
+            context.message.signal = originalSignal;
+        }
+        else {
+            delete context.message.signal;
+        }
+        // The reader stopped early: the transport stops too
+        if (phase === "running")
+            await iterator.return?.();
+    }
+}
+/**
+ * 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 function createOverallTimeoutMiddleware(options) {
+    const { overall: defaultOverall, message = "Overall request timeout" } = options;
+    return (next) => {
+        return async function* (context) {
+            // Read from metadata first (user-provided context), then fall back to options
+            const overall = context.message.metadata.timeout?.overall
+                ?? defaultOverall;
+            if (!overall) {
+                // No timeout - passthrough
+                yield* next(context);
+                return;
+            }
+            // The overall timeout ends the request: a retry inside it cannot help
+            yield* runWithTimeout(next, context, overall, message, false);
+        };
+    };
+}
+/**
+ * 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 function createTimeoutMiddleware(options) {
+    const { perAttempt: defaultPerAttempt, message = "Request timeout" } = options;
+    return (next) => {
+        return async function* (context) {
+            // Read from metadata first (user-provided context), then fall back to options
+            const perAttempt = context.message.metadata.timeout?.perAttempt
+                ?? defaultPerAttempt;
+            if (!perAttempt) {
+                // No timeout - passthrough
+                yield* next(context);
+                return;
+            }
+            // A retry middleware outside this one can start a new attempt
+            yield* runWithTimeout(next, context, perAttempt, message, true);
+        };
+    };
+}
+/**
+ * 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 function createCombinedTimeoutMiddleware(options) {
+    const { overall, perAttempt, message = "Request timeout" } = options;
+    return (next) => {
+        // Compose both timeout middlewares
+        let composed = next;
+        if (perAttempt) {
+            const perAttemptMiddleware = createTimeoutMiddleware({ perAttempt, message: `${message} (per-attempt)` });
+            composed = perAttemptMiddleware(composed);
+        }
+        if (overall) {
+            const overallMiddleware = createOverallTimeoutMiddleware({ overall, message: `${message} (overall)` });
+            composed = overallMiddleware(composed);
+        }
+        return composed;
+    };
+}
+//# sourceMappingURL=timeout.js.map

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

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

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

@@ -0,0 +1,118 @@
+/**
+ * Tracing Middleware
+ *
+ * Adds distributed tracing metadata to requests.
+ * Works with ALL transports (HTTP, WebSocket, Local, Mock).
+ *
+ * Each transport converts metadata.tracing to its protocol format:
+ * - HTTP: X-Trace-Id, X-Span-Id, X-Parent-Span-Id headers
+ * - WebSocket: Frame metadata
+ * - Local: Passed directly to handler
+ *
+ * Compatible with OpenTelemetry, Jaeger, and custom tracing systems.
+ */
+import type { TypedClientMiddleware } from "../types.js";
+import type { TracingContext } from "./contexts.js";
+/**
+ * Tracing Configuration
+ */
+export interface TracingOptions {
+    /** Generate trace ID (default: auto-generate UUID) */
+    generateTraceId?: () => string;
+    /** Generate span ID (default: auto-generate UUID) */
+    generateSpanId?: () => string;
+    /** Get current trace context (for continuing existing traces) */
+    getCurrentTrace?: () => {
+        traceId: string;
+        spanId: string;
+    } | null;
+    /** Service name for tracing */
+    serviceName?: string;
+}
+/**
+ * Create tracing middleware
+ *
+ * Automatically adds tracing metadata to all requests.
+ * Supports both new traces and continuing existing traces.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const client = new Client({
+ *   transport: new HttpTransport({ baseUrl: "https://api.example.com" }),
+ *   middleware: [
+ *     createTracingMiddleware(),  // Auto-generates trace/span IDs
+ *     createRetryMiddleware({ maxAttempts: 3 }),
+ *   ]
+ * });
+ * ```
+ *
+ * @example Custom ID Generation
+ * ```typescript
+ * createTracingMiddleware({
+ *   generateTraceId: () => uuid.v4(),
+ *   generateSpanId: () => uuid.v4(),
+ * })
+ * ```
+ *
+ * @example Continuing Existing Trace
+ * ```typescript
+ * createTracingMiddleware({
+ *   getCurrentTrace: () => {
+ *     const trace = getActiveTrace();  // From your tracing library
+ *     return trace ? {
+ *       traceId: trace.traceId,
+ *       spanId: trace.spanId,
+ *     } : null;
+ *   }
+ * })
+ * ```
+ *
+ * @example OpenTelemetry Integration
+ * ```typescript
+ * import { trace } from "@opentelemetry/api";
+ *
+ * createTracingMiddleware({
+ *   getCurrentTrace: () => {
+ *     const span = trace.getActiveSpan();
+ *     if (!span) return null;
+ *
+ *     const spanContext = span.spanContext();
+ *     return {
+ *       traceId: spanContext.traceId,
+ *       spanId: spanContext.spanId,
+ *     };
+ *   }
+ * })
+ * ```
+ */
+export declare function createTracingMiddleware(options?: TracingOptions): TypedClientMiddleware<TracingContext, {}>;
+/**
+ * Create simple tracing middleware with UUID generation
+ *
+ * Convenience wrapper that uses crypto.randomUUID() if available.
+ *
+ * @example
+ * ```typescript
+ * createSimpleTracingMiddleware()
+ * // Generates: traceId and spanId using crypto.randomUUID() or fallback
+ * ```
+ */
+export declare function createSimpleTracingMiddleware(): TypedClientMiddleware<TracingContext, {}>;
+/**
+ * Extract tracing info from response metadata
+ *
+ * Useful for logging or passing to other systems.
+ *
+ * @example
+ * ```typescript
+ * const response = await client.call(...);
+ * const tracing = extractTracingInfo(response.metadata);
+ * console.log(`Request completed: ${tracing.traceId}`);
+ * ```
+ */
+export declare function extractTracingInfo(metadata: Record<string, unknown>): {
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+} | null;
+//# sourceMappingURL=tracing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../../src/client/middleware/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,eAAe,CAAC,EAAE,MAAM,MAAM,CAAC;IAE/B,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,MAAM,CAAC;IAE9B,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAEnE,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,cAAmB,GAC3B,qBAAqB,CAAC,cAAc,EAAE,EAAE,CAAC,CAsC3C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,IAAI,qBAAqB,CAAC,cAAc,EAAE,EAAE,CAAC,CAWzF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,IAAI,CAWP"}

package/dist/client/middleware/tracing.js

@@ -0,0 +1,152 @@
+/**
+ * Tracing Middleware
+ *
+ * Adds distributed tracing metadata to requests.
+ * Works with ALL transports (HTTP, WebSocket, Local, Mock).
+ *
+ * Each transport converts metadata.tracing to its protocol format:
+ * - HTTP: X-Trace-Id, X-Span-Id, X-Parent-Span-Id headers
+ * - WebSocket: Frame metadata
+ * - Local: Passed directly to handler
+ *
+ * Compatible with OpenTelemetry, Jaeger, and custom tracing systems.
+ */
+/**
+ * Generate a simple unique ID (UUID v4 subset)
+ */
+function generateId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
+/**
+ * Create tracing middleware
+ *
+ * Automatically adds tracing metadata to all requests.
+ * Supports both new traces and continuing existing traces.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const client = new Client({
+ *   transport: new HttpTransport({ baseUrl: "https://api.example.com" }),
+ *   middleware: [
+ *     createTracingMiddleware(),  // Auto-generates trace/span IDs
+ *     createRetryMiddleware({ maxAttempts: 3 }),
+ *   ]
+ * });
+ * ```
+ *
+ * @example Custom ID Generation
+ * ```typescript
+ * createTracingMiddleware({
+ *   generateTraceId: () => uuid.v4(),
+ *   generateSpanId: () => uuid.v4(),
+ * })
+ * ```
+ *
+ * @example Continuing Existing Trace
+ * ```typescript
+ * createTracingMiddleware({
+ *   getCurrentTrace: () => {
+ *     const trace = getActiveTrace();  // From your tracing library
+ *     return trace ? {
+ *       traceId: trace.traceId,
+ *       spanId: trace.spanId,
+ *     } : null;
+ *   }
+ * })
+ * ```
+ *
+ * @example OpenTelemetry Integration
+ * ```typescript
+ * import { trace } from "@opentelemetry/api";
+ *
+ * createTracingMiddleware({
+ *   getCurrentTrace: () => {
+ *     const span = trace.getActiveSpan();
+ *     if (!span) return null;
+ *
+ *     const spanContext = span.spanContext();
+ *     return {
+ *       traceId: spanContext.traceId,
+ *       spanId: spanContext.spanId,
+ *     };
+ *   }
+ * })
+ * ```
+ */
+export function createTracingMiddleware(options = {}) {
+    const { generateTraceId = generateId, generateSpanId = generateId, getCurrentTrace, serviceName, } = options;
+    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?.();
+            if (currentTrace) {
+                // Continue existing trace (create child span)
+                context.message.metadata.tracing = {
+                    traceId: currentTrace.traceId,
+                    spanId: generateSpanId(),
+                    parentSpanId: currentTrace.spanId,
+                };
+            }
+            else {
+                // Start new trace
+                context.message.metadata.tracing = {
+                    traceId: generateTraceId(),
+                    spanId: generateSpanId(),
+                };
+            }
+            // Add service name if provided
+            if (serviceName) {
+                context.message.metadata["serviceName"] = serviceName;
+            }
+        }
+        // Continue middleware chain
+        yield* next(context);
+    };
+}
+/**
+ * Create simple tracing middleware with UUID generation
+ *
+ * Convenience wrapper that uses crypto.randomUUID() if available.
+ *
+ * @example
+ * ```typescript
+ * createSimpleTracingMiddleware()
+ * // Generates: traceId and spanId using crypto.randomUUID() or fallback
+ * ```
+ */
+export function createSimpleTracingMiddleware() {
+    const hasRandomUUID = typeof crypto !== "undefined" && "randomUUID" in crypto;
+    return createTracingMiddleware({
+        generateTraceId: hasRandomUUID
+            ? () => crypto.randomUUID()
+            : generateId,
+        generateSpanId: hasRandomUUID
+            ? () => crypto.randomUUID()
+            : generateId,
+    });
+}
+/**
+ * Extract tracing info from response metadata
+ *
+ * Useful for logging or passing to other systems.
+ *
+ * @example
+ * ```typescript
+ * const response = await client.call(...);
+ * const tracing = extractTracingInfo(response.metadata);
+ * console.log(`Request completed: ${tracing.traceId}`);
+ * ```
+ */
+export function extractTracingInfo(metadata) {
+    if (!metadata["tracing"] || typeof metadata["tracing"] !== "object") {
+        return null;
+    }
+    const tracing = metadata["tracing"];
+    return {
+        ...(typeof tracing["traceId"] === "string" && { traceId: tracing["traceId"] }),
+        ...(typeof tracing["spanId"] === "string" && { spanId: tracing["spanId"] }),
+        ...(typeof tracing["parentSpanId"] === "string" && { parentSpanId: tracing["parentSpanId"] }),
+    };
+}
+//# sourceMappingURL=tracing.js.map

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

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