mega-framework 0.1.0

package/src/core/template.js

@@ -0,0 +1,294 @@
+// @ts-check
+/**
+ * MegaApp 서버사이드 템플릿 자동 등록 — `ejs` + `ejs-mate` 통합 (per ADR-011).
+ *
+ * # 무엇인가 (중학생용 설명)
+ *   서버가 HTML 페이지를 만들어 브라우저로 보내고 싶을 때, 매번 문자열을 손으로 잇는 건 번거롭고 위험하다
+ *   (사용자 값이 그대로 들어가면 XSS). 템플릿 엔진은 `views/posts/show.ejs` 같은 틀 파일에 데이터를 꽂아
+ *   완성된 HTML 을 돌려준다. 본 모듈은 검증된 엔진 `ejs`(표현식 그대로)와 `ejs-mate`(레이아웃·파셜·블록
+ *   1급 지원)를 앱 config 의 `views` 키 기반으로 자동 등록하고, 그 위에 **i18n 노출**(`t`/`lang`)·**관측성**
+ *   (트레이싱 span·메트릭)·**보안**(XSS auto-escape·경로 탐색 차단)을 얹는다.
+ *
+ * # 동작 한눈에 (i18n.js / multipart.js 형제 패턴)
+ *   1. `registerTemplate(fastify, { views })` — `views.dir` 이 있을 때만 옵트인 등록(없으면 reply.render 미정의).
+ *   2. `reply.render(view, data, opts)` 데코레이터 — 정본 `res.render`(docs/03 §618). 렌더 후
+ *      `Content-Type: text/html` 로 send. data 에 요청별 `t`/`lang`(i18n) 자동 병합.
+ *   3. `MegaTemplate#render(view, data, opts)` — 순수 렌더(send 없이 HTML 문자열, docs/03 §892).
+ *   4. ctx-builder 가 `ctx.render` 를 reply.render 로 위임(canonical handler `(req, res, ctx)`).
+ *
+ * # 엔진 = EJS + ejs-mate (ADR-011)
+ *   - **EJS**: `<%= value %>` 는 HTML escape(XSS 기본 방어), `<%- value %>` 는 raw(명시적 신뢰 시만).
+ *   - **ejs-mate**: 템플릿 내 `<% layout('layouts/main') %>`·`<%- partial('partials/header') %>`·
+ *     `block(...)` 지원. 레이아웃·파셜 lookup 은 `settings.views`(= 뷰 루트) 기준(ejs-mate `renderFile`).
+ *
+ * # 위치 관례 (02-architecture §11)
+ *   `views.dir`(뷰 루트, 예 `apps/<name>/views`) 기준. 레이아웃 `<dir>/layouts/main.ejs`, 파셜
+ *   `<dir>/partials/`. i18n `localesDir` 선례처럼 dir 은 config 로 명시받는다(런타임은 앱 디렉터리를 모름).
+ *
+ * # 보안 (12-performance-security / multipart.js sanitize 패턴 정합)
+ *   - **XSS**: EJS `<%=` auto-escape 가 기본. raw 출력(`<%-`)은 호출자가 신뢰 데이터에만 쓴다(엔진 표준).
+ *   - **경로 탐색(path traversal) 차단**: view/layout 이름을 뷰 루트 기준으로 resolve 한 뒤 그 경로가
+ *     **뷰 루트 내부**인지 검증한다. `../` 로 루트를 벗어나면 즉시 거부(400 `template.invalid_view`).
+ *     동적(사용자 입력) view 명이 임의 파일을 읽는 LFI 를 막는 이중 방어.
+ *
+ * # 트레이싱·메트릭 (ADR-126 / ADR-131 인프라 재사용)
+ *   - 트레이싱: 렌더를 `MegaTracing.span('mega.template.render', …)` 로 감싸 `mega.template.{view,layout,bytes}`
+ *     속성을 박는다. 옵트인 OFF 면 0 비용 no-op.
+ *   - 메트릭: `recordTemplate({ result, durationMs, bytes })` — rendered/error + 렌더 시간·바이트 분포.
+ *     view 이름은 라벨에 안 넣는다(카디널리티·경로 노출 방지 — upload/i18n 패턴 정합).
+ *
+ * @module core/template
+ * @see ADR-011 (EJS + ejs-mate 채택), ADR-136
+ * @see https://github.com/JacksonTian/ejs-mate (ejs-mate v4 — express engine signature)
+ * @see https://ejs.co/ (EJS)
+ */
+import { resolve, sep, extname } from 'node:path'
+import { promisify } from 'node:util'
+import ejsMate from 'ejs-mate'
+import { MegaValidationError, MegaInternalError } from '../errors/http-errors.js'
+import * as MegaTracing from '../lib/mega-tracing.js'
+import { recordTemplate } from '../lib/mega-metrics.js'
+
+/** 고정 뷰 엔진·확장자 (ADR-011 — EJS). ejs-mate `settings['view engine']` 과 일치시킨다. */
+export const VIEW_ENGINE = 'ejs'
+
+/** 레이아웃 디렉터리 기본 관례 (02-architecture §11 — `views/layouts/`). */
+export const DEFAULT_LAYOUT_DIR = 'layouts'
+
+/** 파셜 디렉터리 기본 관례 (02-architecture §11 — `views/partials/`). */
+export const DEFAULT_PARTIALS_DIR = 'partials'
+
+/** ejs-mate `renderFile(file, options, cb)` 를 Promise 로 — 콜백 1패스, this 바인딩 없음(standalone). */
+const renderFileAsync = promisify(
+  /** @type {(file: string, options: object, cb: (err: any, html?: string) => void) => void} */ (
+    ejsMate
+  ),
+)
+
+/**
+ * i18n 미등록 앱의 템플릿 `t` 폴백 — ctx-builder passthroughT 와 동형. 번역 없이 defaultValue/key 반환.
+ * 템플릿에서 `<%= t('user.greeting', '안녕') %>` 가 i18n 옵트인 안 한 앱에서도 깨지지 않게.
+ * @param {string} key @param {unknown} [defaultValue] @returns {string}
+ */
+function passthroughT(key, defaultValue) {
+  return typeof defaultValue === 'string' ? defaultValue : key
+}
+
+/**
+ * 앱 `views` config 를 정규화한다. `dir` 이 없으면 null(옵트인 미활성 — i18n normalizeI18n 패턴 정합).
+ *
+ * @param {unknown} views - 앱 config 의 `views` 키.
+ * @returns {{ dir: string, layoutDir: string, partialsDir: string, defaultLayout: string|null, cache: boolean }|null}
+ */
+export function normalizeViews(views) {
+  if (!views || typeof views !== 'object') return null
+  const c = /** @type {Record<string, any>} */ (views)
+  if (typeof c.dir !== 'string' || c.dir.length === 0) return null
+
+  // dir 은 절대경로로 고정 — 상대경로면 프로세스 cwd 기준 resolve(경로 탐색 검증의 기준점이 흔들리지 않게).
+  const dir = resolve(c.dir)
+  const layoutDir =
+    typeof c.layoutDir === 'string' && c.layoutDir.length > 0 ? c.layoutDir : DEFAULT_LAYOUT_DIR
+  const partialsDir =
+    typeof c.partialsDir === 'string' && c.partialsDir.length > 0
+      ? c.partialsDir
+      : DEFAULT_PARTIALS_DIR
+  // defaultLayout: 앱 전역 기본 레이아웃(02-architecture §11 `layouts/main`). 없으면 레이아웃 없이 렌더.
+  const defaultLayout =
+    typeof c.defaultLayout === 'string' && c.defaultLayout.length > 0 ? c.defaultLayout : null
+  // cache: 컴파일 캐시. 명시 우선, 없으면 prod ON(반복 디스크 읽기·컴파일 회피)·dev OFF(편집 즉시 반영).
+  const cache = c.cache !== undefined ? c.cache === true : process.env.NODE_ENV === 'production'
+
+  return { dir, layoutDir, partialsDir, defaultLayout, cache }
+}
+
+/**
+ * view/layout 이름을 뷰 루트 기준 절대 경로로 풀고, 그 경로가 **뷰 루트 내부**인지 검증한다(경로 탐색 차단).
+ * 확장자가 없으면 `.ejs` 를 붙인다. 루트를 벗어나면 400 throw(LFI 방어 — multipart sanitize 이중 방어 정합).
+ *
+ * @param {string} dir - 뷰 루트(절대경로).
+ * @param {string} name - view 또는 layout 상대 이름(예 'posts/show', 'layouts/main').
+ * @param {'view'|'layout'} kind - 에러 메시지 구분용.
+ * @returns {string} 검증된 절대 경로.
+ * @throws {MegaValidationError} 뷰 루트를 벗어나면 `template.invalid_view`.
+ */
+export function resolveViewPath(dir, name, kind = 'view') {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new MegaValidationError(
+      'template.invalid_view',
+      `render: ${kind} name must be a non-empty string.`,
+      { details: { kind, name } },
+    )
+  }
+  const withExt = extname(name) ? name : `${name}.${VIEW_ENGINE}`
+  const abs = resolve(dir, withExt)
+  // 뷰 루트 내부 검증 — 정확히 dir 자신은 파일이 아니므로 `dir + sep` 접두만 허용(경로 탐색 거부).
+  if (abs !== dir && !abs.startsWith(dir + sep)) {
+    throw new MegaValidationError(
+      'template.invalid_view',
+      `render: ${kind} '${name}' escapes the views root (path traversal blocked).`,
+      {
+        details: { kind, name, root: dir },
+      },
+    )
+  }
+  return abs
+}
+
+/**
+ * 순수 렌더 — 뷰를 HTML 문자열로 만든다(send 없이). `MegaTemplate#render` 본체이자 reply.render 의 코어.
+ * 트레이싱 span + 메트릭을 여기서 1회 기록한다(reply.render·ctx.render 가 공유).
+ *
+ * @param {{ dir: string, layoutDir: string, partialsDir: string, defaultLayout: string|null, cache: boolean }} cfg
+ * @param {string} view - 뷰 루트 기준 상대 이름(예 'posts/show').
+ * @param {object} [data] - 템플릿 로컬(데이터). 예약 키 `t`/`lang`/`settings`/`cache` 는 프레임워크가 채운다.
+ * @param {{ layout?: string|false }} [opts] - `layout` 으로 레이아웃 override(false 면 레이아웃 강제 해제).
+ * @param {{ app?: string }} [meta] - 메트릭 app 라벨.
+ * @returns {Promise<string>} 렌더된 HTML.
+ * @throws {MegaValidationError} 경로 탐색 거부(400). @throws {MegaInternalError} 렌더 실패(500).
+ */
+export async function renderView(cfg, view, data = {}, opts = {}, meta = {}) {
+  const start = process.hrtime.bigint()
+  const viewPath = resolveViewPath(cfg.dir, view, 'view')
+
+  // 레이아웃 결정 — opts.layout 우선(false=강제 해제), 미지정이면 앱 defaultLayout. 둘 다 없으면 템플릿
+  // 내부 `<% layout() %>` 호출에 위임(ejs-mate). 지정 시 경로 탐색 검증.
+  /** @type {string|null} */
+  let layoutFile = null
+  if (opts.layout === false) {
+    layoutFile = null
+  } else if (typeof opts.layout === 'string') {
+    resolveViewPath(cfg.dir, opts.layout, 'layout') // 검증만(ejs-mate 가 settings.views 기준 재lookup)
+    layoutFile = opts.layout
+  } else if (cfg.defaultLayout) {
+    resolveViewPath(cfg.dir, cfg.defaultLayout, 'layout')
+    layoutFile = cfg.defaultLayout
+  }
+
+  // ejs-mate 호출 옵션 — data 가 곧 템플릿 로컬(ejs.renderFile data=options). 예약 키는 프레임워크가 덮어쓴다.
+  // settings.views = [dir] → layout/partial lookup 기준. _layoutFile(locals) 은 ejs-mate 가 우선 검사(외부 지정).
+  /** @type {Record<string, any>} */
+  const options = {
+    ...data,
+    settings: { views: [cfg.dir], 'view engine': VIEW_ENGINE },
+    cache: cfg.cache,
+    filename: viewPath,
+  }
+  if (layoutFile !== null) {
+    options.locals = { ...(options.locals ?? {}), _layoutFile: layoutFile }
+  }
+
+  return MegaTracing.span('mega.template.render', async (span) => {
+    span?.setAttributes({
+      'mega.template.view': view,
+      'mega.template.layout': layoutFile ?? '(none)',
+    })
+    let html
+    try {
+      html = await renderFileAsync(viewPath, options)
+    } catch (err) {
+      // 렌더 실패(문법 오류·파일 없음·참조 변수 throw)는 비치명적 묻기 금지 — 500 으로 wrap 후 상위 전파.
+      const durationMs = Number(process.hrtime.bigint() - start) / 1e6
+      recordTemplate({ app: meta.app, result: 'error', durationMs })
+      span?.setAttributes({ 'mega.template.error': true })
+      throw new MegaInternalError('template.render_failed', `Failed to render view '${view}'.`, {
+        details: { view, layout: layoutFile },
+        cause: err,
+      })
+    }
+    const bytes = Buffer.byteLength(html ?? '', 'utf8')
+    const durationMs = Number(process.hrtime.bigint() - start) / 1e6
+    span?.setAttributes({ 'mega.template.bytes': bytes })
+    recordTemplate({ app: meta.app, result: 'rendered', durationMs, bytes })
+    return html ?? ''
+  })
+}
+
+/**
+ * 정본 `MegaTemplate`(docs/03 §892 / 06-class-diagrams) — 옵트인 뷰 config 를 감싼 thin wrapper.
+ * registerTemplate 가 앱당 1개 만들어 reply.render 가 위임한다. i18n/MegaTracing 처럼 본체는 모듈 함수형.
+ */
+export class MegaTemplate {
+  /** @param {unknown} views - 앱 `views` config. @param {string} [appName] - 메트릭 app 라벨. */
+  constructor(views, appName) {
+    const cfg = normalizeViews(views)
+    if (cfg === null) {
+      throw new MegaInternalError(
+        'template.not_configured',
+        'MegaTemplate: views.dir is required (opt-in template needs a views root).',
+      )
+    }
+    /** @type {{ dir: string, layoutDir: string, partialsDir: string, defaultLayout: string|null, cache: boolean }} */
+    this._cfg = cfg
+    /** @type {string|undefined} */
+    this._app = appName
+  }
+
+  /**
+   * 뷰를 HTML 문자열로 렌더(send 없이) — docs/03 §892.
+   * @param {string} viewPath - 뷰 루트 기준 상대 이름(예 'posts/show').
+   * @param {object} [data]
+   * @param {{ layout?: string|false }} [opts]
+   * @returns {Promise<string>}
+   */
+  render(viewPath, data, opts) {
+    return renderView(this._cfg, viewPath, data, opts, { app: this._app })
+  }
+}
+
+/**
+ * MegaApp 에 템플릿을 옵트인 등록한다. `views.dir` 이 있을 때만 `reply.render` 데코레이터를 단다(없으면
+ * 미등록 — render 호출 시 Fastify 가 'reply.render is not a function' 으로 fail-fast, 옵트인 명시).
+ *
+ * `reply.render` 는 정본 `res.render(view, data, { layout })`(docs/03 §618):
+ *   - 요청별 i18n `t`/`lang`(`req.t`/`req.lang`, i18n 미등록이면 passthrough)을 data 에 자동 병합.
+ *   - 렌더 후 `Content-Type: text/html; charset=utf-8` 로 send. 체이닝용으로 reply 반환.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {object} args
+ * @param {unknown} [args.views] - 앱 `views` config(`{ dir, layoutDir, partialsDir, defaultLayout, cache }`).
+ * @param {string} [args.appName] - 메트릭·로그 라벨.
+ * @param {{ debug?: Function }} [args.logger]
+ * @returns {{ enabled: boolean, template: MegaTemplate|null }}
+ */
+export function registerTemplate(
+  fastify,
+  { views, appName = '(unknown)', logger } = /** @type {any} */ ({}),
+) {
+  const cfg = normalizeViews(views)
+  if (cfg === null) {
+    return { enabled: false, template: null }
+  }
+
+  const template = new MegaTemplate(views, appName)
+
+  // reply.render — 정본 res.render. this = reply 인스턴스, this.request 로 요청별 i18n 로컬 접근.
+  fastify.decorateReply(
+    'render',
+    async function (
+      /** @type {string} */ view,
+      /** @type {object} */ data,
+      /** @type {any} */ opts,
+    ) {
+      const reply = /** @type {any} */ (this)
+      const req = /** @type {any} */ (reply.request)
+      // i18n 로컬 자동 노출 — 사용자 data 가 우선(명시 override 허용), 미지정이면 요청 t/lang.
+      const locals = { lang: req.lang ?? null, t: req.t ?? passthroughT, ...(data ?? {}) }
+      logger?.debug?.({ app: appName, view, requestId: req.id }, 'template.render enter')
+      const html = await template.render(view, locals, opts)
+      logger?.debug?.(
+        { app: appName, view, bytes: Buffer.byteLength(html, 'utf8') },
+        'template.render done',
+      )
+      reply.header('content-type', 'text/html; charset=utf-8')
+      reply.send(html)
+      return reply
+    },
+  )
+
+  logger?.debug?.(
+    { app: appName, dir: cfg.dir, defaultLayout: cfg.defaultLayout, cache: cfg.cache },
+    'template.registered',
+  )
+  return { enabled: true, template }
+}

