mega-framework 0.1.9 → 0.1.11

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

@@ -251,12 +251,16 @@
   "jobs_reload": "새로고침",
   "jobs_field_to": "받는 사람",
   "jobs_field_mode": "모드",
+  "jobs_field_delay": "지연(ms) — hang 모드 전용",
+  "jobs_field_delay_hint": "비워두면 기본 8000ms. 5000ms(timeoutMs) 초과 시 timeout 으로 DLQ 격리됩니다.",
   "jobs_mode_ok": "성공",
   "jobs_mode_flaky": "재시도",
   "jobs_mode_fail": "영구 실패",
+  "jobs_mode_hang": "타임아웃",
   "jobs_mode_ok_hint": "첫 시도에 바로 성공",
   "jobs_mode_flaky_hint": "1번째 시도 실패 → 재시도 → 2번째 성공",
   "jobs_mode_fail_hint": "매 시도 실패 → 재시도 소진 후 DLQ 격리",
+  "jobs_mode_hang_hint": "delayMs 만큼 지연 → 5초(timeoutMs) 초과 시 timeout → DLQ",
   "jobs_dlq_title": "DLQ (격리된 잡)",
   "jobs_dlq_desc": "재시도를 모두 소진한 영구 실패 잡이 모이는 곳입니다(NATS 스트림). 원인 분석·재처리용.",
   "jobs_dlq_empty": "아직 DLQ 로 간 잡이 없습니다.",
@@ -274,6 +278,7 @@
   "jobs_status_sent": "발송됨",
   "jobs_status_retry": "재시도",
   "jobs_status_failed": "실패",
+  "jobs_status_running": "처리 중",
   "jobs_notice_enqueued": "잡을 큐에 넣었습니다. 워커가 처리하면 아래 이벤트에 나타납니다.",
   "worker_title": "CPU 워커 데모 (MegaWorker)",
   "worker_subtitle": "SHA-256 N회 반복 같은 CPU-bound 작업을 worker_threads 풀에서 돌립니다. 계산 도중에도 서버가 다른 요청에 즉시 응답하는지(메인 스레드 non-block) 하트비트로 확인합니다.",
@@ -324,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()
+})()

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

