@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/connection-pool.js

@@ -1 +1,500 @@
-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(n){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(e){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)}
+/**
+ * @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;
+    }
+}