@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/cjs/timeouts.js

@@ -1 +1,412 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.globalTimeoutConfig=exports.OperationTimeoutController=exports.TimeoutConfig=exports.DEFAULT_TIMEOUTS=exports.TimeoutError=void 0,exports.createTimeoutController=createTimeoutController,exports.withTimeout=withTimeout,exports.withTimeoutResult=withTimeoutResult,exports.createOperationTimeoutSignal=createOperationTimeoutSignal,exports.createOperationTimeout=createOperationTimeout,exports.isTimeoutError=isTimeoutError,exports.getTimeoutFromError=getTimeoutFromError,exports.createTimeoutConfigFromEnv=createTimeoutConfigFromEnv;const shared_1=require("../_deps/shared/index.js");class TimeoutError extends Error{code="TIMEOUT";operation;timeoutMs;timestamp;constructor(t,e){super(`Operation '${t}' timed out after ${e}ms. Actions: (1) Check network connectivity, (2) Increase timeout threshold, (3) Verify service availability, (4) Implement retry with exponential backoff.`),this.name="TimeoutError",this.operation=t,this.timeoutMs=e,this.timestamp=Date.now()}static withContext(t,e,r){const o=new TimeoutError(t,e);return r&&Object.assign(o,{context:r}),o}}exports.TimeoutError=TimeoutError,exports.DEFAULT_TIMEOUTS={registry:1e4,gateway:15e3,transport:3e4,default:3e4};class TimeoutConfig{registry;gateway;transport;default;constructor(t={}){this.registry=t.registry??exports.DEFAULT_TIMEOUTS.registry,this.gateway=t.gateway??exports.DEFAULT_TIMEOUTS.gateway,this.transport=t.transport??exports.DEFAULT_TIMEOUTS.transport,this.default=t.default??exports.DEFAULT_TIMEOUTS.default,this.validateTimeout("registry",this.registry),this.validateTimeout("gateway",this.gateway),this.validateTimeout("transport",this.transport),this.validateTimeout("default",this.default)}getRegistry(t){return t??this.registry}getGateway(t){return t??this.gateway}getTransport(t){return t??this.transport}getDefault(t){return t??this.default}get(t,e){switch(t){case"registry":return this.getRegistry(e);case"gateway":return this.getGateway(e);case"transport":return this.getTransport(e);case"default":return this.getDefault(e)}}with(t){return new TimeoutConfig({registry:t.registry??this.registry,gateway:t.gateway??this.gateway,transport:t.transport??this.transport,default:t.default??this.default})}validateTimeout(t,e){if(!Number.isFinite(e)||e<=0)throw new Error(`Invalid timeout for '${t}': ${e}. Must be positive finite number.`);e>3e5&&console.warn(`[xbind:timeout] Large timeout for '${t}': ${e}ms. Consider reducing to avoid indefinite hangs.`)}toJSON(){return{registry:this.registry,gateway:this.gateway,transport:this.transport,default:this.default}}}exports.TimeoutConfig=TimeoutConfig;class OperationTimeoutController{signal;timeoutMs;operation;controller;timer;timedOut=!1;constructor(t,e="operation"){this.controller=new AbortController,this.signal=this.controller.signal,this.timeoutMs=t,this.operation=e,this.timer=setTimeout(()=>{this.timedOut=!0,this.controller.abort()},t)}cancel(){clearTimeout(this.timer),this.controller.signal.aborted||this.controller.abort()}clear(){clearTimeout(this.timer)}didTimeout(){return this.timedOut}getTimeoutError(){return this.timedOut?new TimeoutError(this.operation,this.timeoutMs):null}}function createTimeoutController(t,e="operation"){return new OperationTimeoutController(t,e)}async function withTimeout(t,e,r="operation"){const o=createTimeoutController(e,r);try{const i=await Promise.race([t(),new Promise((t,i)=>{o.signal.addEventListener("abort",()=>{i(new TimeoutError(r,e))})})]);return o.clear(),i}catch(t){throw o.clear(),t}}async function withTimeoutResult(t,e,r="operation"){try{const o=await withTimeout(t,e,r);return(0,shared_1.ok)(o)}catch(t){if(t instanceof TimeoutError)return(0,shared_1.err)("TIMEOUT");throw t}}function createOperationTimeoutSignal(t,e="operation"){return createTimeoutController(t,e).signal}function createOperationTimeout(t,e,r,o){return createTimeoutController(t.get(e,o),r)}function isTimeoutError(t){return t instanceof TimeoutError}function getTimeoutFromError(t){return isTimeoutError(t)?t.timeoutMs:void 0}function createTimeoutConfigFromEnv(){const t={},e=process.env.XBIND_TIMEOUT_REGISTRY;if(e){const r=parseInt(e,10);isNaN(r)||(t.registry=r)}const r=process.env.XBIND_TIMEOUT_GATEWAY;if(r){const e=parseInt(r,10);isNaN(e)||(t.gateway=e)}const o=process.env.XBIND_TIMEOUT_TRANSPORT;if(o){const e=parseInt(o,10);isNaN(e)||(t.transport=e)}const i=process.env.XBIND_TIMEOUT_DEFAULT;if(i){const e=parseInt(i,10);isNaN(e)||(t.default=e)}return new TimeoutConfig(t)}exports.OperationTimeoutController=OperationTimeoutController,exports.globalTimeoutConfig=createTimeoutConfigFromEnv();
+"use strict";
+/**
+ * @module timeouts
+ * Configurable request timeouts for xBind operations
+ *
+ * Provides centralized timeout management with:
+ * - Per-operation timeout configuration
+ * - Default timeouts for registry, gateway, transport
+ * - Timeout inheritance and overrides
+ * - Timeout error messages with context
+ * - Integration with AbortController/cancellation tokens
+ *
+ * @example
+ * ```typescript
+ * import { TimeoutConfig, withTimeout, createTimeoutController } from '@private.me/xbind';
+ *
+ * // Create timeout configuration
+ * const config = new TimeoutConfig({
+ *   registry: 10000,
+ *   gateway: 15000,
+ *   transport: 30000,
+ * });
+ *
+ * // Use timeout with fetch
+ * const controller = createTimeoutController(config.registry);
+ * const response = await fetch(url, { signal: controller.signal });
+ *
+ * // Wrap async operation with timeout
+ * const result = await withTimeout(
+ *   async () => performOperation(),
+ *   5000,
+ *   'Operation description'
+ * );
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globalTimeoutConfig = exports.OperationTimeoutController = exports.TimeoutConfig = exports.DEFAULT_TIMEOUTS = exports.TimeoutError = void 0;
+exports.createTimeoutController = createTimeoutController;
+exports.withTimeout = withTimeout;
+exports.withTimeoutResult = withTimeoutResult;
+exports.createOperationTimeoutSignal = createOperationTimeoutSignal;
+exports.createOperationTimeout = createOperationTimeout;
+exports.isTimeoutError = isTimeoutError;
+exports.getTimeoutFromError = getTimeoutFromError;
+exports.createTimeoutConfigFromEnv = createTimeoutConfigFromEnv;
+const shared_1 = require("../_deps/shared/index.js");
+/**
+ * Timeout error with operation context.
+ */
+class TimeoutError extends Error {
+    code = 'TIMEOUT';
+    operation;
+    timeoutMs;
+    timestamp;
+    constructor(operation, timeoutMs) {
+        super(`Operation '${operation}' timed out after ${timeoutMs}ms. ` +
+            `Actions: (1) Check network connectivity, (2) Increase timeout threshold, ` +
+            `(3) Verify service availability, (4) Implement retry with exponential backoff.`);
+        this.name = 'TimeoutError';
+        this.operation = operation;
+        this.timeoutMs = timeoutMs;
+        this.timestamp = Date.now();
+    }
+    /**
+     * Create timeout error with additional context.
+     */
+    static withContext(operation, timeoutMs, context) {
+        const error = new TimeoutError(operation, timeoutMs);
+        if (context) {
+            Object.assign(error, { context });
+        }
+        return error;
+    }
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * Default timeout values (milliseconds).
+ */
+exports.DEFAULT_TIMEOUTS = {
+    registry: 10_000, // 10 seconds for registry lookups
+    gateway: 15_000, // 15 seconds for gateway operations
+    transport: 30_000, // 30 seconds for transport/HTTP
+    default: 30_000, // 30 seconds fallback
+};
+/**
+ * Timeout configuration manager.
+ * Provides timeout values with inheritance and override support.
+ */
+class TimeoutConfig {
+    registry;
+    gateway;
+    transport;
+    default;
+    constructor(options = {}) {
+        this.registry = options.registry ?? exports.DEFAULT_TIMEOUTS.registry;
+        this.gateway = options.gateway ?? exports.DEFAULT_TIMEOUTS.gateway;
+        this.transport = options.transport ?? exports.DEFAULT_TIMEOUTS.transport;
+        this.default = options.default ?? exports.DEFAULT_TIMEOUTS.default;
+        // Validate timeout values
+        this.validateTimeout('registry', this.registry);
+        this.validateTimeout('gateway', this.gateway);
+        this.validateTimeout('transport', this.transport);
+        this.validateTimeout('default', this.default);
+    }
+    /**
+     * Get timeout for registry operations.
+     * @param override - Optional override timeout
+     */
+    getRegistry(override) {
+        return override ?? this.registry;
+    }
+    /**
+     * Get timeout for gateway operations.
+     * @param override - Optional override timeout
+     */
+    getGateway(override) {
+        return override ?? this.gateway;
+    }
+    /**
+     * Get timeout for transport operations.
+     * @param override - Optional override timeout
+     */
+    getTransport(override) {
+        return override ?? this.transport;
+    }
+    /**
+     * Get default timeout.
+     * @param override - Optional override timeout
+     */
+    getDefault(override) {
+        return override ?? this.default;
+    }
+    /**
+     * Get timeout for specific operation category.
+     * @param category - Operation category
+     * @param override - Optional override timeout
+     */
+    get(category, override) {
+        switch (category) {
+            case 'registry':
+                return this.getRegistry(override);
+            case 'gateway':
+                return this.getGateway(override);
+            case 'transport':
+                return this.getTransport(override);
+            case 'default':
+                return this.getDefault(override);
+        }
+    }
+    /**
+     * Create new config with overrides.
+     * @param overrides - Timeout overrides
+     */
+    with(overrides) {
+        return new TimeoutConfig({
+            registry: overrides.registry ?? this.registry,
+            gateway: overrides.gateway ?? this.gateway,
+            transport: overrides.transport ?? this.transport,
+            default: overrides.default ?? this.default,
+        });
+    }
+    /**
+     * Validate timeout value.
+     */
+    validateTimeout(name, value) {
+        if (!Number.isFinite(value) || value <= 0) {
+            throw new Error(`Invalid timeout for '${name}': ${value}. Must be positive finite number.`);
+        }
+        if (value > 300_000) {
+            // Warn if timeout > 5 minutes (likely config error)
+            console.warn(`[xbind:timeout] Large timeout for '${name}': ${value}ms. ` +
+                `Consider reducing to avoid indefinite hangs.`);
+        }
+    }
+    /**
+     * Export configuration as plain object.
+     */
+    toJSON() {
+        return {
+            registry: this.registry,
+            gateway: this.gateway,
+            transport: this.transport,
+            default: this.default,
+        };
+    }
+}
+exports.TimeoutConfig = TimeoutConfig;
+/**
+ * Operation timeout controller with cancellation support.
+ * Wraps AbortController with timeout semantics.
+ */
+class OperationTimeoutController {
+    signal;
+    timeoutMs;
+    operation;
+    controller;
+    timer;
+    timedOut = false;
+    constructor(timeoutMs, operation = 'operation') {
+        this.controller = new AbortController();
+        this.signal = this.controller.signal;
+        this.timeoutMs = timeoutMs;
+        this.operation = operation;
+        // Set timeout
+        this.timer = setTimeout(() => {
+            this.timedOut = true;
+            this.controller.abort();
+        }, timeoutMs);
+    }
+    /**
+     * Cancel the operation (clear timeout).
+     */
+    cancel() {
+        clearTimeout(this.timer);
+        if (!this.controller.signal.aborted) {
+            this.controller.abort();
+        }
+    }
+    /**
+     * Clear timeout if operation completed successfully.
+     * Call this when operation finishes to prevent unnecessary abort.
+     */
+    clear() {
+        clearTimeout(this.timer);
+    }
+    /**
+     * Check if controller timed out (vs manual cancellation).
+     */
+    didTimeout() {
+        return this.timedOut;
+    }
+    /**
+     * Get timeout error if operation timed out.
+     */
+    getTimeoutError() {
+        return this.timedOut ? new TimeoutError(this.operation, this.timeoutMs) : null;
+    }
+}
+exports.OperationTimeoutController = OperationTimeoutController;
+/**
+ * Create timeout controller for operation.
+ * @param timeoutMs - Timeout in milliseconds
+ * @param operation - Operation description for error messages
+ */
+function createTimeoutController(timeoutMs, operation = 'operation') {
+    return new OperationTimeoutController(timeoutMs, operation);
+}
+/**
+ * Wrap async operation with timeout.
+ * Rejects with TimeoutError if operation exceeds timeout.
+ *
+ * @param fn - Async operation to execute
+ * @param timeoutMs - Timeout in milliseconds
+ * @param operation - Operation description for error messages
+ * @returns Result of operation or timeout error
+ *
+ * @example
+ * ```typescript
+ * const result = await withTimeout(
+ *   async () => fetch('https://api.example.com'),
+ *   5000,
+ *   'API request'
+ * );
+ * ```
+ */
+async function withTimeout(fn, timeoutMs, operation = 'operation') {
+    const controller = createTimeoutController(timeoutMs, operation);
+    try {
+        const result = await Promise.race([
+            fn(),
+            new Promise((_, reject) => {
+                controller.signal.addEventListener('abort', () => {
+                    reject(new TimeoutError(operation, timeoutMs));
+                });
+            }),
+        ]);
+        controller.clear();
+        return result;
+    }
+    catch (error) {
+        controller.clear();
+        throw error;
+    }
+}
+/**
+ * Wrap async operation with timeout (Result-based).
+ * Returns ok(result) or err('TIMEOUT') without throwing.
+ *
+ * @param fn - Async operation to execute
+ * @param timeoutMs - Timeout in milliseconds
+ * @param operation - Operation description for error messages
+ * @returns Result with operation result or timeout error
+ *
+ * @example
+ * ```typescript
+ * const result = await withTimeoutResult(
+ *   async () => fetch('https://api.example.com'),
+ *   5000,
+ *   'API request'
+ * );
+ * if (result.ok) {
+ *   console.log('Success:', result.value);
+ * } else {
+ *   console.error('Timeout:', result.error);
+ * }
+ * ```
+ */
+async function withTimeoutResult(fn, timeoutMs, operation = 'operation') {
+    try {
+        const result = await withTimeout(fn, timeoutMs, operation);
+        return (0, shared_1.ok)(result);
+    }
+    catch (error) {
+        if (error instanceof TimeoutError) {
+            return (0, shared_1.err)('TIMEOUT');
+        }
+        throw error; // Re-throw non-timeout errors
+    }
+}
+/**
+ * Create timeout signal for use with fetch/AbortController APIs.
+ *
+ * @param timeoutMs - Timeout in milliseconds
+ * @param operation - Operation description
+ * @returns AbortSignal that aborts after timeout
+ *
+ * @example
+ * ```typescript
+ * const signal = createOperationTimeoutSignal(5000, 'fetch request');
+ * const response = await fetch(url, { signal });
+ * ```
+ */
+function createOperationTimeoutSignal(timeoutMs, operation = 'operation') {
+    return createTimeoutController(timeoutMs, operation).signal;
+}
+/**
+ * Timeout helper for operations with cancellation token.
+ * Returns controller that can be passed to fetch, agent.send, etc.
+ *
+ * @param config - Timeout configuration
+ * @param category - Operation category
+ * @param operation - Operation description
+ * @param override - Optional timeout override
+ * @returns Timeout controller
+ *
+ * @example
+ * ```typescript
+ * const controller = createOperationTimeout(config, 'registry', 'lookup DID');
+ * const response = await fetch(url, { signal: controller.signal });
+ * controller.clear(); // Clear timeout on success
+ * ```
+ */
+function createOperationTimeout(config, category, operation, override) {
+    const timeoutMs = config.get(category, override);
+    return createTimeoutController(timeoutMs, operation);
+}
+/**
+ * Check if error is a timeout error.
+ */
+function isTimeoutError(error) {
+    return error instanceof TimeoutError;
+}
+/**
+ * Extract timeout from error if it's a timeout error.
+ * Returns timeout in milliseconds or undefined.
+ */
+function getTimeoutFromError(error) {
+    return isTimeoutError(error) ? error.timeoutMs : undefined;
+}
+/**
+ * Create timeout configuration from environment variables.
+ * Looks for:
+ * - XBIND_TIMEOUT_REGISTRY
+ * - XBIND_TIMEOUT_GATEWAY
+ * - XBIND_TIMEOUT_TRANSPORT
+ * - XBIND_TIMEOUT_DEFAULT
+ *
+ * Falls back to default values if not set.
+ */
+function createTimeoutConfigFromEnv() {
+    const options = {};
+    const registry = process.env.XBIND_TIMEOUT_REGISTRY;
+    if (registry) {
+        const parsed = parseInt(registry, 10);
+        if (!isNaN(parsed))
+            options.registry = parsed;
+    }
+    const gateway = process.env.XBIND_TIMEOUT_GATEWAY;
+    if (gateway) {
+        const parsed = parseInt(gateway, 10);
+        if (!isNaN(parsed))
+            options.gateway = parsed;
+    }
+    const transport = process.env.XBIND_TIMEOUT_TRANSPORT;
+    if (transport) {
+        const parsed = parseInt(transport, 10);
+        if (!isNaN(parsed))
+            options.transport = parsed;
+    }
+    const defaultTimeout = process.env.XBIND_TIMEOUT_DEFAULT;
+    if (defaultTimeout) {
+        const parsed = parseInt(defaultTimeout, 10);
+        if (!isNaN(parsed))
+            options.default = parsed;
+    }
+    return new TimeoutConfig(options);
+}
+/**
+ * Global default timeout configuration.
+ * Can be overridden by setting environment variables.
+ */
+exports.globalTimeoutConfig = createTimeoutConfigFromEnv();