@private.me/xbind 3.0.2 → 3.0.3

package/dist-standalone/connection-pool.js

@@ -1,500 +1 @@
-/**
- * @module connection-pool
- * HTTP connection pooling for xBind registry/gateway requests
- *
- * Provides connection reuse, keep-alive support, and automatic cleanup
- * to enhance performance for applications making frequent requests.
- *
- * @example
- * ```typescript
- * const pool = new ConnectionPool({
- *   maxConnections: 50,
- *   keepAliveTimeout: 30000,
- * });
- *
- * const response = await pool.fetch('https://api.example.com/data');
- * const data = await response.json();
- * ```
- */
-/**
- * Connection pool for HTTP requests
- *
- * Manages connection lifecycle, keep-alive, and automatic cleanup
- * to optimize performance for frequent requests to the same origins.
- */
-export class ConnectionPool {
-    options;
-    connections = new Map();
-    metrics;
-    cleanupInterval = null;
-    /**
-     * Create a new connection pool
-     *
-     * @param options - Pool configuration options
-     */
-    constructor(options = {}) {
-        this.options = {
-            maxConnections: options.maxConnections ?? 10,
-            minConnections: options.minConnections ?? 2,
-            keepAliveTimeout: options.keepAliveTimeout ?? 30000,
-            idleTimeout: options.idleTimeout ?? 60000,
-            requestTimeout: options.requestTimeout ?? 30000,
-            enableMetrics: options.enableMetrics ?? true,
-            retryOnFailure: options.retryOnFailure ?? true,
-            maxRetries: options.maxRetries ?? 3,
-        };
-        this.metrics = {
-            totalRequests: 0,
-            reuseCount: 0,
-            failedRequests: 0,
-            requestDurations: [],
-            byOrigin: new Map(),
-        };
-        // Start automatic cleanup
-        this.startCleanup();
-    }
-    /**
-     * Make an HTTP request using the connection pool
-     *
-     * @param url - Target URL
-     * @param init - Fetch options
-     * @returns Response promise
-     *
-     * @example
-     * ```typescript
-     * const response = await pool.fetch('https://api.example.com/data', {
-     *   method: 'POST',
-     *   headers: { 'Content-Type': 'application/json' },
-     *   body: JSON.stringify({ key: 'value' }),
-     * });
-     * ```
-     */
-    async fetch(url, init) {
-        const startTime = Date.now();
-        const origin = this.getOrigin(url);
-        try {
-            // Get or create connection
-            const connection = await this.acquireConnection(origin);
-            // Update metrics
-            if (this.options.enableMetrics) {
-                this.metrics.totalRequests++;
-                if (connection.requestCount > 0) {
-                    this.metrics.reuseCount++;
-                }
-            }
-            // Make request with keep-alive
-            const requestInit = {
-                ...init,
-                signal: init?.signal ?? connection.controller.signal,
-                // @ts-ignore - keepalive is a valid fetch option
-                keepalive: true,
-            };
-            const response = await fetch(url, requestInit);
-            // Update connection state
-            connection.requestCount++;
-            connection.lastUsedAt = Date.now();
-            connection.state = 'idle';
-            // Record metrics
-            if (this.options.enableMetrics) {
-                const duration = Date.now() - startTime;
-                this.recordMetrics(origin, duration);
-            }
-            return response;
-        }
-        catch (error) {
-            // Record failure
-            if (this.options.enableMetrics) {
-                this.metrics.failedRequests++;
-            }
-            // Retry if enabled
-            if (this.options.retryOnFailure && init?.signal?.aborted !== true) {
-                return this.retryRequest(url, init, 1);
-            }
-            throw error;
-        }
-    }
-    /**
-     * Retry a failed request with exponential backoff
-     */
-    async retryRequest(url, init, attempt) {
-        if (attempt > this.options.maxRetries) {
-            throw new Error(`Request failed after ${this.options.maxRetries} retries: ${url}`);
-        }
-        // Exponential backoff: 100ms, 200ms, 400ms...
-        const delay = 100 * Math.pow(2, attempt - 1);
-        await new Promise(resolve => setTimeout(resolve, delay));
-        const origin = this.getOrigin(url);
-        try {
-            // Get or create connection
-            const connection = await this.acquireConnection(origin);
-            // Make request with keep-alive
-            const requestInit = {
-                ...init,
-                signal: init?.signal ?? connection.controller.signal,
-                // @ts-ignore - keepalive is a valid fetch option
-                keepalive: true,
-            };
-            const response = await fetch(url, requestInit);
-            // Update connection state
-            connection.requestCount++;
-            connection.lastUsedAt = Date.now();
-            connection.state = 'idle';
-            return response;
-        }
-        catch (error) {
-            if (attempt >= this.options.maxRetries) {
-                throw new Error(`Request failed after ${this.options.maxRetries} retries: ${url}`);
-            }
-            return this.retryRequest(url, init, attempt + 1);
-        }
-    }
-    /**
-     * Acquire a connection from the pool or create a new one
-     */
-    async acquireConnection(origin) {
-        let pool = this.connections.get(origin);
-        if (!pool) {
-            pool = [];
-            this.connections.set(origin, pool);
-        }
-        // Find idle connection
-        const idleConnection = pool.find(conn => conn.state === 'idle');
-        if (idleConnection) {
-            idleConnection.state = 'active';
-            return idleConnection;
-        }
-        // Check if we can create a new connection
-        if (pool.length < this.options.maxConnections) {
-            const connection = this.createConnection(origin);
-            pool.push(connection);
-            return connection;
-        }
-        // Wait for an available connection
-        return this.waitForConnection(origin);
-    }
-    /**
-     * Wait for a connection to become available
-     */
-    async waitForConnection(origin) {
-        const startTime = Date.now();
-        const timeout = this.options.requestTimeout;
-        while (Date.now() - startTime < timeout) {
-            const pool = this.connections.get(origin);
-            if (!pool) {
-                throw new Error(`Connection pool for ${origin} disappeared`);
-            }
-            const idleConnection = pool.find(conn => conn.state === 'idle');
-            if (idleConnection) {
-                idleConnection.state = 'active';
-                return idleConnection;
-            }
-            // Wait a bit before checking again
-            await new Promise(resolve => setTimeout(resolve, 10));
-        }
-        throw new Error(`Timeout waiting for connection to ${origin} after ${timeout}ms`);
-    }
-    /**
-     * Create a new connection
-     */
-    createConnection(origin) {
-        const randomBytes = new Uint8Array(8);
-        crypto.getRandomValues(randomBytes);
-        const id = Array.from(randomBytes)
-            .map(b => b.toString(16).padStart(2, '0'))
-            .join('');
-        return {
-            id: `conn_${id}`,
-            origin,
-            createdAt: Date.now(),
-            lastUsedAt: Date.now(),
-            requestCount: 0,
-            state: 'active',
-            controller: new AbortController(),
-        };
-    }
-    /**
-     * Get origin from URL
-     */
-    getOrigin(url) {
-        try {
-            const parsed = new URL(url);
-            return `${parsed.protocol}//${parsed.host}`;
-        }
-        catch (error) {
-            throw new Error(`Invalid URL: ${url}`);
-        }
-    }
-    /**
-     * Record request metrics
-     */
-    recordMetrics(origin, duration) {
-        this.metrics.requestDurations.push(duration);
-        // Limit stored durations to last 1000 requests
-        if (this.metrics.requestDurations.length > 1000) {
-            this.metrics.requestDurations.shift();
-        }
-        // Record origin-specific metrics
-        let originMetrics = this.metrics.byOrigin.get(origin);
-        if (!originMetrics) {
-            originMetrics = { requests: 0, durations: [] };
-            this.metrics.byOrigin.set(origin, originMetrics);
-        }
-        originMetrics.requests++;
-        originMetrics.durations.push(duration);
-        // Limit origin durations
-        if (originMetrics.durations.length > 100) {
-            originMetrics.durations.shift();
-        }
-    }
-    /**
-     * Get connection pool metrics
-     *
-     * @returns Current metrics snapshot
-     *
-     * @example
-     * ```typescript
-     * const metrics = pool.getMetrics();
-     * console.log(`Hit rate: ${(metrics.hitRate * 100).toFixed(1)}%`);
-     * console.log(`Avg duration: ${metrics.avgRequestDuration}ms`);
-     * ```
-     */
-    getMetrics() {
-        let totalConnections = 0;
-        let activeConnections = 0;
-        let idleConnections = 0;
-        const byOrigin = new Map();
-        for (const [origin, pool] of this.connections.entries()) {
-            totalConnections += pool.length;
-            activeConnections += pool.filter(c => c.state === 'active').length;
-            idleConnections += pool.filter(c => c.state === 'idle').length;
-            const originMetrics = this.metrics.byOrigin.get(origin);
-            if (originMetrics) {
-                const avgDuration = originMetrics.durations.length > 0
-                    ? originMetrics.durations.reduce((a, b) => a + b, 0) /
-                        originMetrics.durations.length
-                    : 0;
-                byOrigin.set(origin, {
-                    connections: pool.length,
-                    requests: originMetrics.requests,
-                    avgDuration: Math.round(avgDuration),
-                });
-            }
-        }
-        const avgRequestDuration = this.metrics.requestDurations.length > 0
-            ? Math.round(this.metrics.requestDurations.reduce((a, b) => a + b, 0) /
-                this.metrics.requestDurations.length)
-            : 0;
-        const hitRate = this.metrics.totalRequests > 0
-            ? this.metrics.reuseCount / this.metrics.totalRequests
-            : 0;
-        return {
-            totalConnections,
-            activeConnections,
-            idleConnections,
-            totalRequests: this.metrics.totalRequests,
-            reuseCount: this.metrics.reuseCount,
-            failedRequests: this.metrics.failedRequests,
-            avgRequestDuration,
-            hitRate,
-            byOrigin,
-        };
-    }
-    /**
-     * Reset metrics counters
-     *
-     * @example
-     * ```typescript
-     * pool.resetMetrics();
-     * // Start fresh measurements
-     * ```
-     */
-    resetMetrics() {
-        this.metrics = {
-            totalRequests: 0,
-            reuseCount: 0,
-            failedRequests: 0,
-            requestDurations: [],
-            byOrigin: new Map(),
-        };
-    }
-    /**
-     * Start automatic connection cleanup
-     */
-    startCleanup() {
-        // Run cleanup every 10 seconds
-        this.cleanupInterval = setInterval(() => {
-            this.cleanup();
-        }, 10000);
-    }
-    /**
-     * Clean up idle and expired connections
-     */
-    cleanup() {
-        const now = Date.now();
-        for (const [origin, pool] of this.connections.entries()) {
-            // Remove expired connections
-            const activePool = pool.filter(conn => {
-                const isExpired = now - conn.lastUsedAt > this.options.idleTimeout &&
-                    conn.state === 'idle';
-                if (isExpired) {
-                    conn.controller.abort();
-                    conn.state = 'closed';
-                    return false;
-                }
-                return conn.state !== 'closed';
-            });
-            // Ensure minimum connections are maintained
-            while (activePool.length < this.options.minConnections &&
-                activePool.length < this.options.maxConnections) {
-                const conn = this.createConnection(origin);
-                conn.state = 'idle';
-                activePool.push(conn);
-            }
-            if (activePool.length > 0) {
-                this.connections.set(origin, activePool);
-            }
-            else {
-                this.connections.delete(origin);
-            }
-        }
-    }
-    /**
-     * Manually trigger connection cleanup
-     *
-     * @example
-     * ```typescript
-     * // Force cleanup of idle connections
-     * pool.cleanupNow();
-     * ```
-     */
-    cleanupNow() {
-        this.cleanup();
-    }
-    /**
-     * Close all connections and shutdown the pool
-     *
-     * @example
-     * ```typescript
-     * // Cleanup on application shutdown
-     * await pool.close();
-     * ```
-     */
-    async close() {
-        // Stop cleanup interval
-        if (this.cleanupInterval) {
-            clearInterval(this.cleanupInterval);
-            this.cleanupInterval = null;
-        }
-        // Close all connections
-        for (const [_origin, pool] of this.connections.entries()) {
-            for (const conn of pool) {
-                conn.controller.abort();
-                conn.state = 'closed';
-            }
-        }
-        this.connections.clear();
-    }
-    /**
-     * Get the number of connections for a specific origin
-     *
-     * @param origin - Target origin (e.g., "https://api.example.com")
-     * @returns Number of connections
-     *
-     * @example
-     * ```typescript
-     * const count = pool.getConnectionCount('https://api.example.com');
-     * console.log(`Active connections: ${count}`);
-     * ```
-     */
-    getConnectionCount(origin) {
-        const pool = this.connections.get(origin);
-        return pool ? pool.length : 0;
-    }
-    /**
-     * Get all origins with active connections
-     *
-     * @returns Array of origins
-     *
-     * @example
-     * ```typescript
-     * const origins = pool.getOrigins();
-     * console.log(`Connected to ${origins.length} origins`);
-     * ```
-     */
-    getOrigins() {
-        return Array.from(this.connections.keys());
-    }
-    /**
-     * Check if the pool is healthy
-     *
-     * @returns True if pool is operating normally
-     *
-     * @example
-     * ```typescript
-     * if (!pool.isHealthy()) {
-     *   console.warn('Connection pool degraded');
-     * }
-     * ```
-     */
-    isHealthy() {
-        const metrics = this.getMetrics();
-        // Check if failure rate is too high
-        const failureRate = metrics.totalRequests > 0
-            ? metrics.failedRequests / metrics.totalRequests
-            : 0;
-        if (failureRate > 0.1) {
-            // More than 10% failure rate
-            return false;
-        }
-        // Check if we have reasonable response times
-        if (metrics.avgRequestDuration > 5000) {
-            // Average over 5 seconds
-            return false;
-        }
-        return true;
-    }
-}
-/**
- * Create a global connection pool instance
- *
- * Useful for sharing a single pool across your application.
- *
- * @param options - Pool configuration
- * @returns Singleton connection pool instance
- *
- * @example
- * ```typescript
- * import { getGlobalPool } from '@private.me/xbind/connection-pool';
- *
- * const pool = getGlobalPool({
- *   maxConnections: 50,
- *   keepAliveTimeout: 30000,
- * });
- *
- * const response = await pool.fetch('https://api.example.com/data');
- * ```
- */
-let globalPool = null;
-export function getGlobalPool(options) {
-    if (!globalPool) {
-        globalPool = new ConnectionPool(options);
-    }
-    return globalPool;
-}
-/**
- * Reset the global connection pool
- *
- * Closes the current pool and allows a new one to be created.
- *
- * @example
- * ```typescript
- * await resetGlobalPool();
- * // Next getGlobalPool() call will create a fresh instance
- * ```
- */
-export async function resetGlobalPool() {
-    if (globalPool) {
-        await globalPool.close();
-        globalPool = null;
-    }
-}
+export class ConnectionPool{options;connections=new Map;metrics;cleanupInterval=null;constructor(t={}){this.options={maxConnections:t.maxConnections??10,minConnections:t.minConnections??2,keepAliveTimeout:t.keepAliveTimeout??3e4,idleTimeout:t.idleTimeout??6e4,requestTimeout:t.requestTimeout??3e4,enableMetrics:t.enableMetrics??!0,retryOnFailure:t.retryOnFailure??!0,maxRetries:t.maxRetries??3},this.metrics={totalRequests:0,reuseCount:0,failedRequests:0,requestDurations:[],byOrigin:new Map},this.startCleanup()}async fetch(t,e){const s=Date.now(),n=this.getOrigin(t);try{const o=await this.acquireConnection(n);this.options.enableMetrics&&(this.metrics.totalRequests++,o.requestCount>0&&this.metrics.reuseCount++);const i={...e,signal:e?.signal??o.controller.signal,keepalive:!0},r=await fetch(t,i);if(o.requestCount++,o.lastUsedAt=Date.now(),o.state="idle",this.options.enableMetrics){const t=Date.now()-s;this.recordMetrics(n,t)}return r}catch(s){if(this.options.enableMetrics&&this.metrics.failedRequests++,this.options.retryOnFailure&&!0!==e?.signal?.aborted)return this.retryRequest(t,e,1);throw s}}async retryRequest(t,e,s){if(s>this.options.maxRetries)throw new Error(`Request failed after ${this.options.maxRetries} retries: ${t}`);const n=100*Math.pow(2,s-1);await new Promise(t=>setTimeout(t,n));const o=this.getOrigin(t);try{const s=await this.acquireConnection(o),n={...e,signal:e?.signal??s.controller.signal,keepalive:!0},i=await fetch(t,n);return s.requestCount++,s.lastUsedAt=Date.now(),s.state="idle",i}catch{if(s>=this.options.maxRetries)throw new Error(`Request failed after ${this.options.maxRetries} retries: ${t}`);return this.retryRequest(t,e,s+1)}}async acquireConnection(t){let e=this.connections.get(t);e||(e=[],this.connections.set(t,e));const s=e.find(t=>"idle"===t.state);if(s)return s.state="active",s;if(e.length<this.options.maxConnections){const s=this.createConnection(t);return e.push(s),s}return this.waitForConnection(t)}async waitForConnection(t){const e=Date.now(),s=this.options.requestTimeout;for(;Date.now()-e<s;){const e=this.connections.get(t);if(!e)throw new Error(`Connection pool for ${t} disappeared`);const s=e.find(t=>"idle"===t.state);if(s)return s.state="active",s;await new Promise(t=>setTimeout(t,10))}throw new Error(`Timeout waiting for connection to ${t} after ${s}ms`)}createConnection(t){const e=new Uint8Array(8);crypto.getRandomValues(e);return{id:`conn_${Array.from(e).map(t=>t.toString(16).padStart(2,"0")).join("")}`,origin:t,createdAt:Date.now(),lastUsedAt:Date.now(),requestCount:0,state:"active",controller:new AbortController}}getOrigin(t){try{const e=new URL(t);return`${e.protocol}//${e.host}`}catch{throw new Error(`Invalid URL: ${t}`)}}recordMetrics(t,e){this.metrics.requestDurations.push(e),this.metrics.requestDurations.length>1e3&&this.metrics.requestDurations.shift();let s=this.metrics.byOrigin.get(t);s||(s={requests:0,durations:[]},this.metrics.byOrigin.set(t,s)),s.requests++,s.durations.push(e),s.durations.length>100&&s.durations.shift()}getMetrics(){let t=0,e=0,s=0;const n=new Map;for(const[o,i]of this.connections.entries()){t+=i.length,e+=i.filter(t=>"active"===t.state).length,s+=i.filter(t=>"idle"===t.state).length;const r=this.metrics.byOrigin.get(o);if(r){const t=r.durations.length>0?r.durations.reduce((t,e)=>t+e,0)/r.durations.length:0;n.set(o,{connections:i.length,requests:r.requests,avgDuration:Math.round(t)})}}const o=this.metrics.requestDurations.length>0?Math.round(this.metrics.requestDurations.reduce((t,e)=>t+e,0)/this.metrics.requestDurations.length):0,i=this.metrics.totalRequests>0?this.metrics.reuseCount/this.metrics.totalRequests:0;return{totalConnections:t,activeConnections:e,idleConnections:s,totalRequests:this.metrics.totalRequests,reuseCount:this.metrics.reuseCount,failedRequests:this.metrics.failedRequests,avgRequestDuration:o,hitRate:i,byOrigin:n}}resetMetrics(){this.metrics={totalRequests:0,reuseCount:0,failedRequests:0,requestDurations:[],byOrigin:new Map}}startCleanup(){this.cleanupInterval=setInterval(()=>{this.cleanup()},1e4)}cleanup(){const t=Date.now();for(const[e,s]of this.connections.entries()){const n=s.filter(e=>t-e.lastUsedAt>this.options.idleTimeout&&"idle"===e.state?(e.controller.abort(),e.state="closed",!1):"closed"!==e.state);for(;n.length<this.options.minConnections&&n.length<this.options.maxConnections;){const t=this.createConnection(e);t.state="idle",n.push(t)}n.length>0?this.connections.set(e,n):this.connections.delete(e)}}cleanupNow(){this.cleanup()}async close(){this.cleanupInterval&&(clearInterval(this.cleanupInterval),this.cleanupInterval=null);for(const[t,e]of this.connections.entries())for(const t of e)t.controller.abort(),t.state="closed";this.connections.clear()}getConnectionCount(t){const e=this.connections.get(t);return e?e.length:0}getOrigins(){return Array.from(this.connections.keys())}isHealthy(){const t=this.getMetrics();return!((t.totalRequests>0?t.failedRequests/t.totalRequests:0)>.1)&&!(t.avgRequestDuration>5e3)}}let globalPool=null;export function getGlobalPool(t){return globalPool||(globalPool=new ConnectionPool(t)),globalPool}export async function resetGlobalPool(){globalPool&&(await globalPool.close(),globalPool=null)}