@@ -0,0 +1,122 @@
+// @ts-check
+/*
+ * /demo/lock 클라이언트 — 분산 락 데모(ADR-226).
+ *
+ *  - 실행/시도: 버튼이 /demo/lock/run · /demo/lock/try 에 JSON POST(폼 아님 → CSRF 토큰 면제 + Origin 검증,
+ *    ADR-051)로 옵션을 보내 ctx.lock.with / tryAcquire 결과(획득 여부·워커 PID·대기시간·fence)를 보여준다.
+ *  - 상태: 2초마다 /demo/lock/status 를 폴링해 보유/대기 수(stats)와 워커별 최근 실행 로그를 갱신한다(탭 숨김 시 멈춤).
+ *    폴링 간격은 앱 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 readBody() {
+    return {
+      key: $('lk-key').value || 'demo:resource',
+      ttl: Number($('lk-ttl').value) || 5000,
+      waitMs: Number($('lk-wait').value),
+      holdMs: Number($('lk-hold').value),
+      fifo: $('lk-fifo').checked,
+      fence: $('lk-fence').checked,
+      extendable: $('lk-ext').checked,
+    }
+  }
+
+  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
+      })
+    })
+  }
+
+  function showResult(/** @type {any} */ d) {
+    var ok = d.acquired
+    var cls = ok ? 'alert-success' : 'alert-warning'
+    var label = ok ? '획득' : d.reason === 'held' ? '이미 보유 중(즉시 실패)' : '경합 — 대기 후 실패'
+    var bits = ['worker PID <code>' + esc(d.pid) + '</code>']
+    if (d.waitedMs != null) bits.push('대기 ' + esc(d.waitedMs) + 'ms')
+    if (d.heldMs != null) bits.push('보유 ' + esc(d.heldMs) + 'ms')
+    if (d.fence != null) bits.push('fence <code>' + esc(d.fence) + '</code>')
+    $('lk-result').innerHTML =
+      '<div class="alert ' + cls + ' py-2 px-3 mb-0"><strong>' + esc(label) + '</strong> · ' + bits.join(' · ') + '</div>'
+  }
+
+  function run(/** @type {string} */ url) {
+    $('lk-result').innerHTML = '<div class="text-body-secondary">실행 중…</div>'
+    postJson(url, readBody())
+      .then(showResult)
+      .catch(function (e) {
+        $('lk-result').innerHTML = '<div class="alert alert-danger py-2 px-3 mb-0">오류: ' + esc(e.message) + '</div>'
+      })
+  }
+
+  $('lk-run').addEventListener('click', function () {
+    run('/demo/lock/run')
+  })
+  $('lk-try').addEventListener('click', function () {
+    run('/demo/lock/try')
+  })
+
+  // ── 상태 폴링 ─────────────────────────────────────────────────────────────
+  var POLL_MS = 2000
+  function renderLog(/** @type {any[]} */ rows) {
+    $('lk-log').innerHTML = (rows || [])
+      .map(function (r) {
+        var res = r.acquired ? '<span class="text-success">획득</span>' : '<span class="text-warning">' + (r.reason === 'held' ? 'held' : 'wait') + '</span>'
+        if (r.fence != null) res += ' f' + esc(r.fence)
+        return (
+          '<tr><td class="text-body-secondary">' +
+          esc((r.at || '').slice(11, 19)) +
+          '</td><td><code>' +
+          esc(r.key) +
+          '</code></td><td>' +
+          esc(r.pid) +
+          '</td><td>' +
+          res +
+          '</td><td>' +
+          (r.waitedMs != null ? esc(r.waitedMs) + 'ms' : '–') +
+          '</td></tr>'
+        )
+      })
+      .join('')
+  }
+  function poll() {
+    if (document.hidden) {
+      setTimeout(poll, POLL_MS)
+      return
+    }
+    fetch('/demo/lock/status', { headers: { accept: 'application/json' } })
+      .then(function (res) {
+        return res.json()
+      })
+      .then(function (j) {
+        var d = j.data != null ? j.data : j
+        if (d.stats) {
+          $('lk-active').textContent = String(d.stats.active)
+          $('lk-waiting').textContent = String(d.stats.waiting)
+          $('lk-driver').textContent = d.stats.driver
+        }
+        renderLog(d.runLog)
+      })
+      .catch(function () {
+        /* 폴링 실패는 비치명적 — 다음 주기에 재시도 */
+      })
+      .then(function () {
+        setTimeout(poll, POLL_MS)
+      })
+  }
+  poll()
+})()

package/sample/crud/apps/main/routes/bus.js

@@ -0,0 +1,43 @@
+// @ts-check
+/**
+ * apps/main/routes/bus.js — /demo/bus 메시지 버스 데모 UI 라우트(자동 로딩, loadRoutes, ADR-157).
+ *
+ * `ctx.bus.emit/.on/.request`(ADR-227) 사용자 메시지 버스 API 를 시연한다. 페이지는 `webRequireAuth`(ADR-155)로
+ * 보호한다. 발행/요청/수신조회는 페이지가 fetch(JSON)로 호출 — JSON POST 는 CSRF 면제 + Origin 검사라
+ * body 스키마는 `additionalProperties:false` 로 닫는다(ADR-074 envelope).
+ */
+import { BusController } from '../controllers/bus-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+/** emit body — subject(구체, wildcard 금지는 매니저가 검증) + payload(임의 객체) + 옵트인 플래그. */
+const emitBody = {
+  type: 'object',
+  required: ['subject'],
+  properties: {
+    subject: { type: 'string', minLength: 1, maxLength: 120 },
+    payload: { type: 'object' },
+    persist: { type: 'boolean' },
+    ordered: { type: 'boolean' },
+  },
+  additionalProperties: false,
+}
+
+/** request body — subject + payload + timeout. */
+const requestBody = {
+  type: 'object',
+  properties: {
+    subject: { type: 'string', minLength: 1, maxLength: 120 },
+    payload: { type: 'object' },
+    timeout: { type: 'integer', minimum: 100, maximum: 10_000 },
+  },
+  additionalProperties: false,
+}
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/demo/bus', BusController.index, guarded)
+  router.http.post('/demo/bus/emit', BusController.emit, { ...guarded, schema: { body: emitBody } })
+  router.http.post('/demo/bus/request', BusController.request, { ...guarded, schema: { body: requestBody } })
+  router.http.get('/demo/bus/events', BusController.events, guarded)
+}

