specmem-hardwicksoftware 3.5.99

package/dist/utils/timeoutMiddleware.d.ts

@@ -0,0 +1,81 @@
+/**
+ * timeoutMiddleware.ts - Request Timeout Middleware
+ *
+ * Provides timeout middleware for Express to prevent long-running requests
+ * from hanging indefinitely and consuming resources.
+ *
+ * Features:
+ * - Configurable timeout per route
+ * - Custom timeout response
+ * - Request cleanup on timeout
+ *
+ * @author hardwicksoftwareservices
+ */
+import { Request, Response, NextFunction } from 'express';
+/**
+ * Timeout configuration options
+ */
+export interface TimeoutConfig {
+    /** Timeout in milliseconds (default: 30000 = 30 seconds) */
+    timeout: number;
+    /** Custom message to send on timeout */
+    message?: string;
+    /** Whether to log timeout events (default: true) */
+    log?: boolean;
+}
+/**
+ * Create request timeout middleware
+ *
+ * @param options Timeout configuration options
+ * @returns Express middleware function
+ */
+export declare function requestTimeout(options?: Partial<TimeoutConfig>): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Set server timeouts
+ * Should be called after server is created
+ */
+export declare function setServerTimeouts(server: import('http').Server | import('https').Server, options?: {
+    /** Keep-alive timeout (default: 5000ms) */
+    keepAliveTimeout?: number;
+    /** Headers timeout (default: 60000ms) */
+    headersTimeout?: number;
+    /** Request timeout (default: 120000ms) */
+    requestTimeout?: number;
+}): void;
+/**
+ * WebSocket ping/pong timeout configuration
+ */
+export interface WsPingPongConfig {
+    /** Ping interval in milliseconds (default: 30000 = 30 seconds) */
+    pingInterval: number;
+    /** Pong timeout in milliseconds (default: 10000 = 10 seconds) */
+    pongTimeout: number;
+}
+/**
+ * Default WebSocket ping/pong configuration
+ */
+export declare const DEFAULT_WS_PING_PONG: WsPingPongConfig;
+/**
+ * Setup WebSocket ping/pong for connection health
+ *
+ * @param ws WebSocket instance
+ * @param config Ping/pong configuration
+ * @returns Cleanup function to stop ping/pong
+ */
+export declare function setupWsPingPong(ws: import('ws').WebSocket, config?: WsPingPongConfig): () => void;
+/**
+ * Database connection timeout configuration
+ * These are already set in connectionPoolGoBrrr.ts, but we export
+ * environment variable names for documentation
+ */
+export declare const DB_TIMEOUT_ENV_VARS: {
+    /** Connection timeout in ms (default: 10000) */
+    connectionTimeout: string;
+    /** Statement timeout in ms (default: 30000) */
+    statementTimeout: string;
+    /** Query timeout in ms (default: 60000) */
+    queryTimeout: string;
+    /** Idle timeout in ms (default: 30000) */
+    idleTimeout: string;
+};
+//# sourceMappingURL=timeoutMiddleware.d.ts.map

package/dist/utils/timeoutMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeoutMiddleware.d.ts","sourceRoot":"","sources":["../../src/utils/timeoutMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG1D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAWD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,IAGrD,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,UAmCxD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,OAAO,MAAM,EAAE,MAAM,GAAG,OAAO,OAAO,EAAE,MAAM,EACtD,OAAO,CAAC,EAAE;IACR,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,IAAI,CAgBN;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,gBAGlC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,OAAO,IAAI,EAAE,SAAS,EAC1B,MAAM,GAAE,gBAAuC,GAC9C,MAAM,IAAI,CAwDZ;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;IAC9B,gDAAgD;;IAEhD,+CAA+C;;IAE/C,2CAA2C;;IAE3C,0CAA0C;;CAE3C,CAAC"}

package/dist/utils/timeoutMiddleware.js

