mega-framework 0.1.10 → 0.1.11

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 스트림을
@@ -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/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>

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

@@ -0,0 +1,99 @@
+<% layout('layouts/main') %>
+
+<div class="mb-4">
+  <h1 class="h3 mb-1"><%= t('lock_title', { defaultValue: '분산 락 데모' }) %></h1>
+  <p class="text-body-secondary small mb-0">
+    <%= t('lock_subtitle', { defaultValue: 'ctx.lock.with / tryAcquire 로 임계구역을 보호합니다. 두 탭에서 같은 키로 동시에 실행하면 한 번에 하나만 들어가고(상호배제), FIFO 면 도착 순서대로 깨어납니다.' }) %>
+    <a href="/guide" class="ms-1">ADR-226 · 가이드</a>
+  </p>
+</div>
+
+<div class="row g-3">
+  <!-- 실행 폼 -->
+  <div class="col-lg-7">
+    <div class="card h-100">
+      <div class="card-body">
+        <h2 class="h5 card-title"><%= t('lock_run_title', { defaultValue: '임계구역 실행' }) %></h2>
+        <p class="card-text text-body-secondary small"><%= t('lock_run_desc', { defaultValue: '키를 잡고 holdMs 동안 점유한 뒤 자동 해제합니다(ctx.lock.with). 다른 시도는 waitMs 까지 대기합니다.' }) %></p>
+
+        <div class="row g-2">
+          <div class="col-12">
+            <label class="form-label small mb-1" for="lk-key"><%= t('lock_f_key', { defaultValue: '자원 키' }) %></label>
+            <input id="lk-key" class="form-control form-control-sm" value="demo:resource" maxlength="80">
+          </div>
+          <div class="col-6 col-md-3">
+            <label class="form-label small mb-1" for="lk-ttl">ttl (ms)</label>
+            <input id="lk-ttl" type="number" class="form-control form-control-sm" value="5000" min="100" max="60000">
+          </div>
+          <div class="col-6 col-md-3">
+            <label class="form-label small mb-1" for="lk-wait">waitMs</label>
+            <input id="lk-wait" type="number" class="form-control form-control-sm" value="3000" min="0" max="30000">
+          </div>
+          <div class="col-6 col-md-3">
+            <label class="form-label small mb-1" for="lk-hold">holdMs</label>
+            <input id="lk-hold" type="number" class="form-control form-control-sm" value="2500" min="0" max="15000">
+          </div>
+        </div>
+
+        <div class="d-flex flex-wrap gap-3 mt-3">
+          <div class="form-check form-switch">
+            <input id="lk-fifo" class="form-check-input" type="checkbox">
+            <label class="form-check-label small" for="lk-fifo">fifo <span class="text-body-secondary"><%= t('lock_f_fifo', { defaultValue: '(도착 순서 보장)' }) %></span></label>
+          </div>
+          <div class="form-check form-switch">
+            <input id="lk-fence" class="form-check-input" type="checkbox">
+            <label class="form-check-label small" for="lk-fence">fence <span class="text-body-secondary"><%= t('lock_f_fence', { defaultValue: '(단조 토큰)' }) %></span></label>
+          </div>
+          <div class="form-check form-switch">
+            <input id="lk-ext" class="form-check-input" type="checkbox">
+            <label class="form-check-label small" for="lk-ext">extendable <span class="text-body-secondary"><%= t('lock_f_ext', { defaultValue: '(watchdog 자동연장)' }) %></span></label>
+          </div>
+        </div>
+
+        <div class="d-flex gap-2 mt-3">
+          <button id="lk-run" class="btn btn-primary btn-sm"><%= t('lock_btn_run', { defaultValue: '실행 (with)' }) %></button>
+          <button id="lk-try" class="btn btn-outline-secondary btn-sm"><%= t('lock_btn_try', { defaultValue: 'tryAcquire' }) %></button>
+        </div>
+
+        <div id="lk-result" class="mt-3 small"></div>
+        <div class="mt-3"><code class="small">ctx.lock.with(key, { ttl, waitMs, fifo, fence, extendable }, fn)</code></div>
+      </div>
+    </div>
+  </div>
+
+  <!-- 상태 패널 -->
+  <div class="col-lg-5">
+    <div class="card h-100">
+      <div class="card-body">
+        <h2 class="h5 card-title"><%= t('lock_status_title', { defaultValue: '현재 상태' }) %></h2>
+        <div class="d-flex gap-4 mb-2">
+          <div>
+            <div class="h4 fw-bold mb-0" id="lk-active"><%= stats ? stats.active : '–' %></div>
+            <div class="text-body-secondary small"><%= t('lock_active', { defaultValue: '보유 중' }) %></div>
+          </div>
+          <div>
+            <div class="h4 fw-bold mb-0" id="lk-waiting"><%= stats ? stats.waiting : '–' %></div>
+            <div class="text-body-secondary small"><%= t('lock_waiting', { defaultValue: '대기 중' }) %></div>
+          </div>
+          <div>
+            <div class="h6 fw-bold mb-0"><span class="badge text-bg-secondary" id="lk-driver"><%= stats ? stats.driver : '?' %></span></div>
+            <div class="text-body-secondary small">driver</div>
+          </div>
+        </div>
+        <p class="text-body-secondary small mb-2">
+          <%= t('lock_worker_pid', { defaultValue: '이 페이지를 처리한 워커 PID' }) %>: <code><%= pid %></code>
+        </p>
+        <hr>
+        <h3 class="h6"><%= t('lock_log_title', { defaultValue: '최근 실행 (이 워커)' }) %></h3>
+        <div class="table-responsive" style="max-height: 320px; overflow-y: auto;">
+          <table class="table table-sm small mb-0">
+            <thead><tr><th>at</th><th>key</th><th>pid</th><th><%= t('lock_log_result', { defaultValue: '결과' }) %></th><th>wait</th></tr></thead>
+            <tbody id="lk-log"></tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<script src="/static/js/lock-demo.js"></script>

