mega-framework 0.1.10 → 0.1.11

package/sample/crud/docs/guide/09-distributed-lock-and-bus.md

@@ -0,0 +1,224 @@
+# 분산 락 · 메시지 버스
+
+여러 인스턴스(클러스터 워커·여러 노드)가 같은 자원을 동시에 건드리거나, 모듈끼리 이벤트로 느슨하게
+결합해야 할 때 쓰는 두 사용자 API다. 둘 다 **별명 선언 없이** `ctx.lock` / `ctx.bus` 로 바로 쓰고, 환경에
+맞춰 driver 가 자동으로 골라진다(redis/nats 있으면 진짜 분산, 없으면 cluster, 그것도 없으면 단일 프로세스).
+
+- 실제 동작: `/demo/lock`(분산 락) · `/demo/bus`(메시지 버스) — 두 탭을 띄워 워커 PID·순서·fan-out 을 눈으로 본다.
+- 정본: 분산 락 = ADR-226, 메시지 버스 = ADR-227.
+
+---
+
+## 1. 분산 락 — `ctx.lock`
+
+### 언제 쓰나
+
+- **race condition 방지**: 재고 차감, 좌석 예약 등 "읽고-고치고-쓰기"를 한 번에 하나만.
+- **단일 실행 보장**: 클러스터에서 정기 작업을 한 인스턴스만(스케줄러 leader election — 단, 스케줄 중복방지는
+  `static lock`(ADR-118)이 따로 있다).
+- **외부 호출 직렬화**: 같은 리소스에 대한 외부 API 호출이 겹치지 않게.
+
+### API — `with` 권장
+
+```js
+// 권장 — 잠그고, 끝나면(성공/예외 무관) 자동 해제
+await ctx.lock.with('stock:42', { ttl: 5000 }, async (lock) => {
+  const row = await stock.byId(42)
+  await stock.update(42, { qty: row.qty - 1 })   // 이 블록은 노드를 넘어 한 번에 하나만 실행
+})
+
+// 수동 — try/finally
+const lock = await ctx.lock.acquire('order:99', { ttl: 5000, waitMs: 1000 })
+try { /* ... */ } finally { await lock.release() }
+
+// 즉시 1회(대기 없음) — 못 잡으면 null
+const got = await ctx.lock.tryAcquire('job:nightly')
+if (got) { try { /* ... */ } finally { await got.release() } }
+```
+
+### 옵션
+
+| 옵션 | 뜻 |
+| --- | --- |
+| `ttl` | 락 보유 시간(ms). 이 시간이 지나면 자동 만료(보유자 crash 안전망). |
+| `waitMs` | 경합 시 획득 대기 상한(ms). `0` = 즉시 실패(tryAcquire 와 동일). |
+| `fifo` | `true` 면 대기자를 **도착 순서**대로 깨운다(기아 방지). |
+| `fence` | `true` 면 단조 증가 토큰(`lock.fence`)을 함께 준다 — 외부 시스템이 stale-writer 를 거를 때. |
+| `extendable` | `true` 면 watchdog 이 ttl 절반마다 자동 연장(긴 작업). |
+
+`acquire`/`with` 는 못 잡으면 `lock.not_acquired`(409) throw, `tryAcquire` 는 `null`.
+
+### driver 자동 폴백 + config
+
+```js
+// mega.config.js (전역)
+lock: { driver: 'auto', cache: 'lock', ttl: 5000, waitMs: 1000, fifo: false }
+```
+
+| driver | 보장 범위 | 전제 |
+| --- | --- | --- |
+| `redis` | 멀티 프로세스·멀티 노드(진짜 분산) | `lock.cache` = redis 캐시 별명 |
+| `cluster` | 같은 노드 워커 간 | `mega start --cluster=N` 워커 |
+| `memory` | 단일 프로세스만 | 없음(개발용) |
+
+`auto`(기본)는 redis 가용 시 redis, 클러스터 워커면 cluster, 그 외 memory + 부팅 경고. 명시 driver 의 전제가
+없으면 부팅 fail-fast. 이 데모(crud)는 `cache: 'lock'`(기존 `caches.lock`)로 redis 분산 락을 켜 둔다.
+
+### 함정
+
+- **ttl 을 임계구역보다 짧게 잡으면** 작업 도중 락이 만료돼 다른 인스턴스가 들어온다 → ttl 을 넉넉히, 긴
+  작업은 `extendable: true`(watchdog).
+- 외부 시스템(DB·파일)에 쓰기를 보호할 땐, 락 만료와 쓰기 사이의 경합을 막으려 **fence 토큰**을 외부에 같이
+  넘겨 stale-writer 를 거르는 패턴을 권장한다.
+- `ctx.lock(alias)`(설정형 redlock, ADR-113)와 `ctx.lock.with(...)`(자동폴백)는 **별개**다. TTL 단위는 둘 다 ms.
+
+---
+
+## 2. 메시지 버스 — `ctx.bus`
+
+### 언제 쓰나
+
+- **도메인 이벤트**: "주문 생성됨" → 이메일·분석·재고가 각각 반응(발행자는 구독자를 모름).
+- **fan-out**: 한 이벤트를 여러 구독자가 동시에 받는다.
+- **느슨한 결합**: 모듈이 서로 직접 호출하지 않고 이벤트로만 연결.
+
+### API
+
+핸들러 시그니처는 **`(payload, meta, subject)`** 다 — 3번째 `subject` 는 메시지가 도착한 **구체** subject
+(wildcard 가 아닌 실제 발행 subject)다. `meta.subject` 에도 같은 값이 담긴다(정본 위치). 기존 `(payload, meta)`
+2-인자 핸들러는 그대로 동작한다(3번째 인자를 안 받아도 무방 — 호환).
+
+```js
+// fan-out — 구독자 전원 수신
+ctx.bus.emit('order.created', { orderId: 42 }, { meta: { traceId } })
+ctx.bus.on('order.created', async (payload, meta) => { await email.sendReceipt(payload.orderId) })
+
+// request/reply — 핸들러 '반환값'이 응답
+ctx.bus.on('catalog.product', async ({ id }) => ({ id, name: 'widget' }))
+const product = await ctx.bus.request('catalog.product', { id: 1 }, { timeout: 1000 })
+
+// 구독 해제 / 요청 단위 meta 바인딩
+const sub = await ctx.bus.on('topic', handler); await sub.unsubscribe()   // 또는 ctx.bus.off('topic', handler)
+const scoped = ctx.bus.with({ traceId }); await scoped.emit('x', payload)  // 이후 emit/request 에 meta 자동 병합
+```
+
+### Wildcards (NATS 식)
+
+구독 subject 에 wildcard 를 쓴다(발행 subject 는 구체적이어야 한다):
+
+- `*` = **정확히 한 토큰**. `order.*` → `order.created`(O), `order.created.eu`(X)
+- `>` = **한 토큰 이상(꼬리 전체)**, 맨 끝에만. `order.>` → `order.created`, `order.created.eu`(둘 다 O)
+
+wildcard 로 구독하면 **3번째 인자 `subject`** 로 어느 구체 subject 가 매칭됐는지 안다:
+
+```js
+ctx.bus.on('order.>', async (payload, meta, subject) => {
+  // subject === 'order.created' | 'order.created.eu' | ... (실제 발행 subject)
+  if (subject === 'order.created') await onCreate(payload)
+  else if (subject.endsWith('.eu')) await onEu(payload)
+})
+```
+
+### 옵션
+
+| 옵션 | 뜻 |
+| --- | --- |
+| `persist`(emit/on) | `true` 면 JetStream 영속(저장 + 재전달). **nats driver 만**; 그 외엔 경고 후 비영속. |
+| `ordered`(on) | `true` 면 같은 구독을 도착 순서대로 1건씩 직렬 처리. |
+| `timeout`(request) | 응답 대기 상한(ms). 초과 시 `bus.request_timeout`, 응답자 없으면 `bus.no_responders`. |
+
+한 구독자가 throw 해도 다른 구독자·다음 메시지엔 영향 없다(매니저가 잡아 로깅 — fan-out 격리).
+
+### driver 자동 폴백 + config
+
+```js
+// mega.config.js (전역)
+bus: { driver: 'auto', nats: 'jobs', prefix: 'app.', defaultPersist: false, requestTimeoutMs: 5000 }
+```
+
+| driver | 보장 범위 | persist | 전제 |
+| --- | --- | --- | --- |
+| `nats` | 멀티 프로세스·멀티 노드 | O(JetStream) | `bus.nats` = NATS 버스 별명 |
+| `cluster` | 같은 노드 워커 간 | X(경고 후 비영속) | `mega start --cluster=N` 워커 |
+| `memory` | 단일 프로세스만 | X | 없음(개발용) |
+
+`prefix`(예: `app.`)는 모든 subject 에 자동으로 붙어 네임스페이스를 격리한다. nats driver 는 기존 잡 큐
+(ADR-119)·클러스터 broadcast(ADR-176)와 **같은 NATS 연결**을 빌려 쓴다(새 연결 X). 이 데모는 `nats: 'jobs'`로
+NATS 버스를 켜 둔다.
+
+### 함정
+
+- **구독하기 전에 발행된 이벤트는 비영속(core)에선 유실된다.** 늦게 붙은 구독자도 받아야 하면 `persist: true`
+  (JetStream 이 저장했다가 전달) — 단 nats driver 필요.
+- subject 는 `.` 으로 나뉜 토큰열이고 공백/wildcard 규칙이 있다(NATS 제약). 발행 subject 에 `*`/`>` 는 금지.
+- `ctx.bus(alias)`(설정형 NATS 어댑터, ADR-110)와 `ctx.bus.emit(...)`(자동폴백)은 **별개** 하위시스템이다.
+
+---
+
+## 3. ctx 없는 곳에서 — `getApp()` (ADR-228)
+
+`ctx.lock`/`ctx.bus` 는 요청 ctx 에만 있다. 요청 흐름 **밖**(백그라운드 타이머·외부 SDK 콜백·테스트)에서는
+`getApp()` 으로 booted 앱을 잡아 **같은 표면**으로 쓴다. lock/bus manager 는 process 싱글톤이라 `app.lock` 은
+`ctx.lock` 과 같은 객체다.
+
+```js
+import { getApp } from 'mega-framework'
+
+// 백그라운드 하트비트 — 요청 ctx 가 없는 setInterval 콜백
+setInterval(async () => {
+  const app = getApp()
+  await app.bus.emit('heartbeat', { ts: Date.now() })
+}, 60_000)
+
+// 외부 SDK 콜백에서 분산 락
+stripe.webhooks.on('charge.succeeded', async (event) => {
+  await getApp().lock.with(`charge:${event.id}`, { ttl: 5000 }, async () => { /* 멱등 처리 */ })
+})
+```
+
+- **표면**: `app.lock` / `app.bus`(ctx 와 동일 API) · `app.db(alias)` / `app.cache(alias)` · `app.log` / `app.name`.
+  요청-스코프(`req`/`user`/`session`/요청 locale `t`)는 **없다** — 그건 ctx 전용이다.
+- **부팅 전 호출은 fail-fast**: 아직 부팅이 안 끝났으면 `app.not_initialized` throw(타이밍 버그를 조용히 넘기지
+  않음). `afterBoot` hook 이후·listen 이후의 백그라운드에서 호출한다. 부팅 여부만 보려면 `hasApp()`.
+- **멀티앱 프로세스**: 앱이 둘 이상이면 `getApp('<name>')` 로 이름을 준다(생략 시 `app.ambiguous`).
+- **권장**: ctx 가 **있는** 곳(라우트·서비스·잡/스케줄 `run(ctx)`)은 여전히 `ctx.lock`/`ctx.bus` 를 쓴다 — 요청
+  로거·user·session 이 함께 묶여 추적이 쉽다. `getApp()` 은 ctx 가 **없을 때만**.
+
+---
+
+## 4. 앱별 lock/bus 분리 — 멀티앱 (ADR-229)
+
+한 프로세스에 여러 앱을 vhost 로 띄울 때(`apps/<name>/`), 앱마다 **다른** lock/bus 를 쓸 수 있다 — `admin` 은
+격리된 NATS·redis, `public` 은 공용처럼. `lock`/`bus` 는 글로벌(`mega.config.js`)·앱(`apps/<name>/app.config.js`)
+**양쪽**에 둘 수 있고(dual-scope), 우선순위는 **앱별 > 글로벌 > 기본값**(앱이 정의하면 글로벌과 합쳐 그 앱 전용
+manager, 미정의면 글로벌 그대로).
+
+```js
+// mega.config.js (글로벌 = fallback)
+lock: { cache: 'lockMain' },
+bus:  { nats: 'natsMain', prefix: 'app.' },
+
+// apps/admin/app.config.js — admin 전용 backend
+lock: { cache: 'lockAdmin' },          // admin 만 다른 redis
+bus:  { nats: 'natsAdmin', prefix: 'admin.' },
+
+// apps/public/app.config.js — bus 만 prefix 분리(같은 NATS, 가벼운 격리)
+bus: { prefix: 'public.' },
+```
+
+- `ctx.lock`/`ctx.bus`(요청은 vhost 로 앱에 라우팅됨)와 `getApp('admin').lock`/`bus`(ctx 없는 영역, ADR-228)는
+  **그 앱의 manager** 를 가리킨다.
+- `lock.cache`/`bus.nats` 는 앱 config 에서도 **글로벌 `services`** 의 키를 참조한다(services 는 글로벌 정의).
+- **한계**: 같은 프로세스라 메모리·CPU·이벤트루프는 공유된다. 강한 격리(다른 스케일·장애 격리)가 필요하면
+  **process-per-app + mega-bus(NATS)** 로 프로세스 간 통신하는 쪽이 정답이다.
+
+---
+
+## 데모로 확인하기
+
+- `/demo/lock` — 키·ttl·waitMs·holdMs 와 fifo/fence/extendable 토글로 임계구역을 실행한다. **두 탭에서 같은
+  키로 동시에 "실행"** 하면 한 쪽은 즉시, 다른 쪽은 대기 후 실행되고(상호배제), fifo 면 도착 순서가 보인다.
+  상태 패널의 보유/대기 수와 워커 PID 로 분산 동작이 드러난다.
+- `/demo/bus` — subject·payload 를 발행하면 페이지가 `demo.>` 구독으로 받아 표시한다. **여러 워커가 받는
+  fan-out**, `order.created`/`order.created.eu`/`user.login` 의 wildcard 매칭, `demo.echo` request/reply(어느
+  워커가 답했는지 PID), persist 배지로 영속 이벤트를 구분해 본다.

