mega-framework 0.1.1 → 0.1.2

package/.env

@@ -92,7 +92,7 @@ NATS_JOBS_URL=nats://localhost:4222
 # WS Hub (mega ws-hub CLI — src/cli/ws-hub.js, runWsHubCli)
 # 코드가 읽는 키는 MEGA_WSHUB_* (언더스코어 없는 단일 service 토큰). TOKENS 만 필수.
 # 비밀 토큰은 운영에서 교체. hub 는 `mega ws-hub` 실행 시에만 기동(자동 기동 없음).
-MEGA_WSHUB_TOKENS=change-me
+MEGA_WSHUB_TOKENS=dev-bridge-token-change-me
 MEGA_WSHUB_PORT=3100
 MEGA_WSHUB_HOST=0.0.0.0
 MEGA_WSHUB_HEARTBEAT_MS=25000

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-framework",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {
@@ -118,4 +118,4 @@
     "redlock": "5.0.0-beta.2",
     "ws": "^8.21.0"
   }
-}
+}

package/sample/crud/.env

@@ -1,4 +1,4 @@
-PORT=4102
+PORT=3000
 DATABASE_URL=postgres://mega:dkTkqkfl12@localhost:5432/mega_test
 MEGA_CLUSTER_WORKERS=8
 SESSION_SECRET=Zz4VoSzf0sYMEoqASu8G_wx5l3uKi2MlHsxDK3MSkoE
@@ -9,6 +9,13 @@ REDIS_LOCK_URL=redis://:dkTkqkfl12@localhost:6379/3
 MONGO_URL=mongodb://mega:dkTkqkfl12@localhost:27017/mega_test?authSource=admin
 NATS_JOBS_URL=nats://localhost:4222
 ASP_MASTER_SECRET=demo-asp-master-7Qe2mWzR1tYbN8sLpKvX0cAfH4dG6jU
+
+MEGA_WSHUB_TOKENS=dev-bridge-token-change-me
+MEGA_WSHUB_TOKEN=dev-bridge-token-change-me
+MEGA_WSHUB_PORT=3100
+MEGA_WSHUB_HOST=0.0.0.0
+MEGA_WSHUB_URL=ws://localhost:3100
+
 MEGA_OTEL_ENABLED=true
 MEGA_OTEL_SERVICE_NAME=sample-crud
 MEGA_OTEL_ENDPOINT=http://localhost:4318/v1/traces
@@ -16,3 +23,5 @@ MEGA_OTEL_EXPORTER=otlp
 MEGA_OTEL_SAMPLING_RATIO=1.0
 MEGA_OTEL_ZIPKIN_API=http://localhost:9411/api/v2
 DEMO_UPLOAD_DIR=var/uploads
+
+BRIDGE_ID=crud-1

package/sample/crud/apps/main/app.config.js

@@ -72,6 +72,18 @@ export default {
     },
   },
 
+  // WS Hub 브릿지(ADR-065/176) — 별도 `mega ws-hub` 서버(localhost:3100, .env MEGA_WSHUB_*)에 연결.
+  // boot 가 이 블록을 보고 **app.connectHub 를 자동 호출**한다(ADR-176 자동배선 — connectHub 코드 불요).
+  // 채팅(/ws/chat)은 app.broadcast → hub fan-out 으로 클러스터 전파된다. retry 로 허브 재시작·drain(4503)·
+  // 네트워크 단절 시 지수 백오프 재연결(ADR-098). ⚠️ global wsCluster(NATS)와 **동시 사용 불가**(부팅 fail-fast).
+  bridgeHub: {
+    url: process.env.MEGA_WSHUB_URL ?? 'ws://localhost:3100',
+    token: process.env.MEGA_WSHUB_TOKEN,
+    bridgeId: process.env.BRIDGE_ID ?? 'main-1',
+    channels: ['chat'],
+    retry: { retries: 30, minTimeout: 1000, maxTimeout: 10_000 },
+  },
+
   // rate limit 상향(ADR-073) — /demo/worker 데모는 1초 간격 하트비트 ping(메인 스레드 non-block 시연)으로
   // 폴링한다. 기본 한도(100/분)는 폴링 + 일반 탐색이 겹치면 쉽게 넘어 데모가 429 로 끊긴다. 데모 앱이라
   // 폴링을 허용하도록 한도를 넉넉히 둔다(여전히 ON — 무제한 아님). 운영 앱은 엔드포인트별로 더 낮게 잡는다.

