mega-framework 0.1.10 → 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.10",
+  "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/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/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",
@@ -329,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": "수신 워커"
 }

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

@@ -329,5 +329,35 @@
   "field_phone": "전화번호",
   "field_phone_ph": "예: 010-1234-5678",
   "col_username": "아이디",
-  "col_nickname": "별명"
+  "col_nickname": "별명",
+  "nav_lock": "Distributed Lock",
+  "nav_bus": "Message Bus",
+  "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": "수신 워커"
 }

package/sample/crud/apps/main/public/js/bus-demo.js

@@ -0,0 +1,131 @@
+// @ts-check
+/*
+ * /demo/bus 클라이언트 — 메시지 버스 데모(ADR-227).
+ *
+ *  - 발행/요청: 버튼이 /demo/bus/emit · /demo/bus/request 에 JSON POST(폼 아님 → CSRF 면제 + Origin 검증).
+ *  - 수신: 2초마다 /demo/bus/events 를 폴링해 이 워커가 demo.> 로 받은 이벤트(subject·persist·수신 PID·payload)를
+ *    보여준다(탭 숨김 시 멈춤). 폴링 간격은 앱 rate limit(100/분, ADR-073) 안에 둔다.
+ */
+;(function () {
+  var $ = function (/** @type {string} */ id) {
+    return /** @type {any} */ (document.getElementById(id))
+  }
+  function esc(/** @type {any} */ s) {
+    return String(s == null ? '' : s).replace(/[&<>"]/g, function (c) {
+      return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]
+    })
+  }
+  function parseJson(/** @type {string} */ text, /** @type {any} */ fallback) {
+    try {
+      return JSON.parse(text)
+    } catch {
+      return fallback
+    }
+  }
+  function postJson(/** @type {string} */ url, /** @type {any} */ body) {
+    return fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify(body),
+    }).then(function (res) {
+      return res.json().then(function (j) {
+        if (!res.ok) throw new Error((j && j.error && j.error.code) || 'http ' + res.status)
+        return j.data != null ? j.data : j
+      })
+    })
+  }
+
+  // ── presets ──────────────────────────────────────────────────────────────
+  var presets = document.querySelectorAll('.bus-preset')
+  for (var i = 0; i < presets.length; i++) {
+    presets[i].addEventListener('click', function (/** @type {any} */ ev) {
+      $('bus-subject').value = ev.target.getAttribute('data-s')
+    })
+  }
+
+  // ── emit ─────────────────────────────────────────────────────────────────
+  $('bus-emit').addEventListener('click', function () {
+    var payload = parseJson($('bus-payload').value, null)
+    if (payload === null || typeof payload !== 'object') {
+      $('bus-emit-result').innerHTML = '<div class="alert alert-danger py-1 px-2 mb-0">payload 가 JSON 객체가 아닙니다.</div>'
+      return
+    }
+    postJson('/demo/bus/emit', {
+      subject: $('bus-subject').value,
+      payload: payload,
+      persist: $('bus-persist').checked,
+      ordered: $('bus-ordered').checked,
+    })
+      .then(function (d) {
+        $('bus-emit-result').innerHTML =
+          '<div class="alert alert-success py-1 px-2 mb-0">발행됨 · <code>' + esc(d.subject) + '</code>' + (d.persist ? ' · <span class="badge text-bg-info">persist</span>' : '') + ' · PID <code>' + esc(d.pid) + '</code></div>'
+      })
+      .catch(function (e) {
+        $('bus-emit-result').innerHTML = '<div class="alert alert-danger py-1 px-2 mb-0">오류: ' + esc(e.message) + '</div>'
+      })
+  })
+
+  // ── request ──────────────────────────────────────────────────────────────
+  $('bus-request').addEventListener('click', function () {
+    var payload = parseJson($('bus-req-payload').value, {})
+    $('bus-req-result').innerHTML = '<div class="text-body-secondary">요청 중…</div>'
+    postJson('/demo/bus/request', { subject: 'demo.echo', payload: payload, timeout: 2000 })
+      .then(function (d) {
+        if (!d.ok) {
+          $('bus-req-result').innerHTML = '<div class="alert alert-warning py-1 px-2 mb-0">' + esc(d.error) + '</div>'
+          return
+        }
+        $('bus-req-result').innerHTML =
+          '<div class="alert alert-success py-1 px-2 mb-0">응답 받음 · 답한 워커 PID <code>' + esc(d.reply && d.reply.pid) + '</code><br><code>' + esc(JSON.stringify(d.reply && d.reply.echo)) + '</code></div>'
+      })
+      .catch(function (e) {
+        $('bus-req-result').innerHTML = '<div class="alert alert-danger py-1 px-2 mb-0">오류: ' + esc(e.message) + '</div>'
+      })
+  })
+
+  // ── 수신 폴링 ─────────────────────────────────────────────────────────────
+  var POLL_MS = 2000
+  function renderEvents(/** @type {any[]} */ rows) {
+    $('bus-events').innerHTML = (rows || [])
+      .map(function (r) {
+        var badge = r.persisted ? '<span class="badge text-bg-info">persist</span>' : '<span class="text-body-secondary">core</span>'
+        return (
+          '<tr><td class="text-body-secondary">' +
+          esc((r.at || '').slice(11, 19)) +
+          '</td><td><code>' +
+          esc(r.subject) +
+          '</code></td><td>' +
+          badge +
+          '</td><td>' +
+          esc(r.pid) +
+          '</td><td><code class="small">' +
+          esc(JSON.stringify(r.payload)) +
+          '</code></td></tr>'
+        )
+      })
+      .join('')
+  }
+  function poll() {
+    if (document.hidden) {
+      setTimeout(poll, POLL_MS)
+      return
+    }
+    fetch('/demo/bus/events', { headers: { accept: 'application/json' } })
+      .then(function (res) {
+        return res.json()
+      })
+      .then(function (j) {
+        var d = j.data != null ? j.data : j
+        if (d.driver) $('bus-driver').textContent = d.driver
+        if (d.pid != null) $('bus-pid').textContent = String(d.pid)
+        renderEvents(d.events)
+      })
+      .catch(function () {
+        /* 비치명적 — 다음 주기에 재시도 */
+      })
+      .then(function () {
+        setTimeout(poll, POLL_MS)
+      })
+  }
+  poll()
+})()