mega-framework 0.1.0

package/src/core/ctx-builder.js

@@ -0,0 +1,253 @@
+// @ts-check
+/**
+ * ctx-builder — 요청 단위 컨텍스트(`ctx`)의 어댑터 lookup 배선 (ADR-102).
+ *
+ * canonical `ctx` 표면(docs/03 §581)의 데이터 어댑터 4종을 함수형으로 노출한다:
+ *   - `ctx.db(alias)`    → MegaDbAdapter   (raw handle 은 `.native`)
+ *   - `ctx.cache(alias)` → MegaCacheAdapter
+ *   - `ctx.bus(alias)`   → MegaBusAdapter
+ *   - `ctx.lock(alias)`  → MegaLockAdapter  (분산 락, ADR-113)
+ *
+ * **별명 → globalKey → 공유 인스턴스** (글로벌 공유 모델, ADR-102):
+ *   앱은 `app.config.js` 에서 `databases: { alias: globalKey }` 로 별명을 선언하고, 코드에서는
+ *   `ctx.db('alias')` 로 부른다. 빌더가 별명을 globalKey 로 바꿔 {@link module:adapters/adapter-manager}
+ *   의 공유 인스턴스를 돌려준다. **미선언 별명 / 미등록 키는 즉시 throw** (silent X — 오타가 런타임에
+ *   조용히 통과하지 않게, docs/04 L570 / ADR-007).
+ *
+ * @module core/ctx-builder
+ */
+import { MegaConfigError } from '../errors/config-error.js'
+import * as AdapterManager from '../adapters/adapter-manager.js'
+import { contextProxy as workersContext } from './workers-manager.js'
+import { tracer as megaTracer } from '../lib/mega-tracing.js'
+
+/** ctx 도메인 함수 ↔ app.config 별명 맵 키. */
+const DOMAIN_ALIAS_KEY = /** @type {const} */ ({ db: 'databases', cache: 'caches', bus: 'buses', lock: 'locks' })
+
+/**
+ * i18n 미등록 앱의 `ctx.t` 폴백 — 번역 없이 defaultValue(있으면) 또는 key 를 그대로 돌려준다. i18n 옵트인
+ * 안 한 앱에서도 `ctx.t(code, message)` 호출이 깨지지 않게(에러 핸들러·코드 호환). i18next 시그니처와 동형:
+ * 2번째 인자가 문자열이면 defaultValue, 객체면 options(번역 없으니 무시하고 key 반환).
+ * @param {string} key @param {unknown} [defaultValue] @returns {string}
+ */
+function passthroughT(key, defaultValue) {
+  return typeof defaultValue === 'string' ? defaultValue : key
+}
+
+/** 요청당 ctx 를 캐싱하는 비열거 키. 글로벌 미들웨어와 라우트 핸들러가 같은 ctx 를 공유하도록 한다. */
+const HTTP_CTX_KEY = Symbol('mega.httpCtx')
+
+/**
+ * `ctx.services.<name>` lazy DI proxy (ADR-148) — 요청별 서비스 인스턴스화·캐시.
+ *
+ * `app.serviceRegistry`(부팅 시 services-loader 가 만든 name→Class 맵)에서 클래스를 찾아 **요청 ctx 로**
+ * 인스턴스화하고, 같은 요청 안에서 한 번만 만들어 캐시한다(요청별 스코프 — 서비스가 ctx.log/db/session/
+ * user 에 바인딩되므로 싱글톤 불가). 서비스 간 합성(`this.services.<name>`)도 같은 proxy 를 거쳐 동일
+ * 인스턴스를 공유한다(mega-service.js `get services()` 가 `this.ctx.services` 위임).
+ *
+ * 미등록 이름 접근은 즉시 throw(`service.not_registered`, fail-fast — 오타가 조용히 undefined 로 통과하지
+ * 않게). 생성 중 재진입(A 생성자 → B → A)은 `service.circular_dependency` 로 차단한다(메서드 레벨 상호
+ * 호출은 정상 — 가드는 컨스트럭터 사이클만).
+ *
+ * @param {Record<string, any>} ctx - 요청 ctx(서비스 생성자에 전달).
+ * @param {import('./mega-app.js').MegaApp} app - serviceRegistry 보유 앱.
+ * @returns {Record<string, any>} 서비스 proxy.
+ */
+function buildServicesProxy(ctx, app) {
+  const registry = /** @type {Map<string, Function>} */ (/** @type {any} */ (app).serviceRegistry)
+  /** @type {Map<string, any>} 요청 내 인스턴스 캐시. */
+  const instances = new Map()
+  /** @type {Set<string>} 생성 진행 중(순환 가드). */
+  const constructing = new Set()
+
+  /** @param {string} name @returns {any} */
+  function resolve(name) {
+    if (instances.has(name)) return instances.get(name)
+    const Cls = registry.get(name)
+    if (!Cls) {
+      throw new MegaConfigError(
+        'service.not_registered',
+        `ctx.services.${name} — app '${app.name}' 에 '${name}' 서비스가 등록돼 있지 않습니다. 등록됨: [${[...registry.keys()].join(', ') || '(none)'}].`,
+        { details: { app: app.name, name } },
+      )
+    }
+    if (constructing.has(name)) {
+      throw new MegaConfigError(
+        'service.circular_dependency',
+        `ctx.services.${name} — 생성 중 순환 의존: [${[...constructing, name].join(' → ')}]. 다른 서비스는 컨스트럭터가 아닌 메서드에서 호출하세요.`,
+        { details: { app: app.name, cycle: [...constructing, name] } },
+      )
+    }
+    constructing.add(name)
+    try {
+      const instance = new (/** @type {any} */ (Cls))(ctx, { app })
+      instances.set(name, instance)
+      return instance
+    } finally {
+      constructing.delete(name)
+    }
+  }
+
+  // 빈 타깃 proxy — get(인스턴스 해석) + has(`'name' in ctx.services`)만 구현. ownKeys/enumerate 는
+  // 의도(접근 시점에만 인스턴스화) 보존을 위해 노출하지 않는다(열거가 전체 서비스를 생성하지 않게).
+  return new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== 'string') return undefined // Symbol(then 등) — non-thenable 유지
+        return resolve(prop)
+      },
+      has(_t, prop) {
+        return typeof prop === 'string' && registry.has(prop)
+      },
+    },
+  )
+}
+
+/**
+ * @typedef {object} AdapterAliasMaps - 앱의 `app.config.js` 별명 선언 (alias → globalKey).
+ * @property {Record<string, string>} [databases]
+ * @property {Record<string, string>} [caches]
+ * @property {Record<string, string>} [buses]
+ * @property {Record<string, string>} [locks]
+ */
+
+/**
+ * @typedef {object} AdapterAccessors
+ * @property {(alias: string) => import('../adapters/mega-adapter.js').MegaAdapter} db
+ * @property {(alias: string) => import('../adapters/mega-adapter.js').MegaAdapter} cache
+ * @property {(alias: string) => import('../adapters/mega-adapter.js').MegaAdapter} bus
+ * @property {(alias: string) => import('../adapters/mega-adapter.js').MegaAdapter} lock
+ */
+
+/**
+ * 앱의 별명 맵으로 `db/cache/bus/lock` 접근자 4종을 만든다. 접근자는 요청과 무관하게 안정적이므로
+ * **앱당 한 번** 만들어 재사용한다(MegaApp 생성자). 각 접근자는 호출 시 별명→globalKey→공유
+ * 인스턴스로 해석하고, 미선언 별명이면 throw.
+ *
+ * @param {AdapterAliasMaps} [aliasMaps] - 앱 별명 선언. 없으면 모든 접근자가 미선언 throw.
+ * @param {string} [appName] - 에러 메시지용 앱 이름.
+ * @returns {AdapterAccessors}
+ */
+export function buildAdapterAccessors(aliasMaps = {}, appName = '(unknown)') {
+  /**
+   * @param {'db'|'cache'|'bus'|'lock'} domain
+   * @returns {(alias: string) => import('../adapters/mega-adapter.js').MegaAdapter}
+   */
+  const make = (domain) => {
+    const aliasMap = aliasMaps[DOMAIN_ALIAS_KEY[domain]] ?? {}
+    return (alias) => {
+      if (typeof alias !== 'string' || alias.length === 0) {
+        throw new MegaConfigError('adapter.invalid_key', `ctx.${domain}(key) — key must be a non-empty string.`, {
+          details: { domain, alias },
+        })
+      }
+      const globalKey = aliasMap[alias]
+      if (globalKey === undefined) {
+        throw new MegaConfigError(
+          'adapter.not_registered',
+          `ctx.${domain}('${alias}') — '${alias}' is not declared in app '${appName}' config.${DOMAIN_ALIAS_KEY[domain]}. Declared: [${Object.keys(aliasMap).join(', ') || '(none)'}].`,
+          { details: { domain, alias, app: appName, declared: Object.keys(aliasMap) } },
+        )
+      }
+      return AdapterManager.get(domain, globalKey) // 별명은 있으나 인스턴스 미등록이면 여기서 throw
+    }
+  }
+  return { db: make('db'), cache: make('cache'), bus: make('bus'), lock: make('lock') }
+}
+
+/**
+ * HTTP 요청 단위 ctx 를 만든다 (canonical handler 시그니처 `(req, res, ctx)`, ADR-074/docs/03).
+ *
+ * canonical ctx 표면: `app / log / requestId / req / reply` + `db/cache/bus` 접근자 +
+ * `workers`(CPU 워커 풀, ADR-124) + `tracer`(사용자 직접 span — `ctx.tracer.span`,
+ * ADR-126). (i18n `t`, `session` 객체, `services` 자동 DI 등 나머지 canonical 필드도 같은 방식으로 추가된다.)
+ *
+ * `app` 이 null(standalone Router — 앱에 바인딩 안 된 테스트 경로)이면 `db/cache/bus` 접근자는
+ * 생략된다(해당 ctx 로는 어댑터 lookup 불가). `workers` 는 글로벌 자원이라 app 무관하게 항상 노출한다
+ * (미등록 이름 접근 시 worker.not_registered fail-fast — 워커 0개면 접근 자체가 없어 무해).
+ *
+ * @param {object} args
+ * @param {import('./mega-app.js').MegaApp | null} args.app
+ * @param {import('fastify').FastifyRequest} args.req
+ * @param {import('fastify').FastifyReply} args.reply
+ * @returns {Record<string, any>}
+ */
+export function buildHttpCtx({ app, req, reply }) {
+  /** @type {Record<string, any>} */
+  const ctx = {
+    app: app ?? null,
+    log: req.log,
+    requestId: req.id,
+    req,
+    reply,
+    workers: workersContext(), // ctx.workers.<name>.run(task) — 글로벌 CPU 워커 풀(ADR-124).
+    tracer: megaTracer, // ctx.tracer.span(name, fn) — 사용자 직접 span(ADR-126). 옵트인 OFF 면 0 비용 no-op.
+    session: /** @type {any} */ (req).session ?? null, // ctx.session — 세션 미들웨어가 채운 요청별 세션 객체(ADR-129). 미활성/미로드 시 null.
+    lang: /** @type {any} */ (req).lang ?? null, // ctx.lang — i18n 미들웨어가 쿠키로 결정한 현재 언어(ADR-038). 미활성 시 null.
+    // ctx.t(key, defaultValue?, params?) — server scope 번역(docs/03 §632, ADR-135). i18n 미등록이면 passthrough.
+    t: /** @type {any} */ (req).t ?? passthroughT,
+    // ctx.render(view, data?, opts?) — reply.render(정본 res.render, ADR-011/136)로 위임. 템플릿 옵트인 안 한
+    // 앱은 reply.render 미정의 → 명확한 fail-fast(template.not_configured). reply.render 가 i18n t/lang 자동 병합.
+    render: (/** @type {string} */ view, /** @type {object} */ data, /** @type {any} */ opts) => {
+      if (typeof (/** @type {any} */ (reply).render) !== 'function') {
+        throw new MegaConfigError('template.not_configured', `ctx.render('${view}') — app '${app?.name ?? '(unknown)'}' has no views config (opt-in template; set app.config views.dir).`, {
+          details: { view, app: app?.name ?? null },
+        })
+      }
+      return /** @type {any} */ (reply).render(view, data, opts)
+    },
+    ...(app?.adapterAccessors ?? {}),
+  }
+  // ctx.bruteForce — MegaBruteForce 단축(ADR-049/130). **lazy getter** 라 접근할 때만 app.bruteForce 가
+  // caches.rate 를 해석한다(브루트포스 미사용 앱은 rate 캐시 없어도 무해). app 미바인딩(standalone)이면 생략.
+  // enumerable:false (L-2) — ctx spread/열거({...ctx}, Object.keys) 시 getter 가 실행돼 의도치 않게
+  // app.bruteForce 해석(미설정 시 throw)되는 걸 막는다. 명시 접근(ctx.bruteForce)으로만 평가.
+  if (app) {
+    Object.defineProperty(ctx, 'bruteForce', { get: () => app.bruteForce, enumerable: false, configurable: true })
+  }
+  // ctx.user — 인증 사용자. getter 는 req.user 를 그대로 반영(인증 가드 mega-framework/auth(ADR-143)는
+  // 라우트 before 경로에서 req.user 에 심는다), setter 는 req.user 에 위임(글로벌 미들웨어가 ctx.user 에
+  // 직접 심는 ADR-134 패턴 호환). 두 경로가 같은 저장소(req.user)를 공유 → 미들웨어→핸들러 일관(미인증 null).
+  Object.defineProperty(ctx, 'user', {
+    get: () => /** @type {any} */ (req).user ?? null,
+    set: (v) => {
+      ;/** @type {any} */ (req).user = v
+    },
+    enumerable: true,
+    configurable: true,
+  })
+  // ctx.services.<name> — 요청별 lazy 서비스 DI(ADR-148). app 미바인딩(standalone)이거나 등록 서비스가
+  // 없으면 생략한다(테스트는 MegaTest 가 services mock 을 ctx 에 직접 주입). enumerable:false — ctx 열거
+  // ({...ctx}/Object.keys)에 노출하지 않아 기존 ctx 표면 스냅샷·spread 동작을 바꾸지 않는다(명시 접근만).
+  if (app && /** @type {any} */ (app).serviceRegistry?.size > 0) {
+    Object.defineProperty(ctx, 'services', {
+      value: buildServicesProxy(ctx, app),
+      enumerable: false,
+      configurable: true,
+    })
+  }
+  return ctx
+}
+
+/**
+ * 요청당 ctx 를 **한 번만** 만들고 `req` 에 캐싱해 재사용한다(ADR-134). 글로벌 미들웨어(preHandler)와
+ * 라우트 핸들러가 같은 요청에서 호출하면 **동일 ctx 객체**를 받으므로, 미들웨어가 ctx 에 심은 값
+ * (예: `ctx.user`)을 핸들러가 그대로 본다. 첫 호출이 build, 이후 호출은 캐시 반환.
+ *
+ * 캐시 키는 비열거 Symbol 이라 `{...ctx}`/`Object.keys(req)` 에 노출되지 않는다. `req` 는 Fastify 가
+ * 요청마다 새로 만드는 객체라 요청 스코프로 자연히 격리된다(요청 종료 시 GC).
+ *
+ * @param {object} args
+ * @param {import('./mega-app.js').MegaApp | null} args.app
+ * @param {import('fastify').FastifyRequest} args.req
+ * @param {import('fastify').FastifyReply} args.reply
+ * @returns {Record<string, any>}
+ */
+export function getHttpCtx({ app, req, reply }) {
+  const cached = /** @type {any} */ (req)[HTTP_CTX_KEY]
+  if (cached) return cached
+  const ctx = buildHttpCtx({ app, req, reply })
+  Object.defineProperty(req, HTTP_CTX_KEY, { value: ctx, enumerable: false, configurable: true })
+  return ctx
+}

