mega-framework 0.1.0

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "mega-framework",
+  "version": "0.1.0",
+  "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
+  "type": "module",
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "main": "src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.nyx-zone.com/mega/mega-framework.git"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./lib": "./src/lib/index.js",
+    "./errors": "./src/errors/index.js",
+    "./auth": "./src/auth/index.js",
+    "./test": "./src/test/index.js",
+    "./eslint-plugin": "./src/eslint-plugin/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/**/*.js",
+    "bin/**/*.js",
+    "templates/**",
+    "sample/**",
+    "infra/**",
+    "docker-compose.yml",
+    ".env",
+    ".env.example",
+    "eslint.config.js",
+    "vitest.config.js",
+    "jsconfig.json",
+    ".prettierrc.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "bin": {
+    "mega": "bin/mega.js",
+    "mega-ws-hub": "bin/mega-ws-hub.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src test",
+    "typecheck": "tsc -p jsconfig.json --noEmit",
+    "format": "prettier -w src test packages",
+    "infra:up": "docker compose up -d --wait",
+    "infra:down": "docker compose down -v",
+    "infra:logs": "docker compose logs -f",
+    "infra:reset": "docker compose down -v && docker compose up -d --wait",
+    "test:integration": "npm run infra:up && vitest run test/integration && npm run infra:down",
+    "test:unit": "vitest run test/unit",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run test:unit",
+    "release": "bash scripts/publish.sh"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.9.1",
+    "@types/opossum": "^8.1.9",
+    "@types/pg": "^8.20.0",
+    "@vitest/coverage-v8": "^4.1.8",
+    "eslint": "^9.0.0",
+    "eslint-plugin-promise": "^7.3.0",
+    "globals": "^14.0.0",
+    "prettier": "^3.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8"
+  },
+  "license": "MIT",
+  "private": false,
+  "dependencies": {
+    "@fastify/cookie": "^11.0.2",
+    "@fastify/cors": "^11.2.0",
+    "@fastify/formbody": "^8.0.2",
+    "@fastify/csrf-protection": "^7.1.0",
+    "@fastify/helmet": "^13.0.2",
+    "@fastify/multipart": "^10.0.0",
+    "@fastify/rate-limit": "^10.3.0",
+    "@fastify/static": "^9.1.3",
+    "@fastify/swagger": "^9.7.0",
+    "@fastify/swagger-ui": "^5.2.6",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-prometheus": "^0.218.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
+    "@opentelemetry/exporter-zipkin": "^2.7.1",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-metrics": "^2.7.1",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "ajv": "^8.20.0",
+    "better-sqlite3": "^12.10.0",
+    "commander": "^15.0.0",
+    "croner": "^10.0.1",
+    "ejs": "^6.0.1",
+    "ejs-mate": "^4.0.0",
+    "fastify": "^5.8.5",
+    "i18next": "^26.3.1",
+    "ioredis": "^5.11.0",
+    "mariadb": "^3.5.2",
+    "mongodb": "^6.21.0",
+    "nats": "^2.29.3",
+    "opossum": "^9.0.0",
+    "p-retry": "^8.0.0",
+    "pg": "^8.21.0",
+    "pino": "^9.14.0",
+    "pino-pretty": "^13.1.3",
+    "pino-roll": "^3.1.0",
+    "prompts": "^2.4.2",
+    "redlock": "5.0.0-beta.2",
+    "ws": "^8.21.0"
+  }
+}

package/sample/crud/.env

@@ -0,0 +1,18 @@
+PORT=4102
+DATABASE_URL=postgres://mega:dkTkqkfl12@localhost:5432/mega_test
+MEGA_CLUSTER_WORKERS=8
+SESSION_SECRET=Zz4VoSzf0sYMEoqASu8G_wx5l3uKi2MlHsxDK3MSkoE
+REDIS_SESSION_URL=redis://:dkTkqkfl12@localhost:6379/0
+REDIS_RATE_URL=redis://:dkTkqkfl12@localhost:6379/2
+REDIS_DEMO_URL=redis://:dkTkqkfl12@localhost:6379/1
+REDIS_LOCK_URL=redis://:dkTkqkfl12@localhost:6379/3
+MONGO_URL=mongodb://mega:dkTkqkfl12@localhost:27017/mega_test?authSource=admin
+NATS_JOBS_URL=nats://localhost:4222
+ASP_MASTER_SECRET=demo-asp-master-7Qe2mWzR1tYbN8sLpKvX0cAfH4dG6jU
+MEGA_OTEL_ENABLED=true
+MEGA_OTEL_SERVICE_NAME=sample-crud
+MEGA_OTEL_ENDPOINT=http://localhost:4318/v1/traces
+MEGA_OTEL_EXPORTER=otlp
+MEGA_OTEL_SAMPLING_RATIO=1.0
+MEGA_OTEL_ZIPKIN_API=http://localhost:9411/api/v2
+DEMO_UPLOAD_DIR=var/uploads

