request-scope-api 1.0.21 → 1.0.23

package/dist/cjs/shutdown-manager.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * ShutdownManager — Manages graceful shutdown of all RequestScope resources.
+ *
+ * This centralizes shutdown logic to prevent multiple shutdown executions,
+ * add comprehensive logging, and expose a shutdown() method that the host
+ * application can call instead of relying on global signal handlers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shutdownManager = void 0;
+const adapter_singleton_js_1 = require("./adapter-singleton.js");
+class ShutdownManager {
+    constructor() {
+        this.isShuttingDown = false;
+        this.resources = {};
+    }
+    /**
+     * Registers resources that need to be cleaned up during shutdown.
+     */
+    registerResources(resources) {
+        this.resources = { ...this.resources, ...resources };
+    }
+    /**
+     * Performs graceful shutdown of all registered resources.
+     *
+     * Steps:
+     * 1. Prevents multiple shutdown executions
+     * 2. Stops retention scheduler
+     * 3. Drains queue with timeout
+     * 4. Destroys queue
+     * 5. Closes all database connections
+     * 6. Logs remaining active handles for debugging
+     */
+    async shutdown(options = {}) {
+        const { drainTimeoutMs = 5000, logHandles = false } = options;
+        // Prevent multiple shutdown executions
+        if (this.isShuttingDown) {
+            process.stderr.write('[RequestScope] Shutdown already in progress, skipping duplicate call\n');
+            return;
+        }
+        this.isShuttingDown = true;
+        process.stderr.write('[RequestScope] Starting graceful shutdown...\n');
+        const startTime = Date.now();
+        try {
+            // 1. Stop retention scheduler
+            if (this.resources.retentionScheduler) {
+                process.stderr.write('[RequestScope] Stopping retention scheduler...\n');
+                this.resources.retentionScheduler.stop();
+            }
+            // 2. Drain queue with timeout
+            if (this.resources.queue) {
+                process.stderr.write(`[RequestScope] Draining queue (timeout: ${drainTimeoutMs}ms)...\n`);
+                try {
+                    await Promise.race([
+                        this.resources.queue.drain(drainTimeoutMs),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error('Queue drain timeout')), drainTimeoutMs))
+                    ]);
+                    process.stderr.write('[RequestScope] Queue drained successfully\n');
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`[RequestScope] Queue drain warning: ${message}\n`);
+                }
+                // 3. Destroy queue (clears timer)
+                process.stderr.write('[RequestScope] Destroying queue...\n');
+                this.resources.queue.destroy();
+            }
+            // 4. Close all database connections
+            process.stderr.write('[RequestScope] Closing database connections...\n');
+            await adapter_singleton_js_1.adapterSingleton.closeAll();
+            process.stderr.write('[RequestScope] Database connections closed\n');
+            const duration = Date.now() - startTime;
+            process.stderr.write(`[RequestScope] Graceful shutdown completed in ${duration}ms\n`);
+            // 5. Log remaining active handles for debugging
+            if (logHandles) {
+                this.logActiveHandles();
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[RequestScope] Shutdown error: ${message}\n`);
+            // Log active handles even on error
+            if (logHandles) {
+                this.logActiveHandles();
+            }
+        }
+    }
+    /**
+     * Logs active handles to help identify what's preventing process exit.
+     */
+    logActiveHandles() {
+        try {
+            // @ts-ignore - _getActiveHandles is not in TypeScript definitions
+            const handles = process._getActiveHandles();
+            process.stderr.write(`[RequestScope] Active handles (${handles.length}):\n`);
+            for (let i = 0; i < Math.min(handles.length, 20); i++) {
+                const handle = handles[i];
+                const type = handle.constructor.name;
+                // @ts-ignore
+                const details = handle._handle?.type || '';
+                process.stderr.write(`  [${i}] ${type}${details ? ` (${details})` : ''}\n`);
+            }
+            if (handles.length > 20) {
+                process.stderr.write(`  ... and ${handles.length - 20} more\n`);
+            }
+        }
+        catch (err) {
+            process.stderr.write('[RequestScope] Could not log active handles\n');
+        }
+    }
+    /**
+     * Returns whether shutdown is currently in progress.
+     */
+    isShutdownInProgress() {
+        return this.isShuttingDown;
+    }
+}
+// Export singleton instance
+exports.shutdownManager = new ShutdownManager();
+//# sourceMappingURL=shutdown-manager.js.map

package/dist/cjs/shutdown-manager.js.map

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

package/dist/esm/adapter-singleton.js

@@ -0,0 +1,140 @@
+/**
+ * AdapterSingleton — Manages singleton database adapter instances.
+ *
+ * Ensures that only one database connection/pool exists per unique configuration
+ * across the entire application lifecycle. This prevents:
+ * - Multiple connection pools when middleware is called multiple times
+ * - Duplicate connections when setup function is imported multiple times
+ * - Connection leaks on server restarts in dev mode (nodemon)
+ *
+ * The singleton is keyed by a hash of the storage configuration, so different
+ * configurations will have separate connections (as expected).
+ */
+import { MongoAdapter } from './adapters/mongo.adapter.js';
+import { MySQLAdapter } from './adapters/mysql.adapter.js';
+import { PgAdapter } from './adapters/pg.adapter.js';
+// ---------------------------------------------------------------------------
+// Configuration hash helper
+// ---------------------------------------------------------------------------
+/**
+ * Creates a stable hash string from storage configuration.
+ * This is used as the key for singleton instances.
+ */
+function hashStorageConfig(config) {
+    const parts = [config.type];
+    if (config.type === 'mongodb') {
+        parts.push(config.uri || '');
+    }
+    else if (config.type === 'mysql' || config.type === 'postgresql') {
+        parts.push(config.host || 'localhost', String(config.port || (config.type === 'mysql' ? 3306 : 5432)), config.database || '', config.username || '');
+    }
+    return parts.join(':');
+}
+class AdapterSingletonManager {
+    constructor() {
+        this.instances = new Map();
+    }
+    /**
+     * Gets or creates a singleton adapter instance for the given configuration.
+     *
+     * @param config - Storage configuration
+     * @returns StorageAdapter instance (shared if already exists)
+     */
+    getOrCreate(config) {
+        const hash = hashStorageConfig(config);
+        const existing = this.instances.get(hash);
+        if (existing) {
+            // Increment reference count
+            existing.refCount++;
+            return existing.adapter;
+        }
+        // Create new adapter instance
+        let adapter;
+        switch (config.type) {
+            case 'mongodb':
+                adapter = new MongoAdapter(config);
+                break;
+            case 'mysql':
+                adapter = new MySQLAdapter(config);
+                break;
+            case 'postgresql':
+                adapter = new PgAdapter(config);
+                break;
+            default:
+                throw new Error(`Unsupported storage type: ${config.type}`);
+        }
+        // Store in singleton map
+        this.instances.set(hash, {
+            adapter,
+            refCount: 1,
+            initialized: false,
+        });
+        return adapter;
+    }
+    /**
+     * Marks an adapter as initialized.
+     * This is called after successful adapter.initialize().
+     */
+    markInitialized(adapter, config) {
+        const hash = hashStorageConfig(config);
+        const entry = this.instances.get(hash);
+        if (entry && entry.adapter === adapter) {
+            entry.initialized = true;
+        }
+    }
+    /**
+     * Decrements reference count for an adapter.
+     * When reference count reaches zero, the adapter is cleaned up.
+     *
+     * @param adapter - StorageAdapter instance to release
+     * @param config - Storage configuration used to create the adapter
+     */
+    release(adapter, config) {
+        const hash = hashStorageConfig(config);
+        const entry = this.instances.get(hash);
+        if (entry && entry.adapter === adapter) {
+            entry.refCount--;
+            // Clean up if no more references
+            if (entry.refCount <= 0) {
+                this.instances.delete(hash);
+                // Close the connection to prevent connection leaks
+                void adapter.close().catch((err) => {
+                    const message = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`[RequestScope] Error closing adapter: ${message}\n`);
+                });
+            }
+        }
+    }
+    /**
+     * Gets the current number of singleton instances (for debugging).
+     */
+    getInstanceCount() {
+        return this.instances.size;
+    }
+    /**
+     * Clears all singleton instances.
+     * This should only be used in tests or on application shutdown.
+     */
+    clearAll() {
+        this.instances.clear();
+    }
+    /**
+     * Closes all adapter connections and clears the singleton instances.
+     * This should be called during application graceful shutdown.
+     */
+    async closeAll() {
+        const closePromises = [];
+        for (const [hash, entry] of this.instances.entries()) {
+            closePromises.push(entry.adapter.close().catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[RequestScope] Error closing adapter [${hash}]: ${message}\n`);
+            }));
+        }
+        await Promise.all(closePromises);
+        this.instances.clear();
+    }
+}
+// ---------------------------------------------------------------------------
+// Export singleton instance
+// ---------------------------------------------------------------------------
+export const adapterSingleton = new AdapterSingletonManager();