package/sample/crud/docs/guide/10-multi-app.md

@@ -0,0 +1,74 @@
+# 멀티앱 — 한 프로세스 vhost
+
+한 프로세스에 **여러 앱**을 띄우고 `Host` 헤더로 라우팅하는 vhost 모델(ADR-063)과, 앱별 lock/bus 분리
+(ADR-229)·cross-app 호출(ADR-228)을 설명합니다. 실동작은 `sample/multi`(web=a.com, admin=b.com)에서 봅니다.
+
+## vhost 모델 — 한 포트, Host 라우팅
+
+`mega.config.js` 의 `apps` 배열에 앱 폴더 이름을 나열하면, 각 `apps/<name>/app.config.js` 의 `hosts` 로 도메인이
+매핑됩니다. boot 는 앱마다 **별도 Fastify 인스턴스**를 만들고 하나의 서버에 vhost 마운트해 **한 포트로 한 번
+listen** 합니다. 매 요청은 `Host` 헤더의 hostname 으로 해당 앱에 라우팅됩니다.
+
+```js
+// mega.config.js
+export default { apps: ['web', 'admin'], server: { port: 3000 }, /* ... */ }
+
+// apps/web/app.config.js   → hosts: ['a.com']
+// apps/admin/app.config.js → hosts: ['b.com']
+```
+
+- **host_collision**: 같은 host 를 두 앱에 매핑하면 부팅 시 `config.host_collision` 로 **fail-fast**(ADR-067) —
+  요청이 어느 앱으로 갈지 모호해지는 것을 부팅에서 막습니다.
+
+## 앱별 lock/bus 분리 (ADR-229)
+
+`lock`/`bus` 는 글로벌(`mega.config.js`)·앱(`apps/<name>/app.config.js`) 양쪽에 둘 수 있습니다(dual-scope). 앱이
+정의하면 글로벌과 합쳐 **그 앱 전용 manager**, 미정의면 글로벌 fallback. `sample/multi` 예:
+
+```js
+// mega.config.js — 글로벌(fallback): bus는 NATS(glob.), lock은 생략 → memory
+bus: { nats: 'events', prefix: 'glob.' },
+
+// apps/web/app.config.js — 앱 전용: redis 락 + web. 버스
+lock: { cache: 'webLock' },         // admin 의 memory 락과 다른 backend
+bus:  { nats: 'events', prefix: 'web.' },
+
+// apps/admin/app.config.js — lock/bus 미정의 → 글로벌(memory 락 + glob. 버스)
+```
+
+확인:
+
+- `a.com/whoami` → `lock: redis`, `b.com/whoami` → `lock: memory` (앱별 backend 분리).
+- web 의 `web.` 발행은 admin(`glob.`)이 **못 받음** (prefix 격리, 같은 NATS 라도 subject 공간이 갈림).
+- 같은 키여도 web(redis)·admin(memory)은 다른 manager 라 **서로 격리**됩니다.
+
+## cross-app 호출 (`getApp`, ADR-228)
+
+ctx 가 없거나 다른 앱의 자원이 필요하면 `getApp('<name>')` 로 잡습니다. 멀티앱이면 **이름 필수**(생략 시
+`app.ambiguous`, 없는 이름은 `app.not_found`, 부팅 전은 `app.not_initialized` — 전부 fail-fast).
+
+```js
+import { getApp } from 'mega-framework'
+// web 의 컨트롤러에서 admin 의 (글로벌) 버스로 직접 발행 → b.com/received 에 도착
+await getApp('admin').bus.emit('notice', { from: 'web' })
+```
+
+`getApp('admin').lock`/`bus`/`db(alias)`/`cache(alias)`/`log` 모두 **그 앱의** manager·자원을 가리킵니다.
+
+## 언제 멀티앱(vhost) vs process-per-app
+
+| 기준 | 멀티앱(vhost) | process-per-app |
+| --- | --- | --- |
+| 자원 공유 | 메모리/CPU/이벤트루프 공유 | 완전 분리 |
+| 배포·스케일 | 함께(한 프로세스) | 독립 스케일·독립 배포 |
+| 장애 격리 | 약함(한 프로세스 죽으면 전부) | 강함 |
+| 통신 | 같은 프로세스(`getApp`) | mega-bus(NATS) cross-process |
+| 적합 | admin+public 처럼 묶여 다니는 앱, 같은 도메인 그룹 | 독립 서비스, 다른 스케일/SLA |
+
+**강한 격리**(다른 스케일·장애 격리·다른 backend 전용)가 필요하면 process-per-app + mega-bus(NATS)로 프로세스 간
+통신하세요. 멀티앱은 "같은 프로세스 안에서 논리 분리(다른 host·다른 lock/bus backend·prefix)"까지가 적정선입니다.
+
+## 실행 — `sample/multi`
+
+`sample/multi/README.md` 참고. `/etc/hosts` 에 `a.com`/`b.com` 을 `127.0.0.1` 로 매핑하고 redis·nats 를 띄운 뒤
+`npm run dev`, `http://a.com:3200`(web)·`http://b.com:3200`(admin) 으로 접속합니다.