package/src/core/workers-manager.js

@@ -0,0 +1,193 @@
+// @ts-check
+/**
+ * MegaWorkersManager — 전역 `MegaWorker` 풀 매니저 (ADR-124).
+ *
+ * adapter-manager 와 같은 **모듈 레벨 싱글톤** 패턴이다 — `config.workers`(Global-only, MegaWorker
+ * 서브클래스 배열)로부터 풀을 인스턴스화·start 하고, `ctx.workers.<name>` lookup 으로 노출하며, graceful
+ * shutdown 시 LIFO 로 정리한다. 워커는 `static name` 으로 전역 키잉(앱 별명 스코프 밖 — adapters 의 db/cache/bus
+ * 와 달리 워커는 글로벌 공유 자원).
+ *
+ * # 부팅 배선 (boot.js prepareRuntime)
+ *   1. `buildWorkers(global, { projectRoot })` — `config.workers` 각 클래스 `new WorkerClass({ projectRoot })`.
+ *      동시에 `'workers:stop'` MegaShutdown hook 등록(어댑터 hook 보다 나중 등록 = 더 먼저 정리 — 워커가
+ *      어댑터를 쓸 수 있으니 어댑터 disconnect 전에 멈춤).
+ *   2. `startAll()` — 모든 풀 start(스레드/프로세스 spawn). 하나라도 실패하면 이미 start 된 것 LIFO 정리 후 throw.
+ *   3. `contextProxy()` — `ctx.workers` 로 줄 Proxy(미등록 이름 접근 시 fail-fast).
+ *
+ * @module core/workers-manager
+ */
+import { MegaConfigError } from '../errors/config-error.js'
+import { MegaShutdown } from '../lib/mega-shutdown.js'
+import { MegaWorker } from '../lib/mega-worker.js'
+
+/** shutdown hook 이름 — 재빌드/리셋 시 중복 등록 방지용 고정 키. */
+const SHUTDOWN_HOOK = 'workers:stop'
+
+/** @type {Map<string, MegaWorker>} static name → 워커 인스턴스. */
+let workers = new Map()
+/** @type {string[]} 빌드(=start) 순서 — stop LIFO 용. */
+let order = []
+/** @type {any} `ctx.workers` 로 재사용하는 Proxy(빌드 시 1회 생성). */
+let proxy = null
+
+/**
+ * `config.workers`(MegaWorker 서브클래스 배열)로부터 워커 풀 인스턴스를 만든다(아직 start 안 함).
+ * config-validator 가 배열·클래스 shape 를 먼저 검증하지만, 여기서도 MegaWorker 서브클래스·이름 중복을
+ * 부팅 시점에 fail-fast(형제 register 패턴).
+ *
+ * @param {{ workers?: Array<typeof MegaWorker> }} [globalConfig] - mega.config.js default export.
+ * @param {{ projectRoot?: string, registerShutdownHook?: boolean }} [opts]
+ * @returns {void}
+ * @throws {MegaConfigError} MegaWorker 서브클래스가 아니거나 `static name` 중복일 때.
+ */
+export function buildWorkers(globalConfig, { projectRoot, registerShutdownHook = true } = {}) {
+  const list = globalConfig?.workers ?? []
+  for (const WorkerClass of list) {
+    if (typeof WorkerClass !== 'function' || !(WorkerClass.prototype instanceof MegaWorker)) {
+      throw new MegaConfigError(
+        'worker.invalid_class',
+        `config.workers — each element must be a subclass of MegaWorker (got ${typeof WorkerClass}).`,
+        { details: { type: typeof WorkerClass } },
+      )
+    }
+    // new 시점에 static 설정(taskFile/mode/poolSize) fail-fast(생성자 검증).
+    const instance = new /** @type {any} */ (WorkerClass)({ projectRoot })
+    const name = instance.name
+    if (workers.has(name)) {
+      throw new MegaConfigError(
+        'worker.duplicate_name',
+        `config.workers — duplicate worker name '${name}' (static name must be unique).`,
+        { details: { name } },
+      )
+    }
+    workers.set(name, instance)
+    order.push(name)
+  }
+  if (registerShutdownHook) {
+    MegaShutdown.unregister(SHUTDOWN_HOOK)
+    MegaShutdown.register(SHUTDOWN_HOOK, async () => stopAll())
+  }
+}
+
+/**
+ * 모든 워커 풀을 start 한다(스레드/프로세스 spawn). 하나라도 실패하면 이미 start 된 풀을 등록 역순(LIFO)으로
+ * stop 한 뒤 원래 에러를 throw(fail-fast + leak 방지 — adapter-manager connectAll 패턴).
+ *
+ * @param {{ logger?: { debug?: Function, info?: Function, warn?: Function } }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function startAll({ logger } = {}) {
+  /** @type {string[]} start 성공 순서(LIFO cleanup 용). */
+  const started = []
+  try {
+    for (const name of order) {
+      const w = /** @type {MegaWorker} */ (workers.get(name))
+      await w.start()
+      started.push(name)
+      logger?.info?.({ worker: name, mode: w.mode, poolSize: w.poolSize }, 'worker pool started')
+    }
+  } catch (err) {
+    for (let i = started.length - 1; i >= 0; i--) {
+      const w = /** @type {MegaWorker} */ (workers.get(started[i]))
+      try {
+        await w.stop()
+      } catch (cleanupErr) {
+        logger?.warn?.({ err: cleanupErr, worker: started[i] }, 'worker cleanup stop failed during startAll abort (continuing)')
+      }
+    }
+    throw err
+  }
+}
+
+/**
+ * `static name` 으로 워커 풀 조회. 미등록이면 fail-fast(silent X — adapter-manager.get 정합).
+ * @param {string} name @returns {MegaWorker} @throws {MegaConfigError}
+ */
+export function get(name) {
+  const w = workers.get(name)
+  if (w === undefined) {
+    throw new MegaConfigError(
+      'worker.not_registered',
+      `No worker registered for name '${name}'. Registered: [${order.join(', ') || '(none)'}]. Add the MegaWorker subclass to mega.config.js 'workers'.`,
+      { details: { name, registered: [...order] } },
+    )
+  }
+  return w
+}
+
+/**
+ * 등록 여부(Boolean — has*, 컨벤션). @param {string} name @returns {boolean}
+ */
+export function has(name) {
+  return workers.has(name)
+}
+
+/**
+ * 등록된 워커 메타 스냅샷(디버그/CLI). @returns {Array<{ name: string, mode: string, poolSize: number, started: boolean }>}
+ */
+export function list() {
+  return order.map((name) => {
+    const w = /** @type {MegaWorker} */ (workers.get(name))
+    return { name, mode: w.mode, poolSize: w.poolSize, started: w.isStarted }
+  })
+}
+
+/**
+ * `ctx.workers` 로 줄 객체 — `ctx.workers.<name>.run(task)`. 미등록 이름 접근은 fail-fast.
+ * 동일 Proxy 를 boot ctx·요청 ctx 가 공유한다(워커는 글로벌 자원이라 요청·앱 무관).
+ * @returns {Record<string, MegaWorker>}
+ */
+export function contextProxy() {
+  if (proxy === null) {
+    proxy = new Proxy(
+      {},
+      {
+        get(_t, prop) {
+          if (typeof prop !== 'string') return undefined
+          return get(prop) // 미등록 → worker.not_registered throw.
+        },
+        has(_t, prop) {
+          return typeof prop === 'string' && has(prop)
+        },
+        ownKeys() {
+          return [...order]
+        },
+        getOwnPropertyDescriptor(_t, prop) {
+          if (typeof prop === 'string' && has(prop)) {
+            return { enumerable: true, configurable: true, value: get(prop) }
+          }
+          return undefined
+        },
+      },
+    )
+  }
+  return proxy
+}
+
+/**
+ * 모든 워커 풀을 graceful stop 한다 — 등록 **역순(LIFO)**. 개별 실패는 비치명적(warn 후 계속).
+ * @param {{ logger?: { debug?: Function, warn?: Function } }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function stopAll({ logger } = {}) {
+  for (let i = order.length - 1; i >= 0; i--) {
+    const w = /** @type {MegaWorker} */ (workers.get(order[i]))
+    try {
+      await w.stop()
+      logger?.debug?.({ worker: order[i] }, 'worker pool stopped')
+    } catch (err) {
+      logger?.warn?.({ err, worker: order[i] }, 'worker pool stop failed (continuing shutdown)')
+    }
+  }
+}
+
+/**
+ * 테스트용 reset — 인스턴스 비우고 shutdown hook 해제(워커는 stop 안 함 — 호출자가 먼저 stopAll).
+ * @returns {void}
+ */
+export function _reset() {
+  workers = new Map()
+  order = []
+  proxy = null
+  MegaShutdown.unregister(SHUTDOWN_HOOK)
+}