package/dist/esm/adapters/mongo.adapter.js

@@ -180,4 +180,14 @@ export class MongoAdapter {
         });
         return result.deletedCount;
     }
+    // -------------------------------------------------------------------------
+    // close()
+    // -------------------------------------------------------------------------
+    async close() {
+        if (this.client) {
+            await this.client.close();
+            this.client = null;
+            this.collection = null;
+        }
+    }
 }

package/dist/esm/adapters/mysql.adapter.js

@@ -224,6 +224,15 @@ export class MySQLAdapter {
         return result.affectedRows;
     }
     // -------------------------------------------------------------------------
+    // close()
+    // -------------------------------------------------------------------------
+    async close() {
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = null;
+        }
+    }
+    // -------------------------------------------------------------------------
     // Private helpers
     // -------------------------------------------------------------------------
     getPool() {

package/dist/esm/adapters/pg.adapter.js

@@ -320,6 +320,15 @@ export class PgAdapter {
         return result.rowCount ?? 0;
     }
     // -------------------------------------------------------------------------
+    // close()
+    // -------------------------------------------------------------------------
+    async close() {
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = null;
+        }
+    }
+    // -------------------------------------------------------------------------
     // Private helpers
     // -------------------------------------------------------------------------
     getPool() {

package/dist/esm/index.js

@@ -11,6 +11,7 @@
 import express from 'express';
 import { requestscope as requestscopeMiddleware, errorHandler, setup } from './middleware.js';
 import { createDashboardRouter } from './dashboard/router.js';
+import { shutdownManager } from './shutdown-manager.js';
 // ---------------------------------------------------------------------------
 // Main middleware factory
 // ---------------------------------------------------------------------------
@@ -55,6 +56,26 @@ export { setup };
 // ---------------------------------------------------------------------------
 export { errorHandler };
 // ---------------------------------------------------------------------------
+// Shutdown function
+// ---------------------------------------------------------------------------
+/**
+ * Gracefully shuts down all RequestScope resources.
+ *
+ * This should be called by the host application during shutdown (e.g., on SIGTERM/SIGINT).
+ * It will:
+ * - Stop the retention scheduler
+ * - Drain the queue with a timeout
+ * - Destroy the queue (clear timers)
+ * - Close all database connections
+ *
+ * @param options - Optional configuration for shutdown
+ * @param options.drainTimeoutMs - Timeout for queue drain in milliseconds (default: 5000)
+ * @param options.logHandles - Whether to log active handles after shutdown (default: false)
+ */
+export async function shutdown(options) {
+    await shutdownManager.shutdown(options);
+}
+// ---------------------------------------------------------------------------
 // Named exports for convenience
 // ---------------------------------------------------------------------------
 export { requestscope as requestscopeMiddleware } from './middleware.js';

package/dist/esm/middleware.js

@@ -11,13 +11,12 @@
  * Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 2.2, 4.1, 4.2, 4.3, 5.1
  */
 import { validateConfig, applyDefaults, buildSensitiveFieldSet } from './config.js';
-import { MongoAdapter } from './adapters/mongo.adapter.js';
-import { MySQLAdapter } from './adapters/mysql.adapter.js';
-import { PgAdapter } from './adapters/pg.adapter.js';
 import { AsyncQueue } from './queue.js';
 import { RetentionScheduler } from './retention.js';
 import { bufferRequestBody, wrapResponse, normalizeRequestUrl, ERROR_DATA_SYMBOL, } from './capture.js';
 import { createDashboardRouter } from './dashboard/router.js';
+import { adapterSingleton } from './adapter-singleton.js';
+import { shutdownManager } from './shutdown-manager.js';
 const ALWAYS_IGNORED_PATHS = ['/favicon.ico', '/requestscope/api', '/requestscope/assets'];
 // ---------------------------------------------------------------------------
 // Factory function
@@ -56,25 +55,15 @@ export function requestscope(config, adapter) {
     validateConfig(config);
     applyDefaults(config);
     const sensitiveFields = buildSensitiveFieldSet(config);
-    // 2. Instantiate the appropriate storage adapter (if not provided)
+    // 2. Get or create singleton adapter instance
     if (!adapter) {
-        switch (config.storage.type) {
-            case 'mongodb':
-                adapter = new MongoAdapter(config.storage);
-                break;
-            case 'mysql':
-                adapter = new MySQLAdapter(config.storage);
-                break;
-            case 'postgresql':
-                adapter = new PgAdapter(config.storage);
-                break;
-            default:
-                // This should never happen due to validateConfig, but TypeScript needs it
-                throw new Error(`Unsupported storage type: ${config.storage.type}`);
-        }
+        adapter = adapterSingleton.getOrCreate(config.storage);
     }
     // 3. Initialize adapter asynchronously (log errors, don't throw)
-    void adapter.initialize().catch((err) => {
+    // Only initialize if not already initialized
+    void adapter.initialize().then(() => {
+        adapterSingleton.markInitialized(adapter, config.storage);
+    }).catch((err) => {
         const message = err instanceof Error ? err.message : String(err);
         process.stderr.write(`[RequestScope] Failed to initialize storage adapter: ${message}\n`);
     });
@@ -83,23 +72,16 @@ export function requestscope(config, adapter) {
     const retentionDays = config.retentionDays ?? 30;
     const retentionScheduler = new RetentionScheduler(adapter, retentionDays);
     retentionScheduler.start();
-    // 5. Attach graceful shutdown handlers (only once per process)
-    const shutdown = async () => {
-        retentionScheduler.stop();
-        await queue.drain(10000);
-        queue.destroy();
-    };
-    // Use a flag to ensure shutdown handlers are only attached once
-    const shutdownKey = '__requestscope_shutdown_attached__';
-    if (!process[shutdownKey]) {
-        process[shutdownKey] = true;
-        process.on('SIGTERM', () => {
-            void shutdown();
-        });
-        process.on('SIGINT', () => {
-            void shutdown();
-        });
-    }
+    // 5. Register resources with shutdown manager
+    shutdownManager.registerResources({
+        queue: {
+            drain: (timeoutMs) => queue.drain(timeoutMs),
+            destroy: () => queue.destroy(),
+        },
+        retentionScheduler: {
+            stop: () => retentionScheduler.stop(),
+        },
+    });
     // 6. Return the request handler middleware
     return async (req, res, next) => {
         // Check ignore list
@@ -153,23 +135,12 @@ export function setup(app, config) {
     // Validate and apply defaults
     validateConfig(config);
     applyDefaults(config);
-    // Instantiate the appropriate storage adapter
-    let adapter;
-    switch (config.storage.type) {
-        case 'mongodb':
-            adapter = new MongoAdapter(config.storage);
-            break;
-        case 'mysql':
-            adapter = new MySQLAdapter(config.storage);
-            break;
-        case 'postgresql':
-            adapter = new PgAdapter(config.storage);
-            break;
-        default:
-            throw new Error(`Unsupported storage type: ${config.storage.type}`);
-    }
+    // Get or create singleton adapter instance
+    const adapter = adapterSingleton.getOrCreate(config.storage);
     // Initialize adapter asynchronously
-    void adapter.initialize().catch((err) => {
+    void adapter.initialize().then(() => {
+        adapterSingleton.markInitialized(adapter, config.storage);
+    }).catch((err) => {
         const message = err instanceof Error ? err.message : String(err);
         process.stderr.write(`[RequestScope] Failed to initialize storage adapter: ${message}\n`);
     });

package/dist/esm/retention.js

@@ -27,6 +27,10 @@ export class RetentionScheduler {
         this.intervalHandle = setInterval(() => {
             void this.runOnce();
         }, TWENTY_FOUR_HOURS_MS);
+        // Allow the Node.js process to exit even if this timer is still active.
+        if (this.intervalHandle.unref) {
+            this.intervalHandle.unref();
+        }
     }
     /**
      * Stops the scheduled retention job.  Inflight `runOnce()` calls are allowed

package/dist/esm/shutdown-manager.js

@@ -0,0 +1,116 @@
+/**
+ * ShutdownManager — Manages graceful shutdown of all RequestScope resources.
+ *
+ * This centralizes shutdown logic to prevent multiple shutdown executions,
+ * add comprehensive logging, and expose a shutdown() method that the host
+ * application can call instead of relying on global signal handlers.
+ */
+import { adapterSingleton } from './adapter-singleton.js';
+class ShutdownManager {
+    constructor() {
+        this.isShuttingDown = false;
+        this.resources = {};
+    }
+    /**
+     * Registers resources that need to be cleaned up during shutdown.
+     */
+    registerResources(resources) {
+        this.resources = { ...this.resources, ...resources };
+    }
+    /**
+     * Performs graceful shutdown of all registered resources.
+     *
+     * Steps:
+     * 1. Prevents multiple shutdown executions
+     * 2. Stops retention scheduler
+     * 3. Drains queue with timeout
+     * 4. Destroys queue
+     * 5. Closes all database connections
+     * 6. Logs remaining active handles for debugging
+     */
+    async shutdown(options = {}) {
+        const { drainTimeoutMs = 5000, logHandles = false } = options;
+        // Prevent multiple shutdown executions
+        if (this.isShuttingDown) {
+            process.stderr.write('[RequestScope] Shutdown already in progress, skipping duplicate call\n');
+            return;
+        }
+        this.isShuttingDown = true;
+        process.stderr.write('[RequestScope] Starting graceful shutdown...\n');
+        const startTime = Date.now();
+        try {
+            // 1. Stop retention scheduler
+            if (this.resources.retentionScheduler) {
+                process.stderr.write('[RequestScope] Stopping retention scheduler...\n');
+                this.resources.retentionScheduler.stop();
+            }
+            // 2. Drain queue with timeout
+            if (this.resources.queue) {
+                process.stderr.write(`[RequestScope] Draining queue (timeout: ${drainTimeoutMs}ms)...\n`);
+                try {
+                    await Promise.race([
+                        this.resources.queue.drain(drainTimeoutMs),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error('Queue drain timeout')), drainTimeoutMs))
+                    ]);
+                    process.stderr.write('[RequestScope] Queue drained successfully\n');
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`[RequestScope] Queue drain warning: ${message}\n`);
+                }
+                // 3. Destroy queue (clears timer)
+                process.stderr.write('[RequestScope] Destroying queue...\n');
+                this.resources.queue.destroy();
+            }
+            // 4. Close all database connections
+            process.stderr.write('[RequestScope] Closing database connections...\n');
+            await adapterSingleton.closeAll();
+            process.stderr.write('[RequestScope] Database connections closed\n');
+            const duration = Date.now() - startTime;
+            process.stderr.write(`[RequestScope] Graceful shutdown completed in ${duration}ms\n`);
+            // 5. Log remaining active handles for debugging
+            if (logHandles) {
+                this.logActiveHandles();
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[RequestScope] Shutdown error: ${message}\n`);
+            // Log active handles even on error
+            if (logHandles) {
+                this.logActiveHandles();
+            }
+        }
+    }
+    /**
+     * Logs active handles to help identify what's preventing process exit.
+     */
+    logActiveHandles() {
+        try {
+            // @ts-ignore - _getActiveHandles is not in TypeScript definitions
+            const handles = process._getActiveHandles();
+            process.stderr.write(`[RequestScope] Active handles (${handles.length}):\n`);
+            for (let i = 0; i < Math.min(handles.length, 20); i++) {
+                const handle = handles[i];
+                const type = handle.constructor.name;
+                // @ts-ignore
+                const details = handle._handle?.type || '';
+                process.stderr.write(`  [${i}] ${type}${details ? ` (${details})` : ''}\n`);
+            }
+            if (handles.length > 20) {
+                process.stderr.write(`  ... and ${handles.length - 20} more\n`);
+            }
+        }
+        catch (err) {
+            process.stderr.write('[RequestScope] Could not log active handles\n');
+        }
+    }
+    /**
+     * Returns whether shutdown is currently in progress.
+     */
+    isShutdownInProgress() {
+        return this.isShuttingDown;
+    }
+}
+// Export singleton instance
+export const shutdownManager = new ShutdownManager();

package/dist/types/adapter-singleton.d.ts

@@ -0,0 +1,52 @@
+/**
+ * AdapterSingleton — Manages singleton database adapter instances.
+ *
+ * Ensures that only one database connection/pool exists per unique configuration
+ * across the entire application lifecycle. This prevents:
+ * - Multiple connection pools when middleware is called multiple times
+ * - Duplicate connections when setup function is imported multiple times
+ * - Connection leaks on server restarts in dev mode (nodemon)
+ *
+ * The singleton is keyed by a hash of the storage configuration, so different
+ * configurations will have separate connections (as expected).
+ */
+import type { StorageAdapter, StorageConfig } from './types.js';
+declare class AdapterSingletonManager {
+    private instances;
+    /**
+     * Gets or creates a singleton adapter instance for the given configuration.
+     *
+     * @param config - Storage configuration
+     * @returns StorageAdapter instance (shared if already exists)
+     */
+    getOrCreate(config: StorageConfig): StorageAdapter;
+    /**
+     * Marks an adapter as initialized.
+     * This is called after successful adapter.initialize().
+     */
+    markInitialized(adapter: StorageAdapter, config: StorageConfig): void;
+    /**
+     * Decrements reference count for an adapter.
+     * When reference count reaches zero, the adapter is cleaned up.
+     *
+     * @param adapter - StorageAdapter instance to release
+     * @param config - Storage configuration used to create the adapter
+     */
+    release(adapter: StorageAdapter, config: StorageConfig): void;
+    /**
+     * Gets the current number of singleton instances (for debugging).
+     */
+    getInstanceCount(): number;
+    /**
+     * Clears all singleton instances.
+     * This should only be used in tests or on application shutdown.
+     */
+    clearAll(): void;
+    /**
+     * Closes all adapter connections and clears the singleton instances.
+     * This should be called during application graceful shutdown.
+     */
+    closeAll(): Promise<void>;
+}
+export declare const adapterSingleton: AdapterSingletonManager;
+export {};

package/dist/types/adapters/mongo.adapter.d.ts

@@ -22,4 +22,5 @@ export declare class MongoAdapter implements StorageAdapter {
         total: number;
     }>;
     deleteOlderThan(date: Date): Promise<number>;
+    close(): Promise<void>;
 }

package/dist/types/adapters/mysql.adapter.d.ts

@@ -20,5 +20,6 @@ export declare class MySQLAdapter implements StorageAdapter {
         total: number;
     }>;
     deleteOlderThan(date: Date): Promise<number>;
+    close(): Promise<void>;
     private getPool;
 }

package/dist/types/adapters/pg.adapter.d.ts

@@ -25,5 +25,6 @@ export declare class PgAdapter implements StorageAdapter {
         total: number;
     }>;
     deleteOlderThan(date: Date): Promise<number>;
+    close(): Promise<void>;
     private getPool;
 }