package/sample/crud/.env.example

@@ -0,0 +1,50 @@
+# sample-crud 환경변수 (.env.example) — 복사해서 .env 로 쓰고 실제 값 채우기. .env 는 git 에 안 올림.
+
+# HTTP 포트
+PORT=3000
+
+# cluster 워커 프로세스 수(ADR-154) — 정수 N 또는 max(CPU 코어 수). 미설정/1=단일 프로세스.
+# MEGA_CLUSTER_WORKERS=max
+
+# Postgres 연결 (필수) — services.databases.primary.url 이 읽는다.
+# 예: docker compose 의 postgres
+DATABASE_URL=postgres://mega:change-me@localhost:5432/mega_test
+
+# 세션 쿠키 HMAC 서명 시크릿 (필수, ADR-155) — server.sessionSecret 이 읽는다. 충분히 긴 랜덤 문자열.
+SESSION_SECRET=change-me-to-a-long-random-secret
+
+# Redis 연결 (필수, ADR-155/157) — 세션 store·brute-force·/demo/redis·cron·jobs 데모 캐시 + 분산 락(redlock).
+# DB 인덱스를 분리해 키 충돌을 피한다(/0 세션, /1 demo, /2 rate, /3 lock).
+REDIS_SESSION_URL=redis://:change-me@localhost:6379/0
+REDIS_RATE_URL=redis://:change-me@localhost:6379/2
+REDIS_DEMO_URL=redis://:change-me@localhost:6379/1
+# 분산 락(redlock, ADR-113) — services.caches.lock 이 읽는다. /demo/cron 스케줄의 클러스터 중복방지(leader election).
+REDIS_LOCK_URL=redis://:change-me@localhost:6379/3
+
+# NATS 연결 (필수, ADR-119) — services.buses.jobs.url 이 읽는다. /demo/jobs 잡 큐(EmailJob)의 JetStream 백엔드.
+# `mega worker` 프로세스가 소비하고 웹은 enqueue 한다. JetStream 활성 NATS 서버 필요(nats-server -js).
+NATS_JOBS_URL=nats://localhost:4222
+
+# MongoDB 연결 (필수, ADR-157) — services.databases.mongo.url 이 읽는다. /demo/notes 데모 컬렉션의 백엔드.
+# url path 의 dbName(mega_test)을 어댑터가 추출한다. authSource 는 인증 DB(보통 admin).
+MONGO_URL=mongodb://mega:change-me@localhost:27017/mega_test?authSource=admin
+
+# ASP WebSocket 데모 masterSecret (필수, ADR-158) — asp.masterSecret 이 읽는다. /ws/chat 의 E:/P:
+# 프레임 키 유도에 쓰인다. ASP 는 클라이언트(WASM MegaSocket)도 같은 secret 으로 키를 만드는 공유-키
+# 구조라 데모 페이지가 이 값을 브라우저에 주입한다 — 운영 secret 과 섞이지 않게 데모 전용 값을 둔다.
+ASP_MASTER_SECRET=change-me-to-a-demo-asp-secret
+
+# OpenTelemetry 트레이싱 (선택, ADR-104/126/163) — /demo/tracing 데모가 요청별 trace_id 를 만들고 Zipkin 으로
+# 잇는다. 미설정/false 면 트레이싱 OFF(데모는 비활성 안내를 보여줌). docker 의 otel-collector(:4318 OTLP HTTP)·
+# zipkin(:9411) 가동 시 true 로 켠다. exporter otlp → collector → zipkin 경로로 span 이 전달된다.
+MEGA_OTEL_ENABLED=false
+MEGA_OTEL_SERVICE_NAME=sample-crud
+MEGA_OTEL_ENDPOINT=http://localhost:4318/v1/traces
+MEGA_OTEL_EXPORTER=otlp
+MEGA_OTEL_SAMPLING_RATIO=1.0
+# Zipkin UI API base — /demo/tracing 이 trace 딥링크 base(.../api/v2 를 떼 UI 루트)로 쓴다.
+MEGA_OTEL_ZIPKIN_API=http://localhost:9411/api/v2
+
+# 업로드 저장 디렉터리 (선택, ADR-163) — /demo/upload 이 파일을 저장할 위치. 상대경로는 프로젝트 루트
+# (cwd) 기준, 절대경로면 그대로. 미설정 시 var/uploads(.gitignore). 다운로드도 같은 위치에서 소스로 읽는다.
+DEMO_UPLOAD_DIR=var/uploads

