lifecycleion 0.0.12 → 0.0.13

package/dist/lib/lifecycle-manager/index.d.cts

@@ -471,6 +471,7 @@ interface LifecycleCommon extends EventEmitterSurface {
     attachSignals(): void;
     detachSignals(): void;
     getSignalStatus(): LifecycleSignalStatus;
+    getShutdownEscalationStatus(): ShutdownEscalationStatus;
     triggerReload(): Promise<SignalBroadcastResult>;
     triggerInfo(): Promise<SignalBroadcastResult>;
     triggerDebug(): Promise<SignalBroadcastResult>;
@@ -681,6 +682,163 @@ interface LifecycleSignalStatus extends ProcessSignalManagerStatus {
     /** How shutdown was triggered (null if not shut down) */
     shutdownMethod: ShutdownMethod | null;
 }
+interface ShutdownEscalationStatusDisabled {
+    /** Whether repeated shutdown escalation is configured */
+    configured: false;
+    /** Whether a shutdown is currently in progress */
+    isShuttingDown: boolean;
+    /** Escalation cannot be armed when the policy is disabled */
+    isArmed: false;
+    /** Config fields are unavailable while the policy is disabled */
+    forceAfterCount: null;
+    withinMS: null;
+    armedAfterFailureMS: null;
+    armedAfterFailureMSSource: null;
+    /** Runtime counters remain empty while the policy is disabled */
+    requestCount: 0;
+    firstMethod: null;
+    latestMethod: null;
+    firstRequestAt: null;
+    latestRequestAt: null;
+    repeatedWindowStartedAt: null;
+    armedUntil: null;
+    hasTriggeredForceShutdown: false;
+}
+interface ShutdownEscalationStatusEnabled {
+    /** Whether repeated shutdown escalation is configured */
+    configured: true;
+    /** Whether a shutdown is currently in progress */
+    isShuttingDown: boolean;
+    /** Whether escalation remains armed after an unsuccessful shutdown */
+    isArmed: boolean;
+    /** Configured force threshold when policy is enabled */
+    forceAfterCount: number;
+    /** Configured escalation window when policy is enabled */
+    withinMS: number;
+    /** Effective post-failure armed duration in ms when policy is enabled */
+    armedAfterFailureMS: number;
+    /** Whether the effective armed duration was explicitly configured or derived from defaults */
+    armedAfterFailureMSSource: 'explicit' | 'derived';
+    /** Whether manual stopAllComponents() retries continue the armed escalation state */
+    countManualRetriesTowardEscalation: boolean;
+    /**
+     * Number of follow-up shutdown requests counted in the current escalation
+     * window (resets when a new window starts). This is a window-local count,
+     * not a cumulative total of all requests since shutdown began.
+     */
+    requestCount: number;
+    /** Method that started the current/most recent shutdown escalation cycle */
+    firstMethod: ShutdownMethod | null;
+    /** Most recent shutdown request method seen by escalation tracking */
+    latestMethod: ShutdownMethod | null;
+    /** Timestamp of the first shutdown request that seeded this escalation state */
+    firstRequestAt: number | null;
+    /** Timestamp of the most recent shutdown request counted by escalation tracking */
+    latestRequestAt: number | null;
+    /** Timestamp when the current post-start escalation window began */
+    repeatedWindowStartedAt: number | null;
+    /** Timestamp when armed-after-failure escalation will expire */
+    armedUntil: number | null;
+    /** Whether onForceShutdown() has already been dispatched for this shutdown cycle */
+    hasTriggeredForceShutdown: boolean;
+}
+/**
+ * Read-only snapshot of repeated shutdown escalation configuration and runtime state.
+ */
+type ShutdownEscalationStatus = ShutdownEscalationStatusDisabled | ShutdownEscalationStatusEnabled;
+/**
+ * Context passed to repeated shutdown force handlers.
+ *
+ * The first request starts graceful shutdown. If additional shutdown requests
+ * arrive within the configured time window and the threshold is reached, the
+ * LifecycleManager invokes `onForceShutdown()` with this snapshot.
+ */
+interface ForceShutdownContext {
+    /** Number of escalation requests counted after shutdown had already started */
+    requestCount: number;
+    /** Method that started the current shutdown cycle */
+    firstMethod: ShutdownMethod;
+    /** Most recent shutdown request method */
+    latestMethod: ShutdownMethod;
+    /** Unix timestamp in ms for the request that started the current shutdown cycle */
+    firstRequestAt: number;
+    /** Unix timestamp in ms for the most recent request in the current window */
+    latestRequestAt: number;
+    /**
+     * Whether shutdown is still actively running when the force callback fires.
+     *
+     * This is `true` when escalation fires during an active shutdown (the normal
+     * path: operator pressed the shutdown signal multiple times while
+     * `stopAllComponents()` was still running).
+     *
+     * This is `false` when escalation fires from the post-failure armed window
+     * (i.e. a previous shutdown attempt already returned unsuccessfully and the
+     * manager kept escalation armed briefly). In that path the force callback
+     * fires before the follow-up `stopAllComponents()` call is issued, so no
+     * shutdown is actively in progress at the moment the callback runs.
+     *
+     * Check `wasArmedAfterFailure` to distinguish the two cases.
+     */
+    isShuttingDown: boolean;
+    /**
+     * Whether this force-shutdown was triggered from the post-failure armed
+     * state rather than during an active shutdown.
+     *
+     * `true`  — a previous shutdown attempt returned unsuccessfully, the manager
+     *           kept escalation armed, and the force threshold was crossed while
+     *           that armed window was still open (no shutdown running yet).
+     *
+     * `false` — the force threshold was crossed while `stopAllComponents()` was
+     *           actively in progress (the common path).
+     *
+     * Use this to decide whether your force handler needs to start or re-trigger
+     * shutdown, or whether it can assume a shutdown run is already underway.
+     */
+    wasArmedAfterFailure: boolean;
+}
+/**
+ * Optional policy for escalating repeated shutdown requests during an already
+ * running shutdown.
+ */
+interface RepeatedShutdownRequestPolicy {
+    /**
+     * Number of shutdown requests required before force escalation runs.
+     * Only escalation requests received after shutdown has already started count
+     * toward this threshold. The initial request that starts graceful shutdown
+     * does not count.
+     * @default 3
+     */
+    forceAfterCount?: number;
+    /**
+     * Time window in ms for counting follow-up escalation requests received
+     * after shutdown has already started.
+     * Requests outside the window start a new escalation window.
+     * @default 2000
+     */
+    withinMS?: number;
+    /**
+     * How long escalation should remain armed after an unsuccessful shutdown
+     * returns. When omitted, the manager derives it as `withinMS * forceAfterCount`.
+     * Set to `0` to disable post-failure arming entirely — the escalation window
+     * will not persist once a shutdown attempt returns, and each new request will
+     * start a fresh escalation cycle. (Note: `withinMS = 0` is a separate option
+     * that controls the width of the active-shutdown escalation window, not this.)
+     */
+    armedAfterFailureMS?: number;
+    /**
+     * If true, manual `stopAllComponents()` retries that happen while the
+     * post-failure armed window is still open continue the same escalation state.
+     * When false, manual retries always start a fresh escalation cycle.
+     * @default false
+     */
+    countManualRetriesTowardEscalation?: boolean;
+    /**
+     * Invoked once per shutdown cycle when repeated requests reach the threshold.
+     * Typical uses: final logging, telemetry flush, `logger.exit()`, or
+     * `process.exit()` by the application.
+     */
+    onForceShutdown: (context: ForceShutdownContext) => void | Promise<void>;
+}
 /**
  * Configuration options for LifecycleManager
  */
@@ -711,6 +869,11 @@ interface LifecycleManagerOptions {
     onInfoRequested?: (broadcastInfo: () => Promise<SignalBroadcastResult>) => void | Promise<void>;
     /** Custom debug signal handler (called instead of default broadcast, receives broadcast function you can optionally call) */
     onDebugRequested?: (broadcastDebug: () => Promise<SignalBroadcastResult>) => void | Promise<void>;
+    /**
+     * Optional policy for escalating repeated shutdown requests received while a
+     * graceful shutdown is already in progress.
+     */
+    repeatedShutdownRequestPolicy?: RepeatedShutdownRequestPolicy;
 }
 
 /**
@@ -1008,6 +1171,7 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private readonly attachSignalsBeforeStartup;
     private readonly attachSignalsOnStart;
     private readonly detachSignalsOnStop;
+    private readonly repeatedShutdownRequestPolicy?;
     private components;
     private runningComponents;
     private componentStates;
@@ -1022,6 +1186,8 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private pendingLoggerExitResolve;
     private shutdownMethod;
     private lastShutdownResult;
+    private repeatedShutdownExpiryTimer;
+    private repeatedShutdownRequestState;
     private processSignalManager;
     private readonly onReloadRequested?;
     private readonly onInfoRequested?;
@@ -1214,6 +1380,10 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
      * Get status information about signal handling.
      */
     getSignalStatus(): LifecycleSignalStatus;
+    /**
+     * Get status information about repeated shutdown escalation configuration and runtime state.
+     */
+    getShutdownEscalationStatus(): ShutdownEscalationStatus;
     /**
      * Enable Logger exit hook integration
      *
@@ -1470,9 +1640,78 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private findAllCircularCycles;
     /**
      * 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.
      */
     private handleShutdownRequest;
+    /**
+     * 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
+     */
+    private handleRepeatedShutdownRequest;
+    /**
+     * Clears repeated shutdown request tracking so a new shutdown cycle starts fresh.
+     */
+    private resetRepeatedShutdownRequestState;
+    /**
+     * Clear any pending expiration timer for the post-failure escalation window.
+     */
+    private clearRepeatedShutdownExpiryTimer;
+    /**
+     * 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.
+     */
+    private normalizeRepeatedShutdownRequestStateArmedStatus;
+    /**
+     * Transition armed post-failure escalation state into its expired/reset state.
+     */
+    private expireRepeatedShutdownRequestState;
+    /**
+     * Arms or refreshes the post-failure escalation window and its expiration timer.
+     */
+    private refreshRepeatedShutdownArmedWindow;
+    /**
+     * 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.
+     */
+    private seedRepeatedShutdownRequestState;
+    /**
+     * 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.
+     */
+    private armRepeatedShutdownAfterFailure;
     /**
      * Handle reload request - calls custom callback or broadcasts to components.
      *
@@ -1637,6 +1876,28 @@ interface LifecycleManagerEventMap {
         method: ShutdownMethod;
         duringStartup: boolean;
     };
+    /** Failed/timed-out shutdown left escalation armed briefly for follow-up force presses. */
+    'lifecycle-manager:shutdown-escalation-armed': {
+        firstMethod: ShutdownMethod;
+        requestCount: number;
+        armedUntil: number;
+    };
+    /** Armed escalation window expired and the manager cleared that old escalation state. */
+    'lifecycle-manager:shutdown-escalation-expired': {
+        firstMethod: ShutdownMethod;
+        latestMethod: ShutdownMethod | null;
+        requestCount: number;
+        armedUntil: number;
+    };
+    /** Repeated shutdown requests crossed the force threshold and onForceShutdown() was invoked. */
+    'lifecycle-manager:shutdown-escalation-forced': {
+        firstMethod: ShutdownMethod;
+        latestMethod: ShutdownMethod;
+        requestCount: number;
+        firstRequestAt: number;
+        latestRequestAt: number;
+        wasArmedAfterFailure: boolean;
+    };
     'component:starting': {
         name: string;
     };
@@ -1713,6 +1974,7 @@ interface LifecycleManagerEventMap {
     };
     'signal:shutdown': {
         method: ShutdownSignal;
+        isAlreadyShuttingDown: boolean;
     };
     'signal:reload': undefined;
     'signal:info': undefined;
@@ -1827,6 +2089,25 @@ declare class LifecycleManagerEvents {
         method: ShutdownMethod;
         duringStartup: boolean;
     }): void;