@@ -0,0 +1,155 @@
+/**
+ * timeoutMiddleware.ts - Request Timeout Middleware
+ *
+ * Provides timeout middleware for Express to prevent long-running requests
+ * from hanging indefinitely and consuming resources.
+ *
+ * Features:
+ * - Configurable timeout per route
+ * - Custom timeout response
+ * - Request cleanup on timeout
+ *
+ * @author hardwicksoftwareservices
+ */
+import { logger } from './logger.js';
+/**
+ * Default timeout configuration
+ */
+const DEFAULT_TIMEOUT_CONFIG = {
+    timeout: parseInt(process.env['SPECMEM_REQUEST_TIMEOUT'] || '180000', 10),
+    message: 'Request timeout',
+    log: true
+};
+/**
+ * Create request timeout middleware
+ *
+ * @param options Timeout configuration options
+ * @returns Express middleware function
+ */
+export function requestTimeout(options) {
+    const config = { ...DEFAULT_TIMEOUT_CONFIG, ...options };
+    return (req, res, next) => {
+        // Skip if response already sent
+        if (res.headersSent) {
+            return next();
+        }
+        // Set up timeout
+        const timeoutId = setTimeout(() => {
+            if (!res.headersSent) {
+                if (config.log) {
+                    logger.warn({
+                        method: req.method,
+                        url: req.url,
+                        timeout: config.timeout
+                    }, 'request timeout');
+                }
+                res.status(503).json({
+                    error: config.message,
+                    timeout: config.timeout
+                });
+            }
+        }, config.timeout);
+        // Clear timeout when response finishes
+        res.on('finish', () => {
+            clearTimeout(timeoutId);
+        });
+        res.on('close', () => {
+            clearTimeout(timeoutId);
+        });
+        next();
+    };
+}
+/**
+ * Set server timeouts
+ * Should be called after server is created
+ */
+export function setServerTimeouts(server, options) {
+    const { keepAliveTimeout = parseInt(process.env['SPECMEM_KEEP_ALIVE_TIMEOUT'] || '5000', 10), headersTimeout = parseInt(process.env['SPECMEM_HEADERS_TIMEOUT'] || '60000', 10), requestTimeout = parseInt(process.env['SPECMEM_REQUEST_TIMEOUT'] || '120000', 10) } = options || {};
+    server.keepAliveTimeout = keepAliveTimeout;
+    server.headersTimeout = headersTimeout;
+    server.requestTimeout = requestTimeout;
+    logger.debug({
+        keepAliveTimeout,
+        headersTimeout,
+        requestTimeout
+    }, 'server timeouts configured');
+}
+/**
+ * Default WebSocket ping/pong configuration
+ */
+export const DEFAULT_WS_PING_PONG = {
+    pingInterval: parseInt(process.env['SPECMEM_WS_PING_INTERVAL'] || '180000', 10),
+    pongTimeout: parseInt(process.env['SPECMEM_WS_PONG_TIMEOUT'] || '60000', 10)
+};
+/**
+ * Setup WebSocket ping/pong for connection health
+ *
+ * @param ws WebSocket instance
+ * @param config Ping/pong configuration
+ * @returns Cleanup function to stop ping/pong
+ */
+export function setupWsPingPong(ws, config = DEFAULT_WS_PING_PONG) {
+    let pingTimeout = null;
+    let pongTimeout = null;
+    let isAlive = true;
+    // Handle pong response
+    const handlePong = () => {
+        isAlive = true;
+        if (pongTimeout) {
+            clearTimeout(pongTimeout);
+            pongTimeout = null;
+        }
+    };
+    ws.on('pong', handlePong);
+    // Send periodic pings
+    const sendPing = () => {
+        if (ws.readyState !== ws.OPEN) {
+            return;
+        }
+        if (!isAlive) {
+            // Didn't receive pong, terminate connection
+            logger.debug('WebSocket connection timed out - no pong received');
+            ws.terminate();
+            return;
+        }
+        isAlive = false;
+        ws.ping();
+        // Set pong timeout
+        pongTimeout = setTimeout(() => {
+            if (!isAlive && ws.readyState === ws.OPEN) {
+                logger.debug('WebSocket pong timeout - terminating connection');
+                ws.terminate();
+            }
+        }, config.pongTimeout);
+    };
+    // Start ping interval
+    pingTimeout = setInterval(sendPing, config.pingInterval);
+    // Return cleanup function
+    return () => {
+        if (pingTimeout) {
+            clearInterval(pingTimeout);
+            pingTimeout = null;
+        }
+        if (pongTimeout) {
+            clearTimeout(pongTimeout);
+            pongTimeout = null;
+        }
+        ws.removeListener('pong', handlePong);
+    };
+}
+/**
+ * Database connection timeout configuration
+ * These are already set in connectionPoolGoBrrr.ts, but we export
+ * environment variable names for documentation
+ */
+export const DB_TIMEOUT_ENV_VARS = {
+    /** Connection timeout in ms (default: 10000) */
+    connectionTimeout: 'SPECMEM_DB_CONNECTION_TIMEOUT',
+    /** Statement timeout in ms (default: 30000) */
+    statementTimeout: 'SPECMEM_DB_STATEMENT_TIMEOUT',
+    /** Query timeout in ms (default: 60000) */
+    queryTimeout: 'SPECMEM_DB_QUERY_TIMEOUT',
+    /** Idle timeout in ms (default: 30000) */
+    idleTimeout: 'SPECMEM_DB_IDLE_TIMEOUT'
+};
+//# sourceMappingURL=timeoutMiddleware.js.map

package/dist/utils/timeoutMiddleware.js.map

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