package/sample/crud/docs/guide/03-service-model-db.md

@@ -636,6 +636,54 @@ caches: {
 
 이 셋은 본 문서(Service+Model+DB) 범위 밖이라 이름만 짚는다.
 
+### 분산 락 사용자 API — `ctx.lock.with/.acquire` (ADR-226)
+
+여러 인스턴스가 같은 자원을 동시에 건드리면 안 될 때(재고 차감, 1회성 작업 등) **분산 락**으로 임계구역을
+보호한다. 위 `redlock`(`ctx.lock('main')`, 스케줄 leader election)과 **별개 하위시스템**으로, 별명 선언 없이
+컨트롤러·서비스에서 바로 쓴다.
+
+```js
+// 권장 — 잠그고, 끝나면(성공/예외 무관) 자동 해제
+await ctx.lock.with('stock:sku-42', { ttl: 5000 }, async () => {
+  const row = await stock.byId(42)
+  await stock.update(42, { qty: row.qty - 1 })   // 이 블록은 노드를 넘어 한 번에 하나만 실행
+})
+
+// 즉시 1회 시도(대기 없음) — 못 잡으면 null
+const lock = await ctx.lock.tryAcquire('job:nightly')
+if (lock) { try { /* ... */ } finally { await lock.release() } }
+```
+
+- **옵션**: `ttl`(보유 ms) · `waitMs`(획득 대기 ms, 0=즉시) · `fifo`(도착 순서 보장) · `fence`(단조 토큰
+  `lock.fence`) · `extendable`(긴 작업 자동 연장). `acquire` 는 못 잡으면 `lock.not_acquired`(409) throw,
+  `tryAcquire` 는 `null`.
+- **driver 자동 폴백**: `mega.config.js` 의 `lock` 블록(주석 처리됨 — 풀어서 `cache: 'lock'` 지정)이 있으면
+  **redis**(진짜 분산), 없고 클러스터 워커면 **cluster**(단일 노드), 그 외엔 **memory**(단일 프로세스, 부팅 경고).
+  redis 활성에 **추가 .env 는 불필요** — 기존 `caches.lock`(`REDIS_LOCK_URL`)을 재사용한다.
+
+### 메시지 버스 사용자 API — `ctx.bus.emit/.on/.request` (ADR-227)
+
+서비스끼리 이벤트로 느슨하게 결합할 때(주문 생성 → 이메일·분석 각각 반응) **메시지 버스**를 쓴다. 위
+`services.buses`(`ctx.bus('jobs')`, 잡 큐)와 **별개 하위시스템**으로, 별명 선언 없이 발행/구독한다.
+
+```js
+// fan-out — 구독자 전원 수신 (핸들러는 payload, meta)
+ctx.bus.emit('order.created', { orderId: 42 }, { meta: { traceId } })
+ctx.bus.on('order.created', async (payload) => { await emailService.sendReceipt(payload.orderId) })
+ctx.bus.on('order.*', async (payload, meta) => { /* order.created/updated 등 — '*' 는 한 토큰 */ })
+
+// request/reply — 핸들러 '반환값'이 응답
+ctx.bus.on('catalog.product', async ({ id }) => ({ id, name: 'widget' }))
+const product = await ctx.bus.request('catalog.product', { id: 1 }, { timeout: 1000 })
+```
+
+- **wildcards**(NATS 식): `order.*` = 한 토큰(`order.created` O, `order.created.eu` X), `order.>` = 꼬리 전체.
+- **옵트인**: `{ persist: true }`(JetStream 영속 — nats driver 만; 그 외엔 경고 후 비영속) · `{ ordered: true }`(순서 보장).
+  한 구독자가 throw 해도 다른 구독자·다음 메시지엔 영향 없다(매니저가 잡아 로깅).
+- **driver 자동 폴백**: `mega.config.js` 의 `bus` 블록(주석 처리됨 — 풀어서 `nats: 'jobs'` 지정)이 있으면
+  **nats**(진짜 분산), 없고 클러스터 워커면 **cluster**(단일 노드), 그 외엔 **memory**(단일 프로세스, 부팅 경고).
+  nats 활성에 **추가 .env 는 불필요** — 기존 `buses.jobs`(`NATS_JOBS_URL`)을 재사용한다.
+
 ---
 
 ## 5. mega migrate — 스키마 마이그레이션 (ADR-149)

package/sample/crud/docs/guide/05-scheduler-job-worker.md

@@ -225,7 +225,9 @@ MegaShutdown.register('worker', async () => { await worker.stop() })
 DLQ 상태를 읽는 쪽 예시(`jobs-demo-service.js`):
 
 ```js
-const jsm = await this.ctx.bus('jobs').native.jetstreamManager()
+// nats v3(ADR-225): jetstreamManager 는 nc 메서드가 아니라 @nats-io/jetstream 의 함수다.
+import { jetstreamManager } from '@nats-io/jetstream'
+const jsm = await jetstreamManager(this.ctx.bus('jobs').native)
 const info = await jsm.streams.info('MEGA_JOBS_demo_email_DLQ')   // count = info.state.messages
 const msg = await jsm.streams.getMessage(DLQ_STREAM, { last_by_subj: 'demo.email.dlq' })
 ```