package/sample/crud/mega.config.js

@@ -111,6 +111,38 @@ export default {
     },
   },
 
+  // ── 분산 락 사용자 API(ADR-226) — `ctx.lock.with/.acquire/.tryAcquire` ─────────────────────────
+  // 위 services.locks(설정형 redlock, `ctx.lock('main')`)와 **별개 하위시스템**이다. 이쪽은 별명 선언 없이
+  // 코드에서 바로 임계구역을 잠근다: `await ctx.lock.with('user:42', { ttl: 5000 }, async () => { ... })`.
+  //
+  // 이 `lock` 블록이 **없어도** ctx.lock.with 는 동작한다 — driver 자동 폴백이 redis 가용 시 redis, 클러스터
+  // 워커면 cluster IPC, 그 외엔 **memory**(단일 프로세스, 부팅 경고)를 고른다. 멀티 프로세스/노드에서 진짜
+  // 분산 락을 쓰려면 아래처럼 **redis cache 별명을 cache 에 지정**한다(추가 .env 불필요 — 기존 caches.lock 재사용).
+  // 이 데모(crud)는 /demo/lock 시연을 위해 redis 분산 락을 켠다(클러스터 워커 간 실 상호배제·FIFO·fence).
+  lock: {
+    driver: 'auto', // 'auto'(기본) | 'redis' | 'cluster' | 'memory'. 명시 시 전제 부재면 부팅 fail-fast.
+    cache: 'lock', // services.caches 의 redis 별명(여기선 caches.lock = REDIS_LOCK_URL). driver redis/auto 시 사용.
+    ttl: 5000, // 락 보유 기본 시간(ms)
+    waitMs: 3000, // 획득 대기 기본 상한(ms, 0 = 즉시 실패). 데모 FIFO 대기가 보이도록 넉넉히.
+    fifo: false, // true = 대기자 도착 순서 보장(기아 방지). subject별 { fifo } 로 덮음.
+  },
+
+  // ── 메시지 버스 사용자 API(ADR-227) — `ctx.bus.emit/.on/.request/.with` ────────────────────────
+  // 위 services.buses(설정형 어댑터, `ctx.bus('jobs')`)와 **별개 하위시스템**이다. 별명 선언 없이 코드에서 바로
+  // 이벤트를 주고받는다: `ctx.bus.emit('order.created', { id })` / `ctx.bus.on('order.*', handler)`.
+  //
+  // 이 `bus` 블록이 **없어도** ctx.bus.emit 은 동작한다 — driver 자동 폴백이 NATS 가용 시 nats, 클러스터 워커면
+  // cluster IPC, 그 외엔 **memory**(단일 프로세스, 부팅 경고)를 고른다. 멀티 프로세스/노드에서 진짜 분산 버스를
+  // 쓰려면 아래처럼 **NATS 버스 별명을 nats 에 지정**한다(추가 .env 불필요 — 기존 buses.jobs 재사용).
+  // 이 데모(crud)는 /demo/bus 시연을 위해 NATS 버스를 켠다(워커 간 fan-out·persist(JetStream)·request/reply).
+  bus: {
+    driver: 'auto', // 'auto'(기본) | 'nats' | 'cluster' | 'memory'. 명시 시 전제 부재면 부팅 fail-fast.
+    nats: 'jobs', // services.buses 의 NATS 별명(여기선 buses.jobs = NATS_JOBS_URL). driver nats/auto 시 사용.
+    prefix: 'app.', // 모든 subject 에 붙는 네임스페이스(충돌 회피). 빈 값이면 그대로.
+    defaultPersist: false, // 기본 비영속. true 면 emit/on 이 기본 JetStream(영속) — subject별 { persist } 로 덮음.
+    requestTimeoutMs: 5000, // request 응답 대기 기본 상한(ms)
+  },
+
   // (예시·미사용) Embedded WS Hub(ADR-137) — `mega ws-hub` 별도 프로세스 대신 같은 프로세스에 허브를 띄움
   //   (single-node). 켜면 app.config.js bridgeHub.url 을 이 host:port 로 맞춘다. acceptedTokens 필수(빈 값=throw).
   // wsHub: {

