mega-framework 0.1.0

package/src/lib/mega-shutdown.js

@@ -0,0 +1,176 @@
+// @ts-check
+
+/**
+ * MegaShutdown — graceful shutdown 시퀀스 + 사용자 cleanup hook 묶음.
+ *
+ * 시퀀스 (docs/10 §3):
+ *   Running → DrainingReady (health 'ready' = 503)
+ *   → ClosingHttp (Fastify close, 진행중 요청 grace)
+ *   → ClosingWs (placeholder)
+ *   → ClosingJobs / ClosingScheduler (placeholder)
+ *   → DisconnectingAdapters (placeholder)
+ *   → FlushingLogs (placeholder)
+ *   → Exited (process.exit(0))
+ *
+ * SIGTERM/SIGINT 캐치 + 사용자 hook 실행 (LIFO) + grace period + hardKill.
+ * 후속 Phase 에서 단계 hook 자동 추가 (Fastify·어댑터·로거 등).
+ *
+ * API 는 docs/10·07 시퀀스에 맞춰 `MegaShutdown` 객체로 통일 (ADR — M-4).
+ *
+ * 사용 예:
+ *   MegaShutdown.register('http', async () => server.close())
+ *   MegaShutdown.register('db', async () => pool.end())
+ *   MegaShutdown.setupSignals({ gracePeriodMs: 30_000, hardKillMs: 60_000 })
+ *   await MegaShutdown.now()   // 수동 트리거
+ */
+
+/** @type {Array<{ name: string, fn: () => Promise<void> | void }>} */
+const handlers = []
+let signalsRegistered = false
+let isShuttingDownFlag = false
+let gracePeriodMs = 30_000
+let hardKillMs = 60_000
+let exitedHandlers = new Set()
+
+/**
+ * cleanup hook 등록. 순서는 등록 역순(LIFO)으로 실행.
+ * @param {string} name - 식별자 (로그용)
+ * @param {() => Promise<void> | void} fn
+ */
+function register(name, fn) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('MegaShutdown.register: name is required (string)')
+  }
+  if (typeof fn !== 'function') {
+    throw new Error('MegaShutdown.register: fn must be a function')
+  }
+  handlers.push({ name, fn })
+}
+
+/**
+ * 등록된 cleanup hook 제거 (같은 name 전부). 런타임 중 동적으로 붙였다 떼는 hook(예: hub link)
+ * 의 누수를 막는다(L1). shutdown 진행 중에는 인덱스 추적(exitedHandlers)과 충돌하므로 무시한다.
+ * @param {string} name - register 시 쓴 식별자.
+ * @returns {number} 제거된 hook 수.
+ */
+function unregister(name) {
+  if (isShuttingDownFlag) return 0   // shutdown 시퀀스 진행 중엔 handlers 배열을 건드리지 않는다.
+  let removed = 0
+  for (let i = handlers.length - 1; i >= 0; i--) {
+    if (handlers[i].name === name) {
+      handlers.splice(i, 1)
+      removed++
+    }
+  }
+  return removed
+}
+
+/**
+ * 현재 shutdown 진행 중인지.
+ * @returns {boolean}
+ */
+function isShuttingDown() {
+  return isShuttingDownFlag
+}
+
+/**
+ * SIGTERM/SIGINT 시그널 등록 (한 번만 등록됨).
+ * @param {{ gracePeriodMs?: number, hardKillMs?: number, signals?: string[] }} [opts]
+ */
+function setupSignals(opts = {}) {
+  if (signalsRegistered) return   // 멱등성
+  signalsRegistered = true
+  if (typeof opts.gracePeriodMs === 'number') gracePeriodMs = opts.gracePeriodMs
+  if (typeof opts.hardKillMs === 'number') hardKillMs = opts.hardKillMs
+  const signals = opts.signals ?? ['SIGTERM', 'SIGINT']
+  for (const sig of signals) {
+    process.on(sig, () => {
+      void now({ signal: sig, exitCode: 0 })
+    })
+  }
+}
+
+/**
+ * 즉시 graceful shutdown 트리거.
+ *
+ * 두 번째 호출(이미 shutdown 진행 중)은 "사용자가 빨리 죽이고 싶다" 는 신호로 보고
+ * 즉시 강제 종료한다 (docs/10 §3 Invariant — M-3).
+ *
+ * @param {{ signal?: string, exitCode?: number }} [opts]
+ */
+async function now({ signal, exitCode = 0 } = {}) {
+  // M-3 — 두 번째 shutdown 시그널: 이미 진행 중이면 grace 무시하고 즉시 force exit 1.
+  if (isShuttingDownFlag) {
+    console.error('[mega-shutdown] MegaShutdown: second shutdown signal — force exit 1')
+    process.exit(1)
+    return   // process.exit mock 시(테스트) 아래로 흐르지 않도록 가드
+  }
+  isShuttingDownFlag = true
+
+  console.log(`[mega-shutdown] starting (signal=${signal ?? 'manual'}, handlers=${handlers.length}, grace=${gracePeriodMs}ms)`)
+
+  // hardKill 보호 — hardKillMs 초과 시 강제 종료
+  const hardKillTimer = setTimeout(() => {
+    console.error('[mega-shutdown] grace period exceeded, force exit(1)')
+    process.exit(1)
+  }, hardKillMs)
+  hardKillTimer.unref()
+
+  // LIFO 순서로 hook 실행 (last registered runs first)
+  for (let i = handlers.length - 1; i >= 0; i--) {
+    const { name, fn } = handlers[i]
+    if (exitedHandlers.has(i)) continue
+    try {
+      console.log(`[mega-shutdown] running '${name}'`)
+      await Promise.race([
+        Promise.resolve(fn()),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error('handler timeout')), gracePeriodMs).unref(),
+        ),
+      ])
+      exitedHandlers.add(i)
+      console.log(`[mega-shutdown] '${name}' done`)
+    } catch (err) {
+      // silent 금지. 핸들러 실패 시 warn 로그 + 다음 hook 진행.
+      console.warn(`[mega-shutdown] '${name}' failed (continuing):`, err?.message ?? err)
+    }
+  }
+
+  clearTimeout(hardKillTimer)
+  console.log(`[mega-shutdown] complete, exit(${exitCode})`)
+  process.exit(exitCode)
+}
+
+/**
+ * 테스트용 — 등록된 hook 수 (디버그).
+ * @returns {number}
+ */
+function registeredCount() {
+  return handlers.length
+}
+
+/**
+ * 테스트용 — 내부 상태 reset (단위 테스트에서만 호출). 프로덕션 코드는 사용 X.
+ */
+function _reset() {
+  handlers.length = 0
+  signalsRegistered = false
+  isShuttingDownFlag = false
+  gracePeriodMs = 30_000
+  hardKillMs = 60_000
+  exitedHandlers = new Set()
+}
+
+/**
+ * MegaShutdown — graceful shutdown 단일 진입점 객체.
+ * docs/10·07 시퀀스가 `MegaShutdown.now()` 형태이므로 객체로 통일 (M-4).
+ */
+export const MegaShutdown = {
+  register,
+  unregister,
+  isShuttingDown,
+  setupSignals,
+  now,
+  registeredCount,
+  _reset,
+}