mega-framework 0.1.0

package/src/adapters/file-session-adapter.js

@@ -0,0 +1,363 @@
+// @ts-check
+/**
+ * MegaFileSessionAdapter — 로컬 파일시스템 세션 스토어 (Node `fs`/`path`/`crypto` 만, ADR-129).
+ *
+ * `MegaSessionAdapter`(ADR-046/027) 의 첫 구체 중 하나. dev / 단일 인스턴스 / Redis 없는 환경에서
+ * 세션 레코드를 로컬 파일로 보관한다 — driver 한 줄만 'redis' 로 바꾸면 분산 환경 전환(ADR-046).
+ * **신규 의존성 0** (`node:fs/promises`/`node:path`/`node:crypto` 표준만).
+ *
+ * # 표준 표면 (MegaSessionAdapter 상속)
+ *   - `_connect()`    — `fs.mkdir(basePath, { recursive: true })` 로 디렉토리 보장(+옵션 cleanup 타이머).
+ *   - `_disconnect()` — cleanup 타이머 정지(파일시스템은 close 개념 없음).
+ *   - `_native()`     — `{ basePath }` (raw "디렉토리 핸들" 개념, ADR-009).
+ *   - `healthCheck()` — basePath 에 probe write→read→unlink 로 실제 읽기/쓰기 가능 확인.
+ *   - `load/save/destroy/touch/cleanup` — 단일 JSON envelope 파일 + TTL 메타데이터(아래).
+ *
+ * # 저장 포맷 — 단일 envelope 파일 (`MegaFileAdapter` 와 동일 전략, ADR-111)
+ *   `{ v:1, sid, data, expiresAt }` 를 한 파일에 묶는다. `expiresAt` 은 epoch ms(무한이면 null —
+ *   세션은 항상 TTL 이 있어 실사용에선 null 이 거의 없다). 쓰기는 **temp write 후 `rename`** 으로
+ *   atomic — 동시 write 가 반쯤 써진 파일을 읽는 일이 없다(POSIX rename 은 같은 파일시스템에서 원자적).
+ *
+ * # 파일명 — sid 의 SHA-256 hex (경로 안전)
+ *   sid 는 ULID(Crockford base32, 경로 안전)지만, 일관성·방어를 위해 SHA-256 hex(64자)로 해싱해
+ *   파일명으로 쓴다(`MegaFileAdapter` 와 동일 — 경로 탈출 불가). 원본 sid 는 envelope 에 보관(디버깅용).
+ *
+ * # cleanup (ADR-046 — "file 모드 cleanup 은 mega scheduler 가 자동 등록")
+ *   `cleanup()` 은 basePath 를 스캔해 만료 파일을 삭제하고 삭제 개수를 반환한다. 멀티 인스턴스는
+ *   `SessionCleanupSchedule`(MegaSchedule, src/core/session-cleanup-schedule.js)을 `mega scheduler` 로
+ *   분산 등록한다. 단일 인스턴스 dev 편의로 `cleanupIntervalMs`(옵션) 가 있으면 내부 unref 타이머가
+ *   주기적으로 `cleanup()` 을 돌린다(프로세스를 살려두지 않음).
+ *
+ * # 설정
+ *   ```js
+ *   session: {
+ *     store: { driver: 'file', basePath: '/var/lib/mega/sessions', cleanupIntervalMs: 3600000 },
+ *     ttlMs: 86400000,   // save() 가 적용할 기본 TTL (미들웨어가 store 생성 시 주입)
+ *   }
+ *   ```
+ *
+ * @module adapters/file-session-adapter
+ */
+import { mkdir, writeFile, readFile, rename, unlink, readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+import { MegaValidationError } from '../errors/http-errors.js'
+import { MegaSessionAdapter } from './mega-session-adapter.js'
+
+/** envelope 스키마 버전 — 포맷 변경 시 마이그레이션 분기용. */
+const ENVELOPE_VERSION = 1
+
+/** save() 가 store 기본 TTL 미설정 시 적용할 폴백 (24시간, ms). */
+const DEFAULT_TTL_MS = 86_400_000
+
+/**
+ * @typedef {object} FileSessionConfig
+ * @property {string} [driver] - 'file' (팩토리가 사용 — 어댑터는 무시).
+ * @property {string} [basePath] - 세션 파일 저장 디렉토리 (필수).
+ * @property {string} [dir] - `basePath` 의 별칭 (하위 호환).
+ * @property {number} [ttlMs] - save() 가 적용할 기본 TTL(ms). 미지정 시 24시간.
+ * @property {number} [cleanupIntervalMs] - 내부 cleanup 타이머 주기(ms). 미지정/0 이면 타이머 없음(단일 dev 편의).
+ * @property {string} [extension] - 파일 확장자 (기본 '.json').
+ */
+
+/**
+ * @typedef {object} SessionEnvelope - 디스크에 저장되는 단일 파일 포맷.
+ * @property {number} v - 스키마 버전.
+ * @property {string} sid - 원본 세션 id(ULID — 파일명은 해시라 역추적 불가).
+ * @property {object} data - 세션 레코드.
+ * @property {number | null} expiresAt - 만료 epoch ms (무한이면 null).
+ */
+
+export class MegaFileSessionAdapter extends MegaSessionAdapter {
+  /** @type {string} 세션 디렉토리 경로. */
+  #basePath
+  /** @type {number} save() 기본 TTL(ms). */
+  #ttlMs
+  /** @type {number} 내부 cleanup 타이머 주기(ms). 0=off. */
+  #cleanupIntervalMs
+  /** @type {string} 파일 확장자. */
+  #extension
+  /** @type {NodeJS.Timeout | null} 내부 cleanup 타이머(있으면). */
+  #timer = null
+
+  /**
+   * @param {FileSessionConfig} [config]
+   * @throws {MegaValidationError} `session.basepath_required` - basePath/dir 누락.
+   * @throws {MegaValidationError} `session.invalid_option` - 옵션 타입 오류.
+   */
+  constructor(config = /** @type {any} */ ({})) {
+    super(config)
+
+    const basePath = config.basePath ?? config.dir
+    if (typeof basePath !== 'string' || basePath.length === 0) {
+      throw new MegaValidationError(
+        'session.basepath_required',
+        'file session store: "basePath" (or alias "dir") is required — the directory to store session files (e.g. "/var/lib/mega/sessions").',
+        { details: { driver: 'file', basePath: basePath ?? null } },
+      )
+    }
+    this.#basePath = basePath
+
+    this.#ttlMs = this.#assertPositiveInt('ttlMs', config.ttlMs, DEFAULT_TTL_MS)
+    this.#cleanupIntervalMs = this.#assertNonNegativeInt('cleanupIntervalMs', config.cleanupIntervalMs, 0)
+
+    const extension = config.extension ?? '.json'
+    if (typeof extension !== 'string' || extension.length === 0) {
+      throw new MegaValidationError('session.invalid_option', 'file session "extension" must be a non-empty string (e.g. ".json").', {
+        details: { driver: 'file', option: 'extension', value: extension },
+      })
+    }
+    this.#extension = extension
+  }
+
+  /**
+   * 양의 정수 검증 헬퍼 (미지정 시 fallback). 잘못된 값은 fail-fast throw.
+   * @param {string} name @param {number | undefined} value @param {number} fallback @returns {number}
+   */
+  #assertPositiveInt(name, value, fallback) {
+    if (value === undefined) return fallback
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new MegaValidationError('session.invalid_option', `file session "${name}" must be a positive integer (ms). Got: ${value}.`, {
+        details: { driver: 'file', option: name, value },
+      })
+    }
+    return value
+  }
+
+  /**
+   * 음이 아닌 정수 검증 헬퍼 (0 허용 — 타이머 off 의미). 잘못된 값은 fail-fast throw.
+   * @param {string} name @param {number | undefined} value @param {number} fallback @returns {number}
+   */
+  #assertNonNegativeInt(name, value, fallback) {
+    if (value === undefined) return fallback
+    if (!Number.isInteger(value) || value < 0) {
+      throw new MegaValidationError('session.invalid_option', `file session "${name}" must be a non-negative integer (ms, 0=off). Got: ${value}.`, {
+        details: { driver: 'file', option: name, value },
+      })
+    }
+    return value
+  }
+
+  /**
+   * 세션 디렉토리 보장 (`mkdir -p`) + (옵션) 내부 cleanup 타이머 시작.
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _connect() {
+    await mkdir(this.#basePath, { recursive: true })
+    if (this.#cleanupIntervalMs > 0 && this.#timer === null) {
+      // 단일 dev 편의용 주기 cleanup. unref() 로 이 타이머가 프로세스 종료를 막지 않게 한다.
+      this.#timer = setInterval(() => {
+        // 타이머 cleanup 실패는 비치명적 — 다음 주기에 재시도. console.warn 로 가시화.
+        this.cleanup().catch((err) => {
+          console.warn('[MegaFileSessionAdapter] periodic cleanup() failed (will retry next interval):', err)
+        })
+      }, this.#cleanupIntervalMs)
+      this.#timer.unref?.()
+    }
+  }
+
+  /**
+   * 내부 cleanup 타이머 정지 (파일시스템은 연결/해제 개념 없음).
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _disconnect() {
+    if (this.#timer !== null) {
+      clearInterval(this.#timer)
+      this.#timer = null
+    }
+  }
+
+  /**
+   * raw "디렉토리 핸들" (ADR-009).
+   * @protected
+   * @returns {{ basePath: string }}
+   */
+  _native() {
+    return { basePath: this.#basePath }
+  }
+
+  /**
+   * 헬스 체크 — basePath 에 probe write→read→unlink 로 실제 읽기/쓰기 가능 확인.
+   * @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) {
+      await unlink(probe).catch(() => {})
+      return { ok: false, driver: 'file', state: this.state, basePath: this.#basePath, error: err instanceof Error ? err.message : String(err) }
+    }
+  }
+
+  /**
+   * 누적 통계 + file 세션 특화.
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, basePath: string, ttlMs: number }}
+   */
+  getStats() {
+    return { ...super.getStats(), driver: 'file', basePath: this.#basePath, ttlMs: this.#ttlMs }
+  }
+
+  /**
+   * sid → 디스크 파일 경로. sid 를 SHA-256 hex 로 해싱해 경로 안전 파일명으로(모듈 docstring).
+   * @param {string} sid @returns {string}
+   */
+  #pathFor(sid) {
+    const hashed = createHash('sha256').update(sid, 'utf8').digest('hex')
+    return join(this.#basePath, hashed + this.#extension)
+  }
+
+  /**
+   * envelope 를 atomic 하게 기록 — temp write 후 `rename`(반쯤 써진 파일 노출 방지).
+   * @param {string} finalPath @param {SessionEnvelope} 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) {
+      await unlink(tmp).catch(() => {})
+      throw err
+    }
+  }
+
+  /**
+   * 세션 조회. 없거나 만료면 `null`(만료 파일은 lazy 삭제).
+   * @param {string} sid
+   * @returns {Promise<object | null>}
+   */
+  async load(sid) {
+    return this._instrument('load', { sid }, async () => {
+      const path = this.#pathFor(sid)
+      let raw
+      try {
+        raw = await readFile(path, 'utf8')
+      } catch (err) {
+        // 파일 없음(ENOENT) = 세션 없음(정상). 그 외 I/O 에러는 전파(무차별 삼킴 X).
+        if (/** @type {any} */ (err)?.code === 'ENOENT') return null
+        throw err
+      }
+      /** @type {SessionEnvelope} */
+      const env = JSON.parse(raw)
+      if (env.expiresAt !== null && Date.now() > env.expiresAt) {
+        await unlink(path).catch(() => {}) // 만료 lazy 삭제(실패는 비치명적, 다음 cleanup 재시도).
+        return null
+      }
+      return env.data
+    })
+  }
+
+  /**
+   * 세션 저장 — store 기본 TTL(`ttlMs`)로 `expiresAt` 설정.
+   * @param {string} sid
+   * @param {object} record - 세션 레코드(JSON 직렬화 가능).
+   * @returns {Promise<void>}
+   */
+  async save(sid, record) {
+    return this._instrument('save', { sid }, async () => {
+      /** @type {SessionEnvelope} */
+      const envelope = { v: ENVELOPE_VERSION, sid, data: record ?? {}, expiresAt: Date.now() + this.#ttlMs }
+      await this.#atomicWrite(this.#pathFor(sid), envelope)
+    })
+  }
+
+  /**
+   * 세션 삭제. 없는 세션 삭제는 에러 아님(idempotent — ENOENT 흡수).
+   * @param {string} sid
+   * @returns {Promise<void>}
+   */
+  async destroy(sid) {
+    return this._instrument('destroy', { sid }, async () => {
+      try {
+        await unlink(this.#pathFor(sid))
+      } catch (err) {
+        if (/** @type {any} */ (err)?.code !== 'ENOENT') throw err // ENOENT=이미 없음(정상).
+      }
+    })
+  }
+
+  /**
+   * rolling TTL 갱신(ADR-046) — 기존 envelope 의 `expiresAt` 만 `now + ttlMs` 로 갱신. 세션이 없으면
+   * no-op(만료/삭제된 세션을 touch 가 되살리지 않음 — 데이터 없는 빈 세션 부활 방지).
+   * @param {string} sid
+   * @param {number} ttlMs - 갱신할 TTL(ms).
+   * @returns {Promise<void>}
+   */
+  async touch(sid, ttlMs) {
+    return this._instrument('touch', { sid, ttlMs }, async () => {
+      const path = this.#pathFor(sid)
+      let raw
+      try {
+        raw = await readFile(path, 'utf8')
+      } catch (err) {
+        if (/** @type {any} */ (err)?.code === 'ENOENT') return // 없는 세션 touch = no-op.
+        throw err
+      }
+      /** @type {SessionEnvelope} */
+      const env = JSON.parse(raw)
+      // 이미 만료된 세션은 touch 로 되살리지 않고 lazy 삭제(load 와 동일 의미).
+      if (env.expiresAt !== null && Date.now() > env.expiresAt) {
+        await unlink(path).catch(() => {})
+        return
+      }
+      env.expiresAt = Date.now() + ttlMs
+      await this.#atomicWrite(path, env)
+    })
+  }
+
+  /**
+   * 만료 세션 파일 일괄 정리(ADR-046). basePath 를 스캔해 `expiresAt` 이 지난 파일을 삭제한다.
+   * 삭제 개수를 반환한다. 읽기 불가/JSON 깨진 파일은 건너뛴다(개별 실패가 전체 cleanup 을 막지 않음).
+   *
+   * @returns {Promise<number>} 삭제된 세션 파일 수.
+   */
+  async cleanup() {
+    return this._instrument('cleanup', {}, async () => {
+      let names
+      try {
+        names = await readdir(this.#basePath)
+      } catch (err) {
+        if (/** @type {any} */ (err)?.code === 'ENOENT') return 0 // 디렉토리 없음 = 정리할 것 없음.
+        throw err
+      }
+      const now = Date.now()
+      let removed = 0
+      for (const name of names) {
+        if (!name.endsWith(this.#extension)) continue // tmp/probe/그 외 파일 건너뜀.
+        const path = join(this.#basePath, name)
+        let raw
+        try {
+          raw = await readFile(path, 'utf8')
+        } catch {
+          // 읽는 사이 사라졌거나 권한 문제 — 개별 파일 실패는 cleanup 전체를 막지 않는다(스캔 best-effort).
+          continue
+        }
+        let env
+        try {
+          env = /** @type {SessionEnvelope} */ (JSON.parse(raw))
+        } catch {
+          continue // 손상 파일은 건드리지 않음(수동 점검 대상).
+        }
+        if (env.expiresAt !== null && now > env.expiresAt) {
+          // unlink 실패(레이스)는 비치명적 — 다음 주기 재시도(삭제 카운트엔 미반영).
+          try {
+            await unlink(path)
+            removed += 1
+          } catch {
+            /* 레이스로 이미 삭제됨 등 — 다음 주기 재시도. */
+          }
+        }
+      }
+      return removed
+    })
+  }
+}

package/src/adapters/index.js

@@ -0,0 +1,38 @@
+// @ts-check
+/**
+ * adapters 배럴 — 어댑터 베이스 트리 + 드라이버 레지스트리 (ADR-027/044/045).
+ *
+ * 빌트인 구체 어댑터(Postgres/Mongo/Maria/Sqlite/Redis/File/Nats/Redlock)는 import 시
+ * 추가되며, 각자 본 배럴의 레지스트리(`MegaAdapterRegistry.register`)에 자기 자신을 등록한다.
+ *
+ * @module adapters
+ */
+export { MegaAdapter } from './mega-adapter.js'
+export { MegaDbAdapter } from './mega-db-adapter.js'
+export { MegaCacheAdapter } from './mega-cache-adapter.js'
+export { MegaBusAdapter } from './mega-bus-adapter.js'
+export { MegaLockAdapter } from './mega-lock-adapter.js'
+export { MegaLogSinkAdapter } from './mega-log-sink-adapter.js'
+export { MegaSessionAdapter } from './mega-session-adapter.js'
+
+// 빌트인 구체 어댑터 — import 시 레지스트리에 자기등록(ADR-044).
+// driver native binding/모듈 은 _connect() lazy import 까지 로드 안 됨 → 미사용 환경 안전.
+export { MegaSqliteAdapter } from './sqlite-adapter.js'
+export { MegaPostgresAdapter } from './postgres-adapter.js'
+export { MegaMariaAdapter } from './maria-adapter.js'
+export { MegaMongoAdapter } from './mongo-adapter.js'
+export { MegaRedisAdapter } from './redis-adapter.js'
+export { MegaFileAdapter } from './file-adapter.js'
+export { MegaNatsAdapter } from './nats-adapter.js'
+export { MegaRedlockAdapter } from './redlock-adapter.js'
+
+// 세션 스토어 어댑터 (ADR-129) — 공유 driver 레지스트리 미사용(createSessionStore 전용 팩토리).
+export { MegaFileSessionAdapter } from './file-session-adapter.js'
+export { MegaRedisSessionAdapter } from './redis-session-adapter.js'
+
+// 드라이버 레지스트리 (ADR-044) — 네임스페이스로 노출 (MegaHealth 패턴 정합).
+export * as MegaAdapterRegistry from './registry.js'
+export { BUILTIN_DRIVERS } from './registry.js'
+
+// 전역 어댑터 인스턴스 매니저 (ADR-102) — 글로벌 공유 인스턴스 소유·connect/disconnect.
+export * as MegaAdapterManager from './adapter-manager.js'