mega-framework 0.1.7 → 0.1.8

package/src/core/ctx-builder.js

@@ -37,6 +37,9 @@ function passthroughT(key, defaultValue) {
 /** 요청당 ctx 를 캐싱하는 비열거 키. 글로벌 미들웨어와 라우트 핸들러가 같은 ctx 를 공유하도록 한다. */
 const HTTP_CTX_KEY = Symbol('mega.httpCtx')
 
+/** 요청당 lazy ctx 프록시 캐싱 키 — 미들웨어·핸들러가 같은 프록시 객체를 받도록 한다 (ADR-214). */
+const LAZY_CTX_KEY = Symbol('mega.lazyHttpCtx')
+
 /**
  * `ctx.services.<name>` lazy DI proxy (ADR-148) — 요청별 서비스 인스턴스화·캐시.
  *
@@ -252,6 +255,61 @@ export function getHttpCtx({ app, req, reply }) {
   const cached = /** @type {any} */ (req)[HTTP_CTX_KEY]
   if (cached) return cached
   const ctx = buildHttpCtx({ app, req, reply })
-  Object.defineProperty(req, HTTP_CTX_KEY, { value: ctx, enumerable: false, configurable: true })
+  // 심볼 직접 대입 (G1 H-2, ADR-214) — 심볼 키는 어차피 Object.keys/spread/JSON 에 안 잡히므로
+  // 비열거 defineProperty 의 실익이 없고, defineProperty 는 hidden class 전이를 유발해 17배 비싸다(실측).
+  ;/** @type {any} */ (req)[HTTP_CTX_KEY] = ctx
   return ctx
 }
+
+/**
+ * **lazy** HTTP ctx — 실제 ctx 빌드를 첫 속성 접근 시점까지 미루는 요청당 프록시 (G1 H-1, ADR-214).
+ *
+ * hot path 단일 최대 프레임워크 비용이 "핸들러가 ctx 를 안 써도 매 요청 무조건 buildHttpCtx"
+ * (1,615 B + ≈0.7 µs/req, CPU 2.3% — audit-G1 실측)였다. 이 프록시는 생성 비용이 객체 1개 수준이고,
+ * 핸들러·미들웨어가 ctx 의 속성을 **처음 만질 때만** {@link getHttpCtx} 로 실 ctx 를 만든다(이후 캐시).
+ *
+ * 호환성: canonical 시그니처 `(req, reply, ctx)` 는 그대로 — 모든 핸들러가 여전히 3번째 인자를 받고,
+ * 참조하는 순간부터는 기존과 동일한 실 ctx 표면(ADR-134 요청당 공유 포함)이다. 프록시 자체도 요청당
+ * 1개로 캐시되어 미들웨어와 핸들러가 **동일 객체**(`===`)를 받는다. 모든 트랩이 실 ctx 로 위임되므로
+ * `in`/spread/`Object.keys`/getter·setter(`ctx.user=`) 동작이 보존된다.
+ *
+ * @param {object} args
+ * @param {import('./mega-app.js').MegaApp | null} args.app
+ * @param {import('fastify').FastifyRequest} args.req
+ * @param {import('fastify').FastifyReply} args.reply
+ * @returns {Record<string, any>}
+ */
+export function getLazyHttpCtx({ app, req, reply }) {
+  const cached = /** @type {any} */ (req)[LAZY_CTX_KEY]
+  if (cached) return cached
+  /** 첫 트랩에서 실 ctx 를 만들고 이후 재사용 (getHttpCtx 가 req 단위 캐시를 겸한다). */
+  const real = () => getHttpCtx({ app, req, reply })
+  const proxy = new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        return Reflect.get(real(), prop)
+      },
+      set(_t, prop, value) {
+        return Reflect.set(real(), prop, value)
+      },
+      has(_t, prop) {
+        return Reflect.has(real(), prop)
+      },
+      ownKeys() {
+        return Reflect.ownKeys(real())
+      },
+      getOwnPropertyDescriptor(_t, prop) {
+        return Object.getOwnPropertyDescriptor(real(), prop)
+      },
+      defineProperty(_t, prop, desc) {
+        return Reflect.defineProperty(real(), prop, desc)
+      },
+      deleteProperty(_t, prop) {
+        return Reflect.deleteProperty(real(), prop)
+      },
+    },
+  )
+  ;/** @type {any} */ (req)[LAZY_CTX_KEY] = proxy
+  return proxy
+}

package/src/core/envelope.js

