lifecycleion 0.0.12 → 0.0.13

package/README.md

@@ -1,4 +1,4 @@
-# Lifecycleion v0.0.12
+# Lifecycleion v0.0.13
 
 [![npm version](https://badge.fury.io/js/lifecycleion.svg)](https://badge.fury.io/js/lifecycleion)
 

package/dist/lib/lifecycle-manager/index.cjs

@@ -1006,6 +1006,9 @@ var ComponentLifecycle = class {
   getSignalStatus() {
     return this.manager.getSignalStatus();
   }
+  getShutdownEscalationStatus() {
+    return this.manager.getShutdownEscalationStatus();
+  }
   triggerReload() {
     return this.manager.triggerReload();
   }
@@ -1184,6 +1187,15 @@ var LifecycleManagerEvents = class {
   lifecycleManagerShutdownCompleted(input) {
     this.emit("lifecycle-manager:shutdown-completed", input);
   }
+  lifecycleManagerShutdownEscalationArmed(input) {
+    this.emit("lifecycle-manager:shutdown-escalation-armed", input);
+  }
+  lifecycleManagerShutdownEscalationExpired(input) {
+    this.emit("lifecycle-manager:shutdown-escalation-expired", input);
+  }
+  lifecycleManagerShutdownEscalationForced(input) {
+    this.emit("lifecycle-manager:shutdown-escalation-forced", input);
+  }
   componentStarting(name) {
     this.emit("component:starting", { name });
   }
@@ -1260,8 +1272,8 @@ var LifecycleManagerEvents = class {
   componentStartupRollback(name) {
     this.emit("component:startup-rollback", { name });
   }
-  signalShutdown(method) {
-    this.emit("signal:shutdown", { method });
+  signalShutdown(method, isAlreadyShuttingDown = false) {
+    this.emit("signal:shutdown", { method, isAlreadyShuttingDown });
   }
   signalReload() {
     this.emit("signal:reload", void 0);
@@ -1971,6 +1983,7 @@ var LifecycleManager = class extends EventEmitterProtected {
   attachSignalsBeforeStartup;
   attachSignalsOnStart;
   detachSignalsOnStop;
+  repeatedShutdownRequestPolicy;
   // Component management
   components = [];
   runningComponents = /* @__PURE__ */ new Set();
@@ -1990,6 +2003,17 @@ var LifecycleManager = class extends EventEmitterProtected {
   pendingLoggerExitResolve = null;
   shutdownMethod = null;
   lastShutdownResult = null;
+  repeatedShutdownExpiryTimer = null;
+  repeatedShutdownRequestState = {
+    requestCount: 0,
+    firstMethod: null,
+    latestMethod: null,
+    firstRequestAt: null,
+    latestRequestAt: null,
+    repeatedWindowStartedAt: null,
+    hasTriggeredForceShutdown: false,
+    remainsArmedUntil: null
+  };
   // Signal management
   processSignalManager = null;
   onReloadRequested;
@@ -2016,6 +2040,37 @@ var LifecycleManager = class extends EventEmitterProtected {
     this.attachSignalsBeforeStartup = options.attachSignalsBeforeStartup ?? false;
     this.attachSignalsOnStart = options.attachSignalsOnStart ?? false;
     this.detachSignalsOnStop = options.detachSignalsOnStop ?? false;
+    const repeatedShutdownRequestPolicy = options.repeatedShutdownRequestPolicy;
+    if (repeatedShutdownRequestPolicy === void 0) {
+      this.repeatedShutdownRequestPolicy = void 0;
+    } else {
+      const hasFiniteExplicitArmedAfterFailureMS = Number.isFinite(
+        repeatedShutdownRequestPolicy.armedAfterFailureMS
+      );
+      const forceAfterCount = finiteClampMin(
+        repeatedShutdownRequestPolicy.forceAfterCount,
+        1,
+        3
+      );
+      const withinMS = finiteClampMin(
+        repeatedShutdownRequestPolicy.withinMS,
+        0,
+        2e3
+      );
+      const armedAfterFailureMS = finiteClampMin(
+        repeatedShutdownRequestPolicy.armedAfterFailureMS,
+        0,
+        withinMS * forceAfterCount
+      );
+      this.repeatedShutdownRequestPolicy = {
+        forceAfterCount,
+        withinMS,
+        armedAfterFailureMS,
+        countManualRetriesTowardEscalation: repeatedShutdownRequestPolicy.countManualRetriesTowardEscalation ?? false,
+        hasExplicitArmedAfterFailureMS: hasFiniteExplicitArmedAfterFailureMS,
+        onForceShutdown: repeatedShutdownRequestPolicy.onForceShutdown
+      };
+    }
     this.onReloadRequested = options.onReloadRequested;
     this.onInfoRequested = options.onInfoRequested;
     this.onDebugRequested = options.onDebugRequested;
@@ -2584,6 +2639,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       };
     }
     this.isStarting = true;
+    this.resetRepeatedShutdownRequestState();
     this.shutdownMethod = null;
     this.lastShutdownResult = null;
     const didAutoAttachSignalsForBulkStartup = this.attachSignalsBeforeStartup ? this.autoAttachSignals("bulk startup") : false;
@@ -3024,6 +3080,51 @@ var LifecycleManager = class extends EventEmitterProtected {
       shutdownMethod: this.shutdownMethod
     };
   }
+  /**
+   * Get status information about repeated shutdown escalation configuration and runtime state.
+   */
+  getShutdownEscalationStatus() {
+    if (this.repeatedShutdownRequestPolicy === void 0) {
+      return {
+        configured: false,
+        isShuttingDown: this.isShuttingDown,
+        isArmed: false,
+        forceAfterCount: null,
+        withinMS: null,
+        armedAfterFailureMS: null,
+        armedAfterFailureMSSource: null,
+        requestCount: 0,
+        firstMethod: null,
+        latestMethod: null,
+        firstRequestAt: null,
+        latestRequestAt: null,
+        repeatedWindowStartedAt: null,
+        armedUntil: null,
+        hasTriggeredForceShutdown: false
+      };
+    }
+    this.normalizeRepeatedShutdownRequestStateArmedStatus();
+    const armedUntil = this.repeatedShutdownRequestState.remainsArmedUntil;
+    const isArmed = armedUntil !== null;
+    return {
+      configured: true,
+      isShuttingDown: this.isShuttingDown,
+      isArmed,
+      forceAfterCount: this.repeatedShutdownRequestPolicy.forceAfterCount,
+      withinMS: this.repeatedShutdownRequestPolicy.withinMS,
+      armedAfterFailureMS: this.repeatedShutdownRequestPolicy.armedAfterFailureMS,
+      armedAfterFailureMSSource: this.repeatedShutdownRequestPolicy.hasExplicitArmedAfterFailureMS ? "explicit" : "derived",
+      countManualRetriesTowardEscalation: this.repeatedShutdownRequestPolicy.countManualRetriesTowardEscalation,
+      requestCount: this.repeatedShutdownRequestState.requestCount,
+      firstMethod: this.repeatedShutdownRequestState.firstMethod,
+      latestMethod: this.repeatedShutdownRequestState.latestMethod,
+      firstRequestAt: this.repeatedShutdownRequestState.firstRequestAt,
+      latestRequestAt: this.repeatedShutdownRequestState.latestRequestAt,
+      repeatedWindowStartedAt: this.repeatedShutdownRequestState.repeatedWindowStartedAt,
+      armedUntil: isArmed ? armedUntil : null,
+      hasTriggeredForceShutdown: this.repeatedShutdownRequestState.hasTriggeredForceShutdown
+    };
+  }
   /**
    * Enable Logger exit hook integration
    *
@@ -4049,9 +4150,26 @@ var LifecycleManager = class extends EventEmitterProtected {
         code: "already_in_progress"
       };
     }
+    this.normalizeRepeatedShutdownRequestStateArmedStatus();
+    const repeatedShutdownPolicy = this.repeatedShutdownRequestPolicy;
+    const isManualRetryWhileArmed = repeatedShutdownPolicy !== void 0 && method === "manual" && this.repeatedShutdownRequestState.firstRequestAt !== null && this.repeatedShutdownRequestState.remainsArmedUntil !== null;
+    if (isManualRetryWhileArmed) {
+      if (repeatedShutdownPolicy.countManualRetriesTowardEscalation) {
+        this.handleRepeatedShutdownRequest(method);
+      } else {
+        this.resetRepeatedShutdownRequestState();
+      }
+    }
+    if (this.repeatedShutdownRequestState.remainsArmedUntil !== null) {
+      this.clearRepeatedShutdownExpiryTimer();
+      this.repeatedShutdownRequestState.remainsArmedUntil = null;
+    }
     this.isShuttingDown = true;
     this.shutdownToken = (0, import_ulid2.ulid)();
     this.shutdownMethod = method;
+    if (this.repeatedShutdownRequestPolicy && this.repeatedShutdownRequestState.firstRequestAt === null) {
+      this.seedRepeatedShutdownRequestState(method);
+    }
     const isDuringStartup = this.isStarting;
     this.logger.info("Stopping all components", { params: { method } });
     this.lifecycleEvents.lifecycleManagerShutdownInitiated(
@@ -4151,15 +4269,26 @@ var LifecycleManager = class extends EventEmitterProtected {
       } else {
         await shutdownOperation();
       }
+      if (!shouldRetryStalled) {
+        for (const name of stalledComponentNames) {
+          const stallInfo = this.stalledComponents.get(name);
+          if (stallInfo && !stalledComponents.some((component) => component.name === name)) {
+            stalledComponents.push(stallInfo);
+          }
+        }
+      }
       const durationMS = Date.now() - startTime;
       const isSuccess = !hasTimedOut && stalledComponents.length === 0;
-      this.logger[isSuccess ? "success" : "warn"]("Shutdown completed", {
-        params: {
-          stopped: stoppedComponents.length,
-          stalled: stalledComponents.length,
-          durationMS
+      this.logger[isSuccess ? "success" : "warn"](
+        isSuccess ? "Shutdown completed successfully" : "Shutdown attempt completed with stalled components or timeout",
+        {
+          params: {
+            stopped: stoppedComponents.length,
+            stalled: stalledComponents.length,
+            durationMS
+          }
         }
-      });
+      );
       const result = {
         success: isSuccess,
         stoppedComponents,
@@ -4177,6 +4306,11 @@ var LifecycleManager = class extends EventEmitterProtected {
         method,
         duringStartup: isDuringStartup
       });
+      if (isSuccess) {
+        this.resetRepeatedShutdownRequestState();
+      } else {
+        this.armRepeatedShutdownAfterFailure();
+      }
       return result;
     } finally {
       if (timeoutHandle) {
@@ -5305,21 +5439,295 @@ var LifecycleManager = class extends EventEmitterProtected {
   }
   /**
    * Handle shutdown signal - initiates stopAllComponents().
-   * Double signal protection: if already shutting down, log warning and ignore.
+   *
+   * Four cases depending on the current shutdown state:
+   *
+   * 1. **Active shutdown** (`isShuttingDown = true`): escalate through the
+   *    repeated-shutdown policy if configured, otherwise log and discard.
+   *    Emits `signal:shutdown` with `isAlreadyShuttingDown: true` and returns
+   *    without starting another shutdown.
+   *
+   * 2. **Armed post-failure** (previous shutdown finished, armed window still
+   *    open): count the request toward the escalation window, emit
+   *    `signal:shutdown` with `isAlreadyShuttingDown: false`, then start a
+   *    new `stopAllComponents()` run to retry.
+   *
+   * 3. **Armed post-failure expired** (armed window opened but has since
+   *    elapsed): expire the stale state, treat the request as a fresh
+   *    shutdown (falls through to case 4).
+   *
+   * 4. **Fresh shutdown** (no prior shutdown state): seed escalation tracking
+   *    if policy is configured, emit `signal:shutdown` with
+   *    `isAlreadyShuttingDown: false`, and start `stopAllComponents()`.
+   *
+   * In all cases `signal:shutdown` is emitted exactly once.
    */
   handleShutdownRequest(method) {
     if (this.isShuttingDown) {
-      this.logger.warn("Shutdown already in progress, ignoring signal", {
-        params: { method }
-      });
-      return;
+      this.lifecycleEvents.signalShutdown(method, true);
+      if (this.handleRepeatedShutdownRequest(method)) {
+        return;
+      }
+    }
+    let didEmitShutdownSignal = false;
+    let shouldSeedRepeatedShutdownState = this.repeatedShutdownRequestPolicy !== void 0;
+    if (this.repeatedShutdownRequestPolicy && this.repeatedShutdownRequestState.firstRequestAt !== null && this.normalizeRepeatedShutdownRequestStateArmedStatus()) {
+      this.lifecycleEvents.signalShutdown(method, false);
+      didEmitShutdownSignal = true;
+      shouldSeedRepeatedShutdownState = false;
+      this.handleRepeatedShutdownRequest(method);
+    }
+    if (shouldSeedRepeatedShutdownState) {
+      this.seedRepeatedShutdownRequestState(method);
     }
     this.logger.info("Shutdown signal received", { params: { method } });
-    this.lifecycleEvents.signalShutdown(method);
+    if (!didEmitShutdownSignal) {
+      this.lifecycleEvents.signalShutdown(method, false);
+    }
     void this.stopAllComponentsInternal(method, {
       ...this.shutdownOptions
     });
   }
+  /**
+   * Tracks repeated shutdown requests during an active shutdown and optionally
+   * invokes the configured force shutdown callback when the threshold is reached.
+   *
+   * @returns true when the request was consumed as part of the repeated-shutdown
+   * escalation flow, false when the caller should treat it as a fresh shutdown request
+   */
+  handleRepeatedShutdownRequest(method) {
+    const policy = this.repeatedShutdownRequestPolicy;
+    if (!policy) {
+      this.logger.warn("Shutdown already in progress, ignoring signal", {
+        params: { method }
+      });
+      return true;
+    }
+    const now = Date.now();
+    const state = this.repeatedShutdownRequestState;
+    if (state.remainsArmedUntil !== null) {
+      if (now >= state.remainsArmedUntil) {
+        this.expireRepeatedShutdownRequestState();
+        return false;
+      }
+      this.refreshRepeatedShutdownArmedWindow(now);
+    }
+    const shouldStartNewWindow = state.repeatedWindowStartedAt === null || now - state.repeatedWindowStartedAt > policy.withinMS;
+    if (shouldStartNewWindow) {
+      state.requestCount = 1;
+      state.repeatedWindowStartedAt = now;
+    } else {
+      state.requestCount++;
+    }
+    state.latestMethod = method;
+    state.latestRequestAt = now;
+    this.logger.warn(
+      this.isShuttingDown ? "Shutdown already in progress, tracking repeated signal" : "Previous shutdown attempt finished with stalled components or timeout, escalation window still armed, tracking repeated request",
+      {
+        params: {
+          method,
+          requestCount: state.requestCount,
+          firstMethod: state.firstMethod,
+          latestMethod: state.latestMethod,
+          firstRequestAt: state.firstRequestAt,
+          latestRequestAt: state.latestRequestAt,
+          repeatedWindowStartedAt: state.repeatedWindowStartedAt,
+          remainsArmedUntil: state.remainsArmedUntil,
+          withinMS: policy.withinMS,
+          forceAfterCount: policy.forceAfterCount
+        }
+      }
+    );
+    if (
+      // Force escalation is single-fire per shutdown cycle. Later requests are
+      // still logged but do not re-enter user force-shutdown logic.
+      state.hasTriggeredForceShutdown || state.requestCount < policy.forceAfterCount || state.firstMethod === null || state.firstRequestAt === null || state.latestMethod === null || state.latestRequestAt === null
+    ) {
+      return true;
+    }
+    state.hasTriggeredForceShutdown = true;
+    const context = {
+      requestCount: state.requestCount,
+      firstMethod: state.firstMethod,
+      latestMethod: state.latestMethod,
+      firstRequestAt: state.firstRequestAt,
+      latestRequestAt: state.latestRequestAt,
+      isShuttingDown: this.isShuttingDown,
+      wasArmedAfterFailure: state.remainsArmedUntil !== null
+    };
+    this.logger.warn(
+      "Repeated shutdown request threshold reached, invoking force shutdown handler",
+      {
+        params: {
+          method,
+          requestCount: context.requestCount,
+          firstMethod: context.firstMethod,
+          latestMethod: context.latestMethod,
+          firstRequestAt: context.firstRequestAt,
+          latestRequestAt: context.latestRequestAt,
+          repeatedWindowStartedAt: state.repeatedWindowStartedAt,
+          remainsArmedUntil: state.remainsArmedUntil,
+          withinMS: policy.withinMS,
+          forceAfterCount: policy.forceAfterCount
+        }
+      }
+    );
+    safeHandleCallback(
+      "repeatedShutdownRequestPolicy.onForceShutdown",
+      policy.onForceShutdown,
+      context
+    );
+    this.lifecycleEvents.lifecycleManagerShutdownEscalationForced({
+      firstMethod: context.firstMethod,
+      latestMethod: context.latestMethod,
+      requestCount: context.requestCount,
+      firstRequestAt: context.firstRequestAt,
+      latestRequestAt: context.latestRequestAt,
+      wasArmedAfterFailure: context.wasArmedAfterFailure
+    });
+    return true;
+  }
+  /**
+   * Clears repeated shutdown request tracking so a new shutdown cycle starts fresh.
+   */
+  resetRepeatedShutdownRequestState() {
+    this.clearRepeatedShutdownExpiryTimer();
+    this.repeatedShutdownRequestState = {
+      requestCount: 0,
+      firstMethod: null,
+      latestMethod: null,
+      firstRequestAt: null,
+      latestRequestAt: null,
+      repeatedWindowStartedAt: null,
+      hasTriggeredForceShutdown: false,
+      remainsArmedUntil: null
+    };
+  }
+  /**
+   * Clear any pending expiration timer for the post-failure escalation window.
+   */
+  clearRepeatedShutdownExpiryTimer() {
+    if (this.repeatedShutdownExpiryTimer === null) {
+      return;
+    }
+    clearTimeout(this.repeatedShutdownExpiryTimer);
+    this.repeatedShutdownExpiryTimer = null;
+  }
+  /**
+   * Returns whether post-failure escalation remains armed after first
+   * normalizing any stale timer-backed state.
+   *
+   * The method can expire old armed windows as a side effect because the timer
+   * callback may not have run yet on a delayed event loop. Callers use this
+   * when they need the effective runtime truth, not just the last timer write.
+   */
+  normalizeRepeatedShutdownRequestStateArmedStatus(now = Date.now()) {
+    const armedUntil = this.repeatedShutdownRequestState.remainsArmedUntil;
+    if (armedUntil === null) {
+      return false;
+    }
+    if (now >= armedUntil) {
+      this.expireRepeatedShutdownRequestState();
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Transition armed post-failure escalation state into its expired/reset state.
+   */
+  expireRepeatedShutdownRequestState() {
+    const policy = this.repeatedShutdownRequestPolicy;
+    const state = this.repeatedShutdownRequestState;
+    if (!policy || state.remainsArmedUntil === null) {
+      return;
+    }
+    const armedUntil = state.remainsArmedUntil;
+    this.clearRepeatedShutdownExpiryTimer();
+    const expiredState = {
+      firstMethod: state.firstMethod,
+      latestMethod: state.latestMethod,
+      requestCount: state.requestCount,
+      armedUntil
+    };
+    this.logger.warn(
+      "Repeated shutdown escalation window expired, clearing previous shutdown state",
+      {
+        params: {
+          remainsArmedUntil: armedUntil,
+          withinMS: policy.withinMS,
+          forceAfterCount: policy.forceAfterCount
+        }
+      }
+    );
+    if (expiredState.firstMethod !== null) {
+      this.lifecycleEvents.lifecycleManagerShutdownEscalationExpired({
+        firstMethod: expiredState.firstMethod,
+        latestMethod: expiredState.latestMethod,
+        requestCount: expiredState.requestCount,
+        armedUntil: expiredState.armedUntil
+      });
+    }
+    this.resetRepeatedShutdownRequestState();
+  }
+  /**
+   * Arms or refreshes the post-failure escalation window and its expiration timer.
+   */
+  refreshRepeatedShutdownArmedWindow(now = Date.now()) {
+    const policy = this.repeatedShutdownRequestPolicy;
+    if (!policy) {
+      return;
+    }
+    this.clearRepeatedShutdownExpiryTimer();
+    const armedUntil = now + policy.armedAfterFailureMS;
+    this.repeatedShutdownRequestState.remainsArmedUntil = armedUntil;
+    this.repeatedShutdownExpiryTimer = setTimeout(() => {
+      this.expireRepeatedShutdownRequestState();
+    }, policy.armedAfterFailureMS);
+    this.repeatedShutdownExpiryTimer.unref();
+  }
+  /**
+   * Seeds shutdown escalation tracking for a new shutdown cycle.
+   *
+   * The first shutdown trigger starts graceful shutdown and arms escalation with
+   * an effective post-start count of 0. Later shutdown requests can then count
+   * toward the configured force threshold regardless of whether the shutdown
+   * started from a signal, keyboard shortcut, or direct API call.
+   */
+  seedRepeatedShutdownRequestState(method) {
+    const now = Date.now();
+    this.repeatedShutdownRequestState = {
+      requestCount: 0,
+      firstMethod: method,
+      latestMethod: method,
+      firstRequestAt: now,
+      latestRequestAt: now,
+      repeatedWindowStartedAt: null,
+      hasTriggeredForceShutdown: false,
+      remainsArmedUntil: null
+    };
+  }
+  /**
+   * Preserves a short-lived post-failure escalation window after shutdown
+   * returns unsuccessfully so operators can keep pressing shutdown without
+   * losing the existing force count the moment the graceful attempt finishes.
+   */
+  armRepeatedShutdownAfterFailure() {
+    const policy = this.repeatedShutdownRequestPolicy;
+    const state = this.repeatedShutdownRequestState;
+    if (!policy || policy.armedAfterFailureMS <= 0 || // armedAfterFailureMS = 0 disables post-failure arming
+    state.firstRequestAt === null || state.hasTriggeredForceShutdown) {
+      return;
+    }
+    this.refreshRepeatedShutdownArmedWindow();
+    const armedUntil = state.remainsArmedUntil;
+    if (state.firstMethod !== null && armedUntil !== null) {
+      this.lifecycleEvents.lifecycleManagerShutdownEscalationArmed({
+        firstMethod: state.firstMethod,
+        requestCount: state.requestCount,
+        armedUntil
+      });
+    }
+  }
   /**
    * Handle reload request - calls custom callback or broadcasts to components.
    *