mega-framework 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-framework",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {

package/sample/crud/yarn.lock

@@ -1234,7 +1234,7 @@ marked@^18.0.5:
   integrity sha512-S6GcvALHg6K4ohtu4E7x0a1AqhAjp6cV8KhLSyN9qVapnzJkusVBxZRcIU9AeYsbe6P1hKDusSbEOzGyyuce6w==
 
 "mega-framework@file:../..":
-  version "0.1.2"
+  version "0.1.4"
   dependencies:
     "@fastify/cookie" "^11.0.2"
     "@fastify/cors" "^11.2.0"

package/src/adapters/file-adapter.js

@@ -6,6 +6,11 @@
  * 같은 `get/set/del/has` API 를 로컬 파일로 만족시킨다 — driver 키 한 줄만 바꿔 환경 전환(ADR-082).
  * **신규 의존성 0** (`node:fs/promises`/`node:path`/`node:crypto` 표준만).
  *
+ * ⚠️ **만료 파일 능동 정리 없음(디스크 증가 주의)**: 만료 envelope 은 **재접근(get/has) 시에만 lazy 삭제**된다.
+ * set 후 다시 조회되지 않는 만료 키는 파일로 영구 잔존하므로, **짧은 TTL + 높은 키 카디널리티**(요청별 캐시 키
+ * 등) 워크로드에선 디스크/inode 가 누적될 수 있다. 그래서 file 캐시는 **dev / 단일·단명 인스턴스 권장**이며,
+ * 프로덕션 장기 구동에는 redis 캐시 또는 외부 정리(cron unlink)를 전제로 한다(능동 sweep 은 후속 과제).
+ *
  * # 표준 표면 (MegaCacheAdapter 상속)
  *   - `_connect()`   — `fs.mkdir(basePath, { recursive: true })` 로 디렉토리 보장.
  *   - `_disconnect()`— no-op (파일시스템은 close 개념 없음).

package/src/adapters/mega-cache-adapter.js

@@ -3,8 +3,12 @@
  * MegaCacheAdapter — key-value 캐시 표준 인터페이스 (추상, 08-class-specs §3.4).
  *
  * `ctx.cache(key)` 가 본 베이스 인스턴스를 반환. 구체: `MegaRedisAdapter` /
- * `MegaFileAdapter` (ADR-082). 사용자 `key` 에 자동 prefix
- * `mega:cache:<appName>:<key>` 가 코어에서 부착됨 (ADR-064).
+ * `MegaFileAdapter` (ADR-082).
+ *
+ * ⚠️ **키 네임스페이스(ADR-064)**: ADR-064 가 `mega:cache:<appName>:<key>` 자동 prefix 를 *결정*했으나
+ * **현재 코어에 미구현**이다(get/set/del 이 raw `key` 를 그대로 사용). 멀티앱이 같은 redis 를 공유하면
+ * 키 충돌 위험이 있으니, **현재는 사용자가 키에 앱별 네임스페이스를 직접 붙여야 한다**. 자동 prefix 구현은
+ * 후속 과제(ADR-064 open). 단일앱(현 sample)에선 무관.
  *
  * @module adapters/mega-cache-adapter
  */

package/src/adapters/nats-adapter.js