package/sample/crud/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "dev": "NODE_ENV=development mega start --watch",
@@ -17,12 +17,13 @@
     "test": "mega test"
   },
   "dependencies": {
+    "@nats-io/jetstream": "^3.4.0",
     "highlight.js": "^11.11.1",
     "marked": "^18.0.5",
     "mega-framework": "file:../.."
   },
   "devDependencies": {
-    "concurrently": "^9.0.0",
+    "concurrently": "^10.0.3",
     "vitest": "^4.1.8"
   }
 }

package/sample/multi/.env

@@ -0,0 +1,16 @@
+# sample-multi 환경변수 (.env) — 로컬 전용(.gitignore). 실제 docker 인프라 값으로 채움.
+
+# HTTP 포트 — 한 포트로 두 앱(web=a.com, admin=b.com)을 vhost 라우팅한다.
+# 3200 사용(sample/crud 앱 3000·crud ws-hub 3100 과 충돌 회피). 점유된 포트면 boot 가 EADDRINUSE 로 실패.
+PORT=3200
+
+# ── 앱별 lock/bus 백엔드 (ADR-229) ───────────────────────────────────────────
+# web 앱 전용 분산 락 backend(redis) — services.caches.webLock. admin 은 글로벌 memory 락이라 불필요.
+# docker mega-redis 는 비밀번호 필요. db 5 사용(crud 가 0~4 점유: 0 세션·1 demo·2 rate·3 lock·4 cache).
+REDIS_WEBLOCK_URL=redis://:dkTkqkfl12@localhost:6379/5
+# 두 앱이 공유하는 NATS — services.buses.events. web 은 prefix 'web.', admin(글로벌)은 'glob.' 로 격리.
+NATS_EVENTS_URL=nats://localhost:4222
+
+# ── /etc/hosts (a.com / b.com 이미 설정됨) ──────────────────────────────────
+# 미설정이면 /etc/hosts 에 추가: 127.0.0.1 a.com / 127.0.0.1 b.com
+# 접속: http://a.com:3200 (web) / http://b.com:3200 (admin)