package/sample/crud/mega.config.js

@@ -79,14 +79,18 @@ export default {
     },
   },
 
-  // WS 클러스터 broadcast + roster 자동배선(ADR-176) — `bus`(NATS 'jobs' 재사용)가 있으면 프레임워크가
-  // app.broadcast/joinSession 의 **클러스터 fan-out·접속자목록 동기화**를 NATS 로 자동 처리한다. 채널
-  // (ChatChannel)은 connectHub·redis pub/sub·roster 코드 없이 ctx.presence 로 비즈니스 로직만 작성한다.
-  // roster.driver:'nats' → 접속자 목록도 NATS 로 동기화(crash 정리는 ttlMs heartbeat). 'none' 이면 로컬만.
-  wsCluster: {
-    bus: 'jobs',
-    roster: { driver: 'nats', ttlMs: 15_000 },
-  },
+  // ── 클러스터 전송 선택(ADR-176, 앱당 하나·상호배타) ───────────────────────────────────────────
+  // 이 샘플은 현재 **WS Hub**(app.config 의 bridgeHub → `mega ws-hub` 서버, localhost:3100)로 채팅을
+  // 클러스터 전파한다. boot 가 bridgeHub 를 보고 app.connectHub 를 자동 호출한다(개발자 배선 불요).
+  //
+  // ⚠️ NATS 로 다시 전환하려면: app.config 의 `bridgeHub` 블록을 제거(또는 주석)하고 아래 wsCluster 를
+  //    되살린다. **둘을 동시에 두면 부팅 시 config.cluster_transport_conflict 로 fail-fast**(이중 전파 방지).
+  //
+  // // NATS wsCluster (대안 — bridgeHub 와 동시 사용 불가):
+  // wsCluster: {
+  //   bus: 'jobs',                                  // services.buses 의 NATS 키 재사용
+  //   roster: { driver: 'nats', ttlMs: 15_000 },    // 접속자목록도 NATS 동기화(crash 정리 heartbeat). 'none'=로컬만
+  // },
 
   // 정기 작업(ADR-028/118) — `mega scheduler` 프로세스가 등록·실행한다(config.schedules, ADR-123).
   schedules: [CronCounterSchedule],

package/sample/crud/scripts/start-ws-hub.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# sample/crud — WS Hub 서버 기동 스크립트 (ADR-032/176)
+#
+# 별도 hub 프로세스(`mega-ws-hub` 바이너리, mega-framework bin)를 localhost:3100 에 띄운다.
+# 앱(`yarn dev` = `mega start`)이 app.config 의 `bridgeHub` 로 이 허브에 **자동 연결**한다(ADR-176).
+#
+# ⚠️ `mega-ws-hub` 는 `mega start` 와 달리 `.env` 를 자동 로드하지 않는다(직접 process.env 만 읽음,
+#    src/cli/ws-hub.js). 그래서 Node 20.6+ 의 `--env-file` 로 .env 를 주입한다.
+#    읽는 env(src/cli/ws-hub.js runWsHubCli): MEGA_WSHUB_TOKENS(필수, 콤마구분) /
+#    MEGA_WSHUB_PORT(기본 3100) / MEGA_WSHUB_HOST(기본 0.0.0.0) / MEGA_WSHUB_HEARTBEAT_MS.
+#
+# 사용:
+#   sample/crud/scripts/start-ws-hub.sh                 # .env 값으로 기동(localhost:3100)
+#   MEGA_WSHUB_PORT=4100 scripts/start-ws-hub.sh        # 일부 오버라이드(실 env 가 .env 보다 우선)
+#   scripts/start-ws-hub.sh --some-extra-flag           # 추가 인자는 mega-ws-hub 로 전달
+# ─────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+# sample/crud 루트로 이동(스크립트 위치 기준 — 어디서 호출해도 동작).
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+ENV_FILE=".env"
+BIN="node_modules/mega-framework/bin/mega-ws-hub.js"
+
+# 사전 점검 — 누락 시 silent 진행 금지, 이유를 명확히 알린다(P4/P7).
+[ -f "$ENV_FILE" ] || {
+  echo "✗ $ROOT/$ENV_FILE 가 없습니다 — MEGA_WSHUB_TOKENS 등 허브 설정이 필요합니다." >&2
+  exit 1
+}
+[ -f "$BIN" ] || {
+  echo "✗ $BIN 없음 — 먼저 'yarn install --ignore-engines'(또는 npm install) 로 mega-framework 를 설치/동기화하세요." >&2
+  exit 1
+}
+
+echo "▶ WS Hub 기동 (mega-ws-hub) — host=${MEGA_WSHUB_HOST:-(.env)} port=${MEGA_WSHUB_PORT:-(.env, 기본 3100)}.  Ctrl+C 로 종료."
+# --env-file: .env 를 process.env 로 로드(이미 export 된 실 env 가 우선 — --env-file 표준 동작).
+# exec 로 교체 실행 → 시그널(SIGINT/SIGTERM)이 mega-ws-hub 로 그대로 전달되어 graceful 종료(drain 4503).
+exec node --env-file="$ENV_FILE" "$BIN" "$@"

