mega-framework 0.1.10 → 0.1.13

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)
@@ -754,12 +802,68 @@ export class User extends MegaModel {
 
 - **옵트인**이다 — `static schema` 가 없는 모델(레거시 raw SQL 운용)은 그냥 무시된다.
 - 같은 `static schema` 선언은 **공통 CRUD([§2-1](#2-1-공통-crud-static-schema-opt-in-adr-212))도 함께 켠다**(SQL 어댑터) — "스키마 1선언 = 마이그레이션 + CRUD".
-- 타입: `serial/bigSerial/integer/bigInteger/smallInteger/real/doublePrecision/decimal(p,s)/varchar(n)/
-  text/char(n)/boolean/timestamp/timestamptz/date/time/uuid/json/jsonb/enum(values)/bytea`.
-- 체인: `.primary() .notNull() .unique({name?}) .default(v | {raw}) .defaultNow() .check(expr,{name?})
-  .references(model, col, {onDelete?, onUpdate?, name?}) .comment(text)`. 복합 PK 는 `t.primary(['a','b'])`.
-- FK 대상은 **모델 이름**(file-scan 범위 안에 있어야 함 — 없으면 fail-fast). 관계는 FK 까지만 —
-  조인 헬퍼/lazy load 같은 ORM 기능은 없다(ADR-009).
+
+#### 컬럼 타입 — `t.<type>()`
+
+각 타입 메서드는 `ColumnBuilder` 를 반환하므로 아래 **수식어를 체인**할 수 있다(`src/core/migration/schema-builder.js`).
+
+| 분류 | 메서드 | 비고 |
+| --- | --- | --- |
+| 정수 | `t.serial()` · `t.bigSerial()` | 자동증가(postgres SERIAL / BIGSERIAL) |
+| 정수 | `t.integer()` · `t.bigInteger()` · `t.smallInteger()` | |
+| 실수 | `t.real()` · `t.doublePrecision()` | |
+| 정밀수 | `t.decimal(precision, scale)` | NUMERIC(p,s) |
+| 문자열 | `t.varchar(maxLength)` · `t.char(length)` · `t.text()` | |
+| 논리 | `t.boolean()` | |
+| 시간 | `t.timestamp()` · `t.timestamptz()` · `t.date()` · `t.time()` | |
+| 기타 | `t.uuid()` · `t.json()` · `t.jsonb()` · `t.bytea()` | |
+| 열거 | `t.enum(values, { name? })` | postgres 는 `TEXT + CHECK (col IN (...))` 로 렌더(native enum 미사용 — 값 추가/삭제가 제약 교체로 단순) |
+| **mongo 전용** | `t.objectId()` · `t.object(shape?)` · `t.array(items?, { uniqueItems? })` | SQL dialect 는 렌더 시 거부. `object`/`array` 의 중첩 필드는 타입·길이·enum·notNull(→required)만 — unique/primary/references/check 는 **최상위 전용** |
+
+#### 컬럼 수식어 (체인) — `ColumnBuilder`
+
+| 메서드 | 뜻 |
+| --- | --- |
+| `.primary()` | 단일 컬럼 PRIMARY KEY. 복합 PK 는 `t.primary(['a','b'])`(아래) |
+| `.notNull()` | NOT NULL |
+| `.nullable()` | 명시 null 허용. SQL 은 기본 nullable 이라 선언적 표시(no-op), mongo 는 `['type','null']` 유니온. `.notNull()` 과 **동시 사용 불가** |
+| `.unique({ name? })` | UNIQUE 제약. 이름 미지정 시 `uniq_<table>_<col>` |
+| `.default(value)` | DEFAULT. literal(string/number/boolean/null) 또는 `{ raw: 'expr' }`(raw SQL 식) |
+| `.defaultNow()` | `DEFAULT CURRENT_TIMESTAMP` 단축 |
+| `.check(expr, { name? })` | CHECK 제약. 이름 미지정 시 `chk_<table>_<col>` |
+| `.references(model, col, { onDelete?, onUpdate?, name? })` | FK. 대상은 **모델 이름**(테이블명 아님 — 스냅샷 시 해석). `onDelete`/`onUpdate` ∈ `cascade · set null · set default · restrict · no action` |
+| `.comment(text)` | `COMMENT ON COLUMN` |
+
+- 테이블 레벨: `t.primary(['a','b'])` — **복합 PRIMARY KEY**(반환값 없음, 컬럼 맵엔 안 들어감). 단일 PK 는 컬럼 체인 `.primary()`.
+- FK 대상 모델은 **file-scan 범위 안에 있어야** 한다(없으면 fail-fast). 관계는 FK 까지만 — 조인 헬퍼/lazy load 같은 ORM 기능은 없다(ADR-009).
+
+#### 인덱스 — `static indexes = (t) => [ t.index(...) ]`
+
+```js
+static indexes = (t) => [
+  t.index(['role', 'createdAt']),                                  // 복합. 이름 자동: idx_<table>_<col…> (= idx_users_role_createdAt)
+  t.index(['email'], { unique: true }),                            // unique 인덱스
+  t.index({ expression: 'lower(email)' }, { name: 'idx_users_email_lower' }),  // 표현식 인덱스
+  t.index(['org_id'], { where: 'deleted_at IS NULL' }),            // 부분 인덱스(조건부)
+  t.index(['payload'], { using: 'gin' }),                          // 인덱스 방법(postgres USING)
+]
+```
+
+| `t.index(컬럼들|식, opts)` 인자 | 뜻 |
+| --- | --- |
+| 1번째: `'col'` / `['a','b']` / `{ expression: 'lower(x)' }` | 단일·복합 컬럼 또는 표현식 인덱스 |
+| `opts.name` | 인덱스 이름 override(기본 dialect 표준명) |
+| `opts.unique` | `true` 면 UNIQUE 인덱스 |
+| `opts.where` | **부분 인덱스** WHERE 조건(예: `'deleted_at IS NULL'`) |
+| `opts.using` | 인덱스 방법(postgres `USING` — 예: `gin`/`gist`/`hash`) |
+
+> 컬럼에 직접 `.unique()` 를 거는 것(=UNIQUE **제약**)과 `t.index([...], { unique: true })`(=UNIQUE **인덱스**)는
+> 비슷하나, 후자는 복합·표현식·부분 인덱스를 지원한다. 단일 컬럼 유일성은 `.unique()` 가 간단하다.
+
+**자동 이름 규칙**(postgres dialect, `{ name }` 미지정 시): 인덱스 `idx_<table>_<cols>` · UNIQUE 인덱스/제약
+`uniq_<table>_<cols>` · FK `fk_<table>_<col>_<reftable>` · CHECK `chk_<table>_<col>`. 63byte 초과 시 거부되니
+길면 `{ name }` 으로 짧게 지정한다.
+
 - 제외 규칙: `_` 로 시작하는 파일/폴더, `*.test.js`, `static skip = true`.
 - 식별자는 63byte(postgres 한도)를 넘으면 거부된다 — 합성 이름(`fk_…`)이 걸리면 `{name}` 으로
   짧은 이름을 명시하면 된다.

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' })
 ```