mega-framework 0.1.7 → 0.1.9

package/src/core/mega-app.js

@@ -63,7 +63,7 @@ export class MegaApp {
    * @param {Object|false} [opts.helmet] - fastify-helmet 옵션 (보안 헤더). false=미등록, undefined=디폴트 ON
    *   (ADR-047/127). 라우트 옵션 오버라이드는 완전 교체(ADR-073).
    * @param {Object|false} [opts.cors] - fastify-cors 옵션. false=미등록, undefined=origin:false(교차출처 거부, 안전 디폴트).
-   * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(IP당 100/min, ADR-048).
+   * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(IP당 1000/min, ADR-048/197).
    *   멀티 인스턴스 분산 카운팅은 `caches.rate` 별명(Redis), 미선언 시 in-memory 폴백.
    * @param {Object|false} [opts.csrf] - fastify-csrf-protection 옵션. false=미등록, undefined=디폴트 ON.
    *   ADR-051: JSON 요청은 토큰 면제+Origin 검증, 폼 요청만 토큰 검증.
@@ -233,53 +233,63 @@ export class MegaApp {
         Date.now()
     })
 
-    // 1b) HTTP 루트 span (ADR-126) — 옵트인 OFF 면 isEnabled() false 라 즉시 return(0 비용).
-    //     onRequest 에서 span 시작 + 활성 컨텍스트 진입(enterWith) → 핸들러의 ctx.tracer.span·어댑터 호출이
-    //     이 span 의 자식으로 중첩됨. onResponse 에서 status_code 기록 후 종료. 각 HTTP 요청은 독립 async
-    //     context 라 enterWith 가 요청 간 누수 없이 격리된다(실측 확인 — ADR-126).
-    this.fastify.addHook('onRequest', async (req, reply) => {
-      if (!MegaTracing.isEnabled()) return
-      const route = /** @type {any} */ (req).routeOptions?.url ?? req.url
-      const host = String(req.headers.host ?? '').split(':')[0]
-      const handle = MegaTracing.enterHttpSpan({
-        method: req.method,
-        route,
-        path: req.url,
-        host,
-        app: this.name,
-        // inbound traceparent/tracestate 를 부모로 복원(W3C trace context, ADR-196) — 게이트웨이/업스트림
-        // trace 에 루트 span 이 이어진다. 무효/부재 헤더는 종전대로 새 루트(fail-safe).
-        headers: req.headers,
-      })
-      ;(/** @type {Record<symbol, any>} */ (/** @type {unknown} */ (reply)))[HTTP_SPAN_SYMBOL] = handle
-    })
-    // onError 는 핸들러/직렬화 throw 시 호출 — 예외를 span 에 기록(상태 ERROR). 종료는 onResponse 담당.
-    this.fastify.addHook('onError', async (req, reply, err) => {
-      const handle = (/** @type {Record<symbol, any>} */ (/** @type {unknown} */ (reply)))[HTTP_SPAN_SYMBOL]
-      handle?.setError(err)
-      // 보안 거부(ASP 복호/drift/replay/signal)도 활성 span 에 사유 기록(ADR-127).
-      // CSRF/rate-limit 은 security.js 가 직접 박는다(throw 전·onExceeded). ASP 는 기존 코드 무변경 위해 여기서.
-      if (err instanceof MegaAspDecryptError) {
-        MegaTracing.tracer.activeSpan()?.setAttributes({ 'mega.security.reason': `asp.${err.rule}` })
-      }
-    })
-    // onResponse 는 성공·에러 응답 모두에서 마지막에 호출 — 상태코드 기록 후 span 종료(단일 종료 지점).
-    this.fastify.addHook('onResponse', async (req, reply) => {
-      const handle = (/** @type {Record<symbol, any>} */ (/** @type {unknown} */ (reply)))[HTTP_SPAN_SYMBOL]
-      handle?.finish(reply.statusCode)
-      // HTTP 요청 메트릭 (ADR-131) — 옵트인 OFF 면 isEnabled() false 라 즉시 return(0 비용).
-      // route 는 **매칭된 패턴**(routeOptions.url)만 — 매칭 안 되면(404) recordHttp 가 __unmatched__ 로 접어
-      // 카디널리티 폭증 차단. reply.elapsedTime = onRequest~onResponse ms(Fastify 제공).
-      if (MegaMetrics.isEnabled()) {
-        MegaMetrics.recordHttp({
+    // 1b) HTTP 루트 span (ADR-126) + 메트릭 (ADR-131) — **부팅 시점 분기** (G1 M-3, ADR-214).
+    //     이전엔 옵트인 OFF 여도 훅을 등록하고 본문에서 즉시 return 했는데, 본문 비용은 0 이어도
+    //     Fastify async hook 디스패치(훅당 Promise 1개) 자체가 매 요청 남는다. 옵트인은 부팅(boot 의
+    //     prepareRuntime 이 metrics → tracing 을 MegaApp 생성 **전에** init)에 결정되므로, 생성 시점에
+    //     OFF 면 훅을 아예 등록하지 않는다. 런타임 중 토글은 공개 표면에 없음(init 은 부팅 1회 계약 —
+    //     앱 생성 후 init 하는 직접 생성 경로는 미지원, ADR-214 명시).
+    const isTracingOn = MegaTracing.isEnabled()
+    const isMetricsOn = MegaMetrics.isEnabled()
+    if (isTracingOn) {
+      //     onRequest 에서 span 시작 + 활성 컨텍스트 진입(enterWith) → 핸들러의 ctx.tracer.span·어댑터 호출이
+      //     이 span 의 자식으로 중첩됨. onResponse 에서 status_code 기록 후 종료. 각 HTTP 요청은 독립 async
+      //     context 라 enterWith 가 요청 간 누수 없이 격리된다(실측 확인 — ADR-126).
+      this.fastify.addHook('onRequest', async (req, reply) => {
+        const route = /** @type {any} */ (req).routeOptions?.url ?? req.url
+        const host = String(req.headers.host ?? '').split(':')[0]
+        const handle = MegaTracing.enterHttpSpan({
           method: req.method,
-          route: /** @type {any} */ (req).routeOptions?.url,
-          statusCode: reply.statusCode,
-          durationMs: reply.elapsedTime,
+          route,
+          path: req.url,
+          host,
           app: this.name,
+          // inbound traceparent/tracestate 를 부모로 복원(W3C trace context, ADR-196) — 게이트웨이/업스트림
+          // trace 에 루트 span 이 이어진다. 무효/부재 헤더는 종전대로 새 루트(fail-safe).
+          headers: req.headers,
         })
-      }
-    })
+        ;(/** @type {Record<symbol, any>} */ (/** @type {unknown} */ (reply)))[HTTP_SPAN_SYMBOL] = handle
+      })
+      // onError 는 핸들러/직렬화 throw 시 호출 — 예외를 span 에 기록(상태 ERROR). 종료는 onResponse 담당.
+      this.fastify.addHook('onError', async (req, reply, err) => {
+        const handle = (/** @type {Record<symbol, any>} */ (/** @type {unknown} */ (reply)))[HTTP_SPAN_SYMBOL]
+        handle?.setError(err)
+        // 보안 거부(ASP 복호/drift/replay/signal)도 활성 span 에 사유 기록(ADR-127).
+        // CSRF/rate-limit 은 security.js 가 직접 박는다(throw 전·onExceeded). ASP 는 기존 코드 무변경 위해 여기서.
+        if (err instanceof MegaAspDecryptError) {
+          MegaTracing.tracer.activeSpan()?.setAttributes({ 'mega.security.reason': `asp.${err.rule}` })
+        }
+      })
+    }
+    // onResponse 는 성공·에러 응답 모두에서 마지막에 호출 — 상태코드 기록 후 span 종료(단일 종료 지점).
+    // 트레이싱(span finish)·메트릭(recordHttp) 둘 중 하나라도 켜져 있을 때만 등록.
+    if (isTracingOn || isMetricsOn) {
+      this.fastify.addHook('onResponse', async (req, reply) => {
+        const handle = (/** @type {Record<symbol, any>} */ (/** @type {unknown} */ (reply)))[HTTP_SPAN_SYMBOL]
+        handle?.finish(reply.statusCode)
+        // HTTP 요청 메트릭 (ADR-131) — route 는 **매칭된 패턴**(routeOptions.url)만. 매칭 안 되면(404)
+        // recordHttp 가 __unmatched__ 로 접어 카디널리티 폭증 차단. reply.elapsedTime = Fastify 제공 ms.
+        if (isMetricsOn && MegaMetrics.isEnabled()) {
+          MegaMetrics.recordHttp({
+            method: req.method,
+            route: /** @type {any} */ (req).routeOptions?.url,
+            statusCode: reply.statusCode,
+            durationMs: reply.elapsedTime,
+            app: this.name,
+          })
+        }
+      })
+    }
 
     // 2) 자동 envelope (ADR-018, ADR-076).
     //    onRoute 훅으로 각 라우트의 preSerialization 체인 "맨 끝" 에 wrapEnvelope 를 붙인다.

package/src/core/pipeline.js

@@ -21,19 +21,20 @@
  *
  * @module core/pipeline
  */
-import { getHttpCtx } from './ctx-builder.js'
+import { getLazyHttpCtx } from './ctx-builder.js'
 
 /**
  * 미들웨어를 Fastify 가 async preHandler 로 인식하는 arity-2 래퍼로 감싸고, canonical ctx 를
  * 3번째 인자로 주입한다 — 핸들러·글로벌 미들웨어와 동일한 `(req, reply, ctx)` 계약(ADR-134/184).
- * getHttpCtx 는 요청당 캐싱이라 같은 요청의 모든 미들웨어·핸들러가 동일 ctx 객체를 공유한다.
+ * ctx 는 **lazy 프록시**(ADR-214) — 미들웨어가 실제로 속성을 만질 때만 빌드되고, 요청당 캐싱이라
+ * 같은 요청의 모든 미들웨어·핸들러가 동일 ctx 객체를 공유한다.
  *
  * @param {Function} fn - `(req, reply, ctx?)` 미들웨어 (arity-2 도 하위 호환 — 3번째 인자 무시).
  * @param {import('./mega-app.js').MegaApp | null} [app] - ctx 의 어댑터·서비스 접근자 출처(없으면 null).
  * @returns {(req: import('fastify').FastifyRequest, reply: import('fastify').FastifyReply) => Promise<any>}
  */
 export function wrapPreHandler(fn, app) {
-  return async (req, reply) => fn(req, reply, getHttpCtx({ app: app ?? null, req, reply }))
+  return async (req, reply) => fn(req, reply, getLazyHttpCtx({ app: app ?? null, req, reply }))
 }
 
 /**
@@ -102,9 +103,10 @@ export function composeAfter(afters, { method, path }) {
 export function buildHttpPipeline({ app = null, method, path, handler, before = [], transform = [], after = [] }) {
   /** @type {HttpPipeline} */
   const pipeline = {
-    // canonical 핸들러 시그니처 (req, res, ctx) (ADR-074, docs/03 §581). getHttpCtx 는 요청당 1회
-    // 캐싱이라 글로벌·before 미들웨어가 먼저 만든 ctx 를 그대로 이어받는다(ADR-134).
-    handler: async (req, reply) => handler(req, reply, getHttpCtx({ app, req, reply })),
+    // canonical 핸들러 시그니처 (req, res, ctx) (ADR-074, docs/03 §581). ctx 는 lazy 프록시
+    // (ADR-214) — 핸들러가 안 쓰면 buildHttpCtx 비용(1.6 KB + 0.7 µs/req, G1 H-1)이 발생하지 않고,
+    // 첫 접근부터는 요청당 1회 캐싱이라 글로벌·before 미들웨어가 먼저 만든 ctx 를 그대로 이어받는다(ADR-134).
+    handler: async (req, reply) => handler(req, reply, getLazyHttpCtx({ app, req, reply })),
     describe: () => ({
       method,
       path,

package/src/core/scope-registry.js

@@ -20,6 +20,7 @@ export const GLOBAL_ONLY_KEYS = Object.freeze([
   'jobs', // MegaJob 서브클래스 배열 — mega worker 가 소비 (ADR-123)
   'schedules', // MegaSchedule 서브클래스 배열 — mega scheduler 가 소비 (ADR-123)
   'workers', // MegaWorker 서브클래스 배열 — CPU 워커 풀, ctx.workers.<name> 배선 (ADR-124)
+  'watch', // mega start --watch 의 ignore/paths 정책 (ADR-220)
 ])
 
 /** apps/<name>/app.config.js 에만 허용되는 키 */

package/src/core/security.js

@@ -43,8 +43,8 @@ import { registerAspPlugin } from '../lib/asp/plugin.js'
 import { MegaForbiddenError } from '../errors/http-errors.js'
 import * as MegaTracing from '../lib/mega-tracing.js'
 
-/** rate-limit 기본값 (ADR-048: IP 당 100 req/min). 사용자 config 로 완전 교체(ADR-073). */
-export const DEFAULT_RATE_LIMIT = Object.freeze({ max: 100, timeWindow: '1 minute' })
+/** rate-limit 기본값 (IP 당 1000 req/min — ADR-048 의 100/min 은 평상 트래픽도 429 를 만드는 운영 함정이라 상향, ADR-214). 사용자 config 로 완전 교체(ADR-073). */
+export const DEFAULT_RATE_LIMIT = Object.freeze({ max: 1000, timeWindow: '1 minute' })
 
 /** CSRF 토큰 검증을 건너뛰는 안전 메서드(상태 변경 없음). */
 const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
@@ -83,7 +83,7 @@ function annotateReject(reason, extra = {}) {
  * @param {string[]} [opts.hosts] - 앱 도메인 목록(CSRF Origin 검증 allowlist, ADR-051).
  * @param {Object|false} [opts.helmet] - fastify-helmet 옵션. false=미등록, undefined=디폴트 ON.
  * @param {Object|false} [opts.cors] - fastify-cors 옵션. false=미등록, undefined=origin:false(교차출처 거부).
- * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(100/min).
+ * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(1000/min, ADR-214).
  * @param {Object|false} [opts.csrf] - fastify-csrf-protection 옵션. false=미등록, undefined=디폴트 ON.
  * @param {{ masterSecret?: string, http?: { enabledPaths?: string[], driftMs?: number, headerSignal?: string, timestampHeader?: string, nonceCache?: any } }} [opts.asp] -
  *   ASP 설정. `masterSecret` + `http.enabledPaths`(비어있지 않음)가 둘 다 있을 때만 HTTP ASP 등록.

package/src/core/session-store.js

@@ -23,6 +23,14 @@ const SESSION_DRIVERS = Object.freeze({
   redis: MegaRedisSessionAdapter,
 })
 
+/**
+ * file driver 만료 스캔 cleanup 기본 주기(1시간, ms) — ADR-046 의 "file 모드 cleanup 자동" 약속 구현(ADR-215).
+ * 어댑터 자체 디폴트는 0(off)이라, 팩토리 경유 생성(=프레임워크 부팅 경로)에서만 기본 주기를 주입한다.
+ * 만료 파일의 lazy 삭제는 같은 sid 재접근 시에만 일어나므로, 주기 스캔이 없으면 미접근 만료 세션이
+ * 디스크에 무한 누적된다(G5 audit M-3). `cleanupIntervalMs: 0` 명시로 옵트아웃(외부 cron/scheduler 운용 시).
+ */
+export const DEFAULT_FILE_CLEANUP_INTERVAL_MS = 3_600_000
+
 /**
  * 세션 스토어 어댑터를 만든다(connect 는 호출자 책임 — MegaApp 가 부팅 시 connect).
  *
@@ -47,7 +55,12 @@ export function createSessionStore(storeConfig, defaults = {}) {
   }
   const Cls = SESSION_DRIVERS[/** @type {'file'|'redis'} */ (driver)]
   // store 에 ttlMs 가 명시되지 않았으면 미들웨어 기본 ttlMs 를 주입(단일 출처 — session.ttlMs).
-  const cfg = storeConfig.ttlMs === undefined && defaults.ttlMs !== undefined ? { ...storeConfig, ttlMs: defaults.ttlMs } : storeConfig
+  let cfg = storeConfig.ttlMs === undefined && defaults.ttlMs !== undefined ? { ...storeConfig, ttlMs: defaults.ttlMs } : storeConfig
+  // file driver 는 만료 스캔 cleanup 을 기본 1h 주기로 — 미지정 시에만 주입(명시 0 = 옵트아웃, ADR-215).
+  // 타이머는 어댑터 _connect 가 unref() 로 걸어 프로세스 종료를 막지 않는다.
+  if (driver === 'file' && cfg.cleanupIntervalMs === undefined) {
+    cfg = { ...cfg, cleanupIntervalMs: DEFAULT_FILE_CLEANUP_INTERVAL_MS }
+  }
   return new Cls(/** @type {any} */ (cfg))
 }
 

package/src/core/ws-presence.js

@@ -18,6 +18,7 @@ import { MegaHubLink } from './hub-link.js'
 import { CLOSE_CODE_REQUEUE } from './ws-upgrade.js'
 import { HUB_MESSAGE_TYPES } from '../lib/hub-protocol.js'
 import { MegaShutdown } from '../lib/mega-shutdown.js'
+import * as MegaHealth from '../lib/mega-health.js'
 
 export class MegaWsPresence {
   /**
@@ -113,16 +114,26 @@ export class MegaWsPresence {
     link.on(HUB_MESSAGE_TYPES.HEARTBEAT, noopHub)
     // 재연결 성공 시 presence 재동기화(ADR-098) — hub 는 절단 시점 presence 를 잃으므로 broadcast 채널을 다시 JOIN.
     link.on(MegaHubLink.EVENTS.RECONNECTED, () => this._resyncPresence())
+
+    // shutdown hook 은 connect **전에** 등록한다(L1 dedup 유지) — 초기 연결이 실패해 백그라운드
+    // 재시도로 전환돼도(아래 throw) hook 이 link.close 로 백오프를 abort 해 프로세스가 행하지 않는다.
+    const hookName = `mega-hublink:${this._appName}`
+    MegaShutdown.unregister(hookName)
+    MegaShutdown.register(hookName, async () => link.close())
+
+    // readiness 에 hub link 상태 노출 — hub 는 best-effort(다운이어도 부팅·로컬 전달 지속)라 readiness 를
+    // **게이트하지 않는다**(ok 고정 true — 어댑터 자동 체크와 달리 503 원인이 되면 안 됨). 연결 상태는
+    // detail 필드(registered/open)로 노출된다(기본 응답은 ok 만 — 상세는 health.exposeCheckDetails 옵트인).
+    MegaHealth.register(`hub:${this._appName}`, () => ({ ok: true, registered: link.isRegistered, open: link.isOpen }))
+
+    // 초기 연결은 단 1회 시도(hub-link connect 계약) — 실패 시 reject 가 전파되고(호출부 boot 가 warn 후
+    // 부팅 계속) retry 설정이 있으면 link 가 백그라운드로 재시도한다. RECONNECTED 핸들러(위)가 성공 시
+    // presence 를 재동기화하므로 여기 실패해도 채널 구독은 복구된다.
     await link.connect()
 
     // 채널 구독 — bridge-subscriber 세션 JOIN(zero-config 브로드캐스트 수신용) + 이미 붙어 있는 실
     // 사용자 세션 재JOIN(예: 첫 connect 전에 클라가 연결됐을 수 있음).
     this._resyncPresence()
-
-    // shutdown hook 누수 방지(L1) — 재연결 등으로 connectHub 가 다시 불려도 hook 은 항상 1개.
-    const hookName = `mega-hublink:${this._appName}`
-    MegaShutdown.unregister(hookName)
-    MegaShutdown.register(hookName, async () => link.close())
     return link
   }
 
@@ -601,6 +612,7 @@ export class MegaWsPresence {
       this._hubLink = null
       this._hubBridgeId = null
       MegaShutdown.unregister(`mega-hublink:${this._appName}`)
+      MegaHealth.unregister(`hub:${this._appName}`) // 닫힌 link 의 stale 체크 제거(register 와 짝맞춤).
     }
     // NATS 클러스터 정리(ADR-176) — 구독·heartbeat/sweep 타이머·roster 멤버 해제. boot 의 shutdown hook 과
     // **양쪽**에서 정리해야 시그널을 안 거치는 종료(server.close()/프로그램적 재시작/멀티앱 부분 종료)에서도

package/src/core/ws-roster.js

@@ -74,9 +74,25 @@ export class MegaWsRedisRoster {
     if (typeof channel !== 'string' || typeof sessionId !== 'string') return
     const key = this._key(channel)
     const value = JSON.stringify({ userId: member?.userId, ...(member?.metadata ? { metadata: member.metadata } : {}), expiresAt: Date.now() + this._ttlMs })
-    await this._redis.hset(key, sessionId, value)
-    // 채널 HASH 키 전체 TTL — 모든 멤버가 stale 가 돼도 키가 영구히 남지 않게(멤버 TTL 의 2배 여유).
-    await this._redis.pexpire(key, this._ttlMs * 2)
+    // HSET + 채널 HASH 키 TTL(멤버 TTL 2배 — 전원 stale 돼도 키가 영구히 안 남게)을 pipeline 1 RT 로.
+    // 직렬 await 2회는 joinSession(채널 수만큼 add)·heartbeat 경로에서 왕복 수가 비용을 지배했다.
+    const results = await this._redis.pipeline().hset(key, sessionId, value).pexpire(key, this._ttlMs * 2).exec()
+    this._throwFirstPipelineError(results)
+  }
+
+  /**
+   * ioredis pipeline.exec() 결과(`[err, res][]`)에서 첫 명령 오류를 throw 한다 — pipeline 은 명령별
+   * 오류를 reject 가 아니라 결과 배열에 싣기 때문에, 묵히면 호출부의 기존 실패 처리(catch+warn)가
+   * 더는 동작하지 않는다(직렬 await 시절의 throw 계약 유지).
+   * @param {Array<[Error | null, any]> | null} results
+   * @returns {void}
+   * @private
+   */
+  _throwFirstPipelineError(results) {
+    if (!Array.isArray(results)) return
+    for (const [err] of results) {
+      if (err) throw err
+    }
   }
 
   /**
@@ -139,13 +155,29 @@ export class MegaWsRedisRoster {
   }
 
   /**
-   * 로컬 멤버 전체를 다시 add(=expiresAt 갱신). @returns {Promise<void>} @private
+   * 로컬 멤버 전체의 `expiresAt` 을 한 pipeline 으로 일괄 갱신. 직렬 add 루프(멤버당 2 RT)는 멤버
+   * 1,000 에 주기당 수백 ms — 갱신 지연이 TTL 윈도를 침식해 살아있는 세션이 lazy 만료될 수 있었다.
+   * pipeline 이면 단일 왕복 수준(실측 ~200×). 채널 키 PEXPIRE 는 채널당 1회만 싣는다.
+   * @returns {Promise<void>} @private
    */
   async _refreshLocal() {
     const members = this._getLocalMembers()
+    if (members.length === 0) return
+    const expiresAt = Date.now() + this._ttlMs
+    const pipeline = this._redis.pipeline()
+    /** @type {Set<string>} PEXPIRE 를 이미 실은 채널(중복 제거). */
+    const touchedChannels = new Set()
     for (const { channel, sessionId, member } of members) {
-      await this.add(channel, sessionId, member)
+      if (typeof channel !== 'string' || typeof sessionId !== 'string') continue
+      const key = this._key(channel)
+      const value = JSON.stringify({ userId: member?.userId, ...(member?.metadata ? { metadata: member.metadata } : {}), expiresAt })
+      pipeline.hset(key, sessionId, value)
+      if (!touchedChannels.has(channel)) {
+        touchedChannels.add(channel)
+        pipeline.pexpire(key, this._ttlMs * 2)
+      }
     }
+    this._throwFirstPipelineError(await pipeline.exec())
   }
 
   /**
@@ -155,12 +187,19 @@ export class MegaWsRedisRoster {
   async stop() {
     if (this._hbTimer) clearInterval(this._hbTimer)
     this._hbTimer = null
-    // graceful: 자기 로컬 멤버 즉시 제거(crash 가 아닌 정상 종료라 TTL 대기 없이 정리).
+    // graceful: 자기 로컬 멤버 즉시 제거(crash 가 아닌 정상 종료라 TTL 대기 없이 정리) — 한 pipeline 으로.
     // 실패해도 종료는 계속(lazy 만료가 정리) — 단 명단에 TTL 까지 남으므로 묵히지 않고 알린다.
-    for (const { channel, sessionId } of this._getLocalMembers()) {
-      await this.remove(channel, sessionId).catch((err) =>
-        this._log?.warn?.({ err, channel, sessionId }, 'ws-roster graceful remove failed (stale until TTL)'),
-      )
+    const members = this._getLocalMembers()
+    if (members.length === 0) return
+    const pipeline = this._redis.pipeline()
+    for (const { channel, sessionId } of members) {
+      if (typeof channel !== 'string' || typeof sessionId !== 'string') continue
+      pipeline.hdel(this._key(channel), sessionId)
+    }
+    try {
+      this._throwFirstPipelineError(await pipeline.exec())
+    } catch (err) {
+      this._log?.warn?.({ err }, 'ws-roster graceful remove failed (stale until TTL)')
     }
   }
 }

package/src/core/ws-upgrade.js

@@ -61,6 +61,104 @@ export const CLOSE_CODE_REQUEUE = 4503
 /** send 버퍼(bufferedAmount) 기본 상한(바이트). 초과 = 소비자가 ack 를 못 따라옴 → 연결 종료(서버 OOM 방지). */
 export const DEFAULT_MAX_BUFFERED_BYTES = 16 * 1024 * 1024
 
+/**
+ * 프로세스 **합산** send 버퍼 기본 budget(바이트, ADR-215 — G5 audit M-6).
+ *
+ * per-conn 상한(위 16MiB)은 연결 1개의 OOM 방어일 뿐이라, 느린 소비자 N 개가 각자 cap 직전까지
+ * 쌓으면 합산은 무제한이었다(이론상 1,000개 × 16MiB = 16GB). 합산이 본 budget 을 넘으면 **가장 큰
+ * 송신 큐를 보유한 연결부터** 1013(slow consumer)으로 종료해 budget 아래로 회수한다.
+ * `configureWsSendBudget({ maxTotalBufferedBytes: 0 })` 으로 무제한 옵트아웃.
+ */
+export const DEFAULT_MAX_TOTAL_BUFFERED_BYTES = 256 * 1024 * 1024
+
+/** 합산 budget 스윕 최소 간격(ms) — 매 send 마다 전 연결 O(N) 합산을 돌지 않게 하는 비용 상한. */
+const BUDGET_SWEEP_INTERVAL_MS = 250
+
+/** budget 추적 대상 연결 — driveWsConnection 경유 실연결만(직접 생성한 테스트 더블은 미추적). @type {Set<MegaWsConnection>} */
+const budgetConns = new Set()
+
+/** @type {number} 현재 합산 budget(바이트). Infinity = 옵트아웃. */
+let maxTotalBufferedBytes = DEFAULT_MAX_TOTAL_BUFFERED_BYTES
+
+/** @type {number} 마지막 budget 스윕 시각(epoch ms). */
+let lastBudgetSweepAt = 0
+
+/**
+ * 프로세스 합산 send budget 을 조정한다(ADR-215). 부팅/운영 튜닝 진입점.
+ * @param {{ maxTotalBufferedBytes?: number }} [opts] - 바이트 budget. `0` = 무제한(옵트아웃).
+ * @returns {{ maxTotalBufferedBytes: number }} 적용된 현재 값.
+ * @throws {TypeError} 음수/비숫자 — 설정 실수 fail-fast.
+ */
+export function configureWsSendBudget({ maxTotalBufferedBytes: max } = {}) {
+  if (max !== undefined) {
+    if (typeof max !== 'number' || Number.isNaN(max) || max < 0) {
+      throw new TypeError(`configureWsSendBudget: maxTotalBufferedBytes must be a non-negative number (0 = unlimited). Got ${max}`)
+    }
+    maxTotalBufferedBytes = max === 0 ? Infinity : max
+  }
+  return { maxTotalBufferedBytes }
+}
+
+/**
+ * 합산 budget 스윕 — 추적 중 전 연결의 `bufferedAmount` 를 합산해 budget 초과면 가장 큰 큐 보유
+ * 연결부터 종료한다. 스로틀({@link BUDGET_SWEEP_INTERVAL_MS}) 안쪽 재호출은 no-op(send 핫패스 보호).
+ * @param {number} [now] - epoch ms(테스트 주입용).
+ * @returns {void}
+ */
+function sweepWsSendBudget(now = Date.now()) {
+  if (now - lastBudgetSweepAt < BUDGET_SWEEP_INTERVAL_MS) return
+  lastBudgetSweepAt = now
+  if (budgetConns.size === 0 || maxTotalBufferedBytes === Infinity) return
+  let total = 0
+  for (const c of budgetConns) total += c._raw.bufferedAmount ?? 0
+  while (total > maxTotalBufferedBytes) {
+    /** @type {MegaWsConnection | null} */
+    let worst = null
+    for (const c of budgetConns) {
+      if (worst === null || (c._raw.bufferedAmount ?? 0) > (worst._raw.bufferedAmount ?? 0)) worst = c
+    }
+    const worstBytes = worst === null ? 0 : (worst._raw.bufferedAmount ?? 0)
+    if (worst === null || worstBytes === 0) break // 잔여가 전부 0 이면 더 회수할 게 없음(무한루프 차단).
+    budgetConns.delete(worst) // close 이벤트 전에 즉시 제외 — 같은 스윕 내 재선정 방지.
+    total -= worstBytes
+    try {
+      worst._raw.close(CLOSE_CODE_SLOW_CONSUMER, 'backpressure: process-wide send budget exceeded')
+    } catch {
+      // 이미 닫히는 중이면 close 는 무의미 — per-conn 가드와 동일 의미(비치명적). Set 에선 이미 제거됨.
+    }
+  }
+}
+
+/** budget 추적 등록(driveWsConnection 전용). @param {MegaWsConnection} conn @returns {void} */
+function trackWsSendBudget(conn) {
+  budgetConns.add(conn)
+}
+
+/** budget 추적 해제(연결 close 시). @param {MegaWsConnection} conn @returns {void} */
+function untrackWsSendBudget(conn) {
+  budgetConns.delete(conn)
+}
+
+/**
+ * 테스트 격리용 — budget 상태 초기화(추적 Set·스로틀·budget 디폴트 복원).
+ * @returns {void}
+ */
+export function _resetWsSendBudget() {
+  budgetConns.clear()
+  lastBudgetSweepAt = 0
+  maxTotalBufferedBytes = DEFAULT_MAX_TOTAL_BUFFERED_BYTES
+}
+
+/** 테스트용 — 연결을 budget 추적에 등록. @param {MegaWsConnection} conn @returns {void} */
+export function _trackWsSendBudget(conn) {
+  trackWsSendBudget(conn)
+}
+
+/** 테스트용 — 스로틀 우회 가능한 스윕 직접 호출. @param {number} [now] @returns {void} */
+export function _sweepWsSendBudget(now) {
+  sweepWsSendBudget(now)
+}
+
 /**
  * 클라↔bridge ping/pong liveness 기본 주기(ms) — 30초. 주기마다 ping 을 보내고 직전 주기의 pong 이
  * 없으면 half-open(상대 사망·네트워크 단절) 으로 보고 terminate 한다 — 좀비 연결이 OS TCP 타임아웃까지
@@ -197,6 +295,10 @@ export class MegaWsConnection {
       }
       return
     }
+    // 프로세스 합산 budget 스윕(ADR-215) — per-conn cap 아래의 "다수의 느린 소비자" 합산 OOM 방어.
+    // 스로틀이 있어 핫패스 비용은 주기당 O(N) 1회. 스윕이 이 연결을 닫았으면(가장 큰 큐) 송신 생략.
+    sweepWsSendBudget()
+    if (this._raw.readyState !== undefined && this._raw.readyState !== 1) return
     // ns 자동 주입 (L1): 명시 안 됐고 연결 ns 가 있으면 채운다. 명시값은 덮어쓰지 않음.
     const withNs = fields.ns === undefined && this.ns !== undefined ? { ...fields, ns: this.ns } : fields
     const env = createWsMessage(withNs)
@@ -284,6 +386,8 @@ function buildWsPresence(app, conn, ns) {
  */
 export function driveWsConnection({ raw, req, route, app, codec, log, auth = null, protocolVersion = WS_PROTOCOL_VERSION }) {
   const conn = new MegaWsConnection(raw, codec, { ns: route.ns, path: route.path })
+  // 프로세스 합산 send budget 추적(ADR-215) — 실연결만 등록, close 에서 해제(아래 'close' 핸들러).
+  trackWsSendBudget(conn)
   // 협상된 envelope 버전 — 이 연결의 검증 기준이자 v2 도입 시 코덱/검증 분기의 기준점.
   conn.protocolVersion = protocolVersion
   // ChannelClass 는 부팅 시 MegaWebSocketController 상속 검증됨 (router.ws). 여기선 인스턴스화만.
@@ -400,6 +504,7 @@ export function driveWsConnection({ raw, req, route, app, codec, log, auth = nul
   }
 
   raw.on('close', (code, reasonBuf) => {
+    untrackWsSendBudget(conn)
     app._untrackWsConn?.(conn)
     const reason = Buffer.isBuffer(reasonBuf) ? reasonBuf.toString('utf8') : String(reasonBuf ?? '')
     log.debug?.({ connId: conn.id, code, reason }, 'ws.disconnect')

package/src/lib/mega-circuit-breaker.js

@@ -72,8 +72,10 @@ export const CAPACITY_ERROR_CODE = 'ESEMLOCKED'
  * @property {number} [resetTimeout=30000] - open 상태 유지 시간(ms). 경과 후 halfOpen 으로 1회 프로빙.
  * @property {number} [rollingCountTimeout=10000] - 실패율 집계 롤링 윈도우 길이(ms).
  * @property {number} [rollingCountBuckets=10] - 롤링 윈도우를 나누는 버킷 수.
- * @property {number} [volumeThreshold=0] - 이 횟수만큼 호출이 쌓이기 전엔 실패율이 높아도 open 안 함
- *   (표본 부족으로 인한 조기 trip 방지). 0=비활성.
+ * @property {number} [volumeThreshold=5] - 롤링 윈도우에 이 횟수만큼 호출이 쌓이기 전엔 실패율이
+ *   높아도 open 안 함(표본 부족 조기 trip 방지). 0=비활성. ⚠️ opossum 정본값(0)과 다른 프레임워크
+ *   디폴트 — 0 이면 부팅 직후/저빈도 호출에서 **첫 실패 1건**이 실패율 100% 가 돼 즉시 30s 차단되는
+ *   풋건이라 5 로 올렸다. opossum 원 동작이 필요하면 명시적으로 0 을 지정.
  * @property {number} [capacity] - 동시 진행(in-flight) 호출 상한. 초과분은 `ESEMLOCKED` 로 즉시 거부.
  *   미지정=무제한.
  * @property {(err: any, ...args: any[]) => boolean} [errorFilter] - `true` 반환 시 그 에러는 **실패로 집계하지 않음**
@@ -149,7 +151,7 @@ export class MegaCircuitBreaker {
       resetTimeout = 30_000,
       rollingCountTimeout = 10_000,
       rollingCountBuckets = 10,
-      volumeThreshold = 0,
+      volumeThreshold = 5, // opossum 정본(0)과 의도적으로 다름 — 단일 실패 즉시 open 풋건 방지.
       capacity,
       errorFilter,
       name,

package/src/lib/mega-health.js

@@ -45,6 +45,16 @@ export function register(name, fn, opts = {}) {
   checks.set(name, { fn, timeoutMs })
 }
 
+/**
+ * 등록된 체크 제거(이름 기준). 닫힌 자원(예: hub link)의 체크가 stale 클로저로 남지 않게
+ * 소유자가 register 와 짝맞춰 부른다.
+ * @param {string} name
+ * @returns {boolean} 제거됐으면 true(미등록 이름이면 false).
+ */
+export function unregister(name) {
+  return checks.delete(name)
+}
+
 /**
  * 모든 체크 실행 (병렬). 하나라도 false 면 전체 ok=false.
  * @returns {Promise<{ ok: boolean, checks: Record<string, { ok: boolean, error?: string, [key: string]: any }> }>}

package/src/lib/mega-job-queue.js

@@ -91,6 +91,8 @@ function truncateStack(stack) {
  *   하트비트가 이 값의 절반마다 lease 를 갱신한다.
  * @property {number} [maxDeliver=5] - JetStream 최대 전달 횟수(워커 크래시 재전달 backstop).
  * @property {number} [heartbeatMs] - `working()` 전송 주기(ms). 기본 `max(1000, ackWaitMs/2)`.
+ *   양의 정수 + `< ackWaitMs` 필수(생성자 fail-fast) — 이상이면 lease 갱신이 늦어 정상 처리 중
+ *   중복 재전달, 0 이하면 working() 플러딩.
  * @property {string} [streamPrefix='MEGA_JOBS'] - 스트림 이름 접두사.
  * @property {number} [dlqMaxAgeMs=604800000] - DLQ 스트림 메시지 보존 기한(ms, 디폴트 7일). 초과한 실패
  *   잡은 NATS 가 자동 만료시킨다(무한 적재 방지, ADR-134). `0` 이면 무제한(끔 — 영구 보존). **신규 DLQ
@@ -135,6 +137,13 @@ export class MegaJobQueue extends EventEmitter {
   /** @type {import('nats').JetStreamClient|null} */ #js = null
   /** @type {import('nats').JetStreamManager|null} */ #jsm = null
   /** @type {Promise<void>|null} ensureReady 멱등 가드. */ #readyPromise = null
+  /**
+   * subject 별 ensureStream 멱등 캐시(#readyPromise 와 동일 패턴). 없으면 enqueue 가 매 호출
+   * `jsm.streams.info` RPC ×2(워크+DLQ)를 반복해 enqueue 비용의 2/3 가 존재 재확인에 낭비된다.
+   * 실패한 Promise 는 캐시에서 비워 다음 호출이 재시도하게 한다.
+   * @type {Map<string, Promise<void>>}
+   */
+  #ensuredStreams = new Map()
 
   /**
    * @param {MegaJobQueueOptions} options
@@ -164,6 +173,11 @@ export class MegaJobQueue extends EventEmitter {
     if (typeof runTimeoutMs !== 'number' || !Number.isInteger(runTimeoutMs) || runTimeoutMs < 0) {
       throw new TypeError(`MegaJobQueue: runTimeoutMs must be an integer >= 0 (0 = unlimited). Got: ${runTimeoutMs}.`)
     }
+    // heartbeatMs: working() lease 갱신 주기. ackWaitMs 이상이면 갱신이 늦어 정상 처리 중 lease 가
+    // 만료돼 중복 재전달(at-least-once 폭증)되고, 0 이하면 setInterval 1ms 클램프로 working() 플러딩.
+    if (heartbeatMs !== undefined && (typeof heartbeatMs !== 'number' || !Number.isInteger(heartbeatMs) || heartbeatMs < 1 || heartbeatMs >= ackWaitMs)) {
+      throw new TypeError(`MegaJobQueue: heartbeatMs must be a positive integer < ackWaitMs (${ackWaitMs}). Got: ${heartbeatMs}.`)
+    }
     this.#nc = nc
     this.#ackWaitMs = ackWaitMs
     this.#maxDeliver = maxDeliver
@@ -336,16 +350,30 @@ export class MegaJobQueue extends EventEmitter {
    * @param {typeof MegaJob} JobClass @returns {Promise<void>}
    */
   async ensureStream(JobClass) {
-    await this.ensureReady()
     const subject = this.#assertJobSubject(JobClass)
-    const nats = /** @type {typeof import('nats')} */ (this.#nats)
-    await this.#ensureStreamExists(this.#workStreamName(subject), [subject], nats.RetentionPolicy.Workqueue)
-    // DLQ 스트림에 한도를 건다(무한 적재 방지, ADR-134). dlqMaxAgeMs=0 이면 max_age 미지정(무제한),
-    // dlqMaxBytes 미지정이면 max_bytes 미지정.
-    await this.#ensureStreamExists(this.#dlqStreamName(subject), [`${subject}.dlq`], nats.RetentionPolicy.Limits, {
-      maxAgeMs: this.#dlqMaxAgeMs,
-      maxBytes: this.#dlqMaxBytes,
-    })
+    // subject 별 1회만 실제 확인(RPC ×2) — 이후 호출은 캐시된 Promise 를 기다린다(동시 호출도 1회).
+    const cached = this.#ensuredStreams.get(subject)
+    if (cached) return cached
+    const ensured = (async () => {
+      await this.ensureReady()
+      const nats = /** @type {typeof import('nats')} */ (this.#nats)
+      await this.#ensureStreamExists(this.#workStreamName(subject), [subject], nats.RetentionPolicy.Workqueue)
+      // DLQ 스트림에 한도를 건다(무한 적재 방지, ADR-134). dlqMaxAgeMs=0 이면 max_age 미지정(무제한),
+      // dlqMaxBytes 미지정이면 max_bytes 미지정.
+      await this.#ensureStreamExists(this.#dlqStreamName(subject), [`${subject}.dlq`], nats.RetentionPolicy.Limits, {
+        maxAgeMs: this.#dlqMaxAgeMs,
+        maxBytes: this.#dlqMaxBytes,
+      })
+    })()
+    this.#ensuredStreams.set(subject, ensured)
+    try {
+      await ensured
+    } catch (err) {
+      // 실패는 캐시하지 않는다 — NATS 일시 장애 후 다음 enqueue/consume 이 재시도할 수 있게.
+      this.#ensuredStreams.delete(subject)
+      throw err
+    }
+    return ensured
   }
 
   /**
@@ -399,14 +427,26 @@ export class MegaJobQueue extends EventEmitter {
   }
 
   /**
-   * 잡을 큐에 넣는다(JetStream publish — 서버에 영속 저장). 스트림이 없으면 만든다.
-   * @param {typeof MegaJob} JobClass @param {any} payload @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
+   * 잡을 큐에 넣는다(JetStream publish — 서버에 영속 저장). 스트림이 없으면 만든다(subject 별 1회 확인 후 캐시).
+   *
+   * @param {typeof MegaJob} JobClass @param {any} payload
+   * @param {{ msgID?: string }} [opts] - `msgID` = JetStream `Nats-Msg-Id` dedup 키(옵트인). 스트림
+   *   duplicate window(NATS 기본 2분 — 운영자가 NATS CLI 로 스트림별 조정) 안의 같은 msgID 재발행은
+   *   적재되지 않고 `duplicate: true` 로 반환된다. 비즈니스 멱등키(주문 ID 등)를 권장. 미지정 시
+   *   dedup 없음 — `duplicate` 는 항상 false.
+   * @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
    */
-  async enqueue(JobClass, payload) {
+  async enqueue(JobClass, payload, { msgID } = /** @type {{ msgID?: string }} */ ({})) {
+    if (msgID !== undefined && (typeof msgID !== 'string' || msgID.length === 0)) {
+      throw new TypeError(`MegaJobQueue.enqueue: msgID, if set, must be a non-empty string. Got: ${msgID}.`)
+    }
     await this.ensureStream(JobClass)
     const subject = /** @type {string} */ (JobClass.subject)
     const js = /** @type {import('nats').JetStreamClient} */ (this.#js)
-    const ack = await js.publish(subject, this.#encode(payload))
+    // msgID(옵트인) = JetStream `Nats-Msg-Id` dedup — 스트림 duplicate window(NATS 기본 2분) 안의
+    // 같은 msgID 재발행은 적재되지 않고 ack.duplicate=true 로 돌아온다(producer 중복: 재시도 enqueue·
+    // 이중 클릭 방어). 미지정 시 dedup 없음(기존 동작, 비용 0) — duplicate 는 그때 항상 false.
+    const ack = await js.publish(subject, this.#encode(payload), msgID !== undefined ? { msgID } : undefined)
     // dispatch 는 publish(부작용) 완료 후 발화 — 리스너 throw 가 반환값/흐름을 오염시키지 않게 safeEmit(L-3).
     this.#safeEmit('dispatch', { subject, seq: ack.seq, stream: ack.stream })
     return { seq: ack.seq, stream: ack.stream, duplicate: ack.duplicate }