package/sample/crud/yarn.lock

@@ -1234,7 +1234,7 @@ marked@^18.0.5:
   integrity sha512-S6GcvALHg6K4ohtu4E7x0a1AqhAjp6cV8KhLSyN9qVapnzJkusVBxZRcIU9AeYsbe6P1hKDusSbEOzGyyuce6w==
 
 "mega-framework@file:../..":
-  version "0.1.0"
+  version "0.1.1"
   dependencies:
     "@fastify/cookie" "^11.0.2"
     "@fastify/cors" "^11.2.0"

package/sample/simple/package.json

@@ -16,7 +16,7 @@
     "test": "mega test"
   },
   "dependencies": {
-    "mega-framework": "file:../.."
+    "mega-framework": "^0.1.1"
   },
   "devDependencies": {
     "concurrently": "^9.0.0",

package/src/core/boot.js

@@ -294,17 +294,30 @@ export async function bootApp(projectRoot, { listen = true, port, host: listenHo
     megaApps.push(app)
   }
 
-  // wsCluster 자동배선 (ADR-176) — global `wsCluster.bus`(NATS) 가 있으면 앱마다 MegaWsCluster 를 만들어
-  // app.broadcast/directToUser/joinSession 의 **클러스터 fan-out·roster 동기화**를 배선한다. 개발자는
-  // connectHub 같은 코드를 쓰지 않고 비즈니스 로직만 작성한다(ADR-176 이 ADR-137 자동배선 거부를 wsCluster
-  // 에 한해 번복). bus 는 글로벌 키 직접 lookup(이미 connect 됨). roster 설정(driver/ttlMs)을 그대로 전달.
+  // 클러스터 전송 자동배선 (ADR-176) — 앱당 **하나**(상호배타, config-validator 가 충돌 fail-fast). config 로 선택:
+  //   - app.config `bridgeHub` → **WS Hub**(`app.connectHub`, 평문 12-타입). `mega ws-hub` 서버에 자동 연결.
+  //   - global `wsCluster.bus`(NATS) → **MegaWsCluster**(NATS pub/sub broadcast + roster 동기화).
+  // 둘 다 개발자가 connectHub 같은 코드를 쓰지 않고 config 만으로 동작한다(ADR-176 이 ADR-137 의 자동배선
+  // 거부를 **명시 config 가 있을 때만** 번복 — 설정이 곧 의도라 "추측 배선" 아님). megaApps[i] 와 apps[i] 동순서.
   const wsClusterCfg = /** @type {any} */ (global).wsCluster
-  if (wsClusterCfg?.bus) {
-    const busAdapter = getAdapter('bus', wsClusterCfg.bus)
-    for (const app of megaApps) {
-      const a = /** @type {any} */ (app) // _deliverBroadcast/_deliverDirect 는 framework-internal(@private).
+  const wsClusterBus = wsClusterCfg?.bus ? getAdapter('bus', wsClusterCfg.bus) : null
+  for (let i = 0; i < megaApps.length; i++) {
+    const app = megaApps[i]
+    const a = /** @type {any} */ (app) // _deliverBroadcast/_deliverDirect 는 framework-internal(@private).
+    const bridgeHub = /** @type {any} */ (apps[i].config).bridgeHub
+    if (bridgeHub?.url) {
+      // WS Hub 자동연결(ADR-065/176). connectHub 가 _hubLink 를 세워 app.broadcast/joinSession 의 hub 경로를
+      // 활성화한다(shutdown hook 도 connectHub 가 등록). 허브 다운이어도 boot 를 막지 않는다 — 초기 연결
+      // 실패는 warn 하고(retry 설정 시 백그라운드 재연결, ADR-098) 앱은 계속 뜬다(로컬 전달은 동작).
+      try {
+        await app.connectHub(bridgeHub)
+        logger?.debug?.({ app: app.name, url: bridgeHub.url }, 'boot.bridgeHub connected (ADR-176)')
+      } catch (err) {
+        logger?.warn?.({ err, app: app.name, url: bridgeHub.url }, 'boot.bridgeHub initial connect failed (retry if configured)')
+      }
+    } else if (wsClusterBus) {
       const cluster = new MegaWsCluster({
-        bus: /** @type {any} */ (busAdapter),
+        bus: /** @type {any} */ (wsClusterBus),
         appName: app.name,
         deliverBroadcast: (/** @type {any} */ p) => a._deliverBroadcast(p),
         deliverDirect: (/** @type {any} */ p) => a._deliverDirect(p),
@@ -317,10 +330,9 @@ export async function bootApp(projectRoot, { listen = true, port, host: listenHo
       // MegaShutdown LIFO — 어댑터 disconnect 보다 먼저 정리(graceful LEAVE 가 NATS 끊기기 전에 나가게).
       MegaShutdown.register(`mega-ws-cluster:${app.name}`, async () => cluster.stop())
     }
-    logger?.debug?.(
-      { bus: wsClusterCfg.bus, apps: megaApps.length, roster: wsClusterCfg.roster?.driver ?? 'none' },
-      'boot.wsCluster wired (ADR-176)',
-    )
+  }
+  if (wsClusterBus) {
+    logger?.debug?.({ bus: wsClusterCfg.bus, roster: wsClusterCfg.roster?.driver ?? 'none' }, 'boot.wsCluster wired (ADR-176)')
   }
 
   // 9단계: HTTP listen(분기 — CLI/테스트가 listen=false 로 mount 까지만 받을 수 있음).

package/src/core/config-validator.js

@@ -265,6 +265,30 @@ export function validateAppConfig(appConfig, expectedFolderName, globalConfig) {
     )
   }
 
+  // 2b) bridgeHub(WS Hub 브릿지, ADR-065/176) 검증 + wsCluster 상호배타.
+  //     클러스터 전송은 앱당 **하나**다 — bridgeHub(WS Hub) 와 global wsCluster(NATS) 를 동시에 쓰면
+  //     app.broadcast 가 양쪽으로 나가 이중 전파된다. 부팅 시 fail-fast 로 막는다(boot 가 둘 중 하나만 배선).
+  if (appConfig.bridgeHub !== undefined) {
+    const bh = appConfig.bridgeHub
+    if (typeof bh !== 'object' || bh === null || Array.isArray(bh)) {
+      throw new MegaConfigError('config.bridgeHub_invalid', `app '${expectedFolderName}': bridgeHub must be an object ({ url, token, ... }).`, {
+        details: { app: expectedFolderName },
+      })
+    }
+    if (typeof bh.url !== 'string' || bh.url.length === 0) {
+      throw new MegaConfigError('config.bridgeHub_url_required', `app '${expectedFolderName}': bridgeHub.url (ws:// hub address) is required.`, {
+        details: { app: expectedFolderName },
+      })
+    }
+    if (globalConfig?.wsCluster?.bus) {
+      throw new MegaConfigError(
+        'config.cluster_transport_conflict',
+        `app '${expectedFolderName}': bridgeHub(WS Hub) 와 global wsCluster(NATS) 를 동시에 쓸 수 없다 — 클러스터 전송은 앱당 하나만 선택하세요(ADR-176).`,
+        { details: { app: expectedFolderName, bridgeHubUrl: bh.url, wsClusterBus: globalConfig.wsCluster.bus } },
+      )
+    }
+  }
+
   // 3) Shared-Reference 키 검증 — 참조하는 키가 globalConfig.services 에 존재해야 함
   for (const refKey of SHARED_REFERENCE_KEYS) {
     if (!appConfig[refKey]) continue