package/sample/crud/README.md

@@ -0,0 +1,85 @@
+# sample-crud
+
+MEGA-FRAMEWORK 의 **postgres CRUD baseline** 샘플. 단일 리소스(`users`)로 정본 계층 흐름을 보여준다:
+
+```
+route → controller → ctx.services.user(자동 DI) → UserService → User 모델 → postgres
+```
+
+- **모델** `apps/main/models/user.js` — `MegaModel`, 계측 SQL(`this.query`)로 CRUD. ORM 없음(ADR-009).
+- **서비스** `apps/main/services/user-service.js` — 비즈니스 로직 + 404/409/400 에러 매핑. 자동 DI 이름 `user`(ADR-148).
+- **컨트롤러** `apps/main/controllers/user-controller.js` — 정적 메서드, `ctx.services.user` 경유(ADR-022). 도메인 데이터만 반환 → 프레임워크가 envelope `{ ok, data, meta }` 로 감쌈(ADR-018/147).
+- **라우트** `apps/main/routes/users.js` — REST 5종(자동 로딩).
+- **마이그레이션** `apps/main/migrations/*.js` — `mega migrate` 러너로 실행(ADR-149).
+
+## 준비
+
+```bash
+# 1) 의존성(레포 내부 참조: file:../..)
+npm install
+
+# 2) 환경변수 — .env.example 복사 후 DATABASE_URL 채우기
+cp .env.example .env
+#   DATABASE_URL=postgres://user:pass@localhost:5432/yourdb
+
+# 3) 스키마 마이그레이션
+npm run migrate            # = mega migrate (pending up 일괄)
+npm run migrate:status     # 적용/미적용 목록
+```
+
+## 실행
+
+```bash
+npm start                  # NODE_ENV=production mega start — HTTP listen (기본 프로덕션)
+npm run dev                # NODE_ENV=development mega start — 개발 모드
+```
+
+> `npm start` 는 **프로덕션 기본**(`NODE_ENV=production`)이라 i18n `saveMissing`(누락 키 자동 기입)이
+> 꺼진다 — 라이브 서버가 ko/en locale 파일을 오염시키지 않게 하기 위함(ADR-164). 누락 키 자동 보완 등
+> 개발 편의가 필요하면 `npm run dev`(`NODE_ENV=development`)로 띄운다.
+
+## API (envelope: `{ ok, data, meta }`)
+
+```bash
+curl -X POST localhost:3000/users -H 'content-type: application/json' \
+  -d '{"name":"Ada","email":"ada@example.com"}'        # 201 → { ok:true, data:{ id, name, email, created_at }, meta }
+curl localhost:3000/users                               # 목록
+curl localhost:3000/users/1                             # 단건 (없으면 404 { ok:false, error })
+curl -X PUT localhost:3000/users/1 -H 'content-type: application/json' -d '{"name":"Ada L."}'
+curl -X DELETE localhost:3000/users/1                   # { ok:true, data:{ deleted:true }, meta }
+```
+
+## 관리 UI (Bootstrap 5, 서버사이드 렌더)
+
+같은 서비스 계층을 쓰는 **MPA 관리 화면**(EJS + ejs-mate + Bootstrap 5)을 함께 제공한다. JSON API(`/users`)와
+충돌하지 않도록 UI 는 `/admin/users` 네임스페이스를 쓴다.
+
+| 경로 | 설명 |
+| --- | --- |
+| `GET /` | 랜딩(관리 UI · JSON API 안내) |
+| `GET /admin/users` | 목록(테이블 + 수정/삭제, 삭제 확인 모달) |
+| `GET /admin/users/new` · `POST /admin/users` | 신규 폼 → 생성(PRG 리다이렉트) |
+| `GET /admin/users/:id/edit` · `POST /admin/users/:id` | 수정 폼(사전 채움) → 수정 |
+| `POST /admin/users/:id/delete` | 삭제 |
+
+- HTML 폼은 GET/POST 만 쓰므로(브라우저 제약) 수정·삭제도 POST. RESTful PUT/DELETE 는 JSON API(`/users`)가 제공.
+- 폼 제출(urlencoded)은 `@fastify/formbody` 가 파싱(views 옵트인 시 자동, ADR-151). CSRF(디폴트 ON) 토큰은
+  폼에 자동 포함된다.
+- navbar 의 언어 메뉴로 ko/en 전환(쿠키 `mega.lang`), 다크모드 토글(`data-bs-theme` + localStorage).
+- Bootstrap 은 `apps/main/public/vendor/bootstrap/` 에 vendored(`/static/vendor/bootstrap/...`).
+
+## 테스트
+
+```bash
+npm test                   # mega test — UserService 단위(모델 스파이, DB 불필요)
+```
+
+> 로컬 검증 주의: 레포 통합 테스트(`postgres-adapter`)가 같은 `mega_test` DB 의 제네릭 `users` 테이블을
+> 매 실행 재생성(다른 스키마)한다. 레포 테스트 직후 이 샘플을 띄우면 `created_at` 컬럼 부재로 충돌하니,
+> `npm run migrate:down && npm run migrate` 로 스키마를 재생성하거나 별도 DB 를 쓴다.
+
+## 롤백
+
+```bash
+npm run migrate:down       # 마지막 마이그레이션 1개 롤백(down)
+```