package/sample/multi/.env.example

@@ -0,0 +1,17 @@
+# sample-multi 환경변수 (.env.example) — 복사해서 .env 로 쓰고 실제 값 채우기. .env 는 git 에 안 올림.
+
+# HTTP 포트 — 한 포트로 두 앱(web=a.com, admin=b.com)을 vhost 라우팅한다.
+# 3200 사용(sample/crud·sample/simple 이 3000 이라 충돌 회피). 이미 점유된 포트면 boot 가 EADDRINUSE 로 실패한다.
+PORT=3200
+
+# ── 앱별 lock/bus 백엔드 (ADR-229) ───────────────────────────────────────────
+# web 앱 전용 분산 락 backend(redis) — services.caches.webLock. admin 은 글로벌 memory 락이라 불필요.
+REDIS_WEBLOCK_URL=redis://localhost:6379/0
+# 두 앱이 공유하는 NATS — services.buses.events. web 은 prefix 'web.', admin(글로벌)은 'glob.' 로 격리.
+NATS_EVENTS_URL=nats://localhost:4222
+
+# ── /etc/hosts (이미 a.com / b.com 설정돼 있다고 가정) ────────────────────────
+# 미설정이면 아래를 /etc/hosts 에 추가:
+#   127.0.0.1 a.com
+#   127.0.0.1 b.com
+# 그 뒤 http://a.com:3200 (web) / http://b.com:3200 (admin) 으로 접속.