package/src/core/envelope.js

@@ -0,0 +1,88 @@
+// @ts-check
+/**
+ * 응답 envelope 헬퍼 (ADR-014, ADR-018).
+ *
+ * 모든 HTTP 응답은 `{ ok, data|error, meta }` 형태로 통일된다.
+ * wrapEnvelope 는 preSerialization 의 마지막 단계에서 raw data 를 감싸고,
+ * errorEnvelope 는 글로벌 에러 핸들러에서 에러를 감싼다.
+ *
+ * @module core/envelope
+ */
+
+/** request 시작 시간 기록용 symbol (meta.took_ms 계산). reply 객체에 부착. */
+export const REPLY_START_SYMBOL = Symbol('mega.reply.start')
+
+/**
+ * 자동 envelope (ADR-018). preSerialization 훅의 마지막 단계에서 호출되어
+ * raw data → `{ ok:true, data, meta }`.
+ *
+ * transform 미들웨어(ADR-091)가 먼저 raw data 를 변환했으면, 그 변환 결과 위에 envelope 만 감쌈
+ * (실행 순서: transform → wrap, ADR-076 / ADR-091).
+ *
+ * 이미 envelope 형태로 보낸 경우(`{ ok:false, error: ... }` 등 명시) 는 그대로 통과 —
+ * 글로벌 에러 핸들러가 만든 error envelope 의 이중 wrap 을 방지.
+ *
+ * @param {Record<string, any>} req - Fastify request
+ * @param {Record<string | symbol, any>} reply - Fastify reply
+ * @param {any} payload - 핸들러/transform 이 만든 raw data 또는 이미 만들어진 envelope
+ * @returns {Object | any} envelope 또는 (이미 envelope 면) 원본 payload
+ */
+export function wrapEnvelope(req, reply, payload) {
+  if (isEnvelope(payload)) return payload
+  return {
+    ok: true,
+    data: payload,
+    meta: buildMeta(req, reply),
+  }
+}
+
+/**
+ * 에러 envelope (ADR-014). 글로벌 에러 핸들러가 사용.
+ * @param {Record<string, any>} req
+ * @param {Record<string | symbol, any>} reply
+ * @param {{ code: string, message?: string, details?: any }} error
+ * @returns {{ ok: false, error: { code: string, message: string, details?: any }, meta: Object }}
+ */
+export function errorEnvelope(req, reply, error) {
+  return {
+    ok: false,
+    error: {
+      code: error.code,
+      message: error.message ?? '',
+      ...(error.details !== undefined ? { details: error.details } : {}),
+    },
+    meta: buildMeta(req, reply),
+  }
+}
+
+/**
+ * 이미 envelope 모양인지 판별 — `ok: boolean` + (`data` | `error`) 키 보유.
+ * @param {any} payload
+ * @returns {boolean}
+ */
+function isEnvelope(payload) {
+  return (
+    payload != null &&
+    typeof payload === 'object' &&
+    !Array.isArray(payload) &&
+    typeof payload.ok === 'boolean' &&
+    ('data' in payload || 'error' in payload)
+  )
+}
+
+/**
+ * meta 빌드 — request_id (있으면) + took_ms (onRequest 에서 시작 시각 기록됐으면).
+ * @param {Record<string, any>} req
+ * @param {Record<string | symbol, any>} reply
+ * @returns {{ request_id?: string, took_ms?: number }}
+ */
+function buildMeta(req, reply) {
+  /** @type {{ request_id?: string, took_ms?: number }} */
+  const meta = {}
+  if (req?.id) meta.request_id = String(req.id)
+  const startedAt = reply?.[REPLY_START_SYMBOL]
+  if (typeof startedAt === 'number') {
+    meta.took_ms = Date.now() - startedAt
+  }
+  return meta
+}

