mega-framework 0.1.9 → 0.1.11

package/README.md

@@ -22,6 +22,8 @@ HTTP·WebSocket 을 동급 일급으로 다루고, 데이터 어댑터·잡/스
 | **HTTP** | `MegaApp`(Fastify v5 래퍼) · `MegaServer`(멀티앱 vhost 라우팅) · 단일 시그니처 `router.http.<method>(path, handler, opts?)` · 라우트 자동 로드 · 자동 envelope(`{ok, data\|error, meta}`) · AJV 검증 에러 → `details` 자동 매핑 |
 | **WebSocket** | `MegaWebSocketController`(타입 자동 디스패치) · Bridge↔Hub 12-타입 프로토콜 · presence · `broadcast`/`directToUser` fan-out · per-message deflate 압축 · embedded/별도 프로세스 hub |
 | **데이터** | `MegaModel`(ORM 없음, native API + 트랜잭션) · 어댑터 베이스 트리(Db/Cache/Bus/Lock/Session) · 드라이버: Postgres·MariaDB·SQLite·MongoDB·Redis·NATS·File · `MegaRedlockAdapter`(분산 락) |
+| **동시성(분산 락)** | `ctx.lock.with/.acquire/.tryAcquire`(ADR-226) · driver 자동폴백 redis>cluster>memory · FIFO·fence·watchdog 옵트인 |
+| **메시지 버스** | `ctx.bus.emit/.on/.request/.with`(ADR-227) · driver 자동폴백 nats>cluster>memory · wildcards(`*`/`>`)·request/reply·persist(JetStream)·ordered 옵트인 |
 | **운영(잡/스케줄)** | `MegaJobQueue`(NATS JetStream + 재시도 + DLQ) · `MegaJobWorker` · `MegaScheduler`(croner + 분산 중복방지) · `MegaWorker`(worker_threads CPU 풀) |
 | **복원력** | `MegaRetry`(p-retry 지수 백오프) · `MegaCircuitBreaker`(opossum) · `MegaHealth`(`/health`·`/health/ready`) · `MegaShutdown`(LIFO graceful) |
 | **관측성** | `MegaTracing`(OpenTelemetry 옵트인, HTTP/WS/어댑터/native query 자동 span, Zipkin) · `MegaMetrics`(Prometheus `/metrics`) |
@@ -128,14 +130,22 @@ docs/            설계·ADR·운영 문서
 
 ## 의존성
 
-- **런타임**: Node.js `>=20` (engines)
+- **런타임**: Node.js `>=20.19.0` (engines — `mongodb` v7 요구)
 - **HTTP/WS**: `fastify` v5 + `@fastify/*`(cookie/cors/csrf/helmet/multipart/rate-limit) · `ws`
-- **데이터**: `pg` · `mariadb` · `mongodb` · `better-sqlite3` · `ioredis` · `nats` · `redlock`
+- **데이터**: `pg` · `mariadb` · `mongodb` · `better-sqlite3` · `ioredis` · `@nats-io/*`(transport-node/jetstream/nats-core, ADR-225) · `redlock`
 - **복원력·운영**: `p-retry` · `opossum` · `croner`
-- **관측성**: `@opentelemetry/*`(api/sdk-trace/sdk-metrics/exporter-zipkin/exporter-prometheus/exporter-otlp)
+- **관측성**: `@opentelemetry/*`(api/sdk-trace/sdk-metrics/exporter-zipkin/exporter-prometheus/exporter-otlp) · `pino`
 - **SSR·i18n·검증**: `ejs` + `ejs-mate` · `i18next` · `ajv`
 
-> 모든 신규 의존성은 [docs/09](./docs/09-decisions-and-open-questions.md) 에 ADR 로 1줄 기록(P8). 커스텀 구현은 Node 빌트인만 사용(scrypt/HMAC/cluster/worker_threads).
+> 모든 신규 의존성은 ADR 로 1줄 기록(P8 — ADR-218+ 는 [docs/adr/](./docs/adr/)). 커스텀 구현은 Node 빌트인만 사용(scrypt/HMAC/cluster/worker_threads).
+
+### `npm update` 호환
+
+받은 직후 `npm update` 로 한 번에 최신화해도 동작하도록 검증한다(검증 매트릭스·정책 = [ADR-224](./docs/adr/0224-dependency-bulk-update-and-npm-update-compat.md)). semver range 는 `^`(caret) 유지로 patch/minor 를 자동 수용한다.
+
+> **OTel 만 예외 — 부분 업데이트 금지**: experimental exporter(`exporter-prometheus`/`exporter-trace-otlp-http`, 0.21x)가 stable `@opentelemetry/core`·`sdk-*`(2.x)를 exact 핀한다. stable 만 올리면 `@opentelemetry/core` 가 중복 로드되어 trace context 전파가 깨진다. `@opentelemetry/*` 는 stable+experimental 을 **항상 함께** 올릴 것.
+
+> **`@nats-io/*` 도 lockstep**: NATS v3 클라이언트는 `transport-node`·`jetstream`·`nats-core` 로 분리됐고 세 패키지는 같은 버전을 함께 써야 한다(`nats-core` 가 다른 둘의 공유 기반 — 버전이 어긋나면 타입/런타임 불일치). `@nats-io/*` 는 **항상 같은 버전으로 동시에** 올릴 것(ADR-225).
 
 ## 문서
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "mega-framework",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {
-    "node": ">=20.6.0"
+    "node": ">=20.19.0"
   },
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -84,17 +84,17 @@
     "release": "bash scripts/publish.sh"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.4",