package/sample/multi/README.md

@@ -0,0 +1,54 @@
+# sample-multi — 한 프로세스 멀티앱 (vhost) 데모
+
+한 프로세스에 **두 앱**을 띄우고, `Host` 헤더로 라우팅(vhost, ADR-063)하며, **앱별 lock/bus 분리**(ADR-229)와
+ctx 없는 영역의 **cross-app 호출**(`getApp`, ADR-228)을 보여주는 최소 데모입니다.
+
+- **web** (`a.com`) — 앱 전용 lock(**redis**) + bus(NATS, prefix `web.`)
+- **admin** (`b.com`) — 앱별 설정 없음 → **글로벌 fallback** (lock=**memory**, bus prefix `glob.`)
+
+> 이 데모는 멀티앱 패턴(vhost·앱별 lock/bus·cross-app)에 집중한 **목적형 최소 앱 2개**입니다. 풀 기능
+> 데모는 단일앱 `sample/crud`(DB·캐시·잡·WS·ASP 등) / `sample/simple`(최소 E2E)을 보세요.
+
+## 실행
+
+```bash
+cd sample/multi
+cp .env.example .env          # REDIS_WEBLOCK_URL / NATS_EVENTS_URL 확인 (redis·nats 필요)
+npm install
+npm run dev
+```
+
+`/etc/hosts` 에 `a.com` / `b.com` 이 `127.0.0.1` 로 매핑돼 있어야 합니다(이미 설정돼 있다고 가정 — 없으면
+`.env.example` 안내 참고). 접속:
+
+| URL | 앱 | 무엇 |
+| --- | --- | --- |
+| http://a.com:3200/ | web | 셸 + 엔드포인트 안내 |
+| http://a.com:3200/whoami | web | lock=`redis`, bus=`nats` (앱 전용) |
+| http://a.com:3200/lock | web | redis 락으로 임계구역 실행 |
+| http://a.com:3200/emit | web | `web.order.created` 발행(admin 미수신) |
+| http://a.com:3200/cross | web | `getApp('admin').bus.emit('notice')` → admin 으로 cross-app |
+| http://b.com:3200/whoami | admin | lock=`memory`, bus=`nats`(글로벌) |
+| http://b.com:3200/received | admin | 글로벌 버스로 받은 이벤트 — web 의 cross-app `notice` 가 보임, `web.` 발행은 격리로 없음 |
+
+## 무엇을 보여주나
+
+- **vhost**: 한 포트(3200) 한 번 listen, `a.com`/`b.com` 이 다른 앱으로 라우팅. 같은 host 를 두 앱에 매핑하면
+  부팅 시 `config.host_collision` 로 fail-fast(ADR-067).
+- **앱별 lock 분리**: `a.com/whoami` 는 `redis`, `b.com/whoami` 는 `memory` — 같은 키여도 다른 manager 라 격리.
+- **앱별 bus prefix 격리**: web 의 `web.` 발행을 admin(`glob.`)이 못 받음.
+- **cross-app**: web 의 `/cross` 가 `getApp('admin').bus` 로 admin 의 글로벌 버스에 직접 발행 → `b.com/received` 에 도착.
+
+## 문제 해결 — `host.not_mounted`
+
+`{"error":{"code":"host.not_mounted"}}` 가 보이면 **다른 mega 앱이 그 포트를 점유**하고 있어, 이 앱이 listen 에
+실패하고 브라우저가 옛 서버를 때리는 것입니다(예: `sample/crud`가 3000 에서 도는 중). 확인·해결:
+
+```bash
+lsof -nP -iTCP:3200 -sTCP:LISTEN     # 누가 점유 중인지
+# → 옛 서버를 끄거나, PORT 를 비어있는 값으로 바꿔 실행: PORT=3201 npm run dev
+```
+
+이 앱은 점유된 포트면 `listen EADDRINUSE` 로 **명확히 실패**합니다 — 그 로그가 보이면 포트를 바꾸세요.
+
+자세한 설명은 프레임워크 가이드 `docs/guide/10-multi-app.md` 참고.

