mega-framework 0.1.6 → 0.1.8

package/src/core/migration-runner.js

@@ -1,19 +1,24 @@
 // @ts-check
 /**
- * 마이그레이션 러너 (ADR-149) — `apps/<app>/migrations/<ts>-<name>.js` 의 up/down 을
+ * 마이그레이션 러너 (ADR-149/184) — `apps/<app>/migrations/<ts>-<name>.js` 의 up/down 을
  * 대상 DB 에 적용·롤백하고, 적용 이력을 대상 DB 의 `mega_migrations` 테이블로 추적한다.
+ * 이력 행에는 파일 내용의 sha-256 `checksum` 을 함께 기록해, 적용 후 파일이 수정된 드리프트를
+ * `migrate:status`(modified)·`migrate`(경고 로그)에서 감지한다(ADR-190).
  *
  * 러너는 **어댑터에 비의존적**이다 — 호출자(`runMigrateHost`)가 연결된 DB 어댑터(`{ query, withTransaction }`)를
  * `db` 로 넘긴다. 마이그레이션 파일의 `up(db)/down(db)` 는 이 어댑터를 받아 SQL 을 실행한다. 어댑터가
  * `withTransaction` 을 지원하면 각 마이그레이션을 트랜잭션으로 감싸 부분 실패를 롤백한다(postgres DDL-in-tx).
+ * 동시 실행 락은 러너가 아니라 **호스트 레벨**({@link module:core/migration-lock}) 책임이다 —
+ * driver 별 락 메커니즘이 달라 어댑터 비의존성을 깨지 않기 위함(ADR-190).
  *
- * 부기 SQL(테이블 생성·SELECT·INSERT·DELETE)은 표준 SQL 만 쓰고, 값(마이그레이션 name·applied_at)은
- * **framework-controlled 라 따옴표가 불가능**(name 은 {@link MIGRATION_FILE_RE} 검증, applied_at 은 ISO)하므로
- * placeholder(`$1` vs `?`) dialect 분기 없이 인라인해도 인젝션-안전하다.
+ * 부기 SQL(테이블 생성·SELECT·INSERT·DELETE)은 표준 SQL 만 쓰고, 값(마이그레이션 name·applied_at·checksum)은
+ * **framework-controlled 라 따옴표가 불가능**(name 은 {@link MIGRATION_FILE_RE} 검증, applied_at 은 ISO,
+ * checksum 은 sha-256 hex)하므로 placeholder(`$1` vs `?`) dialect 분기 없이 인라인해도 인젝션-안전하다.
  *
  * @module core/migration-runner
  */
