@arela/uploader 0.2.12 → 0.3.0

package/src/services/SignalHandler.js

@@ -0,0 +1,255 @@
+/**
+ * Signal Handler Service
+ * Centralizes handling of system signals for graceful shutdown
+ * Manages SIGINT, SIGTERM, SIGHUP, SIGQUIT with cleanup coordination
+ */
+export class SignalHandler {
+  /**
+   * Create a new SignalHandler instance
+   * @param {Object} logger - Logger service instance
+   * @param {Object} cleanupManager - Cleanup manager instance
+   */
+  constructor(logger, cleanupManager) {
+    this.logger = logger;
+    this.cleanupManager = cleanupManager;
+
+    /**
+     * Flag to prevent concurrent signal handling
+     * @type {boolean}
+     */
+    this.shutdownInProgress = false;
+
+    /**
+     * Signal received by process
+     * @type {string|null}
+     */
+    this.signalReceived = null;
+
+    /**
+     * Timestamp when signal was received
+     * @type {number|null}
+     */
+    this.signalTime = null;
+
+    /**
+     * Map of registered signal handlers
+     * @type {Map<string, Function>}
+     */
+    this.signalHandlers = new Map();
+
+    /**
+     * Signals to handle
+     * @type {string[]}
+     */
+    this.supportedSignals = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT'];
+  }
+
+  /**
+   * Register signal handlers
+   * @param {Object} handlers - Map of signal handlers { signal: handler }
+   * @returns {void}
+   */
+  registerSignalHandlers(handlers = {}) {
+    for (const signal of this.supportedSignals) {
+      const handler = handlers[signal] || this.#createDefaultHandler(signal);
+
+      // Store handler reference
+      this.signalHandlers.set(signal, handler);
+
+      // Register with process
+      process.on(signal, () => this.#handleSignal(signal, handler));
+
+      this.logger.debug(`SignalHandler: Registered handler for ${signal}`);
+    }
+  }
+
+  /**
+   * Handle incoming signal
+   * @private
+   * @param {string} signal - Signal name
+   * @param {Function} handler - Handler function
+   * @returns {Promise<void>}
+   */
+  async #handleSignal(signal, handler) {
+    // Prevent concurrent handling
+    if (this.shutdownInProgress) {
+      this.logger.warn(
+        `SignalHandler: Shutdown already in progress, ignoring ${signal}`,
+      );
+      return;
+    }
+
+    this.shutdownInProgress = true;
+    this.signalReceived = signal;
+    this.signalTime = Date.now();
+
+    this.logger.warn(
+      `\n\n🛑 SignalHandler: Received ${signal}, initiating graceful shutdown...`,
+    );
+
+    // Log signal details
+    this.#logSignalEvent(signal);
+
+    try {
+      // Perform cleanup
+      const cleanupResult = await this.cleanupManager.performCleanup(signal);
+
+      if (!cleanupResult.success) {
+        this.logger.error(
+          `SignalHandler: Cleanup had ${cleanupResult.failureCount} failures, but continuing with shutdown`,
+        );
+      }
+
+      // Execute signal-specific handler
+      if (handler && typeof handler === 'function') {
+        await handler();
+      }
+
+      // Determine exit code based on signal
+      const exitCode = this.#getExitCode(signal);
+      this.logger.info(
+        `SignalHandler: Shutdown complete, exiting with code ${exitCode}`,
+      );
+
+      process.exit(exitCode);
+    } catch (error) {
+      this.logger.error(
+        `SignalHandler: Error during signal handling: ${error.message}`,
+      );
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Create default handler for a signal
+   * @private
+   * @param {string} signal - Signal name
+   * @returns {Function} Default handler function
+   */
+  #createDefaultHandler(signal) {
+    return async () => {
+      this.logger.info(
+        `SignalHandler: Executing default handler for ${signal}`,
+      );
+    };
+  }
+
+  /**
+   * Get appropriate exit code for signal
+   * @private
+   * @param {string} signal - Signal name
+   * @returns {number} Exit code
+   */
+  #getExitCode(signal) {
+    const signalExitCodes = {
+      SIGINT: 130, // 128 + 2
+      SIGTERM: 143, // 128 + 15
+      SIGHUP: 129, // 128 + 1
+      SIGQUIT: 131, // 128 + 3
+    };
+
+    return signalExitCodes[signal] || 128;
+  }
+
+  /**
+   * Log signal event details
+   * @private
+   * @param {string} signal - Signal name
+   * @returns {void}
+   */
+  #logSignalEvent(signal) {
+    const signalDescriptions = {
+      SIGINT: 'Interrupt (Ctrl+C)',
+      SIGTERM: 'Termination (kill command)',
+      SIGHUP: 'Hangup (terminal closed)',
+      SIGQUIT: 'Quit (Ctrl+\\)',
+    };
+
+    const description = signalDescriptions[signal] || 'Unknown signal';
+
+    this.logger.info(`SignalHandler: Signal Details`);
+    this.logger.info(`├─ Signal: ${signal} (${description})`);
+    this.logger.info(`├─ Process ID: ${process.pid}`);
+    this.logger.info(`├─ Timestamp: ${new Date().toISOString()}`);
+    this.logger.info(
+      `├─ Memory Usage: ${Math.round(process.memoryUsage().heapUsed / 1024 / 1024)}MB`,
+    );
+    this.logger.info(`└─ Uptime: ${process.uptime().toFixed(2)}s`);
+  }
+
+  /**
+   * Check if shutdown is in progress
+   * @returns {boolean} True if shutdown is happening
+   */
+  isShuttingDown() {
+    return this.shutdownInProgress;
+  }
+
+  /**
+   * Get the signal that was received
+   * @returns {string|null} Signal name or null
+   */
+  getSignalReceived() {
+    return this.signalReceived;
+  }
+
+  /**
+   * Get timestamp when signal was received
+   * @returns {number|null} Timestamp in milliseconds or null
+   */
+  getSignalTime() {
+    return this.signalTime;
+  }
+
+  /**
+   * Generate signal event report
+   * @returns {string} Formatted report
+   */
+  generateSignalReport() {
+    if (!this.signalReceived) {
+      return 'No signal received yet';
+    }
+
+    const duration = this.signalTime ? Date.now() - this.signalTime : 0;
+
+    let report =
+      '\n═══════════════════════════════════════════════════════════\n';
+    report += 'SIGNAL HANDLING REPORT\n';
+    report += '═══════════════════════════════════════════════════════════\n\n';
+    report += `Signal: ${this.signalReceived}\n`;
+    report += `Process ID: ${process.pid}\n`;
+    report += `Received At: ${new Date(this.signalTime).toISOString()}\n`;
+    report += `Shutdown Duration: ${duration}ms\n`;
+    report += `Shutdown Status: ${this.shutdownInProgress ? 'IN PROGRESS' : 'COMPLETE'}\n`;
+    report += '═══════════════════════════════════════════════════════════\n';
+
+    return report;
+  }
+
+  /**
+   * Reset signal handler state (useful for testing)
+   * @returns {void}
+   */
+  reset() {
+    this.shutdownInProgress = false;
+    this.signalReceived = null;
+    this.signalTime = null;
+    this.logger.debug('SignalHandler: Reset to initial state');
+  }
+}
+
+// Export as singleton
+let instance = null;
+
+export function createSignalHandler(logger, cleanupManager) {
+  if (!instance) {
+    instance = new SignalHandler(logger, cleanupManager);
+  }
+  return instance;
+}
+
+export function getSignalHandler() {
+  return instance;
+}
+
+export default SignalHandler;