+    "@eslint/js": "^10.0.1",
     "@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": "^10.5.0",
     "eslint-plugin-promise": "^7.3.0",
-    "globals": "^14.0.0",
+    "globals": "^17.6.0",
     "prettier": "^3.0.0",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.8"
   },
   "license": "MIT",
@@ -102,22 +102,25 @@
   "dependencies": {
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.2.0",
+    "@fastify/csrf-protection": "^8.0.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/rate-limit": "^11.0.0",
     "@fastify/static": "^9.1.3",
     "@fastify/swagger": "^9.7.0",
-    "@fastify/swagger-ui": "^5.2.6",
+    "@fastify/swagger-ui": "^6.0.0",
+    "@nats-io/jetstream": "^3.4.0",
+    "@nats-io/nats-core": "^3.4.0",
+    "@nats-io/transport-node": "^3.4.0",
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/core": "^2.7.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/core": "^2.8.0",
+    "@opentelemetry/exporter-prometheus": "^0.219.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.219.0",
+    "@opentelemetry/exporter-zipkin": "^2.8.0",
+    "@opentelemetry/resources": "^2.8.0",
+    "@opentelemetry/sdk-metrics": "^2.8.0",
+    "@opentelemetry/sdk-trace-base": "^2.8.0",
     "@opentelemetry/semantic-conventions": "^1.41.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
@@ -130,16 +133,15 @@
     "i18next": "^26.3.1",
     "ioredis": "^5.11.0",
     "mariadb": "^3.5.2",
-    "mongodb": "^6.21.0",
-    "nats": "^2.29.3",
+    "mongodb": "^7.3.0",
     "opossum": "^9.0.0",
     "p-retry": "^8.0.0",
     "pg": "^8.21.0",
-    "pino": "^9.14.0",
+    "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
-    "pino-roll": "^3.1.0",
+    "pino-roll": "^4.0.0",
     "prompts": "^2.4.2",
     "redlock": "5.0.0-beta.2",
     "ws": "^8.21.0"
   }
-}
+}

package/sample/crud/.env

@@ -67,7 +67,11 @@ REDIS_DEMO_URL=redis://:dkTkqkfl12@localhost:6379/1
 # 분산 락(redlock, ADR-113) — caches.lock(locks.main 이 빌려 씀). /demo/cron leader election.
 REDIS_LOCK_URL=redis://:dkTkqkfl12@localhost:6379/3
 # 범용 캐시(미사용) — 별도 캐시 어댑터가 필요하면 services.caches 에 추가해 참조.
-# REDIS_CACHE_URL=redis://:dkTkqkfl12@localhost:6379/4
+REDIS_CACHE_URL=redis://:dkTkqkfl12@localhost:6379/4
+
+# 분산 락 사용자 API(ADR-226, ctx.lock.with/.acquire) — driver 자동 폴백이라 **추가 .env 변수는 필요 없다**.
+# redis 분산 락을 켜려면 mega.config.js 의 `lock` 블록 주석을 풀고 `cache: 'lock'`(위 REDIS_LOCK_URL 재사용)을
+# 지정한다. 미설정 시 redis 가용→redis, 클러스터 워커→cluster, 그 외→memory(단일 프로세스, 부팅 경고).
 
 
 # ── NATS 버스 (mega.config.js > services.buses) ──────────────────────────────
@@ -77,6 +81,10 @@ NATS_JOBS_URL=nats://localhost:4222
 # 이벤트 버스(미사용) — pub/sub 등 두 번째 버스가 필요하면 services.buses 에 추가.
 # NATS_EVENTS_URL=nats://localhost:4222
 
+# 메시지 버스 사용자 API(ADR-227, ctx.bus.emit/.on/.request) — driver 자동 폴백이라 **추가 .env 변수는 필요 없다**.
+# NATS 분산 버스를 켜려면 mega.config.js 의 `bus` 블록 주석을 풀고 `nats: 'jobs'`(위 NATS_JOBS_URL 재사용)을
+# 지정한다. 미설정 시 NATS 가용→nats, 클러스터 워커→cluster, 그 외→memory(단일 프로세스, 부팅 경고).
+
 
 # ── WS Hub: 클러스터 채팅 브릿지 (ADR-059/065/137/176) ────────────────────────
 # crud 는 app.config.js 의 bridgeHub 로 /ws/chat 을 클러스터 전파한다. 허브는 `mega ws-hub`(scripts/
