mega-framework 0.1.0

package/src/core/config-loader.js

@@ -0,0 +1,115 @@
+// @ts-check
+/**
+ * 파일 로드 + 전체 검증 진입점.
+ *
+ * 프로젝트 루트에서 mega.config.js + 활성 앱(ADR-066 whitelist) 의 app.config.js 를
+ * import 하고 검증한다. 부팅 시 한 번 호출되며, 검증 실패 시 MegaConfigError 로
+ * fail-fast 한다.
+ *
+ * @module core/config-loader
+ */
+import { statSync } from 'node:fs'
+import { join, resolve as pathResolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { MegaConfigError } from '../errors/config-error.js'
+import {
+  validateGlobalConfig,
+  validateAppConfig,
+  validateHostCollisions,
+} from './config-validator.js'
+
+/**
+ * 프로젝트 루트에서 mega.config.js + 활성 앱 config 들 로드 + 검증.
+ * @param {string} projectRoot - 프로젝트 루트 절대 경로
+ * @returns {Promise<{global: Object, apps: Array<{name: string, config: Object}>}>}
+ * @throws {MegaConfigError}
+ */
+export async function loadAndValidateConfig(projectRoot) {
+  const globalPath = join(projectRoot, 'mega.config.js')
+  const global = await importConfig(globalPath, 'mega.config.js')
+  validateGlobalConfig(global)
+
+  /** @type {Array<{name: string, config: Object}>} */
+  const apps = []
+  const appNames = global.apps ?? []
+  for (const name of appNames) {
+    const folderPath = join(projectRoot, 'apps', name)
+    const appConfigPath = join(folderPath, 'app.config.js')
+
+    if (!isDirectory(folderPath)) {
+      throw new MegaConfigError(
+        'config.app_folder_missing',
+        `App '${name}' is in 'apps' array but folder 'apps/${name}' not found.`,
+      )
+    }
+    if (!isFile(appConfigPath)) {
+      throw new MegaConfigError(
+        'config.app_config_missing',
+        `App '${name}' is in 'apps' array but 'apps/${name}/app.config.js' not found.`,
+      )
+    }
+
+    const config = await importConfig(appConfigPath, `apps/${name}/app.config.js`)
+    validateAppConfig(config, name, global)
+    apps.push({ name, config })
+  }
+
+  validateHostCollisions(apps)
+
+  return { global, apps }
+}
+
+/**
+ * config 파일을 동적 import 하고 default export 를 반환.
+ * @param {string} absPath - 절대 경로
+ * @param {string} label - 에러 메시지용 라벨
+ * @returns {Promise<Record<string, any>>}
+ * @throws {MegaConfigError}
+ */
+async function importConfig(absPath, label) {
+  try {
+    const mod = await import(pathToFileURL(pathResolve(absPath)).href)
+    if (!mod.default) {
+      throw new MegaConfigError('config.no_default_export', `${label} must have a default export.`)
+    }
+    return mod.default
+  } catch (err) {
+    // 우리가 던진 검증 에러는 그대로 전파 (wrap 하면 code 가 가려짐).
+    if (err instanceof MegaConfigError) throw err
+    // 그 외(문법 오류·모듈 해석 실패 등)는 원인 보존하며 wrap (패턴 2).
+    throw new MegaConfigError('config.load_failed', `Failed to load ${label}: ${err.message}`, {
+      cause: err,
+    })
+  }
+}
+
+/**
+ * 경로가 디렉토리인지 검사.
+ * @param {string} p
+ * @returns {boolean}
+ */
+function isDirectory(p) {
+  try {
+    return statSync(p).isDirectory()
+  } catch (err) {
+    // 경로가 없으면(ENOENT) "디렉토리 아님" 이 정상 의미 — 호출부가 missing 처리.
+    // 권한 등 다른 에러는 숨기지 말고 전파 (silent catch 금지).
+    if (err.code === 'ENOENT') return false
+    throw err
+  }
+}
+
+/**
+ * 경로가 일반 파일인지 검사.
+ * @param {string} p
+ * @returns {boolean}
+ */
+function isFile(p) {
+  try {
+    return statSync(p).isFile()
+  } catch (err) {
+    // ENOENT 는 "파일 없음" 정상 케이스. 그 외는 전파.
+    if (err.code === 'ENOENT') return false
+    throw err
+  }
+}

package/src/core/config-validator.js

@@ -0,0 +1,322 @@
+// @ts-check
+/**
+ * MegaConfig 검증 로직.
+ *
+ * 부팅 시 한 번 실행되어 잘못된 config 를 fail-fast 로 throw 한다 (ADR-062).
+ * - 3-스코프 강제 (Global-only / App-only / Shared-Reference — ADR-061)
+ * - 알 수 없는 키 오타 감지 + Did-you-mean suggestion (ADR-062)
+ * - name ↔ 폴더명 일치 + Shared-Reference cross-check (ADR-067)
+ * - 호스트 충돌 감지 (ADR-067)
+ *
+ * @module core/config-validator
+ */
+import { MegaConfigError } from '../errors/config-error.js'
+import { GLOBAL_ONLY_KEYS, APP_ONLY_KEYS, SHARED_REFERENCE_KEYS } from './scope-registry.js'
+import { checkCompressionConfig } from './ws-compression.js'
+
+/**
+ * 메인 config 검증.
+ * @param {Record<string, any>} globalConfig - mega.config.js export 객체
+ * @throws {MegaConfigError}
+ */
+export function validateGlobalConfig(globalConfig) {
+  if (!globalConfig || typeof globalConfig !== 'object') {
+    throw new MegaConfigError('config.invalid', 'mega.config.js must export an object')
+  }
+
+  // 1) 알 수 없는 키 + 잘못된 스코프
+  for (const key of Object.keys(globalConfig)) {
+    if (GLOBAL_ONLY_KEYS.includes(key)) continue
+    if (APP_ONLY_KEYS.includes(key)) {
+      throw new MegaConfigError(
+        'config.wrong_scope',
+        `Global config cannot define '${key}'. Move to apps/<name>/app.config.js (ADR-061).`,
+        { details: { key, scope: 'app-only' } },
+      )
+    }
+    // 알 수 없는 키 — 오타 의심
+    const suggestion = suggestKey(key, [...GLOBAL_ONLY_KEYS, ...APP_ONLY_KEYS])
+    throw new MegaConfigError(
+      'config.unknown_key',
+      `Unknown key '${key}' in mega.config.js.${suggestion ? ` Did you mean '${suggestion}'?` : ''}`,
+      { details: { key, suggestion } },
+    )
+  }
+
+  // 2) apps 배열 형태 검증
+  if (globalConfig.apps !== undefined) {
+    if (
+      !Array.isArray(globalConfig.apps) ||
+      globalConfig.apps.some((n) => typeof n !== 'string')
+    ) {
+      throw new MegaConfigError(
+        'config.invalid_apps',
+        "'apps' must be an array of app name strings (ADR-066).",
+      )
+    }
+  }
+
+  // 3) wsHub.enabled + acceptedTokens 검증 (ADR-068)
+  if (globalConfig.wsHub?.enabled === true) {
+    const tokens = globalConfig.wsHub.acceptedTokens
+    if (!Array.isArray(tokens) || tokens.length === 0 || tokens.some((t) => !t)) {
+      throw new MegaConfigError(
+        'config.wsHub_empty_tokens',
+        'wsHub.acceptedTokens cannot be empty when wsHub.enabled is true.',
+      )
+    }
+  }
+
+  // 4) Bridge↔Hub link 압축 검증 (ADR-078) — threshold 음수 / serverMaxWindowBits 범위.
+  const wsHubViolation = checkCompressionConfig(globalConfig.wsHub?.compression, 'wsHub.compression')
+  if (wsHubViolation) {
+    throw new MegaConfigError('config.invalid_compression', wsHubViolation, {
+      details: { scope: 'wsHub.compression' },
+    })
+  }
+
+  // 5) jobs / schedules / workers 명시 등록 배열 검증 (M-2 + ADR-124 / 04-data-models §1.1).
+  //    GLOBAL_ONLY_KEYS 에 키만 등록돼 있고 shape 검증이 없어, `jobs: SendEmailJob`(배열 잊음)이나
+  //    원소가 클래스 아닌 값이면 흡수 로직이 silent drop 했다. 부팅 시 fail-fast 로 드러낸다.
+  //    원소는 각 베이스 서브클래스(= 함수/클래스)여야 한다(register/buildWorkers 가 다시 정밀 검증).
+  validateClassArray(globalConfig.jobs, 'jobs', 'job', 'MegaJob')
+  validateClassArray(globalConfig.schedules, 'schedules', 'schedule', 'MegaSchedule')
+  validateClassArray(globalConfig.workers, 'workers', 'worker', 'MegaWorker')
+
+  // 6) server.sessionSecret 강도 검증 (M-1, 04-data-models §MegaServerConfig). 세션 쿠키 HMAC 키라
+  //    약한 시크릿은 세션 위조로 직결된다. 세션은 앱별 opt-in 이라 secret 누락(undefined)은 세션 사용
+  //    앱에서 registerSession 이 fail-fast 로 잡으므로(여긴 server.sessionSecret 가 "정의됐을 때만"
+  //    강도를 검증) — 정의됐다면 (a) 기본 placeholder 거부, (b) ≥32자 강제(부팅 fail-fast, ADR-062).
+  validateSessionSecret(globalConfig.server?.sessionSecret)
+}
+
+/** sessionSecret 강도 검증의 최소 길이(바이트 수가 아닌 문자 길이 — base64url 32바이트 ≈ 43자). */
+const SESSION_SECRET_MIN_LENGTH = 32
+
+/**
+ * `server.sessionSecret` 강도 검증 (M-1). 미정의(undefined)면 통과 — 세션 미사용 앱을 위한 선택성 유지.
+ * 정의됐다면: (1) `change-me*` placeholder 거부, (2) 길이 < 32자 거부. 둘 다 부팅 fail-fast(ADR-062).
+ *
+ * @param {unknown} secret - `globalConfig.server.sessionSecret` 값.
+ * @throws {MegaConfigError} `server.sessionSecret_default_unsafe` 또는 `server.sessionSecret_too_short`.
+ */
+function validateSessionSecret(secret) {
+  if (secret === undefined) return // 세션 미사용 앱 — 선택 키(세션 사용 시 registerSession 이 fail-fast).
+  // placeholder 거부를 길이보다 먼저 — '.env' 기본값 'change-me-in-production'(23자)이 "너무 짧음"
+  // 보다 "기본값 교체하라"는 메시지로 떠야 운영자가 원인을 즉시 안다.
+  if (typeof secret === 'string' && /^change-me/i.test(secret)) {
+    throw new MegaConfigError(
+      'server.sessionSecret_default_unsafe',
+      "server.sessionSecret is still the insecure default ('change-me…'). Set SESSION_SECRET to a random value (≥32 chars).",
+    )
+  }
+  if (typeof secret !== 'string' || secret.length < SESSION_SECRET_MIN_LENGTH) {
+    throw new MegaConfigError(
+      'server.sessionSecret_too_short',
+      `server.sessionSecret must be at least ${SESSION_SECRET_MIN_LENGTH} chars.`,
+      { details: { length: typeof secret === 'string' ? secret.length : 0 } },
+    )
+  }
+}
+
+/**
+ * `jobs`/`schedules`/`workers` 같은 "클래스(함수) 배열" config 키를 검증한다 (M-2/ADR-124). 미정의면
+ * 통과(선택 키). 정의됐으면 (1) 배열이어야 하고 (2) 모든 원소가 함수(클래스)여야 한다 — 위반 시 부팅 fail-fast.
+ *
+ * @param {unknown} value - globalConfig[key] 값.
+ * @param {'jobs' | 'schedules' | 'workers'} key - 검증 대상 키(에러 코드·메시지에 사용).
+ * @param {'job' | 'schedule' | 'worker'} singular - 원소 에러 코드용 단수형.
+ * @param {string} baseName - 사용자 메시지용 베이스 클래스명(예: 'MegaJob').
+ * @throws {MegaConfigError} 비배열(`global.invalid_<key>`) 또는 원소 비함수(`global.invalid_<singular>_class`).
+ */
+function validateClassArray(value, key, singular, baseName) {
+  if (value === undefined) return // 선택 키 — 미정의는 정상.
+  if (!Array.isArray(value)) {
+    throw new MegaConfigError(
+      `global.invalid_${key}`,
+      `'${key}' must be an array of ${baseName} subclasses (did you forget the array brackets?).`,
+      { details: { key, type: typeof value } },
+    )
+  }
+  for (let i = 0; i < value.length; i++) {
+    if (typeof value[i] !== 'function') {
+      throw new MegaConfigError(
+        `global.invalid_${singular}_class`,
+        `'${key}[${i}]' must be a ${baseName} subclass (a class), got ${typeof value[i]}.`,
+        { details: { key, index: i, type: typeof value[i] } },
+      )
+    }
+  }
+}
+
+/**
+ * 앱 config 검증.
+ * @param {Record<string, any>} appConfig - apps/<name>/app.config.js export 객체
+ * @param {string} expectedFolderName - 폴더명 (apps/<name>)
+ * @param {Record<string, any>} globalConfig - 메인 (Shared-Reference 키 cross-check 용)
+ * @throws {MegaConfigError}
+ */
+export function validateAppConfig(appConfig, expectedFolderName, globalConfig) {
+  if (!appConfig || typeof appConfig !== 'object') {
+    throw new MegaConfigError(
+      'config.invalid',
+      `apps/${expectedFolderName}/app.config.js must export an object`,
+    )
+  }
+
+  // 1) 알 수 없는 키 + 잘못된 스코프
+  for (const key of Object.keys(appConfig)) {
+    if (APP_ONLY_KEYS.includes(key)) continue
+    if (GLOBAL_ONLY_KEYS.includes(key)) {
+      throw new MegaConfigError(
+        'config.wrong_scope',
+        `App config cannot define '${key}'. Move to mega.config.js (ADR-061).`,
+        { details: { key, scope: 'global-only', app: expectedFolderName } },
+      )
+    }
+    const suggestion = suggestKey(key, [...APP_ONLY_KEYS, ...GLOBAL_ONLY_KEYS])
+    throw new MegaConfigError(
+      'config.unknown_key',
+      `Unknown key '${key}' in app config '${expectedFolderName}'.${suggestion ? ` Did you mean '${suggestion}'?` : ''}`,
+      { details: { key, suggestion, app: expectedFolderName } },
+    )
+  }
+
+  // 2) name 폴더 일치 검증 (ADR-067)
+  if (typeof appConfig.name !== 'string' || appConfig.name.length === 0) {
+    throw new MegaConfigError(
+      'config.missing_name',
+      `App config '${expectedFolderName}' must have a 'name' field.`,
+    )
+  }
+  if (appConfig.name !== expectedFolderName) {
+    throw new MegaConfigError(
+      'config.name_mismatch',
+      `App config name '${appConfig.name}' does not match folder name '${expectedFolderName}'.`,
+      { details: { configName: appConfig.name, folderName: expectedFolderName } },
+    )
+  }
+
+  // 3) Shared-Reference 키 검증 — 참조하는 키가 globalConfig.services 에 존재해야 함
+  for (const refKey of SHARED_REFERENCE_KEYS) {
+    if (!appConfig[refKey]) continue
+    const services = globalConfig?.services?.[refKey]
+    for (const [appAlias, globalKey] of Object.entries(appConfig[refKey])) {
+      if (typeof globalKey !== 'string') {
+        throw new MegaConfigError(
+          'config.invalid_reference',
+          `App '${appConfig.name}' ${refKey}.${appAlias} must be a string key referring to services.${refKey} in mega.config.js.`,
+        )
+      }
+      if (!services || !services[globalKey]) {
+        throw new MegaConfigError(
+          'config.unknown_reference',
+          `App '${appConfig.name}' references ${refKey}.${globalKey} but '${globalKey}' is not defined in services.${refKey} in mega.config.js.`,
+          { details: { app: appConfig.name, refKey, alias: appAlias, globalKey } },
+        )
+      }
+    }
+  }
+
+  // 4) 브라우저↔Bridge WS 압축 검증 (ADR-078) — threshold 음수 / serverMaxWindowBits 범위.
+  const wsViolation = checkCompressionConfig(appConfig.websocket?.compression, 'websocket.compression')
+  if (wsViolation) {
+    throw new MegaConfigError('config.invalid_compression', wsViolation, {
+      details: { app: appConfig.name, scope: 'websocket.compression' },
+    })
+  }
+
+  // 5) 브라우저↔Bridge WS 프레임 최대 크기 검증 (L-3, ADR-099) — 양의 정수만 허용.
+  //    Hub(wsHub.maxPayloadBytes)와 대칭. 위반 시 부팅 fail-fast (ADR-062).
+  const maxPayload = appConfig.websocket?.maxPayloadBytes
+  if (maxPayload !== undefined && (!Number.isInteger(maxPayload) || maxPayload <= 0)) {
+    throw new MegaConfigError(
+      'config.invalid_max_payload',
+      `websocket.maxPayloadBytes must be a positive integer. Got ${maxPayload}`,
+      { details: { app: appConfig.name, scope: 'websocket.maxPayloadBytes' } },
+    )
+  }
+
+  // 6) 정적 자산 prefix ↔ /metrics 경로 충돌 (ADR-071/072) — 같은 경로면 정적 라우트가 메트릭을 가려 부팅 throw.
+  //    metricsPath 디폴트 '/metrics'. exposeMetrics OFF 면 메트릭 라우트가 없어 충돌 불가(검사 skip).
+  if (appConfig.staticAssets?.enabled === true && globalConfig?.health?.exposeMetrics === true) {
+    const metricsPath = globalConfig.health?.metricsPath ?? '/metrics'
+    const prefix = typeof appConfig.staticAssets.prefix === 'string' && appConfig.staticAssets.prefix.length > 0
+      ? appConfig.staticAssets.prefix
+      : '/'
+    if (prefix === metricsPath) {
+      throw new MegaConfigError(
+        'config.static_metrics_conflict',
+        `App '${appConfig.name}' staticAssets.prefix '${prefix}' collides with health.metricsPath. Choose a different prefix.`,
+        { details: { app: appConfig.name, prefix, metricsPath } },
+      )
+    }
+  }
+}
+
+/**
+ * 모든 앱 cross-validate: 호스트 충돌 감지 (ADR-067).
+ * @param {Array<{ name: string, config: Record<string, any> }>} apps
+ * @throws {MegaConfigError}
+ */
+export function validateHostCollisions(apps) {
+  /** @type {Map<string, string>} host → 첫 점유 앱 이름 */
+  const hostMap = new Map()
+  for (const { name, config } of apps) {
+    if (!Array.isArray(config.hosts)) continue
+    for (const host of config.hosts) {
+      if (hostMap.has(host) && hostMap.get(host) !== name) {
+        throw new MegaConfigError(
+          'config.host_collision',
+          `Host '${host}' is claimed by both '${hostMap.get(host)}' and '${name}'.`,
+          { details: { host, apps: [hostMap.get(host), name] } },
+        )
+      }
+      hostMap.set(host, name)
+    }
+  }
+}
+
+/**
+ * 가까운 키 추천 (Levenshtein 거리 기반).
+ * @param {string} input
+ * @param {readonly string[]} known
+ * @returns {string | undefined}
+ */
+export function suggestKey(input, known) {
+  let best = undefined
+  let bestDist = Infinity
+  const maxDist = Math.max(2, Math.floor(input.length / 3))
+  for (const candidate of known) {
+    const dist = levenshtein(input, candidate)
+    if (dist < bestDist && dist <= maxDist) {
+      best = candidate
+      bestDist = dist
+    }
+  }
+  return best
+}
+
+/**
+ * 단순 Levenshtein 거리 — 작은 문자열용.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshtein(a, b) {
+  if (a === b) return 0
+  const m = a.length
+  const n = b.length
+  if (m === 0) return n
+  if (n === 0) return m
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0))
+  for (let i = 0; i <= m; i++) dp[i][0] = i
+  for (let j = 0; j <= n; j++) dp[0][j] = j
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost)
+    }
+  }
+  return dp[m][n]
+}