+    lifecycleManagerShutdownEscalationArmed(input: {
+        firstMethod: ShutdownMethod;
+        requestCount: number;
+        armedUntil: number;
+    }): void;
+    lifecycleManagerShutdownEscalationExpired(input: {
+        firstMethod: ShutdownMethod;
+        latestMethod: ShutdownMethod | null;
+        requestCount: number;
+        armedUntil: number;
+    }): void;
+    lifecycleManagerShutdownEscalationForced(input: {
+        firstMethod: ShutdownMethod;
+        latestMethod: ShutdownMethod;
+        requestCount: number;
+        firstRequestAt: number;
+        latestRequestAt: number;
+        wasArmedAfterFailure: boolean;
+    }): void;
     componentStarting(name: string): void;
     componentStarted(name: string, status?: ComponentStatus): void;
     componentStartTimeout(name: string, error: Error, info?: {
@@ -1862,7 +2143,7 @@ declare class LifecycleManagerEvents {
     componentShutdownForceCompleted(name: string): void;
     componentShutdownForceTimeout(name: string, timeoutMS: number): void;
     componentStartupRollback(name: string): void;
-    signalShutdown(method: ShutdownSignal): void;
+    signalShutdown(method: ShutdownSignal, isAlreadyShuttingDown?: boolean): void;
     signalReload(): void;
     signalInfo(): void;
     signalDebug(): void;
@@ -2048,4 +2329,4 @@ declare const lifecycleManagerErrCodes: {
     readonly StopTimeout: "StopTimeout";
 };
 
-export { BaseComponent, type BaseOperationResult, type BroadcastOptions, type BroadcastResult, type ComponentHealthResult, ComponentNotFoundError, type ComponentOperationFailureCode, type ComponentOperationResult, type ComponentOptions, ComponentRegistrationError, type ComponentSignalResult, type ComponentStallInfo, ComponentStartTimeoutError, ComponentStartupError, type ComponentState, type ComponentStatus, ComponentStopTimeoutError, type ComponentValueResult, DependencyCycleError, type DependencyValidationResult, type GetValueOptions, type HealthCheckResult, type HealthReport, type InsertComponentAtResult, type InsertPosition, InvalidComponentNameError, LifecycleManager, type LifecycleManagerEmit, type LifecycleManagerEventMap, type LifecycleManagerEventName, LifecycleManagerEvents, type LifecycleManagerOptions, type LifecycleManagerStatus, type MessageResult, MissingDependencyError, type RegisterComponentResult, type RegisterOptions, type RegistrationFailureCode, type RestartComponentOptions, type RestartResult, type SendMessageOptions, type ShutdownMethod, type ShutdownResult, type SignalBroadcastResult, type StartComponentOptions, type StartupOptions, type StartupOrderFailureCode, type StartupOrderResult, type StartupResult, StartupTimeoutError, type StopAllOptions, type StopComponentOptions, type SystemState, type UnregisterComponentResult, type UnregisterFailureCode, type UnregisterOptions, type ValueResult, lifecycleManagerErrCodes, lifecycleManagerErrPrefix, lifecycleManagerErrTypes };
+export { BaseComponent, type BaseOperationResult, type BroadcastOptions, type BroadcastResult, type ComponentHealthResult, ComponentNotFoundError, type ComponentOperationFailureCode, type ComponentOperationResult, type ComponentOptions, ComponentRegistrationError, type ComponentSignalResult, type ComponentStallInfo, ComponentStartTimeoutError, ComponentStartupError, type ComponentState, type ComponentStatus, ComponentStopTimeoutError, type ComponentValueResult, DependencyCycleError, type DependencyValidationResult, type ForceShutdownContext, type GetValueOptions, type HealthCheckResult, type HealthReport, type InsertComponentAtResult, type InsertPosition, InvalidComponentNameError, LifecycleManager, type LifecycleManagerEmit, type LifecycleManagerEventMap, type LifecycleManagerEventName, LifecycleManagerEvents, type LifecycleManagerOptions, type LifecycleManagerStatus, type MessageResult, MissingDependencyError, type RegisterComponentResult, type RegisterOptions, type RegistrationFailureCode, type RepeatedShutdownRequestPolicy, type RestartComponentOptions, type RestartResult, type SendMessageOptions, type ShutdownEscalationStatus, type ShutdownMethod, type ShutdownResult, type SignalBroadcastResult, type StartComponentOptions, type StartupOptions, type StartupOrderFailureCode, type StartupOrderResult, type StartupResult, StartupTimeoutError, type StopAllOptions, type StopComponentOptions, type SystemState, type UnregisterComponentResult, type UnregisterFailureCode, type UnregisterOptions, type ValueResult, lifecycleManagerErrCodes, lifecycleManagerErrPrefix, lifecycleManagerErrTypes };