@@ -172,7 +180,7 @@ DEMO_UPLOAD_DIR=var/uploads
 #     DATABASE | DB           → database   /   DBNAME → dbName(Mongo)
 #     POOL_<X>                → pool.{camelCase(X)}    (드라이버 공통, 값 자동 타입변환)
 #     OPTIONS_<X>             → options.{드라이버 표기}  (postgres/sqlite=snake, 그 외=camel; MS 대문자 보존)
-# 공통 풀 인터페이스(min/max/idleTimeoutMs/acquireTimeoutMs/maxLifetimeMs) 예:
+# 공통 풀 인터페이스(min/max/idleTimeoutMs/acquireTimeoutMs/maxLifetimeMs) 예: 
 # MEGA_PG_POOL_MIN=0
 # MEGA_PG_POOL_MAX=10
 # MEGA_PG_POOL_IDLE_TIMEOUT_MS=10000

package/sample/crud/.env.example

@@ -69,6 +69,10 @@ REDIS_LOCK_URL=redis://:change-me@localhost:6379/3
 # 범용 캐시(미사용) — 별도 캐시 어댑터가 필요하면 services.caches 에 추가해 참조.
 # REDIS_CACHE_URL=redis://:change-me@localhost:6379/4
 
+# 분산 락 사용자 API(ADR-226, ctx.lock.with/.acquire) — driver 자동 폴백이라 **추가 .env 변수는 필요 없다**.
+# redis 분산 락을 켜려면 mega.config.js 의 `lock` 블록 주석을 풀고 `cache: 'lock'`(위 REDIS_LOCK_URL 재사용)을
+# 지정한다. 미설정 시 redis 가용→redis, 클러스터 워커→cluster, 그 외→memory(단일 프로세스, 부팅 경고).
+
 
 # ── NATS 버스 (mega.config.js > services.buses) ──────────────────────────────
 # 잡 큐(EmailJob JetStream, ADR-119) — buses.jobs.url. `mega worker` 가 소비, 웹이 enqueue.
@@ -77,6 +81,10 @@ NATS_JOBS_URL=nats://localhost:4222
 # 이벤트 버스(미사용) — pub/sub 등 두 번째 버스가 필요하면 services.buses 에 추가.
 # NATS_EVENTS_URL=nats://localhost:4222
 
+# 메시지 버스 사용자 API(ADR-227, ctx.bus.emit/.on/.request) — driver 자동 폴백이라 **추가 .env 변수는 필요 없다**.
+# NATS 분산 버스를 켜려면 mega.config.js 의 `bus` 블록 주석을 풀고 `nats: 'jobs'`(위 NATS_JOBS_URL 재사용)을
+# 지정한다. 미설정 시 NATS 가용→nats, 클러스터 워커→cluster, 그 외→memory(단일 프로세스, 부팅 경고).
+
 
 # ── WS Hub: 클러스터 채팅 브릿지 (ADR-059/065/137/176) ────────────────────────
 # crud 는 app.config.js 의 bridgeHub 로 /ws/chat 을 클러스터 전파한다. 허브는 `mega ws-hub`(scripts/

package/sample/crud/apps/main/controllers/bus-controller.js

