@vorionsys/security 1.0.0

package/dist/intent/shutdown.js

@@ -0,0 +1,468 @@
+/**
+ * Graceful Shutdown Module
+ *
+ * Provides graceful shutdown handling for the INTENT module to ensure
+ * in-flight requests are completed during deployment.
+ *
+ * Features:
+ * - Track active HTTP requests
+ * - Reject new requests during shutdown with 503 status
+ * - Wait for in-flight requests to complete (with timeout)
+ * - Coordinate BullMQ worker shutdown
+ * - Close database and Redis connections
+ * - Comprehensive shutdown metrics logging
+ *
+ * @packageDocumentation
+ */
+import { createLogger } from '../common/logger.js';
+import { closeDatabase } from '../common/db.js';
+import { closeRedis } from '../common/redis.js';
+import { shutdownWorkers, pauseWorkers, waitForActiveJobs, shutdownCanaryQueue, closePooledConnections, } from './queues.js';
+import { shutdownGdprWorker } from './gdpr.js';
+import { stopScheduler } from './scheduler.js';
+import { shutdownAuditSystem } from './audit.js';
+import { stopRateLimiter } from '../api/rate-limit.js';
+import { resetRateLimitStore } from '../api/middleware/rateLimit.js';
+const logger = createLogger({ component: 'shutdown' });
+// Shutdown state
+let isShuttingDown = false;
+let activeRequests = 0;
+let shutdownPromise = null;
+let shutdownStartTime = null;
+// Configuration
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30000; // 30 seconds max wait
+const REQUEST_POLL_INTERVAL_MS = 1000; // Check every second
+let shutdownMetrics = null;
+/**
+ * Check if the server is currently shutting down
+ */
+export function isServerShuttingDown() {
+    return isShuttingDown;
+}
+/**
+ * Get the current number of active requests
+ */
+export function getActiveRequestCount() {
+    return activeRequests;
+}
+/**
+ * Get the last shutdown metrics (for monitoring/debugging)
+ */
+export function getLastShutdownMetrics() {
+    return shutdownMetrics;
+}
+/**
+ * Track a new request and return a cleanup function to call when complete.
+ * The cleanup function should be called in onResponse hook.
+ */
+export function trackRequest() {
+    if (isShuttingDown) {
+        // Even during shutdown, track for monitoring purposes
+        logger.warn('Request tracked during shutdown phase');
+    }
+    activeRequests++;
+    logger.debug({ activeRequests }, 'Request started');
+    let cleaned = false;
+    return () => {
+        if (cleaned)
+            return; // Prevent double cleanup
+        cleaned = true;
+        activeRequests--;
+        logger.debug({ activeRequests }, 'Request completed');
+    };
+}
+/**
+ * Wait for all active requests to complete with timeout
+ */
+async function waitForRequestsToComplete(timeoutMs) {
+    const startWait = Date.now();
+    const initialCount = activeRequests;
+    while (activeRequests > 0 && Date.now() - startWait < timeoutMs) {
+        logger.info({ activeRequests, elapsedMs: Date.now() - startWait, timeoutMs }, 'Waiting for in-flight requests to complete');
+        await new Promise((resolve) => setTimeout(resolve, REQUEST_POLL_INTERVAL_MS));
+    }
+    const durationMs = Date.now() - startWait;
+    const completed = activeRequests === 0;
+    const completedCount = initialCount - activeRequests;
+    return {
+        completed,
+        completedCount,
+        remainingCount: activeRequests,
+        durationMs,
+    };
+}
+export async function gracefulShutdown(serverOrOptions, legacyOptions) {
+    // Handle both old and new API signatures
+    const isEnhancedOptions = (obj) => {
+        return typeof obj === 'object' && obj !== null && 'httpTimeoutMs' in obj;
+    };
+    if (isEnhancedOptions(serverOrOptions)) {
+        return performEnhancedShutdown(serverOrOptions);
+    }
+    // Legacy API - server passed as first argument
+    const server = serverOrOptions;
+    const options = legacyOptions ?? {};
+    return performLegacyShutdown(server, options);
+}
+/**
+ * Enhanced shutdown implementation with detailed metrics
+ */
+async function performEnhancedShutdown(options) {
+    // Prevent multiple shutdown calls
+    if (shutdownPromise) {
+        logger.info('Shutdown already in progress, waiting...');
+        await shutdownPromise;
+        return shutdownMetrics;
+    }
+    isShuttingDown = true;
+    shutdownStartTime = Date.now();
+    const metrics = {
+        totalDurationMs: 0,
+        httpWaitDurationMs: 0,
+        jobWaitDurationMs: 0,
+        initialActiveRequests: activeRequests,
+        completedRequests: 0,
+        forcedTerminatedRequests: 0,
+        initialActiveJobs: 0,
+        completedJobs: 0,
+        abandonedJobs: 0,
+        forcedShutdown: false,
+        phases: [],
+    };
+    const runPhase = async (name, fn) => {
+        const phaseStart = Date.now();
+        try {
+            await fn();
+            metrics.phases.push({
+                name,
+                durationMs: Date.now() - phaseStart,
+                success: true,
+            });
+        }
+        catch (error) {
+            metrics.phases.push({
+                name,
+                durationMs: Date.now() - phaseStart,
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            });
+            logger.error({ error, phase: name }, `Error during shutdown phase: ${name}`);
+        }
+    };
+    // Create a force shutdown timer
+    const forceShutdownTimer = setTimeout(() => {
+        logger.warn({ forceAfterMs: options.forceAfterMs }, 'Force shutdown timeout reached');
+        metrics.forcedShutdown = true;
+    }, options.forceAfterMs);
+    try {
+        logger.info({
+            httpTimeoutMs: options.httpTimeoutMs,
+            jobTimeoutMs: options.jobTimeoutMs,
+            forceAfterMs: options.forceAfterMs,
+            activeRequests,
+        }, 'Enhanced graceful shutdown initiated');
+        // Phase 1: Wait for HTTP requests to complete
+        await runPhase('http-drain', async () => {
+            const result = await waitForRequestsToComplete(options.httpTimeoutMs);
+            metrics.httpWaitDurationMs = result.durationMs;
+            metrics.completedRequests = result.completedCount;
+            metrics.forcedTerminatedRequests = result.remainingCount;
+            if (!result.completed) {
+                logger.warn({ remaining: result.remainingCount }, 'HTTP drain timeout - some requests will be forcibly terminated');
+            }
+            else {
+                logger.info('All HTTP requests completed gracefully');
+            }
+        });
+        // Phase 2: Pause queue workers (stop accepting new jobs)
+        await runPhase('pause-workers', async () => {
+            await pauseWorkers();
+        });
+        // Phase 3: Wait for active jobs to complete
+        await runPhase('job-drain', async () => {
+            const jobStart = Date.now();
+            const result = await waitForActiveJobs(options.jobTimeoutMs);
+            metrics.jobWaitDurationMs = Date.now() - jobStart;
+            if (!result.completed) {
+                metrics.abandonedJobs = result.remainingJobs;
+                logger.warn({ remaining: result.remainingJobs }, 'Job drain timeout - some jobs will be abandoned');
+            }
+            else {
+                logger.info('All active jobs completed gracefully');
+            }
+        });
+        // Phase 4: Stop scheduler
+        await runPhase('stop-scheduler', async () => {
+            await stopScheduler();
+        });
+        // Phase 5: Shutdown workers
+        await runPhase('shutdown-workers', async () => {
+            // Give workers 5 seconds max for final cleanup
+            await shutdownWorkers(5000);
+            await shutdownGdprWorker();
+            await shutdownCanaryQueue();
+        });
+        // Phase 6: Flush audit system
+        await runPhase('flush-audit', async () => {
+            await shutdownAuditSystem();
+        });
+        // Phase 7: Stop rate limiters
+        await runPhase('stop-rate-limiters', async () => {
+            stopRateLimiter();
+            resetRateLimitStore();
+        });
+        // Phase 8: Close database connections
+        await runPhase('close-database', async () => {
+            await closeDatabase();
+        });
+        // Phase 9: Close Redis connections
+        await runPhase('close-redis', async () => {
+            await closePooledConnections();
+            await closeRedis();
+        });
+    }
+    finally {
+        clearTimeout(forceShutdownTimer);
+        metrics.totalDurationMs = Date.now() - shutdownStartTime;
+        shutdownMetrics = metrics;
+        // Log comprehensive shutdown metrics
+        logger.info({
+            totalDurationMs: metrics.totalDurationMs,
+            httpWaitDurationMs: metrics.httpWaitDurationMs,
+            jobWaitDurationMs: metrics.jobWaitDurationMs,
+            initialActiveRequests: metrics.initialActiveRequests,
+            completedRequests: metrics.completedRequests,
+            forcedTerminatedRequests: metrics.forcedTerminatedRequests,
+            abandonedJobs: metrics.abandonedJobs,
+            forcedShutdown: metrics.forcedShutdown,
+            phases: metrics.phases.map((p) => ({
+                name: p.name,
+                durationMs: p.durationMs,
+                success: p.success,
+            })),
+        }, 'Graceful shutdown complete');
+    }
+    return metrics;
+}
+/**
+ * Legacy shutdown implementation for backward compatibility
+ */
+async function performLegacyShutdown(server, options) {
+    // Prevent multiple shutdown calls
+    if (shutdownPromise) {
+        logger.info('Shutdown already in progress, waiting...');
+        return shutdownPromise;
+    }
+    isShuttingDown = true;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+    shutdownPromise = (async () => {
+        logger.info({ timeoutMs }, 'Graceful shutdown initiated');
+        // 1. Stop accepting new connections
+        try {
+            await server.close();
+            logger.info('HTTP server closed - no longer accepting connections');
+        }
+        catch (error) {
+            logger.error({ error }, 'Error closing HTTP server');
+        }
+        // 2. Stop scheduled jobs and resign leadership
+        if (!options.skipScheduler) {
+            try {
+                await stopScheduler();
+                logger.info('Scheduler stopped and leadership resigned');
+            }
+            catch (error) {
+                logger.error({ error }, 'Error stopping scheduler');
+            }
+        }
+        // 3. Stop processing new queue jobs
+        if (!options.skipWorkers) {
+            try {
+                await shutdownWorkers(timeoutMs / 2); // Give workers half the timeout
+                logger.info('BullMQ workers shutdown complete');
+            }
+            catch (error) {
+                logger.error({ error }, 'Error shutting down workers');
+            }
+            try {
+                await shutdownGdprWorker();
+                logger.info('GDPR workers shutdown complete');
+            }
+            catch (error) {
+                logger.error({ error }, 'Error shutting down GDPR workers');
+            }
+            try {
+                await shutdownCanaryQueue();
+                logger.info('Canary queue shutdown complete');
+            }
+            catch (error) {
+                logger.error({ error }, 'Error shutting down canary queue');
+            }
+        }
+        // 4. Wait for in-flight HTTP requests to complete
+        const requestResult = await waitForRequestsToComplete(timeoutMs / 2);
+        if (!requestResult.completed) {
+            logger.warn({ activeRequests: requestResult.remainingCount }, 'Forcing shutdown with active requests still in progress');
+        }
+        else {
+            logger.info('All in-flight requests completed');
+        }
+        // 5. Shutdown audit system (flush pending entries)
+        try {
+            await shutdownAuditSystem();
+            logger.info('Audit system shutdown complete');
+        }
+        catch (error) {
+            logger.error({ error }, 'Error shutting down audit system');
+        }
+        // 6. Stop rate limiters and cleanup intervals
+        try {
+            stopRateLimiter();
+            resetRateLimitStore();
+            logger.info('Rate limiters stopped');
+        }
+        catch (error) {
+            logger.error({ error }, 'Error stopping rate limiters');
+        }
+        // 7. Close database connections
+        if (!options.skipDatabase) {
+            try {
+                await closeDatabase();
+                logger.info('Database connections closed');
+            }
+            catch (error) {
+                logger.error({ error }, 'Error closing database connections');
+            }
+        }
+        // 8. Close Redis connections
+        if (!options.skipRedis) {
+            try {
+                await closePooledConnections();
+                await closeRedis();
+                logger.info('Redis connections closed');
+            }
+            catch (error) {
+                logger.error({ error }, 'Error closing Redis connections');
+            }
+        }
+        logger.info('Graceful shutdown complete');
+    })();
+    return shutdownPromise;
+}
+/**
+ * Register signal handlers for graceful shutdown.
+ *
+ * Handles:
+ * - SIGTERM: Kubernetes/Docker graceful termination
+ * - SIGINT: Ctrl+C in terminal
+ * - SIGQUIT: Extended timeout shutdown for debugging
+ */
+export function registerShutdownHandlers(server, options) {
+    const defaultTimeout = options?.timeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+    const shutdown = async (signal, extendedTimeout = false) => {
+        const timeoutMs = extendedTimeout ? defaultTimeout * 2 : defaultTimeout;
+        logger.info({ signal, timeoutMs, extendedTimeout }, 'Received shutdown signal');
+        await gracefulShutdown(server, { ...options, timeoutMs });
+        process.exit(0);
+    };
+    // SIGTERM: Kubernetes sends this for graceful termination
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    // SIGINT: Ctrl+C in terminal
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    // SIGQUIT: Extended timeout for debugging (e.g., kill -QUIT pid)
+    process.on('SIGQUIT', () => shutdown('SIGQUIT', true));
+    logger.debug('Shutdown signal handlers registered (SIGTERM, SIGINT, SIGQUIT)');
+}
+/**
+ * Register enhanced signal handlers with separate HTTP and job timeouts.
+ *
+ * This is the recommended way to register shutdown handlers for production.
+ *
+ * @param options - Default shutdown options
+ * @param extendedOptions - Options for SIGQUIT with extended timeouts
+ */
+export function registerEnhancedShutdownHandlers(options, extendedOptions) {
+    const extended = extendedOptions ?? {
+        httpTimeoutMs: options.httpTimeoutMs * 2,
+        jobTimeoutMs: options.jobTimeoutMs * 2,
+        forceAfterMs: options.forceAfterMs * 1.5,
+    };
+    const shutdown = async (signal, opts) => {
+        logger.info({
+            signal,
+            httpTimeoutMs: opts.httpTimeoutMs,
+            jobTimeoutMs: opts.jobTimeoutMs,
+            forceAfterMs: opts.forceAfterMs,
+        }, 'Received shutdown signal');
+        await gracefulShutdown(opts);
+        process.exit(0);
+    };
+    // SIGTERM: Kubernetes sends this for graceful termination
+    process.on('SIGTERM', () => shutdown('SIGTERM', options));
+    // SIGINT: Ctrl+C in terminal
+    process.on('SIGINT', () => shutdown('SIGINT', options));
+    // SIGQUIT: Extended timeout for debugging (e.g., kill -QUIT pid)
+    process.on('SIGQUIT', () => shutdown('SIGQUIT', extended));
+    logger.info({
+        defaultOptions: options,
+        extendedOptions: extended,
+    }, 'Enhanced shutdown signal handlers registered (SIGTERM, SIGINT, SIGQUIT)');
+}
+/**
+ * Default retry delay in seconds for 503 responses during shutdown
+ */
+const DEFAULT_RETRY_AFTER_SECONDS = 5;
+/**
+ * Fastify hook to reject requests during shutdown.
+ * Add this to server.addHook('onRequest', ...)
+ *
+ * When the server is shutting down:
+ * - Returns 503 Service Unavailable
+ * - Includes Retry-After header (RFC 7231)
+ * - Provides structured error response
+ */
+export async function shutdownRequestHook(request, reply) {
+    if (isShuttingDown) {
+        logger.info({ url: request.url, method: request.method }, 'Rejecting request - server is shutting down');
+        // Set Retry-After header per RFC 7231 Section 7.1.3
+        reply
+            .status(503)
+            .header('Retry-After', String(DEFAULT_RETRY_AFTER_SECONDS))
+            .header('Connection', 'close')
+            .send({
+            error: {
+                code: 'SERVICE_UNAVAILABLE',
+                message: 'The server is shutting down. Please retry your request shortly.',
+            },
+            retryAfter: DEFAULT_RETRY_AFTER_SECONDS,
+            timestamp: new Date().toISOString(),
+        });
+        return;
+    }
+    // Track the request
+    const cleanup = trackRequest();
+    // Store cleanup function on request for onResponse hook
+    // Use type assertion to add our custom property
+    request.shutdownCleanup = cleanup;
+}
+/**
+ * Fastify hook to clean up request tracking.
+ * Add this to server.addHook('onResponse', ...)
+ */
+export async function shutdownResponseHook(request) {
+    const cleanup = request.shutdownCleanup;
+    if (cleanup) {
+        cleanup();
+    }
+}
+/**
+ * Reset shutdown state (for testing purposes only)
+ */
+export function resetShutdownState() {
+    isShuttingDown = false;
+    activeRequests = 0;
+    shutdownPromise = null;
+    shutdownStartTime = null;
+    shutdownMetrics = null;
+}
+//# sourceMappingURL=shutdown.js.map