package/sample/multi/apps/admin/app.config.js

@@ -0,0 +1,24 @@
+// @ts-check
+/**
+ * apps/admin/app.config.js — `admin` 앱(b.com). **앱별 lock/bus 미지정** → 글로벌 fallback 을 쓴다(ADR-229):
+ *   - lock: 글로벌(memory) — web 의 redis 락과 격리(다른 manager).
+ *   - bus: 글로벌(NATS, prefix `glob.`) — web 의 `web.` 와 subject 공간이 갈린다.
+ * 멀티앱이라도 앱이 lock/bus 를 정의하지 않으면 종전처럼 글로벌을 그대로 쓴다(호환).
+ */
+export default {
+  name: 'admin',
+  hosts: ['b.com'],
+
+  views: { dir: 'apps/admin/views' },
+
+  // 정적 자산 — 데모 페이지의 클라이언트 JS(/static/js/admin.js)를 서빙(CSP script-src 'self' 호환).
+  staticAssets: { enabled: true, dir: 'apps/admin/public', prefix: '/static' },
+
+  // helmet CSP — 로컬 http 데모라 `upgrade-insecure-requests` 끄기(null). 안 끄면 브라우저가 https 로 강제
+  // 업그레이드해 연결 실패. useDefaults 라 나머지 보안 헤더는 유지(운영 https 에선 이 override 제거 권장).
+  helmet: {
+    contentSecurityPolicy: {
+      directives: { upgradeInsecureRequests: null },
+    },
+  },
+}

package/sample/multi/apps/admin/controllers/admin-controller.js

@@ -0,0 +1,42 @@
+// @ts-check
+/**
+ * AdminController — `admin` 앱(b.com) 컨트롤러. 앱별 lock/bus 미지정이라 **글로벌**(memory 락 + glob. 버스)을 쓴다.
+ *
+ * 첫 요청에서 글로벌 버스의 `>`(= glob.>)를 구독해 받은 이벤트를 링버퍼에 모은다. web 의 `/cross`
+ * (getApp('admin').bus.emit('notice'))가 보낸 cross-app 이벤트가 여기로 들어온다. web 의 `web.` 발행은
+ * prefix 가 달라 들어오지 않는다(격리).
+ */
+
+/** 수신 버퍼(워커별 인메모리). @type {any[]} */
+const received = []
+const MAX = 30
+let subscribed = false
+
+/** 글로벌 버스 1회 구독(워커별 멱등). @param {any} ctx @returns {Promise<void>} */
+async function ensureSubscribed(ctx) {
+  if (subscribed) return
+  subscribed = true
+  await ctx.bus.on('>', (/** @type {any} */ payload, /** @type {any} */ _meta, /** @type {any} */ subject) => {
+    received.push({ subject, payload, at: new Date().toISOString() })
+    if (received.length > MAX) received.shift()
+  })
+}
+
+export class AdminController {
+  /** GET / — 셸 페이지. @param {any} _req @param {any} _reply @param {any} ctx */
+  static async home(_req, _reply, ctx) {
+    await ensureSubscribed(ctx)
+    return ctx.render('index', { app: 'admin', host: 'b.com' })
+  }
+
+  /** GET /whoami — 글로벌 lock/bus driver. @param {any} _req @param {any} _reply @param {any} ctx */
+  static async whoami(_req, _reply, ctx) {
+    return { app: 'admin', lock: (await ctx.lock.stats()).driver, bus: (await ctx.bus.stats()).driver, pid: process.pid }
+  }
+
+  /** GET /received — 글로벌 버스(glob.>)로 받은 이벤트(web 의 cross-app 포함, web. 발행은 격리되어 없음). @param {any} _req @param {any} _reply @param {any} ctx */
+  static async received(_req, _reply, ctx) {
+    await ensureSubscribed(ctx)
+    return { app: 'admin', count: received.length, events: received.slice().reverse() }
+  }
+}

package/sample/multi/apps/admin/public/js/admin.js

@@ -0,0 +1,31 @@
+// @ts-check
+/* admin 앱 데모 — whoami / 수신 이벤트(received)를 fetch 해 인라인 표시 + 2초 자동 새로고침. */
+;(function () {
+  var out = document.getElementById('out')
+  function show(/** @type {any} */ obj) {
+    if (out) out.textContent = JSON.stringify(obj, null, 2)
+  }
+  function load(/** @type {string} */ url) {
+    fetch(url, { headers: { accept: 'application/json' } })
+      .then(function (res) {
+        return res.json()
+      })
+      .then(function (j) {
+        show(j && j.data != null ? j.data : j)
+      })
+      .catch(function (e) {
+        if (out) out.textContent = '오류: ' + e.message
+      })
+  }
+
+  var whoami = document.querySelector('button[data-get="/whoami"]')
+  if (whoami) whoami.addEventListener('click', function () { load('/whoami') })
+  var refresh = document.getElementById('refresh')
+  if (refresh) refresh.addEventListener('click', function () { load('/received') })
+
+  // 첫 로드 + 2초 폴링(탭 숨김 시 멈춤) — web 의 cross-app 이벤트가 도착하는 것을 실시간으로 본다.
+  load('/received')
+  setInterval(function () {
+    if (!document.hidden) load('/received')
+  }, 2000)
+})()