package/src/core/ws-compression.js

@@ -0,0 +1,112 @@
+// @ts-check
+/**
+ * WebSocket per-message deflate 압축 옵션 정규화 (ADR-078).
+ *
+ * 두 곳이 같은 스키마를 쓴다(04-data-models §1.1/§2.1):
+ *   - App-only `websocket.compression`  — 브라우저↔Bridge(embedded WS, MegaApp `_ensureWss`)
+ *   - Global   `wsHub.compression`       — Bridge↔Hub link (MegaWsHub 서버 + MegaHubLink 클라)
+ *
+ * 두 typedef(`MegaWebsocketCompressionConfig` / `MegaWsHubCompressionConfig`)의 6 필드는
+ * 그대로 `ws` 패키지의 `perMessageDeflate` 옵션명과 1:1 매핑된다(검증: node_modules/ws/lib/
+ * permessage-deflate.js — threshold/serverNoContextTakeover/clientNoContextTakeover/
+ * serverMaxWindowBits/concurrencyLimit). `enabled` 만 우리 게이트 — false 면 압축 비활성
+ * (`perMessageDeflate: false`, ws 기본값).
+ *
+ * # threshold 의미 (ws 소스 확인)
+ *   threshold 는 **context takeover 가 비활성일 때만** 적용된다(sender.js: no_context_takeover
+ *   negotiate 시 `rsv1 = byteLength >= threshold`). ADR-078 이 두 NoContextTakeover 디폴트를 true 로
+ *   둔 이유 — threshold 가 실제로 동작하고 연결당 메모리도 절감.
+ *
+ * # negotiate 실패 = 자동 raw fallback
+ *   `permessage-deflate` 확장은 양쪽이 모두 협상해야 활성(RFC 7692). 한쪽이 OFF(`false`)면 협상되지
+ *   않아 자동으로 raw 통신으로 떨어진다 — 별도 fallback 코드 불필요(ws 내장 동작).
+ *
+ * @module core/ws-compression
+ */
+
+/**
+ * 압축 설정 — App `websocket.compression` 과 Global `wsHub.compression` 공통 스키마 (ADR-078).
+ * 04-data-models 의 `MegaWebsocketCompressionConfig` / `MegaWsHubCompressionConfig` 와 동일.
+ * @typedef {Object} WsCompressionConfig
+ * @property {boolean} enabled                     - 디폴트 false. 옵트인 게이트.
+ * @property {number}  [threshold]                 - byte. 디폴트 1024. 미만은 압축 우회(NoContextTakeover 시).
+ * @property {boolean} [serverNoContextTakeover]   - 디폴트 true (연결당 메모리 절감).
+ * @property {boolean} [clientNoContextTakeover]   - 디폴트 true.
+ * @property {number}  [serverMaxWindowBits]       - 디폴트 10. 범위 9~15 (벗어나면 부팅 throw).
+ * @property {number}  [concurrencyLimit]          - 디폴트 10.
+ */
+
+/**
+ * ADR-078 디폴트값. `enabled` 외 5 필드는 `ws` perMessageDeflate 에 그대로 전달된다.
+ * @type {Readonly<{ enabled: boolean, threshold: number, serverNoContextTakeover: boolean, clientNoContextTakeover: boolean, serverMaxWindowBits: number, concurrencyLimit: number }>}
+ */
+export const COMPRESSION_DEFAULTS = Object.freeze({
+  enabled: false,
+  threshold: 1024,
+  serverNoContextTakeover: true,
+  clientNoContextTakeover: true,
+  serverMaxWindowBits: 10,
+  concurrencyLimit: 10,
+})
+
+/** serverMaxWindowBits 허용 범위 (zlib windowBits 최소 9 ~ RFC 7692 최대 15, ADR-078). */
+export const SERVER_MAX_WINDOW_BITS_MIN = 9
+export const SERVER_MAX_WINDOW_BITS_MAX = 15
+
+/**
+ * 압축 설정 검증 — 위반 시 사람이 읽을 에러 메시지, 통과 시 null 반환(throw 안 함).
+ *
+ * 호출부가 컨텍스트(MegaConfigError vs 일반 Error)에 맞게 wrap 한다 — config-validator 는
+ * MegaConfigError 로, MegaApp/MegaWsHub 직접 생성 경로는 일반 Error 로.
+ *
+ * @param {Partial<WsCompressionConfig>} [config] - MegaWebsocketCompressionConfig | MegaWsHubCompressionConfig.
+ * @param {string} [label='websocket.compression'] - 에러 메시지 prefix (예: 'wsHub.compression').
+ * @returns {string | null} 위반 메시지 또는 null.
+ */
+export function checkCompressionConfig(config, label = 'websocket.compression') {
+  if (!config || typeof config !== 'object') return null
+  if (config.threshold !== undefined) {
+    if (typeof config.threshold !== 'number' || Number.isNaN(config.threshold) || config.threshold < 0) {
+      return `${label}.threshold must be >= 0. Got ${config.threshold}`
+    }
+  }
+  if (config.serverMaxWindowBits !== undefined) {
+    const v = config.serverMaxWindowBits
+    if (
+      typeof v !== 'number' ||
+      !Number.isInteger(v) ||
+      v < SERVER_MAX_WINDOW_BITS_MIN ||
+      v > SERVER_MAX_WINDOW_BITS_MAX
+    ) {
+      return `${label}.serverMaxWindowBits must be in [${SERVER_MAX_WINDOW_BITS_MIN}, ${SERVER_MAX_WINDOW_BITS_MAX}]. Got ${v}`
+    }
+  }
+  return null
+}
+
+/**
+ * 압축 설정 → `ws` WebSocket(Server) 의 `perMessageDeflate` 값으로 변환.
+ *
+ * - `enabled !== true` → `false` (압축 비활성, ws 기본값과 동일).
+ * - `enabled === true` → 5 필드를 디폴트로 채운 perMessageDeflate 옵션 객체.
+ *
+ * 부팅(config-validator)에서 이미 검증되지만, 직접 생성 경로(single 모드·테스트)를 위해 여기서도
+ * 방어적으로 검증한다 — 위반 시 throw(silent 금지).
+ *
+ * @param {Partial<WsCompressionConfig>} [config] - MegaWebsocketCompressionConfig | MegaWsHubCompressionConfig.
+ * @param {string} [label='websocket.compression'] - throw 메시지 prefix.
+ * @returns {false | { threshold: number, serverNoContextTakeover: boolean, clientNoContextTakeover: boolean, serverMaxWindowBits: number, concurrencyLimit: number }}
+ * @throws {Error} threshold 음수 / serverMaxWindowBits 범위 위반.
+ */
+export function buildPerMessageDeflate(config, label = 'websocket.compression') {
+  if (!config || config.enabled !== true) return false
+  const violation = checkCompressionConfig(config, label)
+  if (violation) throw new Error(violation)
+  return {
+    threshold: config.threshold ?? COMPRESSION_DEFAULTS.threshold,
+    serverNoContextTakeover: config.serverNoContextTakeover ?? COMPRESSION_DEFAULTS.serverNoContextTakeover,
+    clientNoContextTakeover: config.clientNoContextTakeover ?? COMPRESSION_DEFAULTS.clientNoContextTakeover,
+    serverMaxWindowBits: config.serverMaxWindowBits ?? COMPRESSION_DEFAULTS.serverMaxWindowBits,
+    concurrencyLimit: config.concurrencyLimit ?? COMPRESSION_DEFAULTS.concurrencyLimit,
+  }
+}