@@ -22,13 +22,20 @@ export const REPLY_START_SYMBOL = Symbol('mega.reply.start')
 export const ENVELOPE_MARK = Symbol('mega.envelope')
 
 /**
- * envelope 객체에 비열거 마킹을 부착한다.
+ * envelope 객체에 마킹을 부착한다.
+ *
+ * 심볼 **직접 대입** (G1 M-1, ADR-214) — `Object.defineProperty` 대비 17배 빠르고(136→8 ns/op 실측)
+ * allocation 도 작다. 심볼 키는 어차피 `JSON.stringify`/`Object.keys` 에 안 나오므로 와이어·열거
+ * 동작은 동일하다. 의미 차이는 하나 — spread 복사(`{...env}`)가 마크를 함께 복사한다. 복사본도
+ * "이미 envelope" 로 취급되는데, 이는 이중 wrap 방지(ADR-184)에 오히려 부합한다(복사 후 필드를
+ * 고쳐 재전송하는 패턴도 envelope 그대로 나간다 — 의도된 동작으로 확정, ADR-214).
+ *
  * @template {Record<string, any>} T
  * @param {T} env
  * @returns {T} 같은 객체 (마킹됨).
  */
 function markEnvelope(env) {
-  Object.defineProperty(env, ENVELOPE_MARK, { value: true, enumerable: false })
+  ;/** @type {any} */ (env)[ENVELOPE_MARK] = true
   return env
 }
 

package/src/core/hub-link.js

@@ -189,7 +189,9 @@ export class MegaHubLink {
   /**
    * hub 연결 + REGISTER 핸드셰이크. register_ok 수신 시 resolve.
    *
-   * `retry` 옵션이 있으면 최초 연결도 지수 백오프로 재시도한다(ADR-098). 없으면 단발 시도.
+   * 초기 연결은 retry 유무와 무관하게 **단 1회** 시도한다. `retry` 옵션이 있으면 실패 시 백그라운드
+   * 재연결(지수 백오프)로 전환하고 reject 한다 — 성공 시 RECONNECTED, 소진 시 RECONNECT_FAILED emit.
+   * 호출부(boot)는 reject 를 warn 으로 받고 부팅을 계속한다(허브 다운이 부팅을 막지 않는 계약).
    *
    * @param {Object} [opts]
    * @param {number} [opts.connectTimeoutMs] - register_ok 대기 한도 override(M4). **이 값은 인스턴스에
@@ -214,19 +216,27 @@ export class MegaHubLink {
         throw err
       }
     }
-    // retry 활성 — 최초 연결도 백오프 재시도. AbortError(인증 실패 등) 는 재시도하지 않는다.
-    this._abort = new AbortController()
-    return withRetry(() => this._connectOnce({ connectTimeoutMs: timeout }), {
-      ...this._retry,
-      signal: this._abort.signal,
-      shouldRetry: retryUnlessFatal,
-      onFailedAttempt: (ctx) => {
-        this._log?.warn?.(
-          { bridgeId: this._bridgeId, attempt: ctx.attemptNumber, retriesLeft: ctx.retriesLeft },
-          'hub-link connect attempt failed — backing off',
-        )
-      },
-    })
+    // retry 활성 — 초기 연결은 **단 1회**만 시도하고, 실패하면 백그라운드 재연결로 전환한 뒤 throw 한다.
+    // 예전엔 withRetry 가 최초 연결까지 백오프 전체를 await 해 호출부(boot 의 cluster-transport step)가
+    // 분 단위로 블로킹됐다(crud retry 기준 약 4.7분) — "허브 다운이어도 boot 를 막지 않는다" 는 호출부
+    // 계약과 정반대 동작. 이제 호출부는 즉시 실패를 보고(warn) 부팅을 계속하고, 백그라운드 _reconnect 가
+    // 같은 retry 백오프로 재시도한다 — 성공 시 RECONNECTED 이벤트가 presence 재동기화를 트리거하고,
+    // 소진 시 RECONNECT_FAILED 를 emit 한다. 치명 에러(인증 거부 등 fatal)는 재시도 무의미라 그대로 전파.
+    try {
+      return await this._connectOnce({ connectTimeoutMs: timeout })
+    } catch (err) {
+      // 레거시 hub 폴백(1회) — protocolVersion 필드 거부 판정 후 v1 register 로 즉시 재시도.
+      if (err instanceof Error && err.message === 'hub.legacy_register_fallback') {
+        try {
+          return await this._connectOnce({ connectTimeoutMs: timeout })
+        } catch (err2) {
+          if (retryUnlessFatal({ error: err2 })) void this._reconnect()
+          throw err2
+        }
+      }
+      if (retryUnlessFatal({ error: err })) void this._reconnect()
+      throw err
+    }
   }
 
   /**

package/src/core/index.js

@@ -16,7 +16,7 @@ export { buildErrorHandler } from './error-mapper.js'
 export { ajvErrorToValidationError, MAX_VALIDATION_DETAILS } from './ajv-mapper.js'
 export { loadAndValidateConfig } from './config-loader.js'
 // 요청 ctx 빌더 — db/cache/bus 접근자 배선 (ADR-102)
-export { buildHttpCtx, getHttpCtx, buildAdapterAccessors } from './ctx-builder.js'
+export { buildHttpCtx, getHttpCtx, getLazyHttpCtx, buildAdapterAccessors } from './ctx-builder.js'
 // WS envelope + 컨트롤러 베이스 (ADR-015 / ADR-074)
 export {
   createWsMessage,

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)')
     }
   }
 }