package/sample/crud/apps/main/routes/lock.js

@@ -0,0 +1,35 @@
+// @ts-check
+/**
+ * apps/main/routes/lock.js — /demo/lock 분산 락 데모 UI 라우트(자동 로딩, loadRoutes, ADR-157).
+ *
+ * `ctx.lock.with/.tryAcquire`(ADR-226) 사용자 분산 락 API 를 시연한다. 페이지는 `webRequireAuth`(ADR-155)로
+ * 보호한다. 락 실행/시도/상태 조회는 페이지가 fetch(JSON)로 호출한다 — JSON POST 는 CSRF 토큰 면제 + Origin
+ * 검사라(ADR-074 envelope) body 스키마는 `additionalProperties:false` 로 닫는다.
+ */
+import { LockController } from '../controllers/lock-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+/** run/tryRun body 스키마 — 타입·범위만 본다(ttl/waitMs/holdMs 는 데모 안전 상한). */
+const runBody = {
+  type: 'object',
+  required: ['key'],
+  properties: {
+    key: { type: 'string', minLength: 1, maxLength: 80 },
+    ttl: { type: 'integer', minimum: 100, maximum: 60_000 },
+    waitMs: { type: 'integer', minimum: 0, maximum: 30_000 },
+    holdMs: { type: 'integer', minimum: 0, maximum: 15_000 },
+    fifo: { type: 'boolean' },
+    fence: { type: 'boolean' },
+    extendable: { type: 'boolean' },
+  },
+  additionalProperties: false,
+}
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/demo/lock', LockController.index, guarded)
+  router.http.post('/demo/lock/run', LockController.run, { ...guarded, schema: { body: runBody } })
+  router.http.post('/demo/lock/try', LockController.tryRun, { ...guarded, schema: { body: runBody } })
+  router.http.get('/demo/lock/status', LockController.status, guarded)
+}

package/sample/crud/apps/main/services/jobs-demo-service.js

@@ -1,9 +1,12 @@
 // @ts-check
 import { MegaService, MegaJobQueue } from 'mega-framework'
+// raw nats 핸들(`.native`, ADR-009)로 DLQ 스트림을 직접 읽으려면 드라이버 v3 API 를 쓴다(ADR-225):
+// jetstreamManager 는 함수, not-found 는 JetStreamApiError(code) 로 바뀌었다. .native 는 버전-결합 escape hatch.
+import { jetstreamManager, JetStreamApiError, JetStreamApiCodes } from '@nats-io/jetstream'
 import { EmailJob } from '../jobs/email-job.js'
 