package/sample/crud/apps/main/app.config.js

@@ -0,0 +1,114 @@
+// @ts-check
+/**
+ * apps/main/app.config.js — App-only + Shared-Reference 스코프(ADR-061). 기본 앱 `main`.
+ * 전역 db 'primary'(mega.config.js)를 앱 별명 'db' 로 참조한다(ADR-102 글로벌 공유). 라우트 핸들러는
+ * `ctx.db('db')`, 모델은 `static adapter='primary'`(globalKey 직접)로 같은 인스턴스에 닿는다.
+ */
+import { webRequireAuth } from './middleware/web-auth.js'
+
+export default {
+  name: 'main',
+  hosts: ['localhost', 'main.localhost'],
+
+  // 어댑터 별명 맵 — alias 'db' → globalKey 'primary'(postgres), 'mongo' → 'mongo'(notes 데모, ADR-108).
+  databases: {
+    db: 'primary',
+    mongo: 'mongo',
+  },
+
+  // 캐시 별명 맵 — 'rate' → 'rate'(brute-force, ADR-049/130), 'demo' → 'demo'(/demo/redis·cron·jobs 캐시).
+  caches: {
+    rate: 'rate',
+    demo: 'demo',
+  },
+
+  // 버스 별명 맵 — 'jobs' → 'jobs'(NATS). /demo/jobs 컨트롤러가 ctx.bus('jobs').native(nc)로 EmailJob 을
+  // enqueue 한다(producer 측). 소비는 `mega worker` 프로세스 몫(ADR-119).
+  buses: {
+    jobs: 'jobs',
+  },
+
+  // 세션(ADR-129/046) — redis store. sid 쿠키(HMAC 서명)는 server.sessionSecret 로 서명. rolling TTL 24h.
+  // 로그인 신원(userId/userName)을 세션에 싣고, 미들웨어가 req.session/ctx.session 으로 노출한다.
+  session: {
+    store: {
+      driver: 'redis',
+      url: process.env.REDIS_SESSION_URL,
+    },
+    ttlMs: 86_400_000,
+    rolling: true,
+  },
+
+  // EJS + ejs-mate 서버사이드 렌더(ADR-011/136) — 관리 UI(MPA). views 옵트인이라 HTML 폼 제출
+  // (urlencoded)도 자동 파싱된다(ADR-151, @fastify/formbody). 렌더 시 req.t/req.lang 자동 병합.
+  views: {
+    dir: 'apps/main/views',
+    layoutDir: 'layouts',
+    partialsDir: 'partials',
+  },
+
+  // i18next 다국어(ADR-037/038/039) — locale 은 쿠키(`mega.lang`)로만 결정. server scope 는 `t()`/뷰,
+  // client scope 는 `/i18n/translations`. navbar 의 언어 메뉴가 쿠키를 굽고 새로고침한다.
+  i18n: {
+    default: 'ko',
+    available: ['ko', 'en'],
+    fallback: 'en',
+    localesDir: 'apps/main/locales',
+    exposeTranslations: true,
+  },
+
+  // 정적 자산(ADR-071/139) — Bootstrap 5 + WASM MegaSocket vendored + 브랜드 CSS/JS 를 `${prefix}/...` 로 서빙.
+  staticAssets: {
+    enabled: true,
+    dir: 'apps/main/public',
+    prefix: '/static',
+  },
+
+  // ASP 앱 옵트인(ADR-083/127) — websocket.namespaces 에 든 WS 경로만 기본 암호화(E: 프레임), 나머지는
+  // 평문(P:). masterSecret 은 global(mega.config.js)에서 합성된다. /ws/chat 채팅은 ASP E: 로 종단한다.
+  asp: {
+    websocket: {
+      namespaces: ['/ws/chat'],
+    },
+  },
+
+  // rate limit 상향(ADR-073) — /demo/worker 데모는 1초 간격 하트비트 ping(메인 스레드 non-block 시연)으로
+  // 폴링한다. 기본 한도(100/분)는 폴링 + 일반 탐색이 겹치면 쉽게 넘어 데모가 429 로 끊긴다. 데모 앱이라
+  // 폴링을 허용하도록 한도를 넉넉히 둔다(여전히 ON — 무제한 아님). 운영 앱은 엔드포인트별로 더 낮게 잡는다.
+  rateLimit: { max: 600, timeWindow: '1 minute' },
+
+  // OpenAPI/Swagger 옵트인(ADR-070/140) — @fastify/swagger + swagger-ui 를 `/docs` 에 노출한다(관측 데모).
+  // 라우트에 적은 JSON Schema(routes/*.js 의 opts.schema)와 openapi 메타(opts.openapi)를 코어가 onRoute 로
+  // 긁어모아 OpenAPI 3.x 명세를 자동 생성한다. auth 가드는 핸들러와 같은 시그니처(webRequireAuth) — 비로그인
+  // 브라우저는 로그인 페이지로 리다이렉트된다(데모 API 문서도 로그인 필요). 디폴트 OFF 라 명시적으로 켠다.
+  openapi: {
+    enabled: true,
+    path: '/docs',
+    info: {
+      title: 'sample-crud API',
+      version: '0.1.0',
+      description: 'MEGA-FRAMEWORK CRUD 샘플의 JSON REST API 명세 (users/notes/redis). 관측 데모(ADR-163).',
+    },
+    auth: [webRequireAuth],
+  },
+
+  // 파일 업로드 옵트인(ADR-133) — @fastify/multipart. /demo/upload 데모가 req.saveUploads()로 임시 디렉터리에
+  // 저장한다. MIME 화이트리스트(이미지/PDF/텍스트) + 개수·크기 제한으로 게이트한다. 미옵트인이면 multipart=415.
+  upload: {
+    maxFileSize: 5 * 1024 * 1024,
+    maxFiles: 3,
+    allowedMimeTypes: ['image/*', 'application/pdf', 'text/plain'],
+  },
+
+  // helmet CSP override(ADR-153/158) — /demo/ws 채팅은 WASM MegaSocket(ASP 클라이언트)을 쓴다.
+  // WebAssembly.instantiate 는 CSP script-src 에 'wasm-unsafe-eval' 이 있어야 한다(CSP3) — helmet 기본
+  // script-src 'self' 만으로는 WASM 컴파일이 차단된다. useDefaults(기본 true)라 이 지시문만 교체되고
+  // 나머지(connect-src 'self' = 동일 출처 WebSocket 허용 등)는 helmet 기본을 유지한다.
+  helmet: {
+    contentSecurityPolicy: {
+      directives: {
+        scriptSrc: ["'self'", "'wasm-unsafe-eval'"],
+      },
+    },
+  },
+}