package/src/core/error-mapper.js

@@ -0,0 +1,116 @@
+// @ts-check
+/**
+ * 글로벌 에러 핸들러 (ADR-025, ADR-090). Fastify `setErrorHandler` 에 등록.
+ *
+ * 던져진 모든 에러를 envelope error (ADR-014) 로 통일 변환한다.
+ *
+ * @module core/error-mapper
+ */
+import { MegaHttpError, MegaInternalError } from '../errors/http-errors.js'
+import { MegaError } from '../errors/mega-error.js'
+import { ajvErrorToValidationError } from './ajv-mapper.js'
+import { errorEnvelope } from './envelope.js'
+
+/**
+ * Fastify setErrorHandler 에 등록할 핸들러 빌더.
+ *
+ * 우선순위:
+ *   1) AJV validation 에러 → MegaValidationError 변환 (ADR-090)
+ *   2) MegaHttpError → 그대로 envelope (status/code/message/details 보존)
+ *   3) MegaError → 500 + code/message 보존 (도메인 에러지만 HTTP status 없음)
+ *   4) 그 외 일반 Error → MegaInternalError (스택·메시지는 로그만, envelope 엔 마스킹)
+ *
+ * @param {{ exposeInternalDetails?: boolean }} [opts]
+ *   - exposeInternalDetails: true 면 일반 Error 의 message 를 envelope 에 노출.
+ *     기본 false (보안 — 내부 구현 누출 방지).
+ * @returns {(error: Error, req: any, reply: any) => any}
+ */
+export function buildErrorHandler({ exposeInternalDetails = false } = {}) {
+  return function errorHandler(error, req, reply) {
+    // 에러 캡처 시점 debug 로그 (시크릿 제외, 핵심 필드만).
+    const log = req?.log
+    log?.debug?.(
+      { err: error, route: req?.url, method: req?.method },
+      'error-handler enter',
+    )
+
+    // 1) AJV 변환 시도 → 2~4) MegaHttpError 정규화
+    const fromAjv = ajvErrorToValidationError(error)
+    const e = fromAjv ?? toMegaHttpError(error, exposeInternalDetails)
+
+    reply.code(e.status)
+    return errorEnvelope(req, reply, {
+      code: e.code,
+      message: translateMessage(req, e),
+      details: e.details,
+    })
+  }
+}
+
+/**
+ * 에러 메시지를 i18n 으로 번역한다(ADR-016/135 — 에러 코드 ↔ server scope locale 키 1:1 매핑).
+ *
+ * i18n 옵트인 앱은 요청에 `req.t`(server scope 번역기)가 붙어 있다. 에러 `code`(예: `user.not_found`)를
+ * locale 키로 lookup 하되, 키가 없으면 원본 `message` 를 그대로 쓴다(`defaultValue`). `details` 를
+ * 보간 params 로 넘겨 `{{id}}` 류 치환을 지원한다. i18n 미등록(req.t 없음)이거나 i18n 이전 단계 에러면
+ * 원본 message 반환(하위 호환). dev 면 누락 키가 saveMissing 으로 자동 수집된다.
+ *
+ * @param {any} req - Fastify 요청(i18n 등록 시 `req.t` 보유).
+ * @param {{ code: string, message: string, details?: any }} e - 정규화된 에러.
+ * @returns {string} 번역된(또는 원본) 메시지.
+ */
+function translateMessage(req, e) {
+  const t = req?.t
+  if (typeof t !== 'function') return e.message
+  // i18next: t(key, defaultValue, params) — 키 있으면 번역, 없으면 defaultValue(=원본 message).
+  const params = e.details && typeof e.details === 'object' ? e.details : {}
+  return t(e.code, e.message, params)
+}
+
+/**
+ * 임의의 에러를 MegaHttpError 로 정규화.
+ * @param {any} error
+ * @param {boolean} exposeInternalDetails
+ * @returns {MegaHttpError}
+ */
+function toMegaHttpError(error, exposeInternalDetails) {
+  if (error instanceof MegaHttpError) return error
+  if (error instanceof MegaError) {
+    // 도메인 에러지만 HTTP status 없음 → 500 (code/message/details 보존)
+    return new MegaInternalError(error.code, error.message, {
+      details: error.details,
+      cause: error.cause ?? error,
+    })
+  }
+  // Fastify/플러그인 네이티브 4xx 에러(FST_CSRF_*, 413 body-too-large, 415 unsupported-media 등)는
+  // 클라이언트 잘못이라 status·메시지를 보존한다(ADR-127). 보존 안 하면 모든 4xx 가 500 으로 뭉개져
+  // 디버깅·클라 분기가 깨진다. 5xx/status 없는 일반 Error 만 아래 generic 500 으로 떨어진다.
+  const sc = Number(error?.statusCode)
+  if (Number.isInteger(sc) && sc >= 400 && sc < 500) {
+    return new MegaHttpError(sc, fastifyErrorCode(error?.code), error?.message || 'Request error', {})
+  }
+  // 일반 Error — 내부 상세 노출 금지가 디폴트 (보안)
+  return new MegaInternalError(
+    'server.internal',
+    exposeInternalDetails ? error?.message || 'Internal server error' : 'Internal server error',
+    { cause: error },
+  )
+}
+
+/**
+ * Fastify/플러그인 네이티브 에러 코드(`FST_CSRF_INVALID_TOKEN` 등)를 envelope `domain.error` 코드로
+ * 매핑한다(ADR-016). CSRF 는 명시 매핑, 그 외 알려지지 않은 `FST_*` 는 `request.rejected` 로 통일한다.
+ *
+ * @param {unknown} code - error.code(있으면).
+ * @returns {string} envelope 코드.
+ */
+function fastifyErrorCode(code) {
+  switch (code) {
+    case 'FST_CSRF_INVALID_TOKEN':
+      return 'csrf.invalid_token'
+    case 'FST_CSRF_MISSING_SECRET':
+      return 'csrf.missing_secret'
+    default:
+      return 'request.rejected'
+  }
+}