-import { readdirSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { readdirSync, readFileSync } from 'node:fs'
 import { join, resolve as pathResolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { MegaConfigError } from '../errors/config-error.js'
@@ -62,9 +67,11 @@ export function collectMigrationFiles({ projectRoot, appNames }) {
 }
 
 /**
- * 마이그레이션 모듈 로드 + up/down 검증.
+ * 마이그레이션 모듈 로드 + up/down 검증. `export const transaction = false`(옵트아웃, ADR-205)면
+ * 러너가 트랜잭션 래핑을 끈다 — `CREATE INDEX CONCURRENTLY` 처럼 트랜잭션 안에서 실행 불가한
+ * 문장을 위한 escape hatch(부분 실패 시 롤백 없음은 파일 작성자 책임 — 생성기가 헤더에 명시).
  * @param {string} absPath
- * @returns {Promise<{ up: Function, down: Function }>}
+ * @returns {Promise<{ up: Function, down: Function, useTransaction: boolean }>}
  * @throws {MegaConfigError} import 실패 / up·down 누락.
  */
 export async function loadMigration(absPath) {
@@ -77,35 +84,55 @@ export async function loadMigration(absPath) {
   if (typeof mod.up !== 'function' || typeof mod.down !== 'function') {
     throw new MegaConfigError('migration.invalid', `Migration '${absPath}' must export async function up(db) and down(db).`)
   }
-  return { up: mod.up, down: mod.down }
+  return { up: mod.up, down: mod.down, useTransaction: mod.transaction !== false }
 }
 
 /**
  * 이력 테이블 보장(idempotent). 표준 SQL — postgres/maria/sqlite 공통.
+ * v1(checksum 없는) 기존 테이블은 컬럼 부재를 감지해 ADD COLUMN 으로 보강한다(ADR-190) —
+ * `ADD COLUMN IF NOT EXISTS` 가 sqlite 미지원이라 SELECT 시도로 부재를 판별한다.
  * @param {MigrationDb} db
  * @returns {Promise<void>}
  */
 async function ensureTable(db) {
-  await db.query(`CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (name VARCHAR(255) PRIMARY KEY, applied_at VARCHAR(64) NOT NULL)`)
+  await db.query(
+    `CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (name VARCHAR(255) PRIMARY KEY, applied_at VARCHAR(64) NOT NULL, checksum VARCHAR(64))`,
+  )
+  try {
+    await db.query(`SELECT checksum FROM ${MIGRATIONS_TABLE} LIMIT 1`)
+  } catch {
+    // checksum 컬럼 부재(v1 테이블) — 보강한다. SELECT 실패가 다른 원인이었다면 아래 ALTER 도
+    // 같은 원인으로 throw 하므로 에러가 묻히지 않는다(P4 — silent 무시 아님).
+    await db.query(`ALTER TABLE ${MIGRATIONS_TABLE} ADD COLUMN checksum VARCHAR(64)`)
+  }
 }
 
 /**
- * 적용된 마이그레이션 name 집합.
+ * 적용된 마이그레이션 이력 — name → checksum(checksum 도입 전 v1 행은 null).
  * @param {MigrationDb} db
- * @returns {Promise<Set<string>>}
+ * @returns {Promise<Map<string, string | null>>}
  */
-async function appliedSet(db) {
-  const res = await db.query(`SELECT name FROM ${MIGRATIONS_TABLE}`)
+async function appliedRecords(db) {
+  const res = await db.query(`SELECT name, checksum FROM ${MIGRATIONS_TABLE}`)
   const rows = res?.rows ?? (Array.isArray(res) ? res : [])
-  return new Set(rows.map((/** @type {any} */ r) => r.name))
+  return new Map(rows.map((/** @type {any} */ r) => [r.name, r.checksum ?? null]))
 }
 
 /**
- * 적용 기록 INSERT. name(검증된 [\d a-z -])·iso(ISO)는 따옴표 불가라 인라인 안전(placeholder dialect 회피).
- * @param {MigrationDb} db @param {string} name @param {string} appliedAtIso
+ * 마이그레이션 파일 내용의 sha-256 hex digest — 적용 후 파일 수정(드리프트) 감지용(ADR-190).
+ * @param {string} absPath @returns {string}
  */
-async function recordApplied(db, name, appliedAtIso) {
-  await db.query(`INSERT INTO ${MIGRATIONS_TABLE} (name, applied_at) VALUES ('${name}', '${appliedAtIso}')`)
+function fileChecksum(absPath) {
+  return createHash('sha256').update(readFileSync(absPath)).digest('hex')
+}
+
+/**
+ * 적용 기록 INSERT. name(검증된 [\d a-z -])·iso(ISO)·checksum(sha-256 hex)은 따옴표 불가라 인라인
+ * 안전(placeholder dialect 회피).
+ * @param {MigrationDb} db @param {string} name @param {string} appliedAtIso @param {string} checksum
+ */
+async function recordApplied(db, name, appliedAtIso, checksum) {
+  await db.query(`INSERT INTO ${MIGRATIONS_TABLE} (name, applied_at, checksum) VALUES ('${name}', '${appliedAtIso}', '${checksum}')`)
 }
 
 /**
@@ -120,38 +147,111 @@ async function removeApplied(db, name) {
  * 어댑터가 트랜잭션을 지원하면 fn 을 트랜잭션으로 감싸 실행한다. postgres 는 AsyncLocalStorage 로 tx
  * 컨텍스트를 추적하므로 fn 안의 `db.query` 가 같은 트랜잭션 클라이언트로 라우팅된다(ADR-106).
  * @param {MigrationDb} db @param {() => Promise<void>} fn
+ * @param {{ info?: Function, warn?: Function, debug?: Function }} [log]
  */
-async function runInTransaction(db, fn) {
+async function runInTransaction(db, fn, log) {
   if (typeof db.withTransaction === 'function') {
     await db.withTransaction(async () => {
       await fn()
     })
   } else {
+    // 트랜잭션을 기대(transaction 미선언 = 기본 true)했는데 어댑터가 미지원(mongo 등)이면
+    // 조용한 폴스루가 "tx 보호를 받는다" 는 오인을 만든다(ADR-210 L-4) — 명시 경고 1줄.
+    log?.warn?.('migrate: adapter has no withTransaction — running without transaction (rollback unavailable on failure)')
     await fn()
   }
 }
 
 /**
- * 미적용(pending) 마이그레이션을 타임스탬프 순으로 모두 적용한다. 각 마이그레이션의 up + 이력 기록을
- * 한 트랜잭션으로 묶어 원자적으로 처리한다.
+ * 적용된 파일 중 적용 후 내용이 수정된(드리프트) 마이그레이션 이름 목록 — 저장된 checksum 과 현재
+ * 파일 digest 불일치. checksum 이 null(v1 이력)이면 비교 불가라 제외한다(ADR-190).
+ * @param {MigrationFile[]} files @param {Map<string, string | null>} applied
+ * @returns {string[]}
+ */
+function findModified(files, applied) {
+  return files
+    .filter((m) => {
+      const stored = applied.get(m.name)
+      return stored != null && stored !== fileChecksum(m.absPath)
+    })
+    .map((m) => m.name)
+}
+
+/**
+ * 미적용(pending) 마이그레이션을 타임스탬프 순으로 모두 적용한다. 각 마이그레이션의 up + 이력 기록
+ * (sha-256 checksum 포함, ADR-190)을 한 트랜잭션으로 묶어 원자적으로 처리한다. 이미 적용된 파일이
+ * 적용 후 수정됐으면(checksum 불일치) 경고 로그를 남긴다 — 실행된 스키마와 파일이 어긋난 상태.
  *
- * @param {{ db: MigrationDb, projectRoot: string, appNames: string[], now?: () => string, log?: { info?: Function } }} opts
+ * @param {{ db: MigrationDb, projectRoot: string, appNames: string[], now?: () => string, log?: { info?: Function, warn?: Function, debug?: Function } }} opts
  *   - now: 적용 시각 ISO 문자열 공급자(테스트 주입용, 기본 `new Date().toISOString()`).
  * @returns {Promise<{ applied: string[] }>}
  */
 export async function migrateUp({ db, projectRoot, appNames, now = () => new Date().toISOString(), log }) {
   await ensureTable(db)
-  const applied = await appliedSet(db)
-  const pending = collectMigrationFiles({ projectRoot, appNames }).filter((m) => !applied.has(m.name))
+  const applied = await appliedRecords(db)
+  const all = collectMigrationFiles({ projectRoot, appNames })
+  for (const name of findModified(all, applied)) {
+    log?.warn?.({ migration: name }, 'migrate.up checksum mismatch — file modified after apply')
+  }
+  const pending = all.filter((m) => !applied.has(m.name))
   /** @type {string[]} */
   const done = []
   for (const m of pending) {
-    const { up } = await loadMigration(m.absPath)
+    const { up, useTransaction } = await loadMigration(m.absPath)
+    const checksum = fileChecksum(m.absPath)
     const appliedAt = now()
-    await runInTransaction(db, async () => {
+    let skipped = false
+    const apply = async () => {
+      // 적용 직전 이력 재확인 — pending 산출(시작 시 1회)과 실제 적용 사이에 동시 러너가 끼어들 수
+      // 있다. 락이 약한 dialect(sqlite — 파일 락은 read-check-apply 원자성을 안 줌)에서 패자가
+      // 같은 DDL 을 재실행해 오도성 에러(duplicate column 등)로 죽는 것을, 명시 skip 으로 바꾼다.
+      const recheck = await db.query(`SELECT name FROM ${MIGRATIONS_TABLE} WHERE name = '${m.name}'`)
+      const recheckRows = recheck?.rows ?? (Array.isArray(recheck) ? recheck : [])
+      if (recheckRows.length > 0) {
+        skipped = true
+        log?.warn?.({ migration: m.name }, 'migrate.up skipped — already applied by a concurrent runner')
+        return
+      }
       await up(db)
-      await recordApplied(db, m.name, appliedAt)
-    })
+      await recordApplied(db, m.name, appliedAt, checksum)
+    }
+    try {
+      if (useTransaction) {
+        await runInTransaction(db, apply, log)
+      } else {
+        // `export const transaction = false` 옵트아웃(ADR-205 — CONCURRENTLY 등) — 부분 실패 시
+        // 롤백되지 않음을 로그로 표면화한다(파일 헤더에도 명시됨).
+        log?.warn?.({ migration: m.name }, 'migrate.up no-transaction migration (rollback unavailable on partial failure)')
+        await apply()
+      }
+    } catch (err) {
+      // 실패 후 이력 재확인 — 이력 기록은 적용 성공의 최종 단계라, 이름이 이력에 있으면 동시
+      // 러너가 이미 적용을 완료한 것이다(같은 파일을 정확히 동시에 시작한 패자는 직전 재확인
+      // 창을 지나 DDL 충돌·이력 UNIQUE 로 죽는다 — 실측). 오도성 에러 대신 명시 skip(ADR-208 M-2).
+      let appliedByOther = false
+      try {
+        const after = await db.query(`SELECT name FROM ${MIGRATIONS_TABLE} WHERE name = '${m.name}'`)
+        const afterRows = after?.rows ?? (Array.isArray(after) ? after : [])
+        appliedByOther = afterRows.length > 0
+      } catch (recheckErr) {
+        // 재확인 자체가 실패(연결 단절 등)하면 원인 판별 불가 — 원본 에러를 그대로 보고한다.
+        log?.debug?.({ err: recheckErr, migration: m.name }, 'migrate.up post-failure history recheck failed')
+      }
+      if (appliedByOther) {
+        log?.warn?.({ migration: m.name }, 'migrate.up skipped — already applied by a concurrent runner')
+        continue
+      }
+      // 어느 파일에서 죽었는지 없이 driver 원문만 던지면 다단 적용에서 추적이 어렵다 — 파일 컨텍스트 wrap.
+      // no-tx 파일은 부분 적용이 남을 수 있다 — 멱등 렌더(maria IF EXISTS·mongo not-found 허용)
+      // 덕에 원인 제거 후 같은 파일 재실행이 1차 복구 수단임을 에러에 직접 안내한다(ADR-208/210).
+      const noTxHint = useTransaction ? '' : ' [no-transaction — 부분 적용이 남았을 수 있습니다. 원인 제거 후 재실행하면 멱등 문장은 건너뜁니다]'
+      throw new MegaConfigError(
+        'migration.apply_failed',
+        `Migration '${m.name}' failed during up(): ${/** @type {any} */ (err).message}${noTxHint} (file: ${m.absPath})`,
+        { cause: err, details: { migration: m.name, file: m.absPath, direction: 'up' } },
+      )
+    }
+    if (skipped) continue
     log?.info?.({ migration: m.name }, 'migrate.up applied')
     done.push(m.name)
   }
@@ -160,37 +260,65 @@ export async function migrateUp({ db, projectRoot, appNames, now = () => new Dat
 
 /**
  * 가장 최근 적용된 마이그레이션 1개를 롤백한다(down + 이력 삭제, 한 트랜잭션). 적용분이 없으면 no-op.
- * 적용 이력에 있으나 파일이 사라진 항목은 down 을 실행할 수 없어 건너뛴다.
  *
- * @param {{ db: MigrationDb, projectRoot: string, appNames: string[], log?: { info?: Function } }} opts
+ * 이력상 최신 적용분의 **파일이 사라진 경우 fail-fast** 한다(`migration.history_file_missing`, ADR-190) —
+ * 조용히 건너뛰면 더 오래된 마이그레이션이 롤백되어(순서 역전) 이력과 실제 스키마가 어긋난다.
+ *
+ * @param {{ db: MigrationDb, projectRoot: string, appNames: string[], log?: { info?: Function, warn?: Function } }} opts
  * @returns {Promise<{ rolledBack: string | null }>}
+ * @throws {MegaConfigError} `migration.history_file_missing` - 최신 적용 이력의 파일 부재.
  */
 export async function migrateDown({ db, projectRoot, appNames, log }) {
   await ensureTable(db)
-  const applied = await appliedSet(db)
+  const applied = await appliedRecords(db)
+  if (applied.size === 0) return { rolledBack: null }
+  // 이력의 최신 적용분 — name 은 `<ts>-<kebab>` 라 사전식 정렬 = 시간순.
+  const newest = [...applied.keys()].sort()[applied.size - 1]
   const appliedFiles = collectMigrationFiles({ projectRoot, appNames }).filter((m) => applied.has(m.name))
   const last = appliedFiles[appliedFiles.length - 1]
-  if (!last) return { rolledBack: null }
-  const { down } = await loadMigration(last.absPath)
-  await runInTransaction(db, async () => {
+  if (last === undefined || last.name !== newest) {
+    throw new MegaConfigError(
+      'migration.history_file_missing',
+      `Cannot roll back: migration '${newest}' is recorded in ${MIGRATIONS_TABLE} but its file is missing under apps/*/migrations. ` +
+        'Restore the file, or remove the history row manually after verifying the schema.',
+      { details: { newestApplied: newest, lastFileFound: last?.name ?? null } },
+    )
+  }
+  const { down, useTransaction } = await loadMigration(last.absPath)
+  const rollback = async () => {
     await down(db)
     await removeApplied(db, last.name)
-  })
+  }
+  try {
+    if (useTransaction) {
+      await runInTransaction(db, rollback)
+    } else {
+      log?.warn?.({ migration: last.name }, 'migrate.down no-transaction migration (rollback unavailable on partial failure)')
+      await rollback()
+    }
+  } catch (err) {
+    throw new MegaConfigError(
+      'migration.apply_failed',
+      `Migration '${last.name}' failed during down(): ${/** @type {any} */ (err).message} (file: ${last.absPath})`,
+      { cause: err, details: { migration: last.name, file: last.absPath, direction: 'down' } },
+    )
+  }
   log?.info?.({ migration: last.name }, 'migrate.down rolled back')
   return { rolledBack: last.name }
 }
 
 /**
- * 적용/미적용 마이그레이션 목록(타임스탬프 순).
+ * 적용/미적용/드리프트(적용 후 수정) 마이그레이션 목록(타임스탬프 순, ADR-190).
  * @param {{ db: MigrationDb, projectRoot: string, appNames: string[] }} opts
- * @returns {Promise<{ applied: string[], pending: string[] }>}
+ * @returns {Promise<{ applied: string[], pending: string[], modified: string[] }>}
  */
 export async function migrateStatus({ db, projectRoot, appNames }) {
   await ensureTable(db)
-  const applied = await appliedSet(db)
+  const applied = await appliedRecords(db)
   const all = collectMigrationFiles({ projectRoot, appNames })
   return {
     applied: all.filter((m) => applied.has(m.name)).map((m) => m.name),
     pending: all.filter((m) => !applied.has(m.name)).map((m) => m.name),
+    modified: findModified(all, applied),
   }
 }

package/src/core/multipart.js

@@ -23,6 +23,8 @@
  *     플러그인 내장 기능이 아니라 본 모듈이 게이트로 강제 → 비허용 415(`MegaUnsupportedMediaTypeError`).
  *   - **경로 탐색(path traversal) 차단**: 저장 시 `sanitizeFilename`(basename + 선행 점 제거)으로 파일명에서
  *     디렉터리 성분을 제거하고, 최종 경로가 대상 디렉터리 내부인지 한 번 더 검증(이중 방어).
+ *   - **파일명 충돌 차단**: 저장 파일명은 `uniquifyFilename`(타임스탬프+랜덤 접미)으로 유일화 — 동일명
+ *     동시/연속 업로드의 silent 덮어쓰기·스트림 race 를 막는다. 표시명(meta.filename)은 살균 원본 유지.
  *   - **MIME 스푸핑 한계**: 게이트는 클라가 선언한 `Content-Type`(part header) 기준이다. 매직바이트 스니핑은
  *     하지 않는다(스트림 1패스 비용 회피). 선언 MIME 위조 가능성은 문서화된 한계이며, 진짜 콘텐츠 검증이
  *     필요하면 핸들러에서 `toBuffer()` 후 별도 검사한다.
@@ -47,7 +49,8 @@ import { mkdir, unlink } from 'node:fs/promises'
 import { createWriteStream } from 'node:fs'
 import { stat } from 'node:fs/promises'
 import { pipeline } from 'node:stream/promises'
-import { basename, resolve, sep } from 'node:path'
+import { randomBytes } from 'node:crypto'
+import { basename, extname, resolve, sep } from 'node:path'
 import fastifyMultipart from '@fastify/multipart'
 import { MegaUnsupportedMediaTypeError, MegaPayloadTooLargeError } from '../errors/http-errors.js'
 import * as MegaTracing from '../lib/mega-tracing.js'
@@ -88,6 +91,23 @@ export function sanitizeFilename(name) {
   return cleaned.length > 0 ? cleaned : 'upload'
 }
 
+/**
+ * 살균된 파일명에 타임스탬프+랜덤 접미를 붙여 저장 파일명을 유일화한다.
+ *
+ * 살균만으로는 **같은 이름의 동시/연속 업로드가 silent 덮어쓰기**된다(두 사용자가 'photo.jpg' 를 올리면
+ * 나중 것이 이김, 동시면 스트림 교차 가능). 저장 파일명에 `-<ts36>-<rand8hex>` 를 붙여 충돌을 막는다 —
+ * 반환 메타의 `filename`(표시명)은 살균 원본 그대로 유지하고 `savedAs`(실제 경로)만 유일명을 갖는다.
+ *
+ * @param {string} name - {@link sanitizeFilename} 을 통과한 파일명.
+ * @returns {string} 예: 'photo.jpg' → 'photo-mbz3k1x2-9f2ac01b.jpg'.
+ * @example uniquifyFilename('report.pdf') // 'report-<ts36>-<rand>.pdf'
+ */
+export function uniquifyFilename(name) {
+  const ext = extname(name)
+  const stem = name.slice(0, name.length - ext.length)
+  return `${stem}-${Date.now().toString(36)}-${randomBytes(4).toString('hex')}${ext}`
+}
+
 /**
  * MIME 타입이 화이트리스트에 허용되는지 (Boolean — `is*`). 빈 목록/미지정이면 **전부 허용**(게이트 비활성).
  * 정확 매치 + `type/*` 와일드카드(예: `'image/*'` 는 `'image/png'` 허용)를 지원한다.
@@ -210,9 +230,10 @@ export function registerMultipart(fastify, { upload, appName = '(unknown)', logg
 }
 
 /**
- * 업로드된 모든 파일을 `destDir` 에 안전하게 저장한다(`req.saveUploads` 구현부). 파일명을 살균하고 최종
- * 경로가 대상 디렉터리 내부인지 검증한 뒤 스트리밍으로 디스크에 쓴다. `mega.upload` span + `mega_upload_*`
- * 메트릭을 기록한다. MIME 게이트는 래핑된 `req.files()` 가 적용한다(비허용 415 전파).
+ * 업로드된 모든 파일을 `destDir` 에 안전하게 저장한다(`req.saveUploads` 구현부). 파일명을 살균·유일화하고
+ * 최종 경로가 대상 디렉터리 내부인지 검증한 뒤 스트리밍으로 디스크에 쓴다. `mega.upload` span +
+ * `mega_upload_*` 메트릭을 기록한다. MIME 게이트는 래핑된 `req.files()` 가 적용한다(비허용 415 전파).
+ * 반환 meta 의 `filename` 은 살균 표시명, `savedAs` 는 유일화된 실제 저장 절대경로다.
  *
  * @param {object} args
  * @param {any} args.req - Fastify 요청(래핑된 `files()` 보유).
@@ -236,7 +257,9 @@ async function saveUploads({ req, destDir, appName, saveOpts = {} }) {
       try {
         for await (const part of req.files(saveOpts.filesOptions)) {
           const safeName = sanitizeFilename(part.filename)
-          const abs = resolve(root, safeName)
+          // 저장 파일명은 유일화(동일명 동시/연속 업로드 silent 덮어쓰기·스트림 race 차단). 표시명
+          // (반환 meta.filename)은 살균 원본 유지.
+          const abs = resolve(root, uniquifyFilename(safeName))
           // 이중 방어 — 살균했어도 최종 경로가 root 내부(root/<파일>)가 아니면 거부.
           if (!abs.startsWith(root + sep)) {
             throw new Error(`upload.unsafe_path: resolved path escapes destDir (name='${part.filename}')`)

package/src/core/pipeline.js

@@ -0,0 +1,131 @@
+// @ts-check
+/**
+ * HTTP 라우트 라이프사이클 Pipeline — before/transform/after 합성의 단일 수렴점 (ADR-185).
+ *
+ * 배경: 미들웨어 wiring(arity 흡수·ctx 주입·after 에러 정책)이 router.js(라우트 등록)와
+ * mega-app.js(글로벌 미들웨어)에 비슷하지만 미세하게 다른 복사본으로 흩어져 있었고, 그래서
+ * `router.use` 의 arity 부팅 거부(ADR-184 H2) 같은 사각이 생겼다. 이 모듈이 합성 로직의
+ * 정본이다 — 신규 등록 경로는 반드시 여기를 거친다(복사본 금지).
+ *
+ * 합성 규칙 (ADR-091/134/156/184):
+ *   - before:    각각 arity-2 async 래퍼 + canonical ctx 주입 → Fastify preHandler 배열.
+ *     (Fastify 는 async hook 의 arity 3 이상을 done 콜백으로 오인해 등록을 거부하므로 래퍼 필수.
+ *      래퍼가 독립 preHandler 라 순서·reply 단락 의미는 보존된다.)
+ *   - transform: 순차 await 체인(payload 변환) → 단일 preSerialization. envelope wrap 은
+ *     MegaApp onRoute 가 체인 맨 끝에 별도 append(ADR-076 — transform → wrap 순서 보장).
+ *   - after:     onResponse(응답 전송 후). throw 는 warn 로그 후 무시 — 응답엔 영향 없음,
+ *     silent 금지(P4, ADR-091).
+ *
+ * 파일/앱/전역 레벨 transform·after 슬롯(ADR-021 의 전체 체인)은 Stage 2 — 등록 API 정본
+ * 설계 후 이 모듈에 추가한다(ADR-185).
+ *
+ * @module core/pipeline
+ */
+import { getLazyHttpCtx } from './ctx-builder.js'
+
+/**
+ * 미들웨어를 Fastify 가 async preHandler 로 인식하는 arity-2 래퍼로 감싸고, canonical ctx 를
+ * 3번째 인자로 주입한다 — 핸들러·글로벌 미들웨어와 동일한 `(req, reply, ctx)` 계약(ADR-134/184).
+ * ctx 는 **lazy 프록시**(ADR-214) — 미들웨어가 실제로 속성을 만질 때만 빌드되고, 요청당 캐싱이라
+ * 같은 요청의 모든 미들웨어·핸들러가 동일 ctx 객체를 공유한다.
+ *
+ * @param {Function} fn - `(req, reply, ctx?)` 미들웨어 (arity-2 도 하위 호환 — 3번째 인자 무시).
+ * @param {import('./mega-app.js').MegaApp | null} [app] - ctx 의 어댑터·서비스 접근자 출처(없으면 null).
+ * @returns {(req: import('fastify').FastifyRequest, reply: import('fastify').FastifyReply) => Promise<any>}
+ */
+export function wrapPreHandler(fn, app) {
+  return async (req, reply) => fn(req, reply, getLazyHttpCtx({ app: app ?? null, req, reply }))
+}
+
+/**
+ * transform 배열을 단일 preSerialization 함수로 합성한다 — 순차 await, 각 변환의 반환값이
+ * 다음 변환의 payload 가 된다(raw data 만 다룸 — envelope 는 이후 단계, ADR-091).
+ *
+ * @param {Function[]} transforms
+ * @returns {(req: import('fastify').FastifyRequest, reply: import('fastify').FastifyReply, payload: any) => Promise<any>}
+ */
+export function composeTransform(transforms) {
+  return async (req, reply, payload) => {
+    let current = payload
+    for (const fn of transforms) {
+      current = await fn(req, reply, current)
+    }
+    return current
+  }
+}
+
+/**
+ * after 배열을 단일 onResponse 함수로 합성한다 — 응답 전송 후 side-effect 전용.
+ * 개별 after 의 throw 는 warn 로그 후 다음 after 로 진행(응답 영향 없음, ADR-091 / P4).
+ *
+ * @param {Function[]} afters
+ * @param {{ method: string, path: string }} route - warn 로그 식별용.
+ * @returns {(req: import('fastify').FastifyRequest, reply: import('fastify').FastifyReply) => Promise<void>}
+ */
+export function composeAfter(afters, { method, path }) {
+  return async (req, reply) => {
+    for (const fn of afters) {
+      try {
+        await fn(req, reply)
+      } catch (err) {
+        // ADR-091: silent fallback 금지 — warn 로그.
+        const log = req.log ?? console
+        log.warn?.({ err, hook: 'after', method, path }, `after middleware threw — ignored (response already sent)`)
+      }
+    }
+  }
+}
+
+/**
+ * @typedef {object} HttpPipeline
+ * @property {(req: import('fastify').FastifyRequest, reply: import('fastify').FastifyReply) => Promise<any>} handler -
+ *   canonical `(req, reply, ctx)` 주입이 적용된 Fastify 핸들러.
+ * @property {Function[]} [preHandler] - before 래퍼 배열 (before 없으면 생략).
+ * @property {Function} [preSerialization] - transform 합성 (transform 없으면 생략).
+ * @property {Function} [onResponse] - after 합성 (after 없으면 생략).
+ * @property {() => { method: string, path: string, before: string[], transform: string[], after: string[] }} describe -
+ *   체인 introspection — 단계별 미들웨어 이름 목록(익명은 `(anonymous)`).
+ */
+
+/**
+ * 라우트 1개의 HTTP 라이프사이클을 합성한다. Router._registerHttp 가 Fastify routeOpts 로 옮긴다.
+ *
+ * @param {object} args
+ * @param {import('./mega-app.js').MegaApp | null} args.app - ctx 출처 (standalone Router 면 null).
+ * @param {string} args.method - HTTP 메서드 (소문자).
+ * @param {string} args.path - 라우트 경로.
+ * @param {Function} args.handler - 사용자 핸들러 (inline 또는 static method ref, ADR-074).
+ * @param {Function[]} [args.before]
+ * @param {Function[]} [args.transform]
+ * @param {Function[]} [args.after]
+ * @returns {HttpPipeline}
+ */
+export function buildHttpPipeline({ app = null, method, path, handler, before = [], transform = [], after = [] }) {
+  /** @type {HttpPipeline} */
+  const pipeline = {
+    // canonical 핸들러 시그니처 (req, res, ctx) (ADR-074, docs/03 §581). ctx 는 lazy 프록시
+    // (ADR-214) — 핸들러가 안 쓰면 buildHttpCtx 비용(1.6 KB + 0.7 µs/req, G1 H-1)이 발생하지 않고,
+    // 첫 접근부터는 요청당 1회 캐싱이라 글로벌·before 미들웨어가 먼저 만든 ctx 를 그대로 이어받는다(ADR-134).
+    handler: async (req, reply) => handler(req, reply, getLazyHttpCtx({ app, req, reply })),
+    describe: () => ({
+      method,
+      path,
+      before: before.map(fnName),
+      transform: transform.map(fnName),
+      after: after.map(fnName),
+    }),
+  }
+  if (before.length > 0) pipeline.preHandler = before.map((fn) => wrapPreHandler(fn, app))
+  if (transform.length > 0) pipeline.preSerialization = composeTransform(transform)
+  if (after.length > 0) pipeline.onResponse = composeAfter(after, { method, path })
+  return pipeline
+}
+
+/**
+ * 미들웨어 함수 이름 (introspection 표기용).
+ * @param {Function} fn
+ * @returns {string}
+ */
+function fnName(fn) {
+  return fn.name || '(anonymous)'
+}