package/dist/intent/shutdown.js.map

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

package/dist/intent/state-machine.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Intent Status State Machine
+ *
+ * Defines and enforces valid status transitions for intents.
+ * Prevents invalid state changes and provides detailed error messages.
+ */
+import type { IntentStatus } from '../common/types.js';
+/**
+ * Transition metadata
+ */
+export interface TransitionMeta {
+    /** Human-readable description of the transition */
+    description: string;
+    /** Whether this transition requires a reason */
+    requiresReason?: boolean;
+    /** Whether this transition requires elevated permissions */
+    requiresPermission?: boolean;
+    /** Trigger event type for this transition */
+    event?: string;
+}
+/**
+ * Terminal states that cannot transition to any other state
+ */
+export declare const TERMINAL_STATES: Set<IntentStatus>;
+/**
+ * Active states where the intent is being processed
+ */
+export declare const ACTIVE_STATES: Set<IntentStatus>;
+/**
+ * States that allow cancellation
+ */
+export declare const CANCELLABLE_STATES: Set<IntentStatus>;
+/**
+ * States that allow replay (restart from pending)
+ */
+export declare const REPLAYABLE_STATES: Set<IntentStatus>;
+/**
+ * Result of a transition validation
+ */
+export interface TransitionResult {
+    valid: boolean;
+    meta?: TransitionMeta;
+    error?: string;
+    errorCode?: 'INVALID_TRANSITION' | 'TERMINAL_STATE' | 'REQUIRES_REASON' | 'REQUIRES_PERMISSION';
+}
+/**
+ * Check if a status transition is valid
+ */
+export declare function isValidTransition(fromStatus: IntentStatus, toStatus: IntentStatus): boolean;
+/**
+ * Get metadata for a transition
+ */
+export declare function getTransitionMeta(fromStatus: IntentStatus, toStatus: IntentStatus): TransitionMeta | undefined;
+/**
+ * Validate a status transition with detailed result
+ */
+export declare function validateTransition(fromStatus: IntentStatus, toStatus: IntentStatus, options?: {
+    hasReason?: boolean;
+    hasPermission?: boolean;
+}): TransitionResult;
+/**
+ * Get all valid transitions from a status
+ */
+export declare function getValidTransitions(fromStatus: IntentStatus): IntentStatus[];
+/**
+ * Get the event type for a transition
+ */
+export declare function getTransitionEvent(fromStatus: IntentStatus, toStatus: IntentStatus): string | undefined;
+/**
+ * Check if a status is terminal (no further transitions possible)
+ */
+export declare function isTerminalState(status: IntentStatus): boolean;
+/**
+ * Check if a status is active (intent is being processed)
+ */
+export declare function isActiveState(status: IntentStatus): boolean;
+/**
+ * Check if an intent can be cancelled from the given status
+ */
+export declare function canCancel(status: IntentStatus): boolean;
+/**
+ * Check if an intent can be replayed from the given status
+ */
+export declare function canReplay(status: IntentStatus): boolean;
+/**
+ * Get the next logical status for workflow progression
+ * Returns the primary "happy path" next status
+ */
+export declare function getNextWorkflowStatus(status: IntentStatus): IntentStatus | null;
+/**
+ * State machine error class
+ */
+export declare class StateMachineError extends Error {
+    readonly fromStatus: IntentStatus;
+    readonly toStatus: IntentStatus;
+    readonly errorCode: TransitionResult['errorCode'];
+    constructor(result: TransitionResult, fromStatus: IntentStatus, toStatus: IntentStatus);
+}
+/**
+ * Assert that a transition is valid, throwing if not
+ */
+export declare function assertValidTransition(fromStatus: IntentStatus, toStatus: IntentStatus, options?: {
+    hasReason?: boolean;
+    hasPermission?: boolean;
+}): void;
+/**
+ * Get a visual representation of the state machine
+ * Returns a mermaid diagram string
+ */
+export declare function getStateDiagram(): string;
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/intent/state-machine.d.ts.map

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