package/dist/utils/timerRegistry.d.ts

@@ -0,0 +1,91 @@
+/**
+ * timerRegistry.ts - Graceful Timer Management for SpecMem
+ *
+ * yo this registry keeps track of ALL intervals and timeouts
+ * so we can clean them up properly on shutdown
+ * no more orphaned timers fr fr
+ *
+ * Issue #18 fix - graceful shutdown for intervals/timers
+ */
+/**
+ * Timer types we track
+ */
+type TimerType = 'interval' | 'timeout';
+/**
+ * TimerRegistry - centralized timer management
+ *
+ * Features that SLAP:
+ * - Track all setInterval/setTimeout calls
+ * - Graceful cleanup on shutdown
+ * - Debug logging for timer lifecycle
+ * - Prevent timer leaks in tests
+ */
+declare class TimerRegistry {
+    private timers;
+    private isShuttingDown;
+    private nextId;
+    /**
+     * Register and start an interval
+     */
+    registerInterval(callback: () => void, ms: number, description?: string): string;
+    /**
+     * Register and start a timeout
+     */
+    registerTimeout(callback: () => void, ms: number, description?: string): string;
+    /**
+     * Clear a specific timer by ID
+     */
+    clear(id: string): boolean;
+    /**
+     * Clear all timers - for graceful shutdown
+     */
+    clearAll(): number;
+    /**
+     * Get count of active timers
+     */
+    getActiveCount(): number;
+    /**
+     * Get detailed stats about active timers
+     */
+    getStats(): {
+        total: number;
+        intervals: number;
+        timeouts: number;
+        timers: Array<{
+            id: string;
+            type: TimerType;
+            description: string;
+            ageMs: number;
+        }>;
+    };
+    /**
+     * Reset the registry (for testing)
+     */
+    reset(): void;
+}
+/**
+ * Get the global timer registry
+ */
+export declare function getTimerRegistry(): TimerRegistry;
+/**
+ * Reset the global timer registry (for testing)
+ */
+export declare function resetTimerRegistry(): void;
+/**
+ * Convenience function - register an interval
+ */
+export declare function registerInterval(callback: () => void, ms: number, description?: string): string;
+/**
+ * Convenience function - register a timeout
+ */
+export declare function registerTimeout(callback: () => void, ms: number, description?: string): string;
+/**
+ * Convenience function - clear a timer
+ */
+export declare function clearRegisteredTimer(id: string): boolean;
+/**
+ * Convenience function - clear all timers (for shutdown)
+ */
+export declare function clearAllTimers(): number;
+export { TimerRegistry };
+//# sourceMappingURL=timerRegistry.d.ts.map

package/dist/utils/timerRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timerRegistry.d.ts","sourceRoot":"","sources":["../../src/utils/timerRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,KAAK,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAaxC;;;;;;;;GAQG;AACH,cAAM,aAAa;IACjB,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAK;IAEnB;;OAEG;IACH,gBAAgB,CACd,QAAQ,EAAE,MAAM,IAAI,EACpB,EAAE,EAAE,MAAM,EACV,WAAW,GAAE,MAA2B,GACvC,MAAM;IAsBT;;OAEG;IACH,eAAe,CACb,QAAQ,EAAE,MAAM,IAAI,EACpB,EAAE,EAAE,MAAM,EACV,WAAW,GAAE,MAA0B,GACtC,MAAM;IA4BT;;OAEG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAiB1B;;OAEG;IACH,QAAQ,IAAI,MAAM;IAmBlB;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,QAAQ,IAAI;QACV,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,KAAK,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,SAAS,CAAC;YAAC,WAAW,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACpF;IAkBD;;OAEG;IACH,KAAK,IAAI,IAAI;CAKd;AAKD;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAKzC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,IAAI,EACpB,EAAE,EAAE,MAAM,EACV,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,IAAI,EACpB,EAAE,EAAE,MAAM,EACV,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/utils/timerRegistry.js