package/sample/crud/apps/main/channels/chat-bus.js

@@ -0,0 +1,115 @@
+// @ts-check
+/**
+ * chat-bus.js — redis pub/sub 기반 cluster-wide 채팅 broadcast (ADR-158).
+ *
+ * `app.broadcast`(로컬 ns fan-out)는 단일 프로세스 안에서만 전달된다 — 클러스터(워커 N개)에선 다른
+ * 워커에 붙은 클라에게 닿지 않는다. hub 프로세스 없이 cluster-wide 전파를 하기 위해 redis pub/sub 를 쓴다:
+ *   - 송신: 메시지를 redis 채널(`ws:chat:bcast`)에 **PUBLISH** 만 한다(로컬 직접 전달 안 함).
+ *   - 수신: **워커마다** 전용 구독 연결(ioredis `duplicate()`)이 그 채널을 **SUBSCRIBE** 하고, 도착한
+ *     메시지를 자기 워커의 로컬 연결들에 전달한다.
+ * 결과: PUBLISH 1건 → 모든 워커의 구독자가 받아 각자 로컬 전달 → 전 클러스터 클라가 정확히 1회씩 수신
+ * (송신자 본인 워커도 구독자 경로로 전달받아 echo). 구독 연결은 명령 전용 연결과 분리해야 하므로
+ * (subscribe 모드 연결은 일반 명령 불가) `demo` 캐시의 raw ioredis 를 `duplicate()` 한다.
+ *
+ * 접속자 명단(roster)도 cluster-wide 다 — redis HASH(`ws:chat:roster`, field=sessionId→userName)에 두어
+ * 어느 워커에서든 같은 명단·인원수를 본다(INCR/DECR 카운터의 비정상종료 드리프트 회피, 명단까지 공유).
+ *
+ * @module channels/chat-bus
+ */
+import { MegaShutdown } from 'mega-framework'
+
+/** cluster-wide 전파 채널(redis pub/sub 은 db 와 무관한 글로벌 네임스페이스). */
+export const BCAST_CHANNEL = 'ws:chat:bcast'
+/** 접속자 명단 HASH 키 — field=sessionId, value=userName. */
+export const ROSTER_KEY = 'ws:chat:roster'
+
+/** 이 워커의 로컬 연결 레지스트리. sock → { sessionId, userName }. */
+const localConns = new Map()
+/** 이 워커의 전용 구독 연결(1개, lazy). */
+let subscriber = null
+
+/**
+ * 이 워커의 구독자를 1회 보장한다(첫 연결 시). 채널 SUBSCRIBE + 메시지 → 로컬 전달 + graceful 종료 hook.
+ *
+ * @param {any} app - MegaApp(로깅용).
+ * @param {import('ioredis').Redis} redisNative - `demo` 캐시의 raw ioredis(여기서 duplicate).
+ * @returns {void}
+ */
+export function ensureSubscriber(app, redisNative) {
+  if (subscriber) return
+  const log = app?.fastify?.log
+  subscriber = redisNative.duplicate()
+  subscriber.on('message', (/** @type {string} */ _channel, /** @type {string} */ raw) => {
+    let env
+    try {
+      env = JSON.parse(raw)
+    } catch (err) {
+      // 손상 페이로드는 전달하지 않는다(사유 명시 + 로그, silent 금지).
+      log?.warn?.({ err }, 'chat-bus subscribe payload parse failed')
+      return
+    }
+    deliverLocal(env)
+  })
+  subscriber.on('error', (/** @type {Error} */ err) => {
+    // 구독 연결 오류는 비치명적(ioredis 가 재연결) — 로그만.
+    log?.warn?.({ err }, 'chat-bus subscriber connection error')
+  })
+  // subscribe 실패는 전파 자체가 죽는 심각한 신호 — 로그 + throw(fail-closed, silent 금지).
+  subscriber.subscribe(BCAST_CHANNEL).catch((err) => {
+    log?.error?.({ err, channel: BCAST_CHANNEL }, 'chat-bus subscribe failed')
+    throw err
+  })
+  // 워커 graceful 종료 시 구독 연결 정리(이벤트루프 누수 방지).
+  MegaShutdown.register('sample-chat-bus', async () => {
+    const s = subscriber
+    subscriber = null
+    localConns.clear()
+    if (s) await s.quit().catch(() => {})
+  })
+}
+
+/**
+ * 구독으로 받은 메시지를 이 워커의 로컬 연결에 전달한다. exceptSessionIds 에 든 세션은 건너뛴다.
+ * @param {{ message: { type: string, payload?: object }, exceptSessionIds?: string[] }} env
+ * @returns {void}
+ */
+function deliverLocal({ message, exceptSessionIds }) {
+  if (!message || typeof message.type !== 'string') return
+  const except = Array.isArray(exceptSessionIds) && exceptSessionIds.length > 0 ? new Set(exceptSessionIds) : null
+  for (const [sock, meta] of localConns) {
+    if (!sock.isOpen) continue
+    if (except && except.has(meta.sessionId)) continue
+    sock.send({ type: message.type, payload: message.payload })
+  }
+}
+
+/**
+ * 로컬 연결 등록(onConnect). @param {any} sock @param {{ sessionId: string, userName: string }} meta
+ * @returns {void}
+ */
+export function registerConn(sock, meta) {
+  localConns.set(sock, meta)
+}
+
+/** 로컬 연결 해제(onDisconnect). @param {any} sock @returns {void} */
+export function unregisterConn(sock) {
+  localConns.delete(sock)
+}
+
+/**
+ * cluster-wide 전파 — redis 채널에 PUBLISH(모든 워커 구독자가 받아 로컬 전달).
+ * @param {import('ioredis').Redis} redisNative
+ * @param {{ message: { type: string, payload?: object }, exceptSessionIds?: string[] }} env
+ * @returns {Promise<void>}
+ */
+export async function publish(redisNative, env) {
+  await redisNative.publish(BCAST_CHANNEL, JSON.stringify(env))
+}
+
+/** 테스트 정리용 — 구독 연결 종료 + 레지스트리 초기화. @returns {Promise<void>} */
+export async function closeChatBus() {
+  const s = subscriber
+  subscriber = null
+  localConns.clear()
+  if (s) await s.quit().catch(() => {})
+}