@@ -0,0 +1,122 @@
+// @ts-check
+/**
+ * BusController — /demo/bus 메시지 버스 데모 컨트롤러(ADR-074: 베이스 없음, 정적 메서드만, ADR-227 시연).
+ *
+ * `ctx.bus.emit/.on/.request` 를 그대로 쓴다(프레임워크 확장 X). 워커마다 첫 요청에서 한 번 `demo.>` 를 구독해
+ * (비영속 + 영속 둘 다) 수신 이벤트를 인메모리 링버퍼에 쌓고, `demo.echo` 응답자를 등록한다. 페이지는 폴링으로
+ * 버퍼를 가져와 fan-out·wildcards·persist·request/reply 를 워커 PID 와 함께 시각화한다.
+ *
+ * 핸들러 3번째 인자 `subject`(ADR-227)로 어떤 구체 subject 가 매칭됐는지 안다(`meta.subject` 도 동일). 발행자가
+ * 라벨링할 필요 없이 버스가 직접 알려준다 — wildcard 구독에서 특히 유용.
+ */
+import { currentUser } from '../middleware/web-auth.js'
+
+/** 수신 이벤트 링버퍼(워커별 인메모리). @type {any[]} */
+const eventBuf = []
+const MAX_EVENTS = 60
+let seq = 0
+/** 워커별 1회 구독 가드. @type {boolean} */
+let subscribed = false
+
+/** 버퍼에 수신 이벤트 1건 기록. @param {any} payload @param {any} meta @param {boolean} persisted @param {string} subject @returns {void} */
+function record(payload, meta, persisted, subject) {
+  eventBuf.push({
+    id: ++seq,
+    pid: process.pid,
+    subject: subject || '?',
+    emittedByPid: (meta && meta.emittedByPid) || null,
+    persisted,
+    payload,
+    at: new Date().toISOString(),
+  })
+  if (eventBuf.length > MAX_EVENTS) eventBuf.shift()
+}
+
+/**
+ * 이 워커에서 한 번만 demo 구독을 건다(멱등). 비영속/영속 `demo.>` 와 `demo.echo` 응답자.
+ * @param {any} ctx @returns {Promise<void>}
+ */
+async function ensureSubscribed(ctx) {
+  if (subscribed) return
+  subscribed = true
+  // 비영속 fan-out — 일반 emit 을 받는다. 3번째 인자 subject 로 매칭된 구체 subject 를 안다(ADR-227).
+  await ctx.bus.on('demo.>', (/** @type {any} */ payload, /** @type {any} */ meta, /** @type {any} */ subject) => record(payload, meta, false, subject))
+  // 영속 fan-out — persist:true emit 을 JetStream 에서 받는다(nats driver 만 영속, 그 외엔 비영속으로 폴백).
+  try {
+    await ctx.bus.on('demo.>', (/** @type {any} */ payload, /** @type {any} */ meta, /** @type {any} */ subject) => record(payload, meta, true, subject), { persist: true })
+  } catch (e) {
+    // 영속 구독 실패(드라이버 미지원/JetStream 비활성)는 데모 비치명 — 비영속만으로 계속.
+    ctx.log?.warn?.({ err: e }, 'bus demo: persistent subscribe unavailable')
+  }
+  // request/reply 응답자 — 반환값이 reply.
+  await ctx.bus.on('demo.echo', (/** @type {any} */ payload) => ({ echo: payload, pid: process.pid, at: new Date().toISOString() }))
+}
+
+export class BusController {
+  /** GET /demo/bus — 데모 셸 렌더(구독 보장). @param {any} req @param {any} reply @param {any} ctx */
+  static async index(req, reply, ctx) {
+    await ensureSubscribed(ctx)
+    const stats = await BusController.#safeStats(ctx)
+    return ctx.render('bus/index', {
+      title: ctx.t('bus_title', { defaultValue: '메시지 버스 데모' }),
+      stats,
+      pid: process.pid,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /**
+   * POST /demo/bus/emit — fan-out 발행. subject·payload(JSON)·persist·ordered. meta 에 subject·워커 PID 를 실어 보낸다.
+   * @param {any} req @param {any} reply @param {any} ctx
+   */
+  static async emit(req, reply, ctx) {
+    const body = req.body ?? {}
+    const subject = String(body.subject ?? 'demo.event')
+    const payload = body.payload ?? {}
+    await ctx.bus.emit(subject, payload, {
+      persist: body.persist === true,
+      ordered: body.ordered === true,
+      meta: { emittedByPid: process.pid }, // subject 는 버스가 수신측에 자동 제공(ADR-227) — 라벨링 불필요.
+    })
+    return { ok: true, pid: process.pid, subject, persist: body.persist === true }
+  }
+
+  /**
+   * POST /demo/bus/request — req/reply. demo.echo 응답자가 첫 응답을 준다(어느 워커가 답했는지 reply.pid 로 보임).
+   * @param {any} req @param {any} reply @param {any} ctx
+   */
+  static async request(req, reply, ctx) {
+    const body = req.body ?? {}
+    const subject = String(body.subject ?? 'demo.echo')
+    const timeout = body.timeout ?? 2000
+    try {
+      const answer = await ctx.bus.request(subject, body.payload ?? {}, { timeout })
+      return { ok: true, requestedByPid: process.pid, subject, reply: answer }
+    } catch (e) {
+      // no_responders / request_timeout 은 정상 데모 결과 — 코드와 함께 응답(throw 아님).
+      const code = /** @type {any} */ (e)?.code
+      if (code === 'bus.no_responders' || code === 'bus.request_timeout') {
+        return { ok: false, requestedByPid: process.pid, subject, error: code }
+      }
+      throw e
+    }
+  }
+
+  /** GET /demo/bus/events — 이 워커의 수신 버퍼 + driver(폴링용 JSON). @param {any} _req @param {any} _reply @param {any} ctx */
+  static async events(_req, _reply, ctx) {
+    await ensureSubscribed(ctx)
+    const stats = await BusController.#safeStats(ctx)
+    return { pid: process.pid, driver: stats ? stats.driver : '?', events: eventBuf.slice().reverse() }
+  }
+
+  /** stats 안전 조회. @param {any} ctx @returns {Promise<any>} */
+  static async #safeStats(ctx) {
+    try {
+      return await ctx.bus.stats()
+    } catch (e) {
+      ctx.log?.warn?.({ err: e }, 'bus demo: stats failed')
+      return null
+    }
+  }
+}

package/sample/crud/apps/main/controllers/jobs-controller.js

@@ -8,7 +8,9 @@
 import { currentUser } from '../middleware/web-auth.js'
 
 /** 발송 시뮬레이션 모드 화이트리스트(폼 입력 검증). */
-const MODES = ['ok', 'flaky', 'fail']
+const MODES = ['ok', 'flaky', 'fail', 'hang']
+/** 'hang' 모드 지연 상한(ms) — 폼 입력 검증(10분). 잡 클래스 timeoutMs(5s)와 별개의 입력 가드. */
+const MAX_DELAY_MS = 600_000
 /** 알림 쿼리(?notice=) → 로케일 키 화이트리스트. */
 const NOTICE_KEYS = new Set(['enqueued'])
 
@@ -37,7 +39,25 @@ export class JobsController {
     const to = rawTo.length > 0 ? rawTo : 'demo@example.com'
     // 잡 식별자 — 시도 카운터/이벤트 키에 쓰인다. 같은 페이로드 중복 enqueue 도 서로 구분되게 유니크하게 만든다.
     const id = `email-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
-    await ctx.services.jobsDemo.enqueue({ id, to, mode })
+    /** @type {{ id: string, to: string, mode: string, delayMs?: number }} */
+    const payload = { id, to, mode }
+    // hang 모드만 delayMs 를 싣는다. 미입력·무효(<=0)면 생략 → 잡 클래스가 기본 지연(8s)으로 timeout 을 시연.
+    if (mode === 'hang') {
+      const delayMs = JobsController.#parseDelayMs(body.delayMs)
+      if (delayMs > 0) payload.delayMs = delayMs
+    }
+    await ctx.services.jobsDemo.enqueue(payload)
     return reply.redirect('/demo/jobs?notice=enqueued')
   }
+
+  /**
+   * 폼 delayMs(문자열) → [0, MAX_DELAY_MS] 정수. 비정수·음수는 0 으로, 초과는 상한으로 보정한다. 폼 POST 라
+   * AJV body 스키마 대신 컨트롤러에서 검증한다(기존 mode/to 처리와 동일 스타일 — _csrf/AJV 순서 이슈 회피).
+   * @param {unknown} raw @returns {number} 0 = 미지정(잡 클래스 기본 지연 사용).
+   */
+  static #parseDelayMs(raw) {
+    const n = Number.parseInt(typeof raw === 'string' ? raw : String(raw ?? ''), 10)
+    if (!Number.isFinite(n) || n <= 0) return 0
+    return Math.min(n, MAX_DELAY_MS)
+  }
 }

package/sample/crud/apps/main/controllers/lock-controller.js

@@ -0,0 +1,117 @@
+// @ts-check
+/**
+ * LockController — /demo/lock 분산 락 데모 컨트롤러(ADR-074: 베이스 없음, 정적 메서드만, ADR-226 시연).
+ *
+ * `ctx.lock.with`(권장 — 자동 해제)와 `ctx.lock.tryAcquire`(즉시 1회)를 그대로 쓴다(프레임워크 확장 X). 두 탭에서
+ * 같은 key 로 동시에 "실행"하면 한 번에 하나만 임계구역에 들어가고(상호배제), `fifo` 면 도착 순서대로 깬다 —
+ * 응답의 워커 PID·대기 시간으로 분산 동작이 보인다. 최근 실행 로그는 워커별 모듈 링버퍼에 남긴다(상태 패널).
+ *
+ * 락 핸들을 요청 사이에 들고 있지 않는다(클러스터에서 acquire·release 가 다른 워커에 갈 수 있음) — `with` 가
+ * 한 요청 안에서 획득→대기(hold)→해제까지 자족적으로 끝내므로 워커 경계 문제가 없다.
+ */
+import { currentUser } from '../middleware/web-auth.js'
+
+/** @param {number} ms @returns {Promise<void>} */
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+/** 최근 실행 로그(워커별 인메모리 링버퍼). 상태 패널에 역순으로 보여준다. @type {any[]} */
+const runLog = []
+const MAX_LOG = 25
+
+/** 로그 1건 추가(상한 유지). @param {any} entry @returns {void} */
+function pushLog(entry) {
+  runLog.push(entry)
+  if (runLog.length > MAX_LOG) runLog.shift()
+}
+
+/** 락 옵션 정규화(스키마가 타입은 검증 — 여기선 데모 기본값만). @param {any} body */
+function readOpts(body) {
+  return {
+    key: String(body.key ?? 'demo:resource'),
+    ttl: body.ttl ?? 5000,
+    waitMs: body.waitMs ?? 3000,
+    holdMs: body.holdMs ?? 2000,
+    fifo: body.fifo === true,
+    fence: body.fence === true,
+    extendable: body.extendable === true,
+  }
+}
+
+export class LockController {
+  /** GET /demo/lock — 데모 셸 + 현재 상태(stats) 렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async index(req, reply, ctx) {
+    const stats = await LockController.#safeStats(ctx)
+    return ctx.render('lock/index', {
+      title: ctx.t('lock_title', { defaultValue: '분산 락 데모' }),
+      stats,
+      pid: process.pid,
+      runLog: runLog.slice().reverse(),
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /**
+   * POST /demo/lock/run — `ctx.lock.with` 로 임계구역을 잡고 holdMs 동안 보유 후 해제. 경합 시 waitMs 까지 대기.
+   * @param {any} req @param {any} reply @param {any} ctx
+   */
+  static async run(req, reply, ctx) {
+    const o = readOpts(req.body ?? {})
+    const startedAt = Date.now()
+    try {
+      const inner = await ctx.lock.with(o.key, { ttl: o.ttl, waitMs: o.waitMs, fifo: o.fifo, fence: o.fence, extendable: o.extendable }, async (/** @type {any} */ lock) => {
+        const acquiredAt = Date.now()
+        await sleep(o.holdMs) // 임계구역 점유(다른 시도는 이만큼 대기).
+        return { acquiredAt, fence: lock.fence }
+      })
+      const entry = { ok: true, acquired: true, key: o.key, pid: process.pid, waitedMs: inner.acquiredAt - startedAt, heldMs: o.holdMs, fence: inner.fence ?? null, fifo: o.fifo, at: new Date().toISOString() }
+      pushLog(entry)
+      return entry
+    } catch (e) {
+      // 경합으로 못 잡음(lock.not_acquired, 409)은 **정상 데모 결과** — 그대로 응답한다(throw 아님).
+      if (/** @type {any} */ (e)?.code === 'lock.not_acquired') {
+        const entry = { ok: true, acquired: false, key: o.key, pid: process.pid, waitedMs: Date.now() - startedAt, reason: 'contended', fifo: o.fifo, at: new Date().toISOString() }
+        pushLog(entry)
+        return entry
+      }
+      throw e // 그 외(검증·드라이버 오류)는 표면화(500).
+    }
+  }
+
+  /**
+   * POST /demo/lock/try — `ctx.lock.tryAcquire`(즉시 1회). 잡으면 짧게 보유 후 해제, 못 잡으면 즉시 null.
+   * @param {any} req @param {any} reply @param {any} ctx
+   */
+  static async tryRun(req, reply, ctx) {
+    const o = readOpts(req.body ?? {})
+    const lock = await ctx.lock.tryAcquire(o.key, { ttl: o.ttl, fence: o.fence })
+    if (!lock) {
+      const entry = { ok: true, acquired: false, key: o.key, pid: process.pid, reason: 'held', mode: 'try', at: new Date().toISOString() }
+      pushLog(entry)
+      return entry
+    }
+    try {
+      await sleep(Math.min(o.holdMs, 2000))
+      const entry = { ok: true, acquired: true, key: o.key, pid: process.pid, token: lock.token, fence: lock.fence ?? null, mode: 'try', at: new Date().toISOString() }
+      pushLog(entry)
+      return entry
+    } finally {
+      await lock.release()
+    }
+  }
+
+  /** GET /demo/lock/status — 현재 보유/대기 수(stats) + 워커별 최근 실행 로그(JSON, 페이지 폴링용). @param {any} _req @param {any} _reply @param {any} ctx */
+  static async status(_req, _reply, ctx) {
+    return { stats: await LockController.#safeStats(ctx), pid: process.pid, runLog: runLog.slice().reverse() }
+  }
+
+  /** stats 안전 조회 — 드라이버/연결 문제 시 null(페이지가 깨지지 않게). @param {any} ctx @returns {Promise<any>} */
+  static async #safeStats(ctx) {
+    try {
+      return await ctx.lock.stats()
+    } catch (e) {
+      ctx.log?.warn?.({ err: e }, 'lock demo: stats failed')
+      return null
+    }
+  }
+}

package/sample/crud/apps/main/jobs/email-job.js

@@ -6,6 +6,24 @@ const FLAKY_SUCCEED_ON = 2
 /** 시도 카운터 키 TTL(초) — 데모 잡은 짧게 살고 사라진다. */
 const ATTEMPT_TTL = 600
 
+/**
+ * EmailJob run 전체(재시도 포함) 실행 상한(ms) — 'hang' 모드 timeout 시연용 backstop. run 이 이 값을 넘게
+ * 돌면 MegaJobQueue 가 timeout 으로 판정해 잡을 실패시키고 DLQ 로 보낸다. ok/flaky/fail 의 실 실행 시간
+ * (< 3s — fail 의 백오프 최악치 ~3s 포함)보다 충분히 크게 둬(5s) 기존 모드엔 영향이 없게 한다.
+ */
+const RUN_TIMEOUT_MS = 5000
+/** 'hang' 모드 기본 지연(ms) — RUN_TIMEOUT_MS 보다 커서 그냥 enqueue 해도 timeout 을 시연한다. */
+const HANG_DEFAULT_DELAY_MS = 8000
+
+/**
+ * 지정 ms 만큼 멈춘다('hang' 모드 시뮬레이션). 프레임워크는 timeout 시 진행 중 run 을 **중단하지 않으므로**
+ * (abort 없음 — run 은 멱등 설계), 이 sleep 은 timeout 후에도 백그라운드에서 끝까지 흐른다.
+ * @param {number} ms @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
 /**
  * EmailJob — /demo/jobs 데모 잡(ADR-028/119). `mega worker` 프로세스(ecosystem instances:2)가 소비한다
  * (config.jobs). 실제 메일은 보내지 않고 발송을 **시뮬레이션**하며, payload.mode 로 세 가지 흐름을 시연한다:
@@ -14,6 +32,10 @@ const ATTEMPT_TTL = 600
  *   - `flaky` : 1번째 시도는 throw(일시 실패) → MegaJobQueue 가 재시도(p-retry, static retries/backoff) →
  *               2번째 시도에 성공. "일시 오류는 그냥 throw 하면 재시도된다"(MegaJob 정본)를 보여준다.
  *   - `fail`  : 매 시도 throw(영구 실패) → 재시도 소진 후 DLQ(`<subject>.dlq`)로 격리된다.
+ *   - `hang`  : payload.delayMs 만큼 잠든다(끝나지 않는 잡 시뮬레이션). delayMs 가 `static timeoutMs`(5s)를
+ *               넘으면 MegaJobQueue 가 run 전체에 건 상한을 초과로 판정해 잡을 실패시키고 DLQ 로 보낸다.
+ *               timeout 후에도 run 은 백그라운드에서 계속 흐르므로(abort 없음) delayMs 뒤 'sent' 가 뒤늦게
+ *               남는다 — "run 은 멱등하게 설계하라"는 정본 경고를 눈으로 보여준다.
  *
  * 각 시도를 'demo' 캐시(redis)에 기록해(시도 카운터 + 이벤트 LIST) 웹 페이지가 처리 타임라인을 보여준다.
  * NATS durable consumer group(같은 durable 이름)이라 instances:2 워커가 메시지를 자연 분산 처리한다(중복 X).
@@ -25,6 +47,9 @@ export class EmailJob extends MegaJob {
   // 추가 재시도 2회(첫 시도 포함 최대 3회). 데모 체감용으로 백오프를 짧게 둔다(기본 1s~30s 대신 0.5s~2s).
   static retries = 2
   static backoff = { type: 'exponential', initial: 500, max: 2000 }
+  // run 전체(재시도 포함) 상한 — 'hang' 모드 timeout 시연(미지정이면 큐 디폴트 30분이라 체감 불가). ok/flaky/
+  // fail 은 < 3s 라 영향 없다(fail 백오프 최악치 ~3s + 마진). 초과 run 은 timeout 실패 → DLQ.
+  static timeoutMs = RUN_TIMEOUT_MS
 
   /** 이벤트 LIST 키(LPUSH → 최신이 앞). 웹이 LRANGE 로 읽는다. */
   static EVENTS_KEY = 'demo:jobs:events'
@@ -33,7 +58,7 @@ export class EmailJob extends MegaJob {
 
   /**
    * 메시지 1건 처리. throw 하면 MegaJobQueue 가 재시도/DLQ 를 담당하므로 일시·영구 실패는 그냥 throw 한다.
-   * @param {{ id: string, to: string, subject?: string, mode: 'ok'|'flaky'|'fail' }} payload
+   * @param {{ id: string, to: string, subject?: string, mode: 'ok'|'flaky'|'fail'|'hang', delayMs?: number }} payload
    * @param {Record<string, any>} ctx - worker 프로세스 컨텍스트(ctx.cache('demo') 글로벌 키).
    * @returns {Promise<{ id: string, status: 'sent', attempt: number }>}
    * @throws {Error} flaky 의 1번째 시도, fail 의 모든 시도 — 재시도/DLQ 트리거.
@@ -46,6 +71,16 @@ export class EmailJob extends MegaJob {
     await redis.expire(`demo:jobs:attempt:${id}`, ATTEMPT_TTL)
     ctx.log?.debug?.({ id, mode, attempt }, 'email-job.run')
 
+    if (mode === 'hang') {
+      // 오래 끄는 잡 — delayMs 가 static timeoutMs(5s)를 넘으면 큐가 run 상한 초과로 판정해 잡을 실패시키고
+      // DLQ 로 보낸다(fail(phase:'run') + dlq, ADR-223 로깅으로 표면화). timeout 후에도 이 run 은 백그라운드
+      // 에서 계속 흘러(abort 없음) delayMs 뒤 'sent' 를 뒤늦게 남긴다 — 멱등 설계 경고를 눈으로 보여준다.
+      const delayMs = Number.isInteger(payload.delayMs) ? /** @type {number} */ (payload.delayMs) : HANG_DEFAULT_DELAY_MS
+      await EmailJob.#logEvent(redis, { id, to, mode, attempt, status: 'running' })
+      await sleep(delayMs)
+      await EmailJob.#logEvent(redis, { id, to, mode, attempt, status: 'sent' })
+      return { id, status: 'sent', attempt }
+    }
     if (mode === 'flaky' && attempt < FLAKY_SUCCEED_ON) {
       await EmailJob.#logEvent(redis, { id, to, mode, attempt, status: 'retry' })
       throw new Error(`EmailJob ${id}: simulated transient failure on attempt ${attempt} (will retry)`)
@@ -62,7 +97,7 @@ export class EmailJob extends MegaJob {
   /**
    * 처리 이벤트 1건을 redis LIST 머리에 넣고 최근 N건만 남긴다.
    * @param {any} redis - ioredis 핸들(ctx.cache('demo').native).
-   * @param {{ id: string, to: string, mode: string, attempt: number, status: 'retry'|'failed'|'sent' }} event
+   * @param {{ id: string, to: string, mode: string, attempt: number, status: 'retry'|'failed'|'sent'|'running' }} event
    * @returns {Promise<void>}
    */
   static async #logEvent(redis, event) {

package/sample/crud/apps/main/locales/server/en.json

@@ -221,6 +221,8 @@
   "ws_encrypted_note": "Messages are encrypted with ASP (AES-256-GCM) E: frames in transit.",
   "nav_cron": "Scheduler (Cron)",
   "nav_jobs": "Job Queue (NATS)",
+  "nav_lock": "Distributed Lock",
+  "nav_bus": "Message Bus",
   "nav_worker": "Workers (Threads)",
   "home_demo_cron": "Scheduler demo",
   "home_demo_jobs": "Job queue demo",
@@ -251,12 +253,16 @@
   "jobs_reload": "Reload",
   "jobs_field_to": "Recipient",
   "jobs_field_mode": "Mode",
+  "jobs_field_delay": "Delay (ms) — hang mode only",
+  "jobs_field_delay_hint": "Leave blank for the default 8000ms. Exceeding 5000ms (timeoutMs) isolates the job to the DLQ on timeout.",
   "jobs_mode_ok": "Success",
   "jobs_mode_flaky": "Retry",
   "jobs_mode_fail": "Permanent failure",
+  "jobs_mode_hang": "Timeout",
   "jobs_mode_ok_hint": "succeeds on the first attempt",
   "jobs_mode_flaky_hint": "1st attempt fails → retry → 2nd succeeds",
   "jobs_mode_fail_hint": "every attempt fails → DLQ after retries are exhausted",
+  "jobs_mode_hang_hint": "hangs for delayMs → exceeds 5s (timeoutMs) → timeout → DLQ",
   "jobs_dlq_title": "DLQ (isolated jobs)",
   "jobs_dlq_desc": "Where permanently failed jobs land after retries are exhausted (a NATS stream). For analysis and reprocessing.",
   "jobs_dlq_empty": "No jobs have reached the DLQ yet.",
@@ -274,6 +280,7 @@
   "jobs_status_sent": "sent",
   "jobs_status_retry": "retry",
   "jobs_status_failed": "failed",
+  "jobs_status_running": "running",
   "jobs_notice_enqueued": "Job enqueued. Once a worker processes it, it appears in the events below.",
   "worker_title": "CPU worker demo (MegaWorker)",
   "worker_subtitle": "Runs CPU-bound work like N rounds of SHA-256 in a worker_threads pool. A heartbeat confirms the server still answers other requests instantly while computing (main thread non-blocking).",
@@ -324,5 +331,33 @@
   "field_phone": "전화번호",
   "field_phone_ph": "예: 010-1234-5678",
   "col_username": "아이디",
-  "col_nickname": "별명"
+  "col_nickname": "별명",
+  "lock_title": "분산 락 데모",
+  "lock_subtitle": "ctx.lock.with / tryAcquire 로 임계구역을 보호합니다. 두 탭에서 같은 키로 동시에 실행하면 한 번에 하나만 들어가고(상호배제), FIFO 면 도착 순서대로 깨어납니다.",
+  "lock_run_title": "임계구역 실행",
+  "lock_run_desc": "키를 잡고 holdMs 동안 점유한 뒤 자동 해제합니다(ctx.lock.with). 다른 시도는 waitMs 까지 대기합니다.",
+  "lock_f_key": "자원 키",
+  "lock_f_fifo": "(도착 순서 보장)",
+  "lock_f_fence": "(단조 토큰)",
+  "lock_f_ext": "(watchdog 자동연장)",
+  "lock_btn_run": "실행 (with)",
+  "lock_btn_try": "tryAcquire",
+  "lock_status_title": "현재 상태",
+  "lock_active": "보유 중",
+  "lock_waiting": "대기 중",
+  "lock_worker_pid": "이 페이지를 처리한 워커 PID",
+  "lock_log_title": "최근 실행 (이 워커)",
+  "lock_log_result": "결과",
+  "bus_title": "메시지 버스 데모",
+  "bus_subtitle": "ctx.bus.emit / on / request 로 이벤트를 주고받습니다. 이 페이지는 demo.> 를 구독해 수신 이벤트를 실시간(폴링) 표시합니다 — 다른 워커가 발행해도 fan-out 으로 도착합니다.",
+  "bus_emit_title": "발행 (emit)",
+  "bus_emit_desc": "subject 와 payload(JSON)를 fan-out 발행합니다. persist:true 면 JetStream 에 저장됩니다.",
+  "bus_btn_emit": "Emit",
+  "bus_req_title": "요청/응답 (request)",
+  "bus_req_desc": "demo.echo 응답자가 첫 응답을 돌려줍니다 — 어느 워커가 답했는지 PID 로 보입니다.",
+  "bus_btn_request": "Request demo.echo",
+  "bus_recv_title": "수신 이벤트",
+  "bus_recv_pid": "구독 워커",
+  "bus_recv_desc": "서버가 demo.> 를 구독합니다 — * 는 한 토큰, > 는 꼬리 전체. order.created / order.created.eu / user.login 모두 demo.> 에 매칭됩니다. persist 이벤트는 배지로 구분됩니다.",
+  "bus_recv_pid_col": "수신 워커"
 }