package/sample/multi/apps/admin/routes/pages.js

@@ -0,0 +1,11 @@
+// @ts-check
+/**
+ * apps/admin 라우트 — 자동 로딩. 글로벌 lock/bus(fallback) 사용 + cross-app 으로 받은 이벤트 표시.
+ */
+import { AdminController } from '../controllers/admin-controller.js'
+
+export default (/** @type {any} */ router) => {
+  router.http.get('/', AdminController.home)
+  router.http.get('/whoami', AdminController.whoami) // 글로벌 lock/bus driver 확인
+  router.http.get('/received', AdminController.received) // 글로벌 버스(glob.>)로 받은 이벤트 — web 의 cross-app 포함
+}

package/sample/multi/apps/admin/views/index.ejs

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>admin (b.com) — 멀티앱 데모</title>
+  <style>
+    body { font-family: system-ui, sans-serif; max-width: 760px; margin: 2rem auto; padding: 0 1rem; line-height: 1.6; }
+    code { background: #f3f3f3; padding: .1rem .3rem; border-radius: 3px; }
+    .tag { background: #6c757d; color: #fff; padding: .1rem .5rem; border-radius: 4px; font-size: .85rem; }
+    button { font: inherit; padding: .4rem .8rem; margin: .2rem .3rem .2rem 0; border: 1px solid #6c757d; background: #fff; color: #495057; border-radius: 6px; cursor: pointer; }
+    button:hover { background: #6c757d; color: #fff; }
+    .out { background: #f8f9fa; border: 1px solid #e3e6ea; border-radius: 6px; padding: .5rem .7rem; font-family: ui-monospace, monospace; font-size: .85rem; white-space: pre-wrap; min-height: 1.4rem; margin: .3rem 0; }
+    .desc { color: #555; font-size: .9rem; margin: .1rem 0 .3rem; }
+  </style>
+</head>
+<body>
+  <h1>admin 앱 <span class="tag">b.com</span></h1>
+  <p>이 앱은 <strong>앱별 lock/bus 설정이 없어 글로벌 fallback</strong>(lock=memory, bus prefix <code>glob.</code>)을
+     씁니다 (ADR-229). 같은 프로세스의 <code>web</code>(a.com)은 앱 전용 redis 락 + <code>web.</code> 버스를 씁니다.</p>
+
+  <div>
+    <button data-get="/whoami">whoami</button>
+    <button id="refresh">수신 이벤트 새로고침</button>
+  </div>
+  <div class="desc">이 앱의 lock/bus driver — memory / nats(glob.). 아래는 글로벌 버스로 받은 이벤트입니다.</div>
+  <div class="out" id="out"></div>
+  <p class="desc"><code>web</code> 의 <code>/cross</code>(getApp('admin').bus)가 보낸 <code>notice</code> 가 여기 들어옵니다(cross-app).
+     web 의 <code>web.</code> 발행은 prefix 격리로 들어오지 않습니다. web 앱은 <a href="http://a.com:3200/">a.com</a>.</p>
+
+  <script src="/static/js/admin.js"></script>
+</body>
+</html>

package/sample/multi/apps/web/app.config.js

@@ -0,0 +1,30 @@
+// @ts-check
+/**
+ * apps/web/app.config.js — `web` 앱(a.com). **앱 전용 lock/bus**(ADR-229)로 admin 과 분리한다.
+ *   - lock: redis(`webLock` 캐시) — admin 의 글로벌 memory 락과 다른 backend.
+ *   - bus: NATS, prefix `web.` — 글로벌 `glob.` 와 subject 공간이 갈려 격리된다(같은 NATS 공유).
+ */
+export default {
+  name: 'web',
+  hosts: ['a.com', 'localhost'],
+
+  views: { dir: 'apps/web/views' },
+
+  // 정적 자산 — 데모 페이지의 클라이언트 JS(/static/js/web.js)를 서빙(CSP script-src 'self' 호환).
+  staticAssets: { enabled: true, dir: 'apps/web/public', prefix: '/static' },
+
+  // helmet CSP — 로컬 http 데모라 `upgrade-insecure-requests` 를 끈다(null 로 디폴트 지시어 제거). 안 끄면
+  // 브라우저가 http://a.com:3200 을 https 로 강제 업그레이드해 (TLS 없음) 연결 실패한다. useDefaults 라 나머지
+  // 보안 헤더는 유지. (운영 https 배포에선 이 override 를 빼서 업그레이드를 다시 켜는 게 맞다.)
+  helmet: {
+    contentSecurityPolicy: {
+      directives: { upgradeInsecureRequests: null },
+    },
+  },
+
+  // 앱 전용 분산 락 — 글로벌(memory)과 달리 redis backend. lock.cache 는 글로벌 services.caches 키를 참조.
+  lock: { cache: 'webLock' },
+
+  // 앱 전용 버스 — 글로벌과 같은 NATS(`events`)지만 prefix 가 달라(web.) admin(glob.)과 격리된다.
+  bus: { nats: 'events', prefix: 'web.' },
+}