package/sample/crud/apps/main/channels/chat-channel.js

@@ -0,0 +1,145 @@
+// @ts-check
+/**
+ * ChatChannel — /ws/chat 실시간 채팅 WS 채널 (ADR-158).
+ *
+ * MegaWebSocketController 를 상속해 라이프사이클 3훅 + `type` 자동 디스패치(ADR-015)를 쓴다. 채널
+ * 인스턴스는 **연결마다 새로 생성**되므로 공유 상태는 인스턴스가 아니라:
+ *   - **전파(cluster-wide)**: redis pub/sub({@link module:channels/chat-bus}) — `publish` 로 모든 워커에
+ *     fan-out. `app.broadcast`(로컬 ns 전용)는 클러스터에서 다른 워커에 안 닿으므로 쓰지 않는다(hub 불요).
+ *   - **접속자 명단·기록**: redis(`demo` 캐시 `.native`) — roster HASH(field=sessionId→userName, cluster-wide
+ *     인원수·명단) + 최근기록 캡 리스트(RPUSH/LTRIM).
+ * 에 둔다.
+ *
+ * ASP: `/ws/chat` 는 asp.websocket.namespaces 에 들어 기본 암호화(E: 프레임). 코덱은 프레임워크
+ * (ws-upgrade.js)가 종단하므로 채널은 **평문 envelope** 만 다룬다 — 암복호는 transport 계층 책임.
+ *
+ * 인증: `before`(makeWsRequireAuth) 가 로그인 세션만 통과시키므로 `ctx.auth`(userId/sessionId/userName)가 보장된다.
+ *
+ * @module channels/chat-channel
+ */
+import { MegaWebSocketController } from 'mega-framework'
+import { ensureSubscriber, registerConn, unregisterConn, publish, ROSTER_KEY } from './chat-bus.js'
+
+/** broadcast 논리 채널명(payload 분류용). */
+const CHANNEL = 'chat'
+/** redis 키 — 최근 메시지 캡 리스트(RPUSH + LTRIM). */
+const HISTORY_KEY = 'ws:chat:history'
+/** 보관·재생할 최근 메시지 개수. */
+const HISTORY_LIMIT = 30
+/** 기록 TTL(초) — 1일. 갱신마다 연장. */
+const HISTORY_TTL_SEC = 86_400
+
+export class ChatChannel extends MegaWebSocketController {
+  /**
+   * 연결 수립 — 워커 구독자 보장 + 로컬 등록 + roster 갱신(cluster-wide) + 최근기록 재생 + 입장 전파.
+   * @param {any} sock @param {any} ctx @returns {Promise<void>}
+   */
+  async onConnect(sock, ctx) {
+    const { userId, sessionId, userName } = ctx.auth
+    const redis = this._redis(ctx)
+    if (!redis) {
+      // redis 가 전파 transport — 없으면 채팅 불가. 명시적으로 닫는다(silent 진행 금지).
+      ctx.log?.error?.({ connId: sock.id }, 'ws.chat: redis(demo) unavailable — closing')
+      if (sock.isOpen) sock.close(1011, 'chat backend unavailable')
+      return
+    }
+    ensureSubscriber(ctx.app, redis) // 이 워커의 cluster-wide 구독 1회 보장.
+    registerConn(sock, { sessionId, userName })
+
+    let roster = [userName]
+    let items = []
+    try {
+      await redis.hset(ROSTER_KEY, sessionId, userName)
+      roster = await redis.hvals(ROSTER_KEY)
+      const raw = await redis.lrange(HISTORY_KEY, -HISTORY_LIMIT, -1)
+      for (const s of raw) {
+        try {
+          items.push(JSON.parse(s))
+        } catch (err) {
+          // 손상된 기록 1건은 재생에서 제외(전체 재생을 막지 않음) — 사유 명시 + debug 로그(silent 금지).
+          ctx.log?.debug?.({ err, connId: sock.id }, 'ws.chat skip corrupt history entry')
+        }
+      }
+    } catch (err) {
+      // roster/기록 조회 실패는 비치명적 — 빈 명단·기록으로라도 연결은 유지(다음 동작에서 복구).
+      ctx.log?.warn?.({ err, connId: sock.id }, 'ws.chat onConnect redis read failed (non-fatal)')
+    }
+
+    // 입장 본인에게: 신원 + 최근기록 + 현재 명단/인원 + 워커 PID(클러스터 확인용).
+    sock.send({
+      type: 'chat.history',
+      payload: { me: { userId, userName }, items, online: roster.length, members: roster, workerPid: process.pid },
+    })
+    // 다른 접속자(전 클러스터)에게: 입장 알림 + 갱신된 명단(본인은 제외).
+    await this._publish(ctx, redis, {
+      message: { type: 'chat.presence', payload: { event: 'join', userName, online: roster.length, members: roster } },
+      exceptSessionIds: [sessionId],
+    })
+  }
+
+  /**
+   * `chat.send` — 검증된 text 를 기록 적재 + 전 클러스터 전파(본인 포함, echo).
+   * @param {any} sock @param {any} msg @param {any} ctx @returns {Promise<void>}
+   */
+  async ['chat.send'](sock, msg, ctx) {
+    const text = String(msg.payload?.text ?? '').trim()
+    if (text.length === 0) return // 스키마가 minLength 1 강제하지만 trim 후 공백뿐이면 무시.
+    const redis = this._redis(ctx)
+    if (!redis) return
+    const entry = { userId: ctx.auth.userId, userName: ctx.auth.userName, text, ts: Date.now() }
+    try {
+      await redis.rpush(HISTORY_KEY, JSON.stringify(entry))
+      await redis.ltrim(HISTORY_KEY, -HISTORY_LIMIT, -1)
+      await redis.expire(HISTORY_KEY, HISTORY_TTL_SEC)
+    } catch (err) {
+      // 기록 적재 실패는 비치명적 — 전파는 그대로 진행(다른 사용자는 메시지를 받는다).
+      ctx.log?.warn?.({ err, connId: sock.id }, 'ws.chat history append failed (non-fatal)')
+    }
+    // exceptSessionIds 없음 → 본인도 구독자 경로로 echo 받아 렌더(optimistic 렌더 안 함 → 중복 없음).
+    await this._publish(ctx, redis, { message: { type: 'chat.msg', payload: entry } })
+  }
+
+  /**
+   * 연결 종료 — 로컬 해제 + roster 제거(cluster-wide) + 퇴장 전파.
+   * @param {any} sock @param {any} ctx @returns {Promise<void>}
+   */
+  async onDisconnect(sock, ctx) {
+    unregisterConn(sock)
+    if (!ctx.auth) return
+    const { sessionId, userName } = ctx.auth
+    const redis = this._redis(ctx)
+    if (!redis) return
+    let roster = []
+    try {
+      await redis.hdel(ROSTER_KEY, sessionId)
+      roster = await redis.hvals(ROSTER_KEY)
+    } catch (err) {
+      ctx.log?.warn?.({ err, connId: sock.id }, 'ws.chat onDisconnect redis failed (non-fatal)')
+    }
+    await this._publish(ctx, redis, {
+      message: { type: 'chat.presence', payload: { event: 'leave', userName, online: roster.length, members: roster } },
+      exceptSessionIds: [sessionId],
+    })
+  }
+
+  /**
+   * 전파 1건 — 실패해도 연결을 막지 않는다(메시지 1건 유실은 비치명적, 로그). silent 금지.
+   * @param {any} ctx @param {import('ioredis').Redis} redis @param {object} env @returns {Promise<void>}
+   * @private
+   */
+  async _publish(ctx, redis, env) {
+    try {
+      await publish(redis, env)
+    } catch (err) {
+      ctx.log?.warn?.({ err }, 'ws.chat publish failed (message dropped)')
+    }
+  }
+
+  /**
+   * 'demo' redis 캐시의 raw ioredis 핸들(원자적 연산·pub/sub용). 미배선(단위 테스트 mock app)이면 null.
+   * @param {any} ctx @returns {any|null} @private
+   */
+  _redis(ctx) {
+    return ctx.cache?.('demo')?.native ?? null
+  }
+}