mega-framework 0.1.0

package/src/adapters/file-adapter.js

@@ -0,0 +1,350 @@
+// @ts-check
+/**
+ * MegaFileAdapter — 로컬 파일시스템 캐시 어댑터 (Node `fs`/`path` 만, ADR-082/111).
+ *
+ * `MegaCacheAdapter` 의 두 번째 구체(Redis 다음). dev / 단일 인스턴스 / Redis 없는 환경에서
+ * 같은 `get/set/del/has` API 를 로컬 파일로 만족시킨다 — driver 키 한 줄만 바꿔 환경 전환(ADR-082).
+ * **신규 의존성 0** (`node:fs/promises`/`node:path`/`node:crypto` 표준만).
+ *
+ * # 표준 표면 (MegaCacheAdapter 상속)
+ *   - `_connect()`   — `fs.mkdir(basePath, { recursive: true })` 로 디렉토리 보장.
+ *   - `_disconnect()`— no-op (파일시스템은 close 개념 없음).
+ *   - `_native()`    — `{ basePath }` (raw "디렉토리 핸들" 개념, ADR-009).
+ *   - `healthCheck()`— basePath 에 probe 파일 write→read→unlink 로 실제 읽기/쓰기 가능 확인.
+ *   - `getStats()`   — 베이스 stats + file 특화(basePath/serializer/extension).
+ *   - `get/set/del/has` — 단일 JSON envelope 파일 + TTL 메타데이터(아래).
+ *
+ * # 저장 포맷 — 단일 envelope 파일 (`.meta` 사이드카 X, ADR-111 이 ADR-082 스케치를 정제)
+ *   ADR-082 초안은 값 파일 + 별도 `<key>.meta` TTL 파일 2개였으나, 두 파일이 desync 되면(한쪽만
+ *   써지거나 지워지면) 만료 판정이 깨진다. 본 구현은 **값과 만료시각을 한 파일의 JSON envelope**
+ *   `{ v:1, key, value, expiresAt }` 로 묶어 그 위험을 제거한다(더 안전한 단일-파일 대안).
+ *   `expiresAt` 은 epoch ms(무한이면 null). 쓰기는 **temp 파일 write 후 `rename`** 으로 atomic —
+ *   동시 write 가 반쯤 써진 파일을 읽는 일이 없다(POSIX rename 은 같은 파일시스템에서 원자적).
+ *
+ * # 파일명 — key 의 SHA-256 hex (경로 안전)
+ *   캐시 key 는 `mega:cache:<app>:<key>`(ADR-064) 처럼 `:` `/` 등 임의 문자를 포함할 수 있어 그대로
+ *   파일명에 못 쓴다(경로 탈출·길이 초과 위험). key 를 SHA-256 hex(64자)로 해싱해 파일명으로 쓰고,
+ *   원본 key 는 envelope 안에 보관(디버깅용). 해시라 충돌 가능성은 무시 가능하고 경로 탈출이 불가능.
+ *
+ * # serializer 옵션
+ *   - `'json'`(디폴트): `value` 는 임의 JSON 직렬화 가능 값. envelope 의 `value` 에 그대로 담겨 round-trip.
+ *   - `'raw'`: `value` 는 **문자열만** 허용 — 추가 JSON 인코딩 없이 불투명 문자열로 저장/복원.
+ *   두 모드 모두 파일은 JSON envelope 라 TTL 메타데이터가 일관되게 동작한다.
+ *
+ * # 미지원 옵션 (명시 — silent no-op 금지)
+ *   `gracefulErrors`(에러 삼킴 금지), `concurrencyLimit`(atomic rename 이 동시쓰기 안전성을 이미
+ *   보장) 은 채택하지 않는다. 알 수 없는 옵션은 `adapter.invalid_option` throw(fail-fast) —
+ *   File 은 옵션을 흡수할 하위 드라이버가 없어 오타가 조용히 무시되면 안 된다.
+ *
+ * # 설정 (services.caches.<key>) — ADR-111
+ *   ```js
+ *   services: {
+ *     caches: {
+ *       local: {
+ *         driver: 'file',
+ *         basePath: '/var/cache/mega',          // 필수 (별칭 dir 도 허용, ADR-082 정합)
+ *         options: { serializer: 'json', extension: '.json' },
+ *       },
+ *     },
+ *   }
+ *   ```
+ *
+ * @module adapters/file-adapter
+ */
+import { mkdir, writeFile, readFile, rename, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+import { MegaValidationError } from '../errors/http-errors.js'
+import { MegaCacheAdapter } from './mega-cache-adapter.js'
+import * as Registry from './registry.js'
+
+/** envelope 스키마 버전 — 포맷 변경 시 마이그레이션 분기용. */
+const ENVELOPE_VERSION = 1
+
+/** 허용 options 키 (그 외는 fail-fast throw). */
+const KNOWN_OPTIONS = new Set(['serializer', 'extension'])
+
+/**
+ * @typedef {object} FileConfig
+ * @property {string} [driver] - 'file' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} [basePath] - 캐시 파일 저장 디렉토리 (필수).
+ * @property {string} [dir] - `basePath` 의 별칭 (ADR-082 정합, 하위 호환).
+ * @property {{ serializer?: 'json' | 'raw', extension?: string }} [options]
+ */
+
+/**
+ * @typedef {object} CacheEnvelope - 디스크에 저장되는 단일 파일 포맷.
+ * @property {number} v - 스키마 버전.
+ * @property {string} key - 원본 캐시 key (디버깅용 — 파일명은 해시라 역추적 불가).
+ * @property {any} value - 저장 값(serializer='raw' 면 문자열).
+ * @property {number | null} expiresAt - 만료 epoch ms (무한이면 null).
+ */
+
+export class MegaFileAdapter extends MegaCacheAdapter {
+  /** @type {string} 캐시 디렉토리 절대/상대 경로. */
+  #basePath
+  /** @type {'json' | 'raw'} */
+  #serializer
+  /** @type {string} 파일 확장자 (예 '.json'). */
+  #extension
+
+  /**
+   * @param {FileConfig} [config] - services.caches.<key> 설정.
+   * @throws {MegaValidationError} `adapter.basepath_required` - basePath/dir 누락.
+   * @throws {MegaValidationError} `adapter.invalid_option` - 옵션 타입/미지원 키 오류.
+   */
+  constructor(config = /** @type {any} */ ({})) {
+    super(config)
+
+    // basePath 필수 (dir 별칭 허용 — ADR-082 가 'dir' 로 스케치했으므로 하위 호환).
+    const basePath = config.basePath ?? config.dir
+    if (typeof basePath !== 'string' || basePath.length === 0) {
+      throw new MegaValidationError(
+        'adapter.basepath_required',
+        'file: "basePath" (or alias "dir") is required — the directory to store cache files (e.g. "/var/cache/mega").',
+        { details: { driver: 'file', basePath: basePath ?? null } },
+      )
+    }
+    this.#basePath = basePath
+
+    const options = config.options ?? {}
+    if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+      throw new MegaValidationError('adapter.invalid_option', 'file "options" must be a plain object.', {
+        details: { driver: 'file', type: Array.isArray(options) ? 'array' : options === null ? 'null' : typeof options },
+      })
+    }
+    // 알 수 없는 옵션 fail-fast — File 은 옵션을 흡수할 하위 드라이버가 없다.
+    for (const k of Object.keys(options)) {
+      if (!KNOWN_OPTIONS.has(k)) {
+        throw new MegaValidationError('adapter.invalid_option', `file: unknown option "${k}". Known: ${[...KNOWN_OPTIONS].join(', ')}.`, {
+          details: { driver: 'file', option: k },
+        })
+      }
+    }
+
+    const serializer = options.serializer ?? 'json'
+    if (serializer !== 'json' && serializer !== 'raw') {
+      throw new MegaValidationError('adapter.invalid_option', `file "serializer" must be 'json' or 'raw' (got "${serializer}").`, {
+        details: { driver: 'file', option: 'serializer', value: serializer },
+      })
+    }
+    this.#serializer = serializer
+
+    const extension = options.extension ?? '.json'
+    if (typeof extension !== 'string' || extension.length === 0) {
+      throw new MegaValidationError('adapter.invalid_option', 'file "extension" must be a non-empty string (e.g. ".json").', {
+        details: { driver: 'file', option: 'extension', value: extension },
+      })
+    }
+    this.#extension = extension
+  }
+
+  /**
+   * 캐시 디렉토리 보장 (`mkdir -p`). 이미 있으면 no-op.
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _connect() {
+    await mkdir(this.#basePath, { recursive: true })
+  }
+
+  /**
+   * no-op — 파일시스템은 연결/해제 개념이 없다(베이스 디폴트와 동일하지만 의도를 명시).
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _disconnect() {}
+
+  /**
+   * raw "디렉토리 핸들" (ADR-009). 파일 어댑터는 native driver 가 없어 basePath 정보를 노출한다.
+   * @protected
+   * @returns {{ basePath: string }}
+   */
+  _native() {
+    return { basePath: this.#basePath }
+  }
+
+  /**
+   * 헬스 체크 — basePath 에 probe 파일을 write→read→unlink 해 실제 읽기/쓰기 가능 확인
+   * (베이스 디폴트는 상태만 반영). 실패는 throw 없이 `ok:false` + 사유(베이스 계약).
+   *
+   * @returns {Promise<{ ok: boolean, driver: 'file', state: string, basePath?: string, error?: string }>}
+   */
+  async healthCheck() {
+    if (this.state !== 'connected') {
+      return { ok: false, driver: 'file', state: this.state }
+    }
+    const probe = join(this.#basePath, `.health-${randomUUID()}`)
+    try {
+      await writeFile(probe, 'ok', 'utf8')
+      const back = await readFile(probe, 'utf8')
+      await unlink(probe)
+      return { ok: back === 'ok', driver: 'file', state: this.state, basePath: this.#basePath }
+    } catch (err) {
+      // probe 실패 시 잔여 파일 정리(존재하면) — 정리 실패는 비치명적.
+      await unlink(probe).catch(() => {})
+      return {
+        ok: false,
+        driver: 'file',
+        state: this.state,
+        basePath: this.#basePath,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+
+  /**
+   * 누적 통계 + file 특화(basePath/serializer/extension).
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, basePath: string, serializer: string, extension: string }}
+   */
+  getStats() {
+    return {
+      ...super.getStats(),
+      driver: 'file',
+      basePath: this.#basePath,
+      serializer: this.#serializer,
+      extension: this.#extension,
+    }
+  }
+
+  /**
+   * 캐시 key → 디스크 파일 경로. key 를 SHA-256 hex 로 해싱해 경로 안전 파일명으로 만든다(모듈 docstring).
+   * @param {string} key @returns {string}
+   */
+  #pathFor(key) {
+    const hashed = createHash('sha256').update(key, 'utf8').digest('hex')
+    return join(this.#basePath, hashed + this.#extension)
+  }
+
+  /**
+   * envelope 를 atomic 하게 기록 — temp 파일에 쓴 뒤 `rename` 으로 교체(반쯤 써진 파일 노출 방지).
+   * temp 는 같은 디렉토리에 둬야 rename 이 같은 파일시스템 내에서 원자적으로 동작한다.
+   * @param {string} finalPath @param {CacheEnvelope} envelope @returns {Promise<void>}
+   */
+  async #atomicWrite(finalPath, envelope) {
+    const tmp = `${finalPath}.tmp-${randomUUID()}`
+    try {
+      await writeFile(tmp, JSON.stringify(envelope), 'utf8')
+      await rename(tmp, finalPath)
+    } catch (err) {
+      // rename 전 실패 시 temp 잔여 정리 — 정리 실패는 원본 에러를 가리지 않게 격리.
+      await unlink(tmp).catch(() => {})
+      throw err
+    }
+  }
+
+  /**
+   * 키 조회. 없거나 만료면 `null`(만료 파일은 lazy 삭제). serializer='raw' 면 문자열로 복원.
+   * @param {string} key
+   * @returns {Promise<any>}
+   */
+  async get(key) {
+    return this._instrument('get', { key }, async () => {
+      const path = this.#pathFor(key)
+      let raw
+      try {
+        raw = await readFile(path, 'utf8')
+      } catch (err) {
+        // 파일 없음(ENOENT) = cache miss(정상). 그 외 I/O 에러는 진짜 실패라 전파(무차별 삼킴 X).
+        if (/** @type {any} */ (err)?.code === 'ENOENT') return null
+        throw err
+      }
+      /** @type {CacheEnvelope} */
+      const env = JSON.parse(raw)
+      if (env.expiresAt !== null && Date.now() > env.expiresAt) {
+        // 만료 — lazy 삭제 후 miss. 삭제 실패는 비치명적(다음 set/get 이 재시도).
+        await unlink(path).catch(() => {})
+        return null
+      }
+      return env.value
+    })
+  }
+
+  /**
+   * 키 저장. `ttl`(초) 지정 시 `expiresAt = now + ttl*1000`, 없으면 무한(null).
+   * serializer='raw' 면 value 는 문자열이어야 한다(아니면 `cache.unserializable`).
+   *
+   * @param {string} key
+   * @param {any} value
+   * @param {{ ttl?: number }} [opts] - `ttl` 초 단위 양의 정수(베이스 `_assertTtl` 검증).
+   * @returns {Promise<void>}
+   */
+  async set(key, value, { ttl } = {}) {
+    // TTL·직렬화 검증은 의도적으로 `_instrument` **밖**(fail-fast). 잘못된 인자는 디스크 I/O·hook·stats
+    // 이전에 거부 — 프로그래밍 오류를 instrumented 호출 통계에 섞지 않는다(L-1, redis 어댑터와 동일 결정).
+    this._assertTtl(ttl)
+    if (this.#serializer === 'raw' && typeof value !== 'string') {
+      throw new MegaValidationError('cache.unserializable', `file set("${key}"): serializer='raw' requires a string value (got ${typeof value}).`, {
+        details: { key, type: typeof value, serializer: 'raw' },
+      })
+    }
+    if (this.#serializer === 'json') {
+      // JSON 모드 — 직렬화 불가 값(undefined/함수/심볼)은 명시 거부(silent 손상 X).
+      const probe = JSON.stringify(value)
+      if (probe === undefined) {
+        throw new MegaValidationError('cache.unserializable', `file set("${key}"): value is not JSON-serializable (undefined/function/symbol).`, {
+          details: { key, type: typeof value },
+        })
+      }
+    }
+    return this._instrument('set', { key, ttl }, async () => {
+      /** @type {CacheEnvelope} */
+      const envelope = {
+        v: ENVELOPE_VERSION,
+        key,
+        value,
+        expiresAt: ttl !== undefined ? Date.now() + ttl * 1000 : null,
+      }
+      await this.#atomicWrite(this.#pathFor(key), envelope)
+    })
+  }
+
+  /**
+   * 키 삭제. 없는 키 삭제는 에러 아님(idempotent — ENOENT 흡수).
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async del(key) {
+    return this._instrument('del', { key }, async () => {
+      try {
+        await unlink(this.#pathFor(key))
+      } catch (err) {
+        // ENOENT = 이미 없음(del idempotent — 정상). 그 외 I/O 에러는 전파(무차별 삼킴 X).
+        if (/** @type {any} */ (err)?.code !== 'ENOENT') throw err
+      }
+    })
+  }
+
+  /**
+   * 키 존재 여부 (Boolean — `has*`, ADR-036). 만료된 키는 없는 것으로 취급(+lazy 삭제).
+   *
+   * `get()` 과 동일하게 **단일 readFile** 로 읽고 ENOENT 를 miss(=false)로 흡수한다(L-3). 이전엔
+   * `access()`+`readFile()` 2회 I/O 였는데, 그 사이 파일이 사라지는 TOCTOU 레이스 + 불필요한
+   * 이중 I/O 가 있었다 — get 패턴으로 통일해 둘 다 제거.
+   * @param {string} key
+   * @returns {Promise<boolean>}
+   */
+  async has(key) {
+    return this._instrument('has', { key }, async () => {
+      const path = this.#pathFor(key)
+      let raw
+      try {
+        raw = await readFile(path, 'utf8')
+      } catch (err) {
+        // 파일 없음(ENOENT) = 없음(false). 그 외 I/O 에러는 전파(무차별 삼킴 X).
+        if (/** @type {any} */ (err)?.code === 'ENOENT') return false
+        throw err
+      }
+      // 존재하더라도 만료면 false — get 과 동일 의미 유지(+lazy 삭제).
+      const env = /** @type {CacheEnvelope} */ (JSON.parse(raw))
+      if (env.expiresAt !== null && Date.now() > env.expiresAt) {
+        await unlink(path).catch(() => {})
+        return false
+      }
+      return true
+    })
+  }
+}
+
+// 빌트인 driver 자기등록 (ADR-044) — 신규 의존성 0이라 import 부작용 없음.
+Registry.register('file', MegaFileAdapter)