@@ -295,11 +295,16 @@ export class MegaNatsAdapter extends MegaBusAdapter {
    * 잡 처리 등록 — **queue group** 구독(같은 queue 구독자끼리 load-balance). 기본 queue 이름은 jobName
    * (같은 잡의 모든 워커가 한 그룹).
    *
+   * ⚠️ **전달 보장 = at-most-once(비영속, H5)**: 이건 **core NATS** queue group 이라 메시지가 디스크에
+   * 남지 않는다 — 구독자가 없거나 처리 중 죽으면 그 메시지는 **유실**된다(재시도·DLQ 없음). 유실이
+   * 치명적이거나 영속 큐/재시도/DLQ 가 필요하면 **`MegaJobQueue`(JetStream, at-least-once, ADR-028/112)**
+   * 를 쓴다. `ctx.bus(x).process` 와 `mega worker`(JetStream) 는 **전달 보장이 다르므로 혼용 금지**.
+   *
    * **subscription 핸들을 반환하지 않는 건 의도적**(L-2): worker 는 앱 수명 동안 상주하는 것이
    * 정상이고(개별 잡 처리 등록을 런타임에 떼었다 붙였다 하는 패턴은 비표준), 정리는 disconnect 시
    * `_disconnect()` 의 `nc.drain()` 이 **모든 구독을 일괄 비우며** 처리한다. 개별 unsubscribe 가
    * 필요한 일시 구독은 `subscribe()`(핸들 반환)를 쓴다 — `process` 는 fire-and-forget `enqueue` 와
-   * 대칭인 상주 worker 용이다. 영속 큐/재시도/DLQ 가 필요하면 `MegaJob`(jetstream, ADR-028).
+   * 대칭인 상주 worker 용이다.
    *
    * @param {string} jobName
    * @param {(payload: any) => any} handler

package/src/cli/commands/console-cmd.js

@@ -30,7 +30,7 @@ function defaultReplFactory() {
  * @param {(msg: string) => void} [deps.out]
  * @param {() => (Promise<void> | void)} [deps.shutdown] - 주입용(테스트). REPL 종료 시 호출하는 graceful
  *   shutdown 트리거. 기본 {@link MegaShutdown.now}(등록 hook 실행 후 process.exit).
- * @param {(opts: { signals?: string[] }) => void} [deps.setupSignals] - 주입용(테스트). 시그널 핸들러 등록.
+ * @param {(opts: { signals?: string[], globalErrorHandlers?: boolean }) => void} [deps.setupSignals] - 주입용(테스트). 시그널 핸들러 등록.
  *   기본 {@link MegaShutdown.setupSignals}.
  * @returns {Promise<{ ctx: Record<string, any>, config: object, server: { context: Record<string, any> } }>}
  */
@@ -44,7 +44,9 @@ export async function startConsole(
   // 두면 REPL 종료 후에도 열린 핸들(DB 풀·redis·wsHub listen)로 프로세스가 행하고 어댑터가 미정리된다.
   // 따라서 SIGTERM 은 graceful shutdown 으로 받는다. SIGINT 은 REPL 이 소유(빈 줄 클리어 / 이중 입력 시
   // 'exit')하므로 가로채지 않는다 — 가로채면 한 번의 Ctrl-C 가 콘솔을 죽인다(ADR-167).
-  setupSignals({ signals: ['SIGTERM'] })
+  // REPL 은 전역 에러 핸들러를 끈다(globalErrorHandlers:false) — 대화형에서 사용자 코드 예외가
+  // 프로세스를 graceful shutdown 시키면 안 되고, REPL 자체 에러 복구를 방해하지 않기 위함(ADR-178).
+  setupSignals({ signals: ['SIGTERM'], globalErrorHandlers: false })
   const server = replFactory()
   Object.assign(server.context, { ctx, config: global, mega: { config: global, host } })
   // REPL 종료(.exit / Ctrl-D / 이중 Ctrl-C)는 'exit' 이벤트로 온다 — 이때 graceful shutdown 으로 어댑터 등을

package/src/cli/commands/new.js

@@ -1,26 +1,94 @@
 // @ts-check
 /**
- * `mega new <project>` — 빈 폴더에서 멀티앱 hello world 까지 한 명령 스캐폴드 (roadmap §336, ADR-142).
+ * `mega new <project>` — `sample/crud` 데모앱을 그대로 스캐폴드한다(ADR-179, 기존 미니멀/--views 모드 대체).
  *
- * 기본 앱 `main` + `*.localhost` 호스트 + README · `.env.example` · `.gitignore` · `package.json`
- * (scripts + concurrently devDep + PM2 `ecosystem.config.cjs`) 를 만든다. `ejsMate` 옵트인이면 EJS +
- * ejs-mate 뷰 골격(ADR-011/136) + i18next 다국어(ADR-037~039) + Bootstrap 5 디자인(ADR-151)을 더한다 —
- * 뷰 렌더 라우트, ko/en 로케일, 그리고 토큰 치환 없이 그대로 복사하는 정적 자산(vendored Bootstrap +
- * 브랜드 CSS/JS). 신규 dep 설치는 하지 않고(네트워크 회피) 안내만 출력한다.
+ * 빈 폴더에 14개 기능(auth·notes/users CRUD·WS 채팅·jobs·cron·metrics·logs·perf·redis·tracing·upload·
+ * worker·guide)을 모두 갖춘 멀티앱 데모를 찍어낸다. 원본은 레포의 `sample/crud`(npm `files` 에 포함돼
+ * 패키지에도 동봉) 트리를 **바이트 그대로 복사**하고, 프로젝트 이름이 박힌 소수 파일(package.json·README·
+ * ecosystem·.env)만 토큰 치환한다 — `sample-crud` → 프로젝트명, dep `file:../..` → 실제 버전(`^x.y.z`).
+ * 로컬 인프라 기동용 루트 `docker-compose.yml` 도 함께 복사한다(개발자 학습용, ADR-103).
+ *
+ * 복사 제외: 빌드 산출물(node_modules·coverage)·로크파일(package-lock/yarn.lock)·런타임 로그(*.log)·VCS,
+ * 그리고 런타임 업로드 데이터(`var/uploads/*` — 개인정보 포함 가능). 업로드 데모가 쓰는 디렉토리는
+ * 빈 `.gitkeep` 으로만 만든다. 신규 dep 설치는 하지 않고(네트워크 회피) 안내만 출력한다.
  *
  * @module cli/commands/new
  */
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { nameVariants, renderTemplate } from '../template-engine.js'
+import { nameVariants } from '../template-engine.js'
+
+/** 이 파일이 있는 디렉토리(src/cli/commands). 아래 원본 경로의 기준점. */
+const HERE = dirname(fileURLToPath(import.meta.url))
+/** 스캐폴드 원본 = 레포의 `sample/crud` 데모앱(src/cli/commands 기준 3단계 위 + sample/crud). */
+const SAMPLE_ROOT = resolve(HERE, '../../../sample/crud')
+/** 루트 `docker-compose.yml` — 로컬 인프라(postgres·mariadb·mongo·redis·nats·zipkin·otel) 기동용. */
+const COMPOSE_SRC = resolve(HERE, '../../../docker-compose.yml')
+/** 프레임워크 자체 package.json — 스캐폴드 dep 버전 핀(`^x.y.z`) 의 소스. */
+const FRAMEWORK_PKG = resolve(HERE, '../../../package.json')
+
+/** 복사 제외 디렉토리/파일 basename — 빌드 산출물·로크파일·VCS·런타임 데이터 디렉토리. */
+const EXCLUDE_NAMES = new Set([
+  'node_modules',
+  '.git',
+  'coverage',
+  '.nyc_output',
+  '.vitest',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  '.DS_Store',
+])
+/** 복사 제외 상대경로 prefix — 런타임 업로드 산출물(개인정보 포함 가능, 대신 .gitkeep 만 생성). */
+const EXCLUDE_PREFIXES = ['var/uploads']
+/** 프로젝트 이름 토큰 치환을 적용할 텍스트 파일(그 외는 바이트 그대로 복사 — 바이너리 보존). */
+const TRANSFORM_FILES = new Set(['package.json', 'README.md', 'ecosystem.config.cjs', '.env', '.env.example'])
+
+/**
+ * 한 상대경로가 복사 제외 대상인지.
+ * @param {string} rel - POSIX 슬래시 상대경로.
+ * @returns {boolean}
+ */
+function isExcluded(rel) {
+  if (rel.endsWith('.log')) return true
+  if (EXCLUDE_PREFIXES.some((p) => rel === p || rel.startsWith(`${p}/`))) return true
+  return rel.split('/').some((seg) => EXCLUDE_NAMES.has(seg))
+}
 
-/** templates/project 루트. src/cli/commands/new.js 기준 3단계 위 + templates/project. */
-const PROJECT_TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), '../../../templates/project')
+/**
+ * 디렉토리를 재귀 순회해 복사 대상 파일의 상대경로(POSIX 슬래시) 목록을 만든다. 제외 디렉토리는
+ * 통째로 건너뛴다(node_modules 등 큰 트리 순회 비용 회피).
+ * @param {string} dir - 현재 순회 디렉토리(절대).
+ * @param {string} base - 상대경로 기준 루트(절대).
+ * @param {string[]} acc - 누적 결과.
+ * @returns {string[]}
+ */
+function walk(dir, base, acc) {
+  for (const ent of readdirSync(dir, { withFileTypes: true })) {
+    const abs = join(dir, ent.name)
+    const rel = relative(base, abs).split(sep).join('/')
+    if (isExcluded(rel)) continue
+    if (ent.isDirectory()) walk(abs, base, acc)
+    else acc.push(rel)
+  }
+  return acc
+}
 
-/** 프로젝트 템플릿을 읽어 토큰 치환. @param {string} file @param {Record<string,string>} vars @returns {string} */
-function renderProject(file, vars) {
-  return renderTemplate(readFileSync(join(PROJECT_TEMPLATES, file), 'utf8'), vars)
+/**
+ * 토큰 치환 — `sample-crud` 를 프로젝트명으로, package.json 의 모노레포 dep(`file:../..`)을 실제 버전으로.
+ * @param {string} rel - 파일 상대경로.
+ * @param {string} content - 원본 텍스트.
+ * @param {{ name: string, version: string }} vars
+ * @returns {string}
+ */
+function transformText(rel, content, vars) {
+  let out = content.replaceAll('sample-crud', vars.name)
+  if (rel === 'package.json') {
+    // 모노레포 로컬 링크 → 퍼블리시된 프레임워크 버전 핀. 스캐폴드된 프로젝트는 독립 패키지라 file: 가 안 풀린다.
+    out = out.replace('"file:../.."', `"^${vars.version}"`)
+  }
+  return out
 }
 
 /**
@@ -28,74 +96,54 @@ function renderProject(file, vars) {
  * @param {string} targetDir - 프로젝트 루트 절대/상대 경로.
  * @param {object} [opts]
  * @param {string} [opts.name] - 프로젝트 이름(기본: targetDir 의 마지막 세그먼트).
- * @param {boolean} [opts.ejsMate] - EJS + ejs-mate 뷰 골격 포함(기본 false).
  * @param {boolean} [opts.force] - 기존 파일 덮어쓰기(기본 false — 건너뜀).
  * @returns {{ root: string, written: string[], skipped: string[] }}
  */
-export function scaffoldProject(targetDir, { name, ejsMate = false, force = false } = {}) {
+export function scaffoldProject(targetDir, { name, force = false } = {}) {
   const root = resolve(targetDir)
   const projectName = nameVariants(name ?? root.split(/[/\\]/).pop() ?? 'mega-app').kebab
-  const vars = { name: projectName, Name: nameVariants(projectName).pascal }
-
-  // 뷰 옵트인이면 GET / 를 뷰 렌더로 바꾸고(JSON hello 대신) 그에 맞는 테스트를 쓴다.
-  /** @type {Array<{ rel: string, tpl: string }>} */
-  const files = [
-    { rel: 'mega.config.js', tpl: 'mega.config.tpl' },
-    { rel: 'apps/main/app.config.js', tpl: ejsMate ? 'app.config.views.tpl' : 'app.config.tpl' },
-    { rel: 'apps/main/routes/index.js', tpl: ejsMate ? 'route.views.tpl' : 'route.tpl' },
-    { rel: 'test/apps/main/index.test.js', tpl: ejsMate ? 'route.test.views.tpl' : 'route.test.tpl' },
-    { rel: 'package.json', tpl: 'package.tpl' },
-    { rel: 'README.md', tpl: 'readme.tpl' },
-    { rel: '.env.example', tpl: 'env.tpl' },
-    { rel: '.gitignore', tpl: 'gitignore.tpl' },
-    { rel: 'vitest.config.js', tpl: 'vitest.config.tpl' },
-    { rel: 'ecosystem.config.cjs', tpl: 'ecosystem.config.tpl' },
-  ]
-  if (ejsMate) {
-    files.push(
-      { rel: 'apps/main/views/layouts/main.ejs', tpl: 'views/layout.ejs.tpl' },
-      { rel: 'apps/main/views/index.ejs', tpl: 'views/index.ejs.tpl' },
-      { rel: 'apps/main/locales/server/ko.json', tpl: 'locales/server/ko.json.tpl' },
-      { rel: 'apps/main/locales/server/en.json', tpl: 'locales/server/en.json.tpl' },
-      { rel: 'apps/main/locales/client/ko.json', tpl: 'locales/client/ko.json.tpl' },
-      { rel: 'apps/main/locales/client/en.json', tpl: 'locales/client/en.json.tpl' },
-    )
-  }
-
-  // 정적 자산 — 토큰 치환 없이 바이트 그대로 복사한다(vendored Bootstrap 5 min 번들 + 브랜드 CSS/JS).
-  // 이들은 템플릿이 아니라 정적 파일이므로 renderTemplate(`{{token}}`)을 거치지 않는다.
-  /** @type {Array<{ rel: string, src: string }>} */
-  const assets = ejsMate
-    ? [
-        { rel: 'apps/main/public/vendor/bootstrap/bootstrap.min.css', src: 'public/vendor/bootstrap/bootstrap.min.css' },
-        { rel: 'apps/main/public/vendor/bootstrap/bootstrap.bundle.min.js', src: 'public/vendor/bootstrap/bootstrap.bundle.min.js' },
-        { rel: 'apps/main/public/css/app.css', src: 'public/css/app.css' },
-        { rel: 'apps/main/public/js/app.js', src: 'public/js/app.js' },
-        { rel: 'apps/main/public/js/theme-init.js', src: 'public/js/theme-init.js' },
-      ]
-    : []
+  /** @type {string} */
+  const version = JSON.parse(readFileSync(FRAMEWORK_PKG, 'utf8')).version
+  const vars = { name: projectName, version }
 
   /** @type {string[]} */ const written = []
   /** @type {string[]} */ const skipped = []
-  for (const { rel, tpl } of files) {
-    const out = join(root, rel)
+
+  /**
+   * 출력 파일 1개를 기록(존재 + !force 면 skip).
+   * @param {string} out - 출력 절대경로.
+   * @param {() => void} write - 실제 기록 동작.
+   */
+  const emit = (out, write) => {
     if (existsSync(out) && !force) {
       skipped.push(out)
-      continue
+      return
     }
     mkdirSync(dirname(out), { recursive: true })
-    writeFileSync(out, renderProject(tpl, vars))
+    write()
     written.push(out)
   }
-  for (const { rel, src } of assets) {
+
+  // 1) sample/crud 트리 복사(제외 규칙 적용). 토큰 치환 대상만 텍스트로 렌더, 그 외는 바이트 그대로.
+  for (const rel of walk(SAMPLE_ROOT, SAMPLE_ROOT, [])) {
+    const src = join(SAMPLE_ROOT, rel)
     const out = join(root, rel)
-    if (existsSync(out) && !force) {
-      skipped.push(out)
-      continue
-    }
-    mkdirSync(dirname(out), { recursive: true })
-    copyFileSync(join(PROJECT_TEMPLATES, src), out)
-    written.push(out)
+    emit(out, () => {
+      if (TRANSFORM_FILES.has(rel)) {
+        writeFileSync(out, transformText(rel, readFileSync(src, 'utf8'), vars))
+      } else {
+        copyFileSync(src, out)
+      }
+    })
   }
+
+  // 2) 루트 docker-compose.yml — 로컬 인프라(개발자 학습용). 프로젝트 이름과 무관해 그대로 복사.
+  const compose = join(root, 'docker-compose.yml')
+  emit(compose, () => copyFileSync(COMPOSE_SRC, compose))
+
+  // 3) 업로드 데모가 쓰는 디렉토리 placeholder — 실제 업로드 데이터(개인정보 PDF 등)는 동봉하지 않는다.
+  const gitkeep = join(root, 'var/uploads/.gitkeep')
+  emit(gitkeep, () => writeFileSync(gitkeep, ''))
+
   return { root, written, skipped }
 }

package/src/cli/commands/scaffold.js

@@ -7,7 +7,6 @@
  * @module cli/commands/scaffold
  */
 import { Command } from 'commander'
-import prompts from 'prompts'
 import { generate, GENERATOR_KINDS } from '../generators/index.js'
 import { scaffoldProject } from './new.js'
 import { runRoutesCommand } from './routes.js'
@@ -50,21 +49,16 @@ export async function runScaffoldCommand(argv, { out, err, projectRoot, logger }
 
   program
     .command('new <project>')
-    .description('빈 폴더에서 멀티앱 hello world 스캐폴드')
-    .option('--views', 'EJS + ejs-mate 뷰 골격 포함')
+    .description('sample/crud 데모앱(14기능) 전체를 빈 폴더에 스캐폴드')
     .option('--force', '기존 파일 덮어쓰기')
-    .action(async (/** @type {string} */ project, /** @type {any} */ opts) => {
-      // --views 미지정 + 대화형 터미널이면 ejs-mate 옵트인을 묻는다(비-TTY/CI 는 기본 false).
-      let ejsMate = opts.views === true
-      if (opts.views === undefined && process.stdin.isTTY) {
-        const ans = /** @type {any} */ (await prompts({ type: 'confirm', name: 'views', message: 'EJS + ejs-mate 뷰 골격을 포함할까요?', initial: false }))
-        ejsMate = ans.views === true
-      }
+    .action((/** @type {string} */ project, /** @type {any} */ opts) => {
       const target = project === '.' ? projectRoot : `${projectRoot}/${project}`
-      const r = scaffoldProject(target, { name: project === '.' ? undefined : project, ejsMate, force: opts.force === true })
+      const r = scaffoldProject(target, { name: project === '.' ? undefined : project, force: opts.force === true })
       out(`mega: scaffolded project at ${r.root}`)
       reportFiles(out, r, r.root)
-      out('\n다음 단계:\n  cd ' + project + '\n  npm install\n  npm run dev')
+      // 풀 데모는 로컬 인프라(postgres·redis·mongo·nats)가 있어야 부팅된다 — docker compose 로 띄운 뒤 마이그레이션.
+      const cd = project === '.' ? '' : `  cd ${project}\n`
+      out(`\n다음 단계:\n${cd}  npm install\n  docker compose up -d        # 로컬 인프라 기동(postgres·redis·mongo·nats)\n  npm run migrate             # DB 스키마 생성\n  npm run dev                 # 개발 서버`)
     })
 
   program

package/src/cli/index.js

@@ -45,7 +45,7 @@ Usage:
   mega migrate [--db KEY] [--root DIR]             pending 마이그레이션 일괄 적용(up)
   mega migrate:down [--db KEY]                      마지막 적용 마이그레이션 1개 롤백(down)
   mega migrate:status [--db KEY]                    적용/미적용 마이그레이션 목록
-  mega new <project> [--views] [--force]           빈 폴더에서 멀티앱 hello world 스캐폴드
+  mega new <project> [--force]                     sample/crud 데모앱(14기능) 전체를 스캐폴드
   mega g <kind> <name> [--app A] [--version vN]    코드+테스트 생성 (별칭: generate)
                        [--kind K] [--lng L] [--force]
   mega routes [--root DIR]                          등록 라우트 트리 출력

package/src/core/mega-app.js

@@ -968,9 +968,9 @@ export class MegaApp {
     }
     // redis(cluster-wide) — 다른 워커/허브의 세션까지.
     if (this._wsRoster) {
-      for (const ch of want) {
-        for (const m of await this._wsRoster.list(ch)) if (!out.has(m.sessionId)) out.set(m.sessionId, m)
-      }
+      // 여러 채널 redis 조회를 **병렬화**(Promise.all) — onConnect 핫패스의 직렬 라운드트립 누적 제거(Med).
+      const lists = await Promise.all([...want].map((ch) => this._wsRoster.list(ch)))
+      for (const list of lists) for (const m of list) if (!out.has(m.sessionId)) out.set(m.sessionId, m)
     }
     return [...out.values()]
   }
@@ -1259,6 +1259,14 @@ export class MegaApp {
       this._hubBridgeId = null
       MegaShutdown.unregister(`mega-hublink:${this.name}`)
     }
+    // NATS 클러스터 정리(ADR-176) — 구독·heartbeat/sweep 타이머·roster 멤버 해제. boot 의 shutdown hook 과
+    // **양쪽**에서 정리해야 시그널을 안 거치는 종료(server.close()/프로그램적 재시작/멀티앱 부분 종료)에서도
+    // 누수가 없다(_hubLink/_wsRoster 와 동일 대칭, H1). stop() 은 _isStarted 가드로 멱등이라 중복 안전.
+    if (this._wsCluster) {
+      await this._wsCluster.stop().catch((err) => this.fastify.log?.warn?.({ err, app: this.name }, 'ws-cluster stop failed'))
+      this._wsCluster = null
+      MegaShutdown.unregister(`mega-ws-cluster:${this.name}`)
+    }
     // redis roster 정리(ADR-177) — heartbeat 중지 + 로컬 멤버 즉시 제거. _sessionConns 를 비우기 **전에**
     // 호출해야 stop() 이 localRosterMembers 로 자기 멤버를 redis 에서 뺄 수 있다.
     if (this._wsRoster) {

package/src/core/mega-cluster.js

@@ -50,10 +50,16 @@ export class MegaCluster {
     /** @type {(() => Promise<void>) | null} */
     this._workerFn = null
 
-    // M1 — respawn backoff (crash-loop 보호)
-    this._respawnTooFast = 0          // 빠른 연속 crash 카운터
-    this._maxRapidRespawn = 5         // 5번 연속 너무 빨리 crash 하면 중단
-    this._minRespawnIntervalMs = 1000 // 1초 이내 crash 는 "너무 빠름"
+    // M1 — respawn backoff (crash-loop 보호). 멀티워커 정확성: 전역 카운터 + 정상종료-리셋은 한 워커의
+    // 정상 종료가 다른 워커들의 누적 빠른-crash 카운트를 통째로 지워 crash-loop 를 마스킹한다. 그래서
+    // **빠른 crash 타임스탬프의 슬라이딩 윈도우**로 판정한다(윈도우 내 N회 → 포기). 정상 종료는 카운트에
+    // 기여하지 않고, 오래된 빠른-crash 는 윈도우에서 자연 소거된다(안정화되면 자동 리셋).
+    this._maxRapidRespawn = 5         // 윈도우 내 5번 빠른 crash 면 중단
+    this._minRespawnIntervalMs = 1000 // 이 lifetime 미만 crash 는 "너무 빠름"
+    /** @type {number[]} 윈도우 내 빠른-crash 타임스탬프(ms). */
+    this._rapidCrashTimes = []
+    /** @type {ReturnType<typeof setTimeout>|null} SIGTERM grace 강제-kill 타이머(전원 정상종료 시 취소). */
+    this._graceTimer = null
   }
 
   /**
@@ -103,13 +109,15 @@ export class MegaCluster {
       this._shuttingDown = true
       console.log(`[mega-cluster] received ${sig}, broadcasting shutdown to ${this._workers.size} workers (grace ${this._gracePeriodMs}ms)`)
       this._broadcastShutdown()
-      // grace 초과 시 강제 kill
-      setTimeout(() => {
+      // grace 초과 시 강제 kill. 핸들을 보관해 전원 정상종료(exit 핸들러) 시 취소 — 정상 종료가 이 타이머의
+      // exit(1) 과 경합해 exit code 가 흔들리지 않게 한다(k8s/systemd 종료 판정 노이즈 제거).
+      this._graceTimer = setTimeout(() => {
         for (const w of this._workers) {
           try { w.kill('SIGKILL') } catch (err) { console.warn('[mega-cluster] SIGKILL failed:', err.message) }
         }
         this._proc.exit(1)
-      }, this._gracePeriodMs).unref()
+      }, this._gracePeriodMs)
+      this._graceTimer.unref()
     }
     this._proc.on('SIGTERM', () => onSignal('SIGTERM'))
     this._proc.on('SIGINT', () => onSignal('SIGINT'))
@@ -124,33 +132,35 @@ export class MegaCluster {
       this._workers.delete(worker)
       if (this._shuttingDown) {
         if (this._workers.size === 0) {
+          if (this._graceTimer) clearTimeout(this._graceTimer) // 전원 정상종료 — 강제-kill 타이머 취소(exit code 경합 제거).
+          this._graceTimer = null
           console.log('[mega-cluster] all workers exited, primary exiting 0')
           this._proc.exit(0)
         }
         return
       }
       if (this._respawn) {
-        // M1 — respawn backoff: 너무 빨리 연속 crash 하면 crash-loop 으로 보고 respawn 중단.
+        // M1 — respawn backoff: 빠른 crash 의 슬라이딩 윈도우로 crash-loop 판정(멀티워커 정확).
         const now = Date.now()
         const lastBirth = worker._megaBirthAt ?? now
         const lifetimeMs = now - lastBirth
+        // 윈도우 = maxRapidRespawn 회의 빠른 재시작이 걸릴 시간 + 여유. 이보다 오래된 빠른-crash 는 소거.
+        const windowMs = this._minRespawnIntervalMs * this._maxRapidRespawn * 2
+        this._rapidCrashTimes = this._rapidCrashTimes.filter((t) => now - t < windowMs)
         if (lifetimeMs < this._minRespawnIntervalMs) {
-          this._respawnTooFast += 1
-          if (this._respawnTooFast >= this._maxRapidRespawn) {
-            // H-1 — crash-loop 포기 시 그냥 return 하면 이벤트루프가 비어 exit 0(성공)으로
-            //   보인다 → systemd/k8s 가 "정상 종료" 로 판단해 재시작 안 함.
-            //   명시적 exit 1 로 "비정상 종료" 를 외부 supervisor 에 알려 재시작을 유도한다.
+          this._rapidCrashTimes.push(now) // 빠른 crash 만 윈도우에 기록(정상 lifetime 은 기여 X).
+          if (this._rapidCrashTimes.length >= this._maxRapidRespawn) {
+            // H-1 — crash-loop 포기 시 그냥 return 하면 이벤트루프가 비어 exit 0(성공)으로 보인다 →
+            //   systemd/k8s 가 "정상 종료" 로 오판. 명시적 exit 1 로 비정상 종료를 알려 재시작을 유도한다.
             console.error(
-              `[mega-cluster] rapid crash-loop detected (${this._respawnTooFast} restarts within ${this._minRespawnIntervalMs}ms), giving up — exiting 1. Last exit: code=${code}, signal=${signal}.`,
+              `[mega-cluster] rapid crash-loop detected (${this._rapidCrashTimes.length} rapid crashes within ${windowMs}ms), giving up — exiting 1. Last exit: code=${code}, signal=${signal}.`,
             )
             this._proc.exit(1)
             return   // 실 process.exit 은 즉시 종료하나, 주입된 fake 는 계속 실행되므로 명시적 중단
           }
-        } else {
-          this._respawnTooFast = 0   // 정상 lifetime 이면 카운터 reset
         }
         console.warn(
-          `[mega-cluster] worker ${worker.process.pid} died (code=${code}, signal=${signal}, lifetime=${lifetimeMs}ms), respawning (rapid-crash-count=${this._respawnTooFast}/${this._maxRapidRespawn})`,
+          `[mega-cluster] worker ${worker.process.pid} died (code=${code}, signal=${signal}, lifetime=${lifetimeMs}ms), respawning (rapid-crashes=${this._rapidCrashTimes.length}/${this._maxRapidRespawn} in ${windowMs}ms)`,
         )
         this._forkWorker()
       } else {

package/src/core/ws-upgrade.js

@@ -46,6 +46,12 @@ export const CLOSE_CODE_DECRYPT_FAILED = 4500
  */
 export const CLOSE_CODE_INTERNAL_ERROR = 1011
 
+/** 느린 소비자 백프레셔 close code (RFC 6455 §7.4.1 표준 1013 "Try Again Later", Med). */
+export const CLOSE_CODE_SLOW_CONSUMER = 1013
+
+/** send 버퍼(bufferedAmount) 기본 상한(바이트). 초과 = 소비자가 ack 를 못 따라옴 → 연결 종료(서버 OOM 방지). */
+export const DEFAULT_MAX_BUFFERED_BYTES = 16 * 1024 * 1024
+
 /**
  * WS 프레임 코덱 — 평문/암호 와이어 변환을 추상화한다.
  * @typedef {Object} WsFrameCodec
@@ -93,11 +99,13 @@ export class MegaWsConnection {
   /**
    * @param {import('ws').WebSocket} rawSocket
    * @param {WsFrameCodec} codec
-   * @param {{ id?: string, ns?: string, path: string }} meta
+   * @param {{ id?: string, ns?: string, path: string, maxBufferedBytes?: number }} meta
    */
   constructor(rawSocket, codec, meta) {
     /** @type {import('ws').WebSocket} */
     this._raw = rawSocket
+    /** @type {number} send 버퍼 상한(바이트) — 초과 시 느린 소비자로 보고 연결 종료(백프레셔). */
+    this._maxBufferedBytes = Number.isFinite(meta.maxBufferedBytes) ? /** @type {number} */ (meta.maxBufferedBytes) : DEFAULT_MAX_BUFFERED_BYTES
     /** @type {WsFrameCodec} */
     this._codec = codec
     /** @type {string} 연결 식별자 (ULID). */
@@ -136,6 +144,16 @@ export class MegaWsConnection {
    * @returns {void}
    */
   send(fields) {
+    // 백프레셔 가드(Med): 송신 버퍼가 상한을 넘으면 소비자가 ack 를 못 따라오는 것 → 더 쌓지 않고 연결을
+    // 종료한다(느린 소비자 몇 개가 fan-out 으로 서버 힙을 무한 적재→OOM 시키는 것 방지). close code 1013.
+    if (this._raw.bufferedAmount > this._maxBufferedBytes) {
+      try {
+        this._raw.close(CLOSE_CODE_SLOW_CONSUMER, 'backpressure: send buffer exceeded')
+      } catch {
+        // 이미 닫히는 중이면 close 는 무의미 — 무시(비치명적, 다음 send 는 isOpen 가드로 걸러짐).
+      }
+      return
+    }
     // ns 자동 주입 (L1): 명시 안 됐고 연결 ns 가 있으면 채운다. 명시값은 덮어쓰지 않음.
     const withNs = fields.ns === undefined && this.ns !== undefined ? { ...fields, ns: this.ns } : fields
     const env = createWsMessage(withNs)

package/src/lib/asp/nonce-cache.js

@@ -22,6 +22,9 @@ const NONCE_KEY_PREFIX = 'asp:nonce:'
 /** 기본 TTL — drift 윈도우(±60s) 의 2배 (ADR-058: EX 120). */
 const DEFAULT_TTL_SEC = 120
 
+/** in-memory nonce store 의 lazy sweep 주기 — insert 이 이 횟수만큼 누적되면 만료 일괄 제거(Med). */
+const SWEEP_EVERY_OPS = 500
+
 /**
  * MegaAspNonceCache — nonce SETNX 래퍼.
  */
@@ -62,6 +65,8 @@ export class MegaMemoryNonceStore {
   constructor() {
     /** @type {Map<string, number>} key → 만료 epoch ms */
     this._store = new Map()
+    /** @type {number} 마지막 sweep 이후 insert 횟수 — SWEEP_EVERY_OPS 마다 만료 일괄 제거. */
+    this._opsSinceSweep = 0
   }
 
   /**
@@ -71,6 +76,13 @@ export class MegaMemoryNonceStore {
    */
   async setIfNotExists(key, ttlSec) {
     const now = Date.now()
+    // lazy 주기 sweep(Med) — setIfNotExists 가 키 단건만 만료 갱신하므로, 다시 안 들어오는 nonce 는 영구
+    // 잔존(메모리 릭)한다. 타이머 없이 insert 누적이 임계를 넘을 때마다 만료를 일괄 제거해 Map 을 bound 한다
+    // (타이머 lifecycle/dispose 불필요 → 안전). 활성(미만료) nonce 는 TTL 로 자연 bound.
+    if (++this._opsSinceSweep >= SWEEP_EVERY_OPS) {
+      this.evictExpired(now)
+      this._opsSinceSweep = 0
+    }
     const exp = this._store.get(key)
     if (exp !== undefined && exp > now) return false
     this._store.set(key, now + ttlSec * 1000)

package/src/lib/logger/telegram-core.js

@@ -76,16 +76,31 @@ const LEVEL_NAMES = /** @type {Record<number, string>} */ ({
  *   rename·rm 된 inode 로 가서 항목이 **유실**된다(rename-claim 의 "유실 0" 이 깨지는 좁은 창). 그래서 큐
  *   연산을 promise 체인 mutex 로 **직렬화**해 인터리브를 원천 차단한다. 큐 연산은 드물어(전송 실패 시
  *   append + 주기 drain) 직렬화 비용은 무시 가능. rename-claim 은 cross-process 안전용으로 그대로 둔다.
+ *
+ * # 상한(cap) — 무한 증가 방지 (H4, 최적화 리포트)
+ *   텔레그램이 장기 장애(토큰 만료·차단·네트워크 단절)면 실패분이 무한 적재되고, drain 이 파일 전체를
+ *   메모리로 읽어 재시도→또 실패→전량 재append 한다. 그래서 `drain` 이 **maxAge 만료 + maxEntries 상한**을
+ *   적용해(오래된 것부터 드롭, 드롭 수는 `onDrop` 으로 관측) 디스크·드레인 메모리를 함께 bound 한다.
+ *   write 경로 append rate 는 transport throttle 로 이미 제한되므로 drain 시점 cap 으로 충분하다.
  */
 export class RetryQueue {
   /**
    * @param {string} filePath - JSONL 큐 파일 경로(없으면 비어 있음).
+   * @param {{ maxEntries?: number, maxAgeMs?: number, onDrop?: (count: number) => void }} [opts]
+   *   maxEntries: 보관 최대 항목 수(기본 5000, 0=무제한). maxAgeMs: 항목 최대 보존 ms(기본 24h, 0=무제한).
+   *   onDrop: cap 으로 드롭된 수 통지(관측용).
    */
-  constructor(filePath) {
+  constructor(filePath, { maxEntries = 5000, maxAgeMs = 86_400_000, onDrop } = {}) {
     /** @type {string} */
     this._file = filePath
     /** @type {Promise<unknown>} 직렬화 락의 꼬리 — append/drain/clear 를 이 체인에 줄세운다. */
     this._tail = Promise.resolve()
+    /** @type {number} 보관 최대 항목 수(0=무제한). */
+    this._maxEntries = Number.isInteger(maxEntries) && maxEntries > 0 ? maxEntries : 0
+    /** @type {number} 항목 최대 보존 ms(0=무제한). */
+    this._maxAgeMs = Number.isInteger(maxAgeMs) && maxAgeMs > 0 ? maxAgeMs : 0
+    /** @type {((count: number) => void) | null} cap 드롭 수 통지. */
+    this._onDrop = typeof onDrop === 'function' ? onDrop : null
   }
 
   /**
@@ -134,19 +149,32 @@ export class RetryQueue {
       }
       const raw = await readFile(claim, 'utf8')
       await rm(claim, { force: true })
-      /** @type {string[]} */
-      const texts = []
+      const now = Date.now()
+      /** @type {Array<{ text: string, ts: number }>} */
+      let entries = []
       for (const line of raw.split('\n')) {
         if (!line.trim()) continue
         try {
           const obj = JSON.parse(line)
-          if (typeof obj.text === 'string') texts.push(obj.text)
+          if (typeof obj.text === 'string') entries.push({ text: obj.text, ts: typeof obj.ts === 'number' ? obj.ts : now })
         } catch {
           // 손상된 라인은 건너뛴다 — 큐 전체를 막지 않기 위함(비치명적, 다음 항목 계속).
           continue
         }
       }
-      return texts
+      // cap(H4) — maxAge 만료 + maxEntries 상한. 오래된 것부터 드롭(최신 보존). 드롭 수는 onDrop 으로 관측.
+      let dropped = 0
+      if (this._maxAgeMs > 0) {
+        const before = entries.length
+        entries = entries.filter((e) => now - e.ts <= this._maxAgeMs)
+        dropped += before - entries.length
+      }
+      if (this._maxEntries > 0 && entries.length > this._maxEntries) {
+        dropped += entries.length - this._maxEntries
+        entries = entries.slice(entries.length - this._maxEntries) // 최신 maxEntries 만 유지.
+      }
+      if (dropped > 0 && this._onDrop) this._onDrop(dropped)
+      return entries.map((e) => e.text)
     })
   }