mega-framework 0.1.0

package/src/core/boot.js

@@ -0,0 +1,323 @@
+// @ts-check
+/**
+ * 중앙 부팅 orchestrator — config·어댑터·플러그인·앱을 02-architecture §14 순서로 엮는다.
+ *
+ * config-loader / adapter-manager / MegaPluginHost / MegaApp·MegaServer 는 각자 완결돼 있으나
+ * 이를 잇는 중앙 지점이 없었다([ADR-122](../../docs/09-decisions-and-open-questions.md)).
+ * 본 모듈이 그 단일 지점이다 — `loadPlugins` 를 실 부팅 시퀀스에 끼우고 lifecycle hook(beforeBoot/
+ * afterBoot/beforeShutdown)을 구동한다(ADR-123).
+ *
+ * # 부팅 시퀀스 (02-architecture §14 — 4·5단계 = 플러그인)
+ *   1. `loadAndValidateConfig(projectRoot)` — mega.config.js + app.config.js 로드·검증(1~3단계).
+ *   4·5. `loadPlugins(global.plugins, host, { projectRoot })` — resolve→shape→apiVersion→install(순서대로).
+ *   2. `buildFromGlobalConfig(global)` — 어댑터 인스턴스화 + LIFO shutdown hook(**앱 생성보다 먼저**,
+ *      adapter-manager 종료 순서 주석).
+ *   3. `connectAll({ ping })` — 어댑터 connect(+옵션 healthCheck). 실패 시 매니저가 LIFO cleanup 후 throw.
+ *   7. `host.runLifecycle('beforeBoot', ctx)` — 부팅 직전 hook(L-2 ctx 주입).
+ *   6. 각 앱: `new MegaApp({ ...config, plugins, globalMiddlewares })` + 라우트 자동 로딩 + vhost mount.
+ *   9. `server.listen({ port, host })`(listen=false 면 건너뜀 — 테스트/CLI 분기).
+ *   10. `host.runLifecycle('afterBoot', ctx)` — 부팅 완료 hook.
+ *   +  beforeShutdown hook 을 `MegaShutdown` 에 브리지(graceful, per-hook catch — ADR-122).
+ *
+ * # ⚠️ install → buildFromGlobalConfig 순서 (config-driven driver 의 핵심 제약)
+ *   roadmap §224 검증기준("샘플 플러그인이 `adapters.register('sample')` → `services.databases.x.driver:
+ *   'sample'` 동작")이 성립하려면 **플러그인 install 이 `buildFromGlobalConfig` 보다 먼저** 와야 한다 —
+ *   install 이 driver 를 레지스트리에 등록해야 buildFromGlobalConfig 가 `registry.resolve('sample')` 로
+ *   인스턴스화할 수 있다. 그래서 §14 의 4·5(플러그인)를 어댑터 빌드 앞에 둔다(adapter-manager 의 "앱
+ *   생성보다 먼저" 제약도 그대로 만족 — install < build < app).
+ *
+ * wsHub embedded 모드(ADR-137): `global.wsHub.enabled === true` 면 본 orchestrator 가 어댑터 connect
+ * 뒤·앱 생성 전에 같은 프로세스에 `MegaWsHub` 를 띄운다(single-node). 앱↔hub 연결은 여전히 명시
+ * (`app.connectHub`/`bridgeHub` — localhost 주소)이며 자동 배선하지 않는다 — 프로토콜은 별도 프로세스
+ * (`bin/mega-ws-hub.js`)와 완전 동일(WS over localhost). `enabled` 가 아니면 hub 를 띄우지 않는다.
+ *
+ * @module core/boot
+ */
+import { join } from 'node:path'
+// 빌트인 어댑터(postgres/mongodb/mariadb/sqlite/redis/file/nats/redlock)는 import 시 레지스트리에
+// 자기등록한다(ADR-044). CLI 런타임 부팅(`mega start`/`worker`/`scheduler`/`migrate`)은 사용자 코드가
+// 'mega-framework' 를 import 하기 전에 `buildFromGlobalConfig` 로 driver 를 resolve 하므로, 이 배럴을
+// 부팅 진입 모듈에서 side-effect 로 먼저 로드해 빌트인 driver 등록을 보장한다(ADR-150 — E2E 발견 결함).
+import '../adapters/index.js'
+import { loadAndValidateConfig } from './config-loader.js'
+import { loadRoutes } from './routes-loader.js'
+import { loadServices } from './services-loader.js'
+import { MegaApp } from './mega-app.js'
+import { MegaServer } from './mega-server.js'
+import { MegaPluginHost, loadPlugins } from '../lib/mega-plugin.js'
+import { MegaShutdown } from '../lib/mega-shutdown.js'
+import { buildLogger } from '../lib/mega-logger.js'
+import { buildFromGlobalConfig, connectAll, get as getAdapter, entries as adapterEntries } from '../adapters/adapter-manager.js'
+import { buildWorkers, startAll as startWorkers, contextProxy as workersContext } from './workers-manager.js'
+import * as MegaMetrics from '../lib/mega-metrics.js'
+import * as MegaTracing from '../lib/mega-tracing.js'
+import { MegaWsHub } from '../cli/ws-hub.js'
+
+/**
+ * 부팅 결과 핸들.
+ * @typedef {Object} BootResult
+ * @property {MegaServer} server - mount 된 MegaServer(listen=false 면 미-listen 상태).
+ * @property {MegaPluginHost} host - 플러그인 호스트(install 완료, queryable).
+ * @property {Object} config - mega.config.js default export(global).
+ * @property {Array<{ name: string, config: Object }>} apps - 로드된 앱 config 목록.
+ * @property {MegaApp[]} megaApps - 생성된 MegaApp 인스턴스(등록 순서).
+ * @property {BootContext} ctx - lifecycle hook 에 넘긴 boot context.
+ * @property {import('../cli/ws-hub.js').MegaWsHub | null} wsHub - embedded wsHub(ADR-137, `wsHub.enabled` OFF 면 null).
+ */
+
+/**
+ * lifecycle hook(beforeBoot/afterBoot/beforeShutdown)이 받는 boot context (L-2/ADR-123).
+ * `db/cache/bus/lock` 은 **글로벌 키 직접 lookup**(앱 별명 변환 없음 — boot 레벨은 별명 스코프 밖).
+ * @typedef {Object} BootContext
+ * @property {Object} config - global config.
+ * @property {{ debug?: Function, info?: Function, warn?: Function }} [log]
+ * @property {(globalKey: string) => import('../adapters/mega-adapter.js').MegaAdapter} db
+ * @property {(globalKey: string) => import('../adapters/mega-adapter.js').MegaAdapter} cache
+ * @property {(globalKey: string) => import('../adapters/mega-adapter.js').MegaAdapter} bus
+ * @property {(globalKey: string) => import('../adapters/mega-adapter.js').MegaAdapter} lock
+ * @property {Record<string, import('../lib/mega-worker.js').MegaWorker>} workers - `ctx.workers.<name>.run(task)` (ADR-124).
+ */
+
+/**
+ * ASP 설정 합성 (ADR-127) — global 스코프의 `masterSecret`(시크릿)과 앱 스코프의 옵트인 범위
+ * (`http.enabledPaths` / `websocket.namespaces`)를 하나로 합친다. 앱이 자체 masterSecret 을 명시하면
+ * 그쪽이 우선한다(앱 override). 둘 다 없으면 `undefined`(ASP 미사용).
+ *
+ * @param {{ masterSecret?: string } | undefined} globalAsp - mega.config.js 의 `asp`.
+ * @param {Record<string, any> | undefined} appAsp - app.config.js 의 `asp`.
+ * @returns {Record<string, any> | undefined}
+ */
+function composeAspConfig(globalAsp, appAsp) {
+  const masterSecret = appAsp?.masterSecret ?? globalAsp?.masterSecret
+  if (!masterSecret && !appAsp) return undefined
+  return { ...appAsp, ...(masterSecret ? { masterSecret } : {}) }
+}
+
+/**
+ * boot/CLI 컨텍스트 — `db/cache/bus/lock` 을 글로벌 키로 직접 조회하고, `workers` 는 `static name` 으로
+ * lookup 한다(앱 별명 변환 없음 — 둘 다 글로벌 자원). worker/scheduler CLI 도 같은 형태를 재사용한다
+ * (잡/스케줄의 `static bus`/`static lock` = 글로벌 키; 잡이 CPU 작업을 `ctx.workers` 로 오프로드 가능).
+ * @param {Object} global - global config.
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
+ * @returns {BootContext}
+ */
+export function buildBootContext(global, logger) {
+  return {
+    config: global,
+    log: logger,
+    db: (key) => getAdapter('db', key),
+    cache: (key) => getAdapter('cache', key),
+    bus: (key) => getAdapter('bus', key),
+    lock: (key) => getAdapter('lock', key),
+    workers: workersContext(), // ctx.workers.<name> — 미등록 이름 접근 시 worker.not_registered fail-fast.
+  }
+}
+
+/**
+ * 런타임 공통 준비 — config 로드 → 플러그인 install → 어댑터 build → connect → boot ctx.
+ * `bootApp`(서버)·`mega worker`/`mega scheduler`(CLI 호스트)가 **같은 순서**를 공유한다(install <
+ * build — config-driven driver 제약, 위 주석 참조). lifecycle hook/앱 생성/ listen 직전까지의 토대.
+ *
+ * @param {string} projectRoot
+ * @param {{ ping?: boolean, logger?: { debug?: Function, info?: Function, warn?: Function } }} [opts]
+ * @returns {Promise<{ global: Object, apps: Array<{ name: string, config: Object }>, host: MegaPluginHost, ctx: BootContext, wsHub: (MegaWsHub | null) }>}
+ */
+export async function prepareRuntime(projectRoot, { ping = false, logger } = {}) {
+  // 1~3단계: config 로드 + 검증.
+  const { global, apps } = await loadAndValidateConfig(projectRoot)
+  logger?.debug?.({ apps: apps.map((a) => a.name) }, 'boot.config loaded')
+
+  // 4·5단계: 플러그인 로딩 + install — **어댑터 빌드보다 먼저**(config-driven driver, 상단 주석 참조).
+  const host = new MegaPluginHost({ logger })
+  await loadPlugins(/** @type {any} */ (global).plugins, host, { projectRoot, logger })
+  logger?.debug?.({ plugins: host.loadedPlugins.map((p) => p.name) }, 'boot.plugins installed')
+
+  // 어댑터 인스턴스화 + connect (MegaApp 생성보다 먼저 — LIFO shutdown 순서, adapter-manager 주석).
+  buildFromGlobalConfig(global)
+  await connectAll({ logger, ping })
+  logger?.debug?.('boot.adapters connected')
+
+  // 메트릭 SDK 옵트인 (ADR-072/131) — global `health.exposeMetrics:true` 면 MegaMetrics 초기화
+  // + 어댑터 onCallEnd 일괄 구독(connect 직후 — 모든 공유 어댑터 호출이 mega_adapter_* 메트릭으로 집계).
+  // 옵트인 OFF 면 init 미호출 → 모든 record* 가 0 비용. /metrics 라우트는 MegaApp 이 같은 config 로 등록.
+  const healthCfg = /** @type {any} */ (global).health
+  if (healthCfg && healthCfg.exposeMetrics === true && !MegaMetrics.isEnabled()) {
+    MegaMetrics.init({
+      serviceName: healthCfg.serviceName ?? /** @type {any} */ (global).server?.serviceName ?? process.env.MEGA_OTEL_SERVICE_NAME ?? 'mega-framework',
+      version: /** @type {any} */ (global).server?.version,
+      environment: process.env.NODE_ENV,
+    })
+    const subscribed = MegaMetrics.attachToManager({ entries: adapterEntries })
+    MegaShutdown.register('mega-metrics', async () => {
+      await MegaMetrics.shutdown()
+    })
+    logger?.debug?.({ subscribed }, 'boot.metrics enabled')
+  }
+
+  // 트레이싱 SDK 옵트인 (ADR-104/114/126/163) — `MEGA_OTEL_ENABLED=true` env 면 MegaTracing 초기화 + 어댑터
+  // onCallEnd 일괄 구독(자동 span, ADR-114). 메트릭(위)과 대칭 — `fromEnv` 가 env 게이트(미설정/false=no-op,
+  // 0 비용)한다. 미옵트인이면 mega-app 의 HTTP/WS 루트 span·`ctx.tracer.span` 이 모두 no-op. **부팅에서 한 번
+  // 켜야 프로덕션 분산 트레이싱이 동작한다** — 이전엔 boot 가 `MegaTracing.fromEnv()` 를 호출하지 않아(메트릭만
+  // 배선) 프로덕션에서 트레이싱이 미작동했다(ADR-163 에서 boot 배선 추가). 재진입 방지로 isEnabled 가드.
+  if (!MegaTracing.isEnabled() && MegaTracing.fromEnv() === true) {
+    const tracedAdapters = MegaTracing.attachToManager({ entries: adapterEntries })
+    MegaShutdown.register('mega-tracing', async () => {
+      await MegaTracing.shutdown()
+    })
+    logger?.debug?.({ subscribed: tracedAdapters }, 'boot.tracing enabled')
+  }
+
+  // CPU 워커 풀(ADR-124) — 등록 소스 = `config.workers`(정적) + 플러그인 `host.listWorkers()`(동적,
+  // ADR-134). jobs/schedules 듀얼 소스(`collectRegistrations`, ADR-123)와 동형이다. `buildWorkers` 가
+  // `static name` 중복을 부팅 시 fail-fast 한다. 어댑터 connect **뒤**에 등록되므로 MegaShutdown LIFO 상
+  // 워커가 어댑터보다 먼저 정리된다(워커가 어댑터를 쓰는 정리를 어댑터 종료 전에 끝냄).
+  const workerClasses = [...(/** @type {any} */ (global).workers ?? []), ...host.listWorkers()]
+  buildWorkers({ workers: /** @type {any} */ (workerClasses) }, { projectRoot })
+  await startWorkers({ logger })
+  logger?.debug?.({ workers: workerClasses.length }, 'boot.workers started')
+
+  // embedded wsHub (ADR-137) — `global.wsHub.enabled=true` 면 같은 프로세스에 hub 를 띄운다(single-node).
+  // 어댑터 connect 뒤·앱 생성 전에 listen 상태로 만들어 앱이 bridgeHub(localhost)로 붙을 수 있게 한다.
+  // 빈 acceptedTokens 면 MegaWsHub 생성자가 fail-fast throw(ADR-059). SIGTERM 시 drain(4503) 종료.
+  const wsHub = await startEmbeddedWsHub(/** @type {any} */ (global).wsHub, logger)
+
+  const ctx = buildBootContext(global, logger)
+  return { global, apps, host, ctx, wsHub }
+}
+
+/**
+ * embedded wsHub 기동 (ADR-137) — `cfg.enabled === true` 일 때만 `MegaWsHub` 를 같은 프로세스에 띄우고
+ * `MegaShutdown` 에 drain 종료 hook 을 등록한다. 아니면 `null`(미기동). 검증(빈 토큰 등)은 MegaWsHub
+ * 생성자에 위임한다(ADR-059 — fail-fast). 별도 프로세스(`runWsHubCli`)와 동일한 hub 구현·프로토콜.
+ *
+ * @param {any} cfg - `global.wsHub`(MegaWsHubConfig).
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
+ * @returns {Promise<MegaWsHub | null>}
+ */
+async function startEmbeddedWsHub(cfg, logger) {
+  if (!cfg || cfg.enabled !== true) return null
+  const hub = new MegaWsHub({
+    acceptedTokens: cfg.acceptedTokens,
+    heartbeatMs: cfg.heartbeatMs,
+    compression: cfg.compression,
+    logger,
+  })
+  const addr = await hub.start({ port: cfg.port, host: cfg.host })
+  MegaShutdown.register('mega-ws-hub-embedded', async () => hub.stop({ drain: true }))
+  logger?.debug?.({ host: addr.host, port: addr.port, hubId: hub.hubId }, 'boot.wsHub embedded started')
+  return hub
+}
+
+/**
+ * 프로젝트를 부팅한다 — config→어댑터→플러그인→앱→listen 을 §14 순서로 엮는다.
+ *
+ * 어느 단계든 실패하면 그대로 throw(fail-fast). 어댑터 connect 실패는 매니저가 LIFO cleanup 하고,
+ * 그 외 단계 실패(예: server.listen EADDRINUSE, beforeBoot hook throw)는 어댑터가 이미 connect 돼
+ * `'adapters:disconnect'` MegaShutdown hook 이 등록된 상태라, 호출자가 `MegaShutdown.now` 로 그 hook 을
+ * LIFO 실행해 정리해야 한다 — `bin/mega.js` 의 catch 가 이 정리 경로를 배선한다(M-1). 그러지 않으면
+ * 연결된 어댑터가 이벤트루프를 살려 프로세스가 hang 한다.
+ *
+ * @param {string} projectRoot - 프로젝트 루트 절대 경로(mega.config.js 가 있는 곳).
+ * @param {Object} [opts]
+ * @param {boolean} [opts.listen=true] - false 면 mount 까지만(테스트·검증용).
+ * @param {number} [opts.port] - listen 포트(미지정 시 server/global 기본).
+ * @param {string} [opts.host] - listen 호스트.
+ * @param {boolean} [opts.ping=false] - connectAll 시 healthCheck 까지 검증.
+ * @param {{ debug?: Function, info?: Function, warn?: Function }} [opts.logger] - 길목 debug 로그(선택).
+ * @returns {Promise<BootResult>}
+ */
+export async function bootApp(projectRoot, { listen = true, port, host: listenHost, ping = false, logger } = {}) {
+  logger?.debug?.({ projectRoot }, 'boot.start')
+
+  // 1~5단계 + 어댑터 connect 공통 토대(config → 플러그인 install → 어댑터 build → connect → boot ctx).
+  const { global, apps, host, ctx, wsHub } = await prepareRuntime(projectRoot, { ping, logger })
+
+  // 7단계: beforeBoot hook(부팅 직전, fail-fast).
+  await host.runLifecycle('beforeBoot', ctx)
+
+  // pino 로거(ADR-023/141) — global.logger 로 인스턴스를 한 번 만들어 모든 앱이 공유한다(worker thread·
+  // 파일 핸들 1벌). 비활성(logger 미설정/sinks 없음)이면 null → 앱은 logger:false(무로그). graceful shutdown
+  // 시 flush(버퍼·worker transport drain). MegaShutdown LIFO 라 어댑터/앱보다 나중 등록 = 가장 먼저 정리되지
+  // 않게(로그가 종료 과정 끝까지 살아 있도록) — 마지막 flush 단계(07-sequence §6).
+  const appLogger = buildLogger(/** @type {any} */ (global).logger)
+  if (appLogger) {
+    MegaShutdown.register('mega-logger', async () => {
+      await new Promise((resolve) => appLogger.flush(() => resolve(undefined)))
+    })
+  }
+
+  // listen 포트·호스트 해석 — CLI 인자(`--port`/`--host`) 우선, 없으면 정본 server config
+  // (`global.server.port`/`host`, 04-data-models §183: port 기본 3000·host 기본 '0.0.0.0').
+  // boot 가 config→listen 의 유일한 배선 지점이라 여기서 읽지 않으면 `server.port`/`PORT` 가 죽는다.
+  // 최종 폴백(3000/'0.0.0.0')은 MegaServer.listen 이 가진다(여기선 undefined 면 그대로 위임).
+  const serverCfg = /** @type {any} */ (global).server ?? {}
+  const resolvedPort = port ?? serverCfg.port
+  const resolvedHost = listenHost ?? serverCfg.host
+
+  // 6단계: 각 앱 Fastify 인스턴스 생성 + 라우트 자동 로딩 + 플러그인 주입 + vhost mount.
+  const server = new MegaServer({ port: resolvedPort, host: resolvedHost })
+  /** @type {MegaApp[]} */
+  const megaApps = []
+  for (const { name, config } of apps) {
+    const app = new MegaApp({
+      ...config,
+      name, // config.name(검증됨) 위에 폴더명을 확정(둘은 동일, ADR-067).
+      logger: appLogger ?? false, // pino 로거 주입(공유 인스턴스, ADR-141).
+      // ASP masterSecret 은 global 스코프(시크릿, scope-registry)라 앱 asp 옵트인에 합성한다(ADR-127).
+      // 앱 config.asp 가 http.enabledPaths/websocket 등 옵트인 범위를, global.asp 가 masterSecret 을 제공.
+      asp: composeAspConfig(/** @type {any} */ (global).asp, /** @type {any} */ (config).asp),
+      // 세션 쿠키 HMAC 시크릿은 global 스코프(server.sessionSecret, scope-registry)라 앱에 주입한다
+      // (ASP masterSecret 합성과 동일 패턴, ADR-129). 앱 session.secret 명시 시 그쪽이 우선(MegaApp).
+      sessionSecret: /** @type {any} */ (global).server?.sessionSecret,
+      // 운영 관측성 config 는 Global-only(ADR-072/131) — global `health` 블록을 모든 앱에 주입한다(/metrics
+      // 라우트 등록 + 보안 면제 + IP allowList). sessionSecret 주입과 동일 패턴.
+      health: /** @type {any} */ (global).health,
+      plugins: host.fastifyPlugins,
+      globalMiddlewares: host.globalMiddlewares,
+    })
+    // OpenAPI 옵트인 시 배리어(ADR-140): @fastify/swagger 의 onRoute 수집 훅은 plugin 로드 후 설치되므로,
+    // 라우트 동기 등록 전에 swagger 를 먼저 로드시켜야 라우트가 명세에 수집된다. `after()` 가 생성자에서 큐된
+    // 등록(swagger 포함)을 flush 한다. 비-openapi 앱은 timing 변경 없이 건너뜀(_openapiPath=null).
+    if (app._openapiPath) await app.fastify.after()
+    // 서비스 자동 로딩(ADR-148) — apps/<name>/services/*.js 를 name→Class 레지스트리로 만들어 앱에 주입한다.
+    // 라우트 등록 전에 채워 두면, 요청 ctx 의 ctx.services.<name> lazy DI 가 첫 요청부터 동작한다.
+    const servicesDir = join(projectRoot, 'apps', name, 'services')
+    const serviceRegistry = await loadServices({ servicesDir, appName: name })
+    app.setServiceRegistry(serviceRegistry)
+    logger?.debug?.({ app: name, services: serviceRegistry.size }, 'boot.services loaded')
+
+    const routesDir = join(projectRoot, 'apps', name, 'routes')
+    const { filesLoaded } = await loadRoutes({ fastify: app.fastify, appName: name, routesDir, app })
+    logger?.debug?.({ app: name, filesLoaded }, 'boot.routes loaded')
+    server.mount(app)
+    megaApps.push(app)
+  }
+
+  // 9단계: HTTP listen(분기 — CLI/테스트가 listen=false 로 mount 까지만 받을 수 있음).
+  if (listen) {
+    await server.listen({ port: resolvedPort, host: resolvedHost })
+    logger?.info?.({ hosts: server.hosts }, 'boot.listening')
+  }
+
+  // 10단계: afterBoot hook(부팅 완료).
+  await host.runLifecycle('afterBoot', ctx)
+
+  // beforeShutdown hook 을 graceful 종료 경로에 브리지(per-hook catch — graceful 중 한 hook 실패가
+  // 나머지 정리를 막으면 안 됨, ADR-122). MegaShutdown LIFO 라 어댑터 hook 보다 나중 등록 =
+  // 어댑터 disconnect 보다 먼저 실행(플러그인이 어댑터를 쓰는 정리를 어댑터 종료 전에 끝냄).
+  const shutdownHooks = host.lifecycleHooks('beforeShutdown')
+  if (shutdownHooks.length > 0) {
+    MegaShutdown.register('plugin:beforeShutdown', async () => {
+      for (const fn of shutdownHooks) {
+        try {
+          await fn(ctx)
+        } catch (err) {
+          logger?.warn?.({ err }, 'plugin beforeShutdown hook failed (continuing shutdown)')
+        }
+      }
+    })
+  }
+
+  logger?.debug?.('boot.done')
+  return { server, host, config: global, apps, megaApps, ctx, wsHub }
+}