package/src/core/formbody.js

@@ -0,0 +1,69 @@
+// @ts-check
+/**
+ * MegaApp HTML 폼 바디 파싱 자동 등록 — `@fastify/formbody` 통합.
+ *
+ * # 무엇인가 (중학생용 설명)
+ *   웹 페이지의 `<form>` 을 제출하면 브라우저는 입력값을 `application/x-www-form-urlencoded`
+ *   (예: `name=Ada&email=ada%40x.com`) 형식으로 보낸다. Fastify 는 기본으로 JSON·text 만 파싱하므로
+ *   이 형식은 그냥 두면 `req.body` 가 비어 있다. 본 모듈은 검증된 공식 플러그인 `@fastify/formbody` 를
+ *   등록해 urlencoded 바디를 객체로 파싱해 `req.body` 에 채운다(서버사이드 폼 처리 = MPA).
+ *
+ * # 옵트인 조건 (views 연동)
+ *   서버사이드 뷰(`views.dir`)를 켠 앱만 등록한다. 서버 렌더 뷰가 있다는 건 HTML 폼 제출을 받을
+ *   가능성이 높다는 뜻이라, 폼 파싱을 뷰 옵트인에 묶는다(별도 config 키 없이). JSON 전용 API 앱은
+ *   기존처럼 JSON·text 만 파싱(동작 변화 없음). urlencoded 가 필요한 API 앱은 직접
+ *   `fastify.addContentTypeParser(...)` 로 등록할 수 있다(formbody 미등록이라 충돌 없음).
+ *
+ * # CSRF 통합
+ *   `security.js` 가 `application/x-www-form-urlencoded` 를 **폼**으로 분류해 CSRF 토큰을 검증한다(ADR-051).
+ *   폼 파싱과 무관하게 적용되므로, 폼은 `_csrf` 토큰을 함께 보내야 한다(csrf 활성 시).
+ *
+ * @module core/formbody
+ * @see ADR-151
+ * @see https://github.com/fastify/fastify-formbody (@fastify/formbody v8)
+ */
+import fastifyFormbody from '@fastify/formbody'
+
+/**
+ * 폼 바디 파서 자동 등록 결과 요약(디버그·테스트용).
+ * @typedef {Object} FormbodySummary
+ * @property {boolean} enabled - 등록 여부.
+ */
+
+/**
+ * views 설정이 서버사이드 렌더를 켰는지 (Boolean — `has*`). `views.dir` 가 비지 않은 문자열일 때만 true.
+ * registerTemplate 의 옵트인 판정과 같은 기준이라 폼 파싱이 뷰 등록과 정확히 짝을 이룬다.
+ * @param {unknown} views
+ * @returns {boolean}
+ */
+export function hasServerViews(views) {
+  return (
+    views != null &&
+    typeof views === 'object' &&
+    typeof /** @type {Record<string, any>} */ (views).dir === 'string' &&
+    /** @type {Record<string, any>} */ (views).dir.length > 0
+  )
+}
+
+/**
+ * Fastify 인스턴스에 `@fastify/formbody` 를 등록한다 — 서버사이드 뷰를 켠 앱에 한해 옵트인.
+ *
+ * `views` 가 없으면 **미등록**(JSON·text 만 파싱, 기존 동작 유지). 호출 시점은 라우트 등록 이전이어야
+ * 한다(content-type 파서는 글로벌이라 등록 후 도착하는 모든 요청에 적용) — MegaApp 생성자가 그 지점이다.
+ *
+ * @param {import('fastify').FastifyInstance} fastify - 대상 앱 Fastify 인스턴스.
+ * @param {Object} opts
+ * @param {unknown} opts.views - `MegaViewsConfig`(dir/layoutDir/...). 서버 뷰 옵트인 판정에 쓴다.
+ * @param {string} [opts.appName] - 앱 이름(로그용).
+ * @param {{ debug?: Function }} [opts.logger] - 흐름 길목 debug 로그(선택).
+ * @returns {FormbodySummary}
+ */
+export function registerFormbody(fastify, { views, appName = '(unknown)', logger } = /** @type {any} */ ({})) {
+  if (!hasServerViews(views)) {
+    return { enabled: false }
+  }
+  // 기본 옵션 — urlencoded 를 Node querystring 으로 파싱해 req.body 객체로. bodyLimit 등은 Fastify 전역 기본 적용.
+  fastify.register(fastifyFormbody)
+  logger?.debug?.({ app: appName }, 'formbody.registered')
+  return { enabled: true }
+}