@@ -0,0 +1,187 @@
+/**
+ * timerRegistry.ts - Graceful Timer Management for SpecMem
+ *
+ * yo this registry keeps track of ALL intervals and timeouts
+ * so we can clean them up properly on shutdown
+ * no more orphaned timers fr fr
+ *
+ * Issue #18 fix - graceful shutdown for intervals/timers
+ */
+import { logger } from './logger.js';
+/**
+ * TimerRegistry - centralized timer management
+ *
+ * Features that SLAP:
+ * - Track all setInterval/setTimeout calls
+ * - Graceful cleanup on shutdown
+ * - Debug logging for timer lifecycle
+ * - Prevent timer leaks in tests
+ */
+class TimerRegistry {
+    timers = new Map();
+    isShuttingDown = false;
+    nextId = 0;
+    /**
+     * Register and start an interval
+     */
+    registerInterval(callback, ms, description = 'unnamed interval') {
+        if (this.isShuttingDown) {
+            logger.warn({ description }, 'attempted to register interval during shutdown');
+            // Return a dummy ID and don't actually create the interval
+            return `shutdown-blocked-${this.nextId++}`;
+        }
+        const id = `interval-${this.nextId++}`;
+        const handle = setInterval(callback, ms);
+        this.timers.set(id, {
+            id,
+            handle,
+            type: 'interval',
+            description,
+            createdAt: new Date()
+        });
+        logger.debug({ id, description, intervalMs: ms }, 'registered interval');
+        return id;
+    }
+    /**
+     * Register and start a timeout
+     */
+    registerTimeout(callback, ms, description = 'unnamed timeout') {
+        if (this.isShuttingDown) {
+            logger.warn({ description }, 'attempted to register timeout during shutdown');
+            return `shutdown-blocked-${this.nextId++}`;
+        }
+        const id = `timeout-${this.nextId++}`;
+        // Wrap callback to auto-remove from registry when it fires
+        const wrappedCallback = () => {
+            this.timers.delete(id);
+            callback();
+        };
+        const handle = setTimeout(wrappedCallback, ms);
+        this.timers.set(id, {
+            id,
+            handle,
+            type: 'timeout',
+            description,
+            createdAt: new Date()
+        });
+        logger.debug({ id, description, delayMs: ms }, 'registered timeout');
+        return id;
+    }
+    /**
+     * Clear a specific timer by ID
+     */
+    clear(id) {
+        const timer = this.timers.get(id);
+        if (!timer) {
+            return false;
+        }
+        if (timer.type === 'interval') {
+            clearInterval(timer.handle);
+        }
+        else {
+            clearTimeout(timer.handle);
+        }
+        this.timers.delete(id);
+        logger.debug({ id, description: timer.description }, 'cleared timer');
+        return true;
+    }
+    /**
+     * Clear all timers - for graceful shutdown
+     */
+    clearAll() {
+        this.isShuttingDown = true;
+        let count = 0;
+        for (const [id, timer] of this.timers) {
+            if (timer.type === 'interval') {
+                clearInterval(timer.handle);
+            }
+            else {
+                clearTimeout(timer.handle);
+            }
+            logger.debug({ id, description: timer.description, type: timer.type }, 'cleared timer during shutdown');
+            count++;
+        }
+        this.timers.clear();
+        logger.info({ clearedCount: count }, 'all timers cleared during shutdown');
+        return count;
+    }
+    /**
+     * Get count of active timers
+     */
+    getActiveCount() {
+        return this.timers.size;
+    }
+    /**
+     * Get detailed stats about active timers
+     */
+    getStats() {
+        const now = Date.now();
+        const intervals = Array.from(this.timers.values()).filter(t => t.type === 'interval').length;
+        const timeouts = this.timers.size - intervals;
+        return {
+            total: this.timers.size,
+            intervals,
+            timeouts,
+            timers: Array.from(this.timers.values()).map(t => ({
+                id: t.id,
+                type: t.type,
+                description: t.description,
+                ageMs: now - t.createdAt.getTime()
+            }))
+        };
+    }
+    /**
+     * Reset the registry (for testing)
+     */
+    reset() {
+        this.clearAll();
+        this.isShuttingDown = false;
+        this.nextId = 0;
+    }
+}
+// Singleton instance - THE ONE AND ONLY timer registry
+let registryInstance = null;
+/**
+ * Get the global timer registry
+ */
+export function getTimerRegistry() {
+    if (!registryInstance) {
+        registryInstance = new TimerRegistry();
+    }
+    return registryInstance;
+}
+/**
+ * Reset the global timer registry (for testing)
+ */
+export function resetTimerRegistry() {
+    if (registryInstance) {
+        registryInstance.reset();
+    }
+    registryInstance = null;
+}
+/**
+ * Convenience function - register an interval
+ */
+export function registerInterval(callback, ms, description) {
+    return getTimerRegistry().registerInterval(callback, ms, description);
+}
+/**
+ * Convenience function - register a timeout
+ */
+export function registerTimeout(callback, ms, description) {
+    return getTimerRegistry().registerTimeout(callback, ms, description);
+}
+/**
+ * Convenience function - clear a timer
+ */
+export function clearRegisteredTimer(id) {
+    return getTimerRegistry().clear(id);
+}
+/**
+ * Convenience function - clear all timers (for shutdown)
+ */
+export function clearAllTimers() {
+    return getTimerRegistry().clearAll();
+}
+export { TimerRegistry };
+//# sourceMappingURL=timerRegistry.js.map

package/dist/utils/timerRegistry.js.map

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