package/src/core/cluster-metrics.js

@@ -0,0 +1,278 @@
+// @ts-check
+/**
+ * 클러스터 메트릭 집계 — `mega start` 클러스터 모드(ADR-154)에서 워커별로 흩어진 Prometheus 메트릭을
+ * 한 응답으로 합산한다(ADR-163).
+ *
+ * # 왜 필요한가 (중학생용 설명)
+ *   클러스터는 같은 포트를 여러 워커 프로세스가 나눠 받는다. 메트릭(요청 수 등)은 **프로세스마다 따로**
+ *   쌓이므로, `/metrics` 를 한 번 긁으면 그때 응답한 워커의 숫자만 나온다 — 새로고침마다 다른 워커라 숫자가
+ *   들쭉날쭉해 보인다. OpenTelemetry SDK 에는 프로세스 간 합산 기능이 없다(prom-client 의 AggregatorRegistry
+ *   가 하는 일을 우리가 한다). 그래서 마스터가 모든 워커의 메트릭을 IPC 로 모아 합산해 돌려준다.
+ *
+ * # 흐름 (prom-client AggregatorRegistry 패턴)
+ *   1. `/metrics` 요청이 한 워커에 도착 → 그 워커가 마스터에 `request` 를 보낸다({@link collectCluster}).
+ *   2. 마스터가 모든 워커에 `collect` 를 fan-out → 각 워커가 자기 `MegaMetrics.collect()` 텍스트를 `collected`
+ *      로 회신({@link installWorkerResponder}).
+ *   3. 마스터가 회신을 모아(전원 응답 또는 timeout) {@link mergeExposition} 로 합산 → 요청 워커에 `aggregated`
+ *      회신({@link installPrimaryAggregator}).
+ *   4. 요청 워커가 그 합산 텍스트로 응답.
+ *
+ * Node `cluster` IPC 는 워커↔마스터만 가능(워커끼리 직통 X)하므로 마스터가 relay 한다. 단일 프로세스(클러스터
+ * 비활성)면 `collectCluster` 가 그냥 로컬 `collect()` 를 돌려준다(IPC 없음).
+ *
+ * @module core/cluster-metrics
+ * @see ADR-154 (클러스터)
+ * @see ADR-163 (본 집계)
+ * @see https://github.com/siimon/prom-client (AggregatorRegistry 참고 패턴)
+ */
+import cluster from 'node:cluster'
+import * as MegaMetrics from '../lib/mega-metrics.js'
+
+/** IPC 메시지 타입 — 충돌 방지 prefix. */
+const MSG_REQUEST = 'mega:metrics:request' // 워커(HTTP) → 마스터: 클러스터 집계 요청.
+const MSG_AGGREGATED = 'mega:metrics:aggregated' // 마스터 → 워커(HTTP): 합산 결과.
+const MSG_COLLECT = 'mega:metrics:collect' // 마스터 → 전 워커: 메트릭 회신 요청.
+const MSG_COLLECTED = 'mega:metrics:collected' // 워커 → 마스터: 자기 메트릭 텍스트.
+
+/** 요청 correlation id 시퀀스(워커측). pid 와 합쳐 유니크. */
+let reqSeq = 0
+
+/**
+ * 여러 워커의 Prometheus exposition 텍스트를 하나로 합산한다(순수 — 테스트 가능).
+ *
+ * - **counter / histogram(_bucket/_sum/_count)**: 동일 `name{labels}` 끼리 값 **합산**(클러스터 누적).
+ * - **gauge**: 합산(메모리·CPU 는 클러스터 합이 유의미). 단 프로세스별 gauge(uptime 등)는 합이 N배가 되는
+ *   문서화된 한계 — prom-client 기본도 gauge=sum. `_info`/`target_info` 메타는 합산 대신 **첫 값 유지**(=1).
+ * - `# HELP`/`# TYPE` 는 패밀리별 1줄로 dedupe 하고, 패밀리(TYPE 이름) 단위로 묶어 재출력한다.
+ *
+ * @param {string[]} texts - 각 워커 `collect()` 결과(빈 문자열 허용).
+ * @returns {string} 합산된 exposition 텍스트(끝 개행 포함). 입력이 모두 비면 빈 문자열.
+ */
+export function mergeExposition(texts) {
+  /** @type {Map<string,string>} name → HELP 본문. */
+  const help = new Map()
+  /** @type {Map<string,string>} name → TYPE(예: 'counter'). */
+  const type = new Map()
+  /** @type {Map<string,{ labels: string, value: number, name: string }>} fullKey → 누적 샘플. */
+  const samples = new Map()
+
+  for (const text of texts) {
+    if (typeof text !== 'string' || text.length === 0) continue
+    for (const raw of text.split('\n')) {
+      const line = raw.trim()
+      if (line.length === 0) continue
+      if (line.startsWith('# HELP ')) {
+        const m = line.match(/^# HELP (\S+) (.*)$/)
+        if (m && !help.has(m[1])) help.set(m[1], m[2])
+        continue
+      }
+      if (line.startsWith('# TYPE ')) {
+        const m = line.match(/^# TYPE (\S+) (\S+)$/)
+        if (m && !type.has(m[1])) type.set(m[1], m[2])
+        continue
+      }
+      if (line.startsWith('#')) continue // 기타 주석 무시.
+      // 샘플: `name{labels} value [timestamp]`. 값 직전 마지막 공백으로 분리(라벨 안 공백 보존).
+      const sp = line.lastIndexOf(' ')
+      if (sp < 0) continue
+      const head = line.slice(0, sp) // name{labels}
+      const value = Number(line.slice(sp + 1))
+      if (!Number.isFinite(value)) continue
+      const brace = head.indexOf('{')
+      const name = brace < 0 ? head : head.slice(0, brace)
+      const labels = brace < 0 ? '' : head.slice(brace)
+      const key = head
+      const isInfo = name.endsWith('_info') || name === 'target_info'
+      const prev = samples.get(key)
+      if (prev === undefined) {
+        samples.set(key, { labels, value, name })
+      } else if (!isInfo) {
+        prev.value += value // info 메타는 첫 값 유지(N배 방지), 나머지는 합산.
+      }
+    }
+  }
+
+  if (samples.size === 0) return ''
+
+  // 패밀리(TYPE 이름) 단위로 묶어 출력 — HELP/TYPE 뒤에 해당 패밀리 샘플들.
+  const families = [...type.keys()].sort()
+  /** @type {Set<string>} 이미 출력한 샘플 키. */
+  const emitted = new Set()
+  const out = []
+  for (const fam of families) {
+    if (help.has(fam)) out.push(`# HELP ${fam} ${help.get(fam)}`)
+    out.push(`# TYPE ${fam} ${type.get(fam)}`)
+    const famSamples = [...samples.entries()]
+      .filter(([, s]) => belongsToFamily(s.name, fam))
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    for (const [key, s] of famSamples) {
+      out.push(`${key} ${formatValue(s.value)}`)
+      emitted.add(key)
+    }
+  }
+  // 패밀리(TYPE)에 안 묶인 고아 샘플 — 정렬해 뒤에 붙인다.
+  const orphans = [...samples.entries()].filter(([k]) => !emitted.has(k)).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+  for (const [key, s] of orphans) out.push(`${key} ${formatValue(s.value)}`)
+
+  return out.join('\n') + '\n'
+}
+
+/**
+ * 샘플 metric 이름이 패밀리(TYPE 이름)에 속하는지 — 정확히 같거나 히스토그램/서머리 suffix.
+ * @param {string} name @param {string} family @returns {boolean}
+ */
+function belongsToFamily(name, family) {
+  if (name === family) return true
+  return ['_bucket', '_sum', '_count', '_created'].some((suf) => name === family + suf)
+}
+
+/**
+ * 합산 값 직렬화. `String(v)` 가 정수(`8`)·소수(`0.5`)·지수(`1e+21`)를 모두 Prometheus 가 허용하는
+ * 형태로 내므로 분기 없이 그대로 쓴다(정수/소수 분기는 동일 결과라 제거 — 사문화 방지).
+ * @param {number} v @returns {string}
+ */
+function formatValue(v) {
+  return String(v)
+}
+
+/**
+ * 워커 프로세스에 collect 응답기를 설치한다 — 마스터의 `collect` 요청에 자기 `MegaMetrics.collect()` 로 회신.
+ * 클러스터 워커가 아니면 no-op. `process.on('message')` 다중 리스너라 MegaCluster shutdown 핸들러와 공존한다.
+ *
+ * IPC 경로는 fork 워커 안에서만 실행돼 부모 v8 커버리지로 측정 불가다. cluster/process 를 주입 seam 으로
+ * 분리해 fake 로 in-process 단위 검증한다(per ADR-165 — `MegaCluster` 와 동일 패턴). 프로덕션 호출부는
+ * 인자를 안 넘겨 실 전역을 쓴다.
+ * @param {{ _cluster?: import('node:cluster').Cluster, _proc?: NodeJS.Process }} [opts]
+ * @returns {void}
+ */
+export function installWorkerResponder({ _cluster = cluster, _proc = process } = {}) {
+  if (!_cluster.isWorker || typeof _proc.send !== 'function') return
+  _proc.on('message', (msg) => {
+    const m = /** @type {any} */ (msg)
+    if (m?.type !== MSG_COLLECT) return
+    // 비동기 collect 를 즉시 회신. 실패는 비치명적(부분 메트릭) — warn 후 빈 텍스트로 회신해 마스터가 안 멈추게.
+    Promise.resolve()
+      .then(() => MegaMetrics.collect())
+      .then((text) => trySend(_proc, { type: MSG_COLLECTED, roundId: m.roundId, pid: _proc.pid, text }))
+      .catch((err) => {
+        console.warn(`[mega-cluster-metrics] worker ${_proc.pid} collect failed:`, /** @type {any} */ (err)?.message ?? err)
+        trySend(_proc, { type: MSG_COLLECTED, roundId: m.roundId, pid: _proc.pid, text: '' })
+      })
+  })
+}
+
+/**
+ * 마스터 프로세스에 집계기를 설치한다 — 워커의 `request` 를 받아 전 워커에 fan-out, 회신을 모아 합산해 회신.
+ * 마스터가 아니면 no-op. `cluster.on('message')` 로 모든 워커 메시지를 한 핸들러로 받는다.
+ *
+ * IPC 경로는 마스터 안에서만 실행돼 부모 v8 커버리지로 측정 불가다 — cluster 를 주입 seam 으로 분리해
+ * fake 로 in-process 단위 검증한다(per ADR-165).
+ * @param {{ timeoutMs?: number, _cluster?: import('node:cluster').Cluster }} [opts] - 라운드 수집 timeout(전원 미응답 시 부분 합산). 기본 2000ms.
+ * @returns {void}
+ */
+export function installPrimaryAggregator({ timeoutMs = 2000, _cluster = cluster } = {}) {
+  if (!_cluster.isPrimary) return
+  let roundSeq = 0
+  /** @type {Map<number, { replies: Map<number,string>, expected: number, timer: NodeJS.Timeout, requester: import('node:cluster').Worker, reqId: string }>} */
+  const rounds = new Map()
+
+  const finishRound = (/** @type {number} */ roundId) => {
+    const round = rounds.get(roundId)
+    if (!round) return
+    rounds.delete(roundId)
+    clearTimeout(round.timer)
+    const merged = mergeExposition([...round.replies.values()])
+    try {
+      round.requester.send({ type: MSG_AGGREGATED, id: round.reqId, text: merged })
+    } catch (err) {
+      // 요청 워커가 이미 죽음 — 비치명적(스크레이프 1건 유실). silent 금지: warn.
+      console.warn('[mega-cluster-metrics] failed to send aggregated metrics to requester:', err?.message ?? err)
+    }
+  }
+
+  _cluster.on('message', (worker, msg) => {
+    const m = /** @type {any} */ (msg)
+    if (m?.type === MSG_REQUEST) {
+      const roundId = ++roundSeq
+      const workers = Object.values(_cluster.workers ?? {}).filter(Boolean)
+      const replies = new Map()
+      const timer = setTimeout(() => finishRound(roundId), timeoutMs)
+      timer.unref?.()
+      let expected = 0
+      for (const w of workers) {
+        try {
+          /** @type {any} */ (w).send({ type: MSG_COLLECT, roundId })
+          expected += 1
+        } catch (err) {
+          // 죽은(disconnecting) 워커엔 못 보냄 — expected 에서 제외돼 라운드는 정상 완료된다. 다만 부분
+          // 스크레이프가 됐음을 운영자가 알도록 surface(silent 금지, P4) — requester 송신 실패 warn 과 동형.
+          console.warn('[mega-cluster-metrics] skipped a worker (send failed, excluded from round):', /** @type {any} */ (err)?.message ?? err)
+        }
+      }
+      rounds.set(roundId, { replies, expected, timer, requester: worker, reqId: m.id })
+      if (expected === 0) finishRound(roundId)
+    } else if (m?.type === MSG_COLLECTED) {
+      const round = rounds.get(m.roundId)
+      if (!round) return
+      round.replies.set(m.pid, m.text)
+      if (round.replies.size >= round.expected) finishRound(m.roundId)
+    }
+  })
+}
+
+/**
+ * 현재 프로세스 기준 메트릭을 수집한다 — 클러스터 워커면 마스터를 통해 **전 워커 합산**, 단일 프로세스면 로컬.
+ * `/metrics` 라우트와 `/demo/metrics` 가 쓴다. timeout/마스터 부재 시 로컬 `collect()` 로 폴백(스크레이프가 안
+ * 멈추도록).
+ * cluster/process 는 주입 seam(테스트용 — per ADR-165). 프로덕션 호출부는 인자를 안 넘겨 실 전역을 쓴다.
+ * @param {{ timeoutMs?: number, _cluster?: import('node:cluster').Cluster, _proc?: NodeJS.Process }} [opts] - 응답 대기 timeout(라운드 timeout 보다 넉넉히). 기본 2500ms.
+ * @returns {Promise<string>} Prometheus exposition 텍스트.
+ */
+export function collectCluster({ timeoutMs = 2500, _cluster = cluster, _proc = process } = {}) {
+  // 단일 프로세스(클러스터 워커 아님) → 로컬 수집.
+  if (!_cluster.isWorker || typeof _proc.send !== 'function') {
+    return MegaMetrics.collect()
+  }
+  const id = `${_proc.pid}:${++reqSeq}`
+  return new Promise((resolve) => {
+    let done = false
+    const cleanup = () => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      _proc.off('message', onMsg)
+    }
+    const onMsg = (/** @type {any} */ msg) => {
+      if (msg?.type === MSG_AGGREGATED && msg.id === id) {
+        cleanup()
+        resolve(typeof msg.text === 'string' ? msg.text : '')
+      }
+    }
+    const timer = setTimeout(() => {
+      cleanup()
+      // 마스터 무응답 → 로컬 폴백(이 워커 메트릭만이라도).
+      Promise.resolve(MegaMetrics.collect())
+        .then(resolve)
+        .catch(() => resolve(''))
+    }, timeoutMs)
+    timer.unref?.()
+    _proc.on('message', onMsg)
+    try {
+      _proc.send({ type: MSG_REQUEST, id })
+    } catch {
+      cleanup()
+      Promise.resolve(MegaMetrics.collect())
+        .then(resolve)
+        .catch(() => resolve(''))
+    }
+  })
+}
+
+/** @private 워커 회신 송신(실패 시 warn — silent 금지). @param {NodeJS.Process} proc @param {object} payload */
+function trySend(proc, payload) {
+  try {
+    proc.send?.(payload)
+  } catch (err) {
+    console.warn('[mega-cluster-metrics] worker failed to send metrics reply:', /** @type {any} */ (err)?.message ?? err)
+  }
+}