-/** JetStream NOT_FOUND API 에러 코드(스트림/메시지 없음) — mega-job-queue 의 동일 상수와 정합. */
-const NOT_FOUND_CODE = '404'
+/** JetStream stream-not-found 판별(v3) — `e instanceof JetStreamApiError && code===StreamNotFound`. @param {unknown} e @returns {boolean} */
+const isStreamNotFound = (e) => e instanceof JetStreamApiError && e.code === JetStreamApiCodes.StreamNotFound
 
 /**
  * EmailJob 의 DLQ 스트림/서브젝트 이름. MegaJobQueue 는 `<subject>.dlq` 로 발행하고 DLQ 스트림을
@@ -25,7 +28,7 @@ const DLQ_STREAM = `MEGA_JOBS_${EmailJob.subject.replace(/[^A-Za-z0-9_-]/g, '_')
 export class JobsDemoService extends MegaService {
   /**
    * EmailJob 1건을 큐에 넣는다(JetStream publish — 서버에 영속 저장 후 워커가 가져감).
-   * @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
    * @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
    */
   async enqueue(payload) {
@@ -53,30 +56,34 @@ export class JobsDemoService extends MegaService {
    */
   async dlq() {
     const nc = this.ctx.bus('jobs').native
-    const jsm = await nc.jetstreamManager()
+    const jsm = await jetstreamManager(nc)
     let count = 0
     try {
       const info = await jsm.streams.info(DLQ_STREAM)
       count = info.state.messages
     } catch (e) {
-      // 스트림 미존재(404)는 "DLQ 로 간 잡이 아직 없음" — 빈 상태로 본다. 그 외(연결 장애 등)는 전파.
-      if (/** @type {any} */ (e)?.code !== NOT_FOUND_CODE) throw e
-      return { count: 0, latest: null }
+      // 스트림 미존재는 "DLQ 로 간 잡이 아직 없음" — 빈 상태(count=0)로 본다. 그 외(연결 장애 등)는 전파.
+      if (!isStreamNotFound(e)) throw e
+      return { count, latest: null }
     }
     if (count === 0) return { count, latest: null }
     let latest = null
     try {
+      // v3(ADR-225): getMessage 는 메시지 없음을 **null** 로 반환한다(v2 는 404 throw 였다). count>0 직후
+      // 경쟁 삭제로 null 이면 latest 없이 카운트만 보여준다.
       const msg = await jsm.streams.getMessage(DLQ_STREAM, { last_by_subj: DLQ_SUBJECT })
-      const body = /** @type {any} */ (msg.json())
-      latest = {
-        failedAt: body.failedAt,
-        deliveryCount: body.deliveryCount,
-        error: body.error?.message ?? String(body.error ?? ''),
-        payload: body.payload,
+      if (msg) {
+        const body = /** @type {any} */ (msg.json())
+        latest = {
+          failedAt: body.failedAt,
+          deliveryCount: body.deliveryCount,
+          error: body.error?.message ?? String(body.error ?? ''),
+          payload: body.payload,
+        }
       }
     } catch (e) {
-      // 카운트는 있으나 마지막 메시지 조회가 404(경쟁 삭제 등)면 latest 없이 카운트만 보여준다. 그 외는 전파.
-      if (/** @type {any} */ (e)?.code !== NOT_FOUND_CODE) throw e
+      // 카운트 조회 후 스트림이 통째로 사라진 race 면 latest 없이 카운트만. 그 외(연결 장애 등)는 전파.
+      if (!isStreamNotFound(e)) throw e
     }
     return { count, latest }
   }

package/sample/crud/apps/main/views/bus/index.ejs

@@ -0,0 +1,80 @@
+<% layout('layouts/main') %>
+
+<div class="mb-4">
+  <h1 class="h3 mb-1"><%= t('bus_title', { defaultValue: '메시지 버스 데모' }) %></h1>
+  <p class="text-body-secondary small mb-0">
+    <%= t('bus_subtitle', { defaultValue: 'ctx.bus.emit / on / request 로 이벤트를 주고받습니다. 이 페이지는 demo.> 를 구독해 수신 이벤트를 실시간(폴링) 표시합니다 — 다른 워커가 발행해도 fan-out 으로 도착합니다.' }) %>
+    <a href="/guide" class="ms-1">ADR-227 · 가이드</a>
+  </p>
+</div>
+
+<div class="row g-3">
+  <!-- 발행 + 요청 -->
+  <div class="col-lg-5">
+    <div class="card mb-3">
+      <div class="card-body">
+        <h2 class="h5 card-title"><%= t('bus_emit_title', { defaultValue: '발행 (emit)' }) %></h2>
+        <p class="card-text text-body-secondary small mb-2"><%= t('bus_emit_desc', { defaultValue: 'subject 와 payload(JSON)를 fan-out 발행합니다. persist:true 면 JetStream 에 저장됩니다.' }) %></p>
+        <label class="form-label small mb-1" for="bus-subject">subject</label>
+        <input id="bus-subject" class="form-control form-control-sm mb-2" value="demo.order.created" maxlength="120">
+        <div class="d-flex flex-wrap gap-1 mb-2">
+          <button type="button" class="btn btn-outline-secondary btn-sm py-0 px-2 bus-preset" data-s="demo.order.created">order.created</button>
+          <button type="button" class="btn btn-outline-secondary btn-sm py-0 px-2 bus-preset" data-s="demo.order.created.eu">order.created.eu</button>
+          <button type="button" class="btn btn-outline-secondary btn-sm py-0 px-2 bus-preset" data-s="demo.user.login">user.login</button>
+        </div>
+        <label class="form-label small mb-1" for="bus-payload">payload (JSON)</label>
+        <textarea id="bus-payload" class="form-control form-control-sm font-monospace" rows="3">{ "orderId": 42 }</textarea>
+        <div class="d-flex flex-wrap gap-3 mt-2">
+          <div class="form-check form-switch">
+            <input id="bus-persist" class="form-check-input" type="checkbox">
+            <label class="form-check-label small" for="bus-persist">persist <span class="text-body-secondary">(JetStream)</span></label>
+          </div>
+          <div class="form-check form-switch">
+            <input id="bus-ordered" class="form-check-input" type="checkbox">
+            <label class="form-check-label small" for="bus-ordered">ordered</label>
+          </div>
+        </div>
+        <button id="bus-emit" class="btn btn-primary btn-sm mt-2"><%= t('bus_btn_emit', { defaultValue: 'Emit' }) %></button>
+        <div id="bus-emit-result" class="mt-2 small"></div>
+      </div>
+    </div>
+
+    <div class="card">
+      <div class="card-body">
+        <h2 class="h5 card-title"><%= t('bus_req_title', { defaultValue: '요청/응답 (request)' }) %></h2>
+        <p class="card-text text-body-secondary small mb-2"><%= t('bus_req_desc', { defaultValue: 'demo.echo 응답자가 첫 응답을 돌려줍니다 — 어느 워커가 답했는지 PID 로 보입니다.' }) %></p>
+        <label class="form-label small mb-1" for="bus-req-payload">payload (JSON)</label>
+        <textarea id="bus-req-payload" class="form-control form-control-sm font-monospace" rows="2">{ "ping": 1 }</textarea>
+        <button id="bus-request" class="btn btn-outline-primary btn-sm mt-2"><%= t('bus_btn_request', { defaultValue: 'Request demo.echo' }) %></button>
+        <div id="bus-req-result" class="mt-2 small"></div>
+        <div class="mt-2"><code class="small">ctx.bus.request('demo.echo', payload, { timeout })</code></div>
+      </div>
+    </div>
+  </div>
+
+  <!-- 수신 패널 -->
+  <div class="col-lg-7">
+    <div class="card h-100">
+      <div class="card-body d-flex flex-column">
+        <div class="d-flex justify-content-between align-items-center">
+          <h2 class="h5 card-title mb-0"><%= t('bus_recv_title', { defaultValue: '수신 이벤트' }) %></h2>
+          <div class="small">
+            driver <span class="badge text-bg-secondary" id="bus-driver"><%= stats ? stats.driver : '?' %></span>
+            · <%= t('bus_recv_pid', { defaultValue: '구독 워커' }) %> <code id="bus-pid"><%= pid %></code>
+          </div>
+        </div>
+        <p class="text-body-secondary small mb-2">
+          <%= t('bus_recv_desc', { defaultValue: '서버가 demo.> 를 구독합니다 — * 는 한 토큰, > 는 꼬리 전체. order.created / order.created.eu / user.login 모두 demo.> 에 매칭됩니다. persist 이벤트는 배지로 구분됩니다.' }) %>
+        </p>
+        <div class="table-responsive flex-grow-1" style="max-height: 520px; overflow-y: auto;">
+          <table class="table table-sm small mb-0">
+            <thead><tr><th>at</th><th>subject</th><th>persist</th><th><%= t('bus_recv_pid_col', { defaultValue: '수신 워커' }) %></th><th>payload</th></tr></thead>
+            <tbody id="bus-events"></tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<script src="/static/js/bus-demo.js"></script>

package/sample/crud/apps/main/views/jobs/index.ejs

@@ -1,8 +1,8 @@
 <% layout('layouts/main') %>
 <%
   function fmt(d) { return new Date(d).toLocaleString('ko-KR', { hour12: false }) }
-  function statusBadge(s) { return s === 'sent' ? 'text-bg-success' : (s === 'retry' ? 'text-bg-warning' : 'text-bg-danger') }
-  function modeBadge(m) { return m === 'ok' ? 'text-bg-success' : (m === 'flaky' ? 'text-bg-warning' : 'text-bg-danger') }
+  function statusBadge(s) { return s === 'sent' ? 'text-bg-success' : (s === 'retry' ? 'text-bg-warning' : (s === 'running' ? 'text-bg-info' : 'text-bg-danger')) }
+  function modeBadge(m) { return m === 'ok' ? 'text-bg-success' : (m === 'flaky' ? 'text-bg-warning' : (m === 'hang' ? 'text-bg-info' : 'text-bg-danger')) }
 %>
 
 <div class="mb-4">
@@ -39,9 +39,15 @@
             <div class="form-text small">
               <%= t('jobs_mode_ok', { defaultValue: '성공' }) %>: <%= t('jobs_mode_ok_hint', { defaultValue: '첫 시도에 바로 성공' }) %><br />
               <%= t('jobs_mode_flaky', { defaultValue: '재시도' }) %>: <%= t('jobs_mode_flaky_hint', { defaultValue: '1번째 시도 실패 → 재시도 → 2번째 성공' }) %><br />
-              <%= t('jobs_mode_fail', { defaultValue: '영구 실패' }) %>: <%= t('jobs_mode_fail_hint', { defaultValue: '매 시도 실패 → 재시도 소진 후 DLQ 격리' }) %>
+              <%= t('jobs_mode_fail', { defaultValue: '영구 실패' }) %>: <%= t('jobs_mode_fail_hint', { defaultValue: '매 시도 실패 → 재시도 소진 후 DLQ 격리' }) %><br />
+              <%= t('jobs_mode_hang', { defaultValue: '타임아웃' }) %>: <%= t('jobs_mode_hang_hint', { defaultValue: 'delayMs 만큼 지연 → 5초(timeoutMs) 초과 시 timeout → DLQ' }) %>
             </div>
           </div>
+          <div class="mb-3">
+            <label for="delayMs" class="form-label small"><%= t('jobs_field_delay', { defaultValue: '지연(ms) — hang 모드 전용' }) %></label>
+            <input type="number" class="form-control form-control-sm" id="delayMs" name="delayMs" min="0" max="600000" step="500" placeholder="8000" />
+            <div class="form-text small"><%= t('jobs_field_delay_hint', { defaultValue: '비워두면 기본 8000ms. 5000ms(timeoutMs) 초과 시 timeout 으로 DLQ 격리됩니다.' }) %></div>
+          </div>
           <button type="submit" class="btn btn-primary btn-sm"><%= t('jobs_enqueue_btn', { defaultValue: '큐에 넣기' }) %></button>
           <a href="/demo/jobs" class="btn btn-outline-secondary btn-sm ms-1"><%= t('jobs_reload', { defaultValue: '새로고침' }) %></a>
         </form>

package/sample/crud/apps/main/views/layouts/main.ejs

@@ -45,6 +45,8 @@
                 <li><a class="dropdown-item" href="/demo/ws"><%= t('nav_ws', '채팅 (WS+ASP)') %></a></li>
                 <li><a class="dropdown-item" href="/demo/cron"><%= t('nav_cron', '스케줄러 (Cron)') %></a></li>
                 <li><a class="dropdown-item" href="/demo/jobs"><%= t('nav_jobs', '잡 큐 (NATS)') %></a></li>
+                <li><a class="dropdown-item" href="/demo/lock"><%= t('nav_lock', '분산 락 (Lock)') %></a></li>
+                <li><a class="dropdown-item" href="/demo/bus"><%= t('nav_bus', '메시지 버스 (Bus)') %></a></li>
                 <li><a class="dropdown-item" href="/demo/worker"><%= t('nav_worker', '워커 (Threads)') %></a></li>
                 <li><hr class="dropdown-divider" /></li>
                 <li><a class="dropdown-item" href="/demo/metrics"><%= t('nav_metrics', '메트릭') %></a></li>