mega-framework 0.1.0

package/src/adapters/postgres-adapter.js

@@ -0,0 +1,341 @@
+// @ts-check
+/**
+ * MegaPostgresAdapter — PostgreSQL 어댑터 (`pg` = node-postgres 래퍼, ADR-106).
+ *
+ * Sqlite(ADR-105)에 이어 두 번째 SQL 어댑터이자 **첫 docker 실 컨테이너 통합** 대상.
+ * Sqlite 의 manual 트랜잭션 패턴을 잇되, Postgres 가 SAVEPOINT 를 지원하므로 nested 정책이
+ * Sqlite 의 "재진입 거부" 와 분기한다(아래 "트랜잭션 패턴" 참조).
+ *
+ * # 표준 표면 (MegaDbAdapter 상속)
+ *   - `_connect()`   — `new Pool(cfg)` (driver 는 connect 시점 lazy import) + `SELECT 1` 검증.
+ *   - `_disconnect()`— `pool.end()` (모든 클라이언트 drain + 종료).
+ *   - `_native()`    — `pg` Pool 인스턴스(raw handle, ADR-009). `MegaModel.db` 가 노출.
+ *   - `healthCheck()`— `pool.query('SELECT 1')` 실행으로 실제 응답성 확인.
+ *   - `getStats()`   — 베이스 stats + 풀 통계(total/idle/waiting).
+ *   - `withTransaction(fn)` — 명시적 트랜잭션 경계 (ADR-010). 아래 "트랜잭션 패턴" 참조.
+ *
+ * # 트랜잭션 패턴 — 풀 클라이언트 1개 + manual `BEGIN/COMMIT/ROLLBACK`
+ *   `pool.connect()` 으로 클라이언트 1개를 잡아 그 위에서 `BEGIN → fn(client) → COMMIT`(성공) /
+ *   `ROLLBACK`(실패) 한다. `fn` 에는 **트랜잭션 컨텍스트 클라이언트**(같은 connection)를 넘겨,
+ *   사용자가 그 client 로 쿼리하면 전부 한 트랜잭션에 묶인다. `client.release()` 는 finally 에서
+ *   반드시 호출해 풀로 반납한다(누수 방지). ROLLBACK 자체 실패(드묾)는 원본 에러를 가리지 않도록
+ *   격리 후 원본 re-throw(ADR-010).
+ *
+ * # nested 트랜잭션 정책 — SAVEPOINT (Sqlite 와 분기, ADR-106)
+ *   Sqlite(단일 연결, ADR-105)는 nested 를 **거부**하지만, Postgres 는 SAVEPOINT 로 부분 롤백을
+ *   지원한다. `withTransaction` 안에서 `withTransaction` 을 다시 부르면(nested), 새 풀 연결을 잡지
+ *   않고 **같은 클라이언트에 `SAVEPOINT sp_<depth>`** 를 건다 — 성공 시 `RELEASE SAVEPOINT`,
+ *   실패 시 `ROLLBACK TO SAVEPOINT` 후 re-throw 하여 바깥 트랜잭션은 살린다.
+ *
+ *   **컨텍스트 추적은 `AsyncLocalStorage`** 로 한다(인스턴스 필드 카운터 X). store 에 `{ client, depth }`
+ *   를 담고 nesting 마다 새 store 로 `als.run` 격리하므로, **동시 트랜잭션**(서로 다른 풀 연결을 잡는
+ *   top-level 호출)은 각자 독립 store 를 가져 depth 가 섞이지 않는다(async race-free). 만약 인스턴스
+ *   필드로 depth 를 셌다면 두 트랜잭션의 `await` 인터리빙에서 카운터가 오염됐을 것이다 — ALS 가 그
+ *   문제를 구조적으로 제거한다. 별도 풀 연결을 잡지 않으므로 `max:1` 풀에서도 nested 가 deadlock 되지
+ *   않는다.
+ *
+ *   ⚠️ **"race-free" 의 경계**: 위 race-free 는 **서로 다른 top-level 호출 사이의
+ *   동시성**에만 해당한다. **단일 트랜잭션 내부**에서 sibling nested 를 `Promise.all` 등으로 **병렬**
+ *   실행하는 것은 **미지원**이다 — 같은 클라이언트(단일 connection) 위에 SAVEPOINT 이름이 `depth` 로만
+ *   결정되므로 두 sibling 이 동시에 `depth+1` 을 보면 둘 다 `sp_1` 을 만들어 충돌하고, 애초에 pg 단일
+ *   connection 은 쿼리를 직렬화하므로 병렬 이득도 없다. nested 는 **순차 호출**(await 로 한 번에 하나)할 것.
+ *
+ * # 설정 (services.databases.<key>) — 통합 옵션 구조 (ADR-109)
+ *   ```js
+ *   services: {
+ *     databases: {
+ *       primary: {
+ *         driver: 'postgres',
+ *         // (a) 연결 — url 또는 discrete (상호 배타)
+ *         url: 'postgres://user:pw@host:5432/db',           // 또는 ↓
+ *         host: 'localhost', port: 5432, user: 'mega', password: '...', database: 'mega_test',
+ *         // (b) pool — 공통 풀 인터페이스 (드라이버 키로 매핑)
+ *         pool: { min: 0, max: 10, idleTimeoutMs: 10000, acquireTimeoutMs: 0, maxLifetimeMs: 0 },
+ *         // (c) options — pg 특화 passthrough (그대로 pg.Pool 에 전달)
+ *         options: { ssl: false, statement_timeout: 30000, application_name: 'mega', keepAlive: true },
+ *       },
+ *     },
+ *   }
+ *   ```
+ *   `url`(또는 deprecated 별칭 `connectionString`) **XOR** discrete 연결필드(host/port/user/password/
+ *   database). 둘 다 없으면 `adapter.connection_required`, 동시 지정은 `adapter.connection_conflict`
+ *   (ADR-109). `pool`/`options` 는 어느 연결 모드와도 조합 가능. pool 매핑: min→min, max→max,
+ *   idleTimeoutMs→idleTimeoutMillis, acquireTimeoutMs→connectionTimeoutMillis, maxLifetimeMs→
+ *   maxLifetimeSeconds(ms÷1000). 비밀번호·url 은 healthCheck/getStats/에러 details 에 절대 노출하지
+ *   않는다(시크릿 마스킹 정합).
+ *
+ * @module adapters/postgres-adapter
+ */
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { MegaDbAdapter } from './mega-db-adapter.js'
+import { resolveConnection, normalizePool, assertPlainObject, PG_POOL_SPEC } from './adapter-options.js'
+import * as Registry from './registry.js'
+
+/**
+ * @typedef {object} PostgresConfig
+ * @property {string} [driver] - 'postgres' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} [url] - `postgres://user:pw@host:port/db` (discrete 필드와 배타).
+ * @property {string} [connectionString] - `url` 의 deprecated 별칭 (하위 호환).
+ * @property {string} [host] @property {number} [port] @property {string} [user]
+ * @property {string} [password] @property {string} [database]
+ * @property {{ min?: number, max?: number, idleTimeoutMs?: number, acquireTimeoutMs?: number, maxLifetimeMs?: number }} [pool] - 공통 풀 인터페이스.
+ * @property {Record<string, any>} [options] - pg.Pool passthrough (ssl, statement_timeout, application_name, keepAlive, query_timeout, …).
+ */
+
+/**
+ * @typedef {object} PgTxContext - AsyncLocalStorage 에 담기는 트랜잭션 컨텍스트.
+ * @property {import('pg').PoolClient} client - 이 트랜잭션을 소유한 풀 클라이언트.
+ * @property {number} depth - nesting 깊이 (top-level=0, 첫 nested=1, ...).
+ */
+
+export class MegaPostgresAdapter extends MegaDbAdapter {
+  /** @type {import('pg').Pool | null} 연결된 Pool 인스턴스 (connect 후에만). */
+  #pool = null
+  /** @type {import('pg').PoolConfig} _connect 에서 `new Pool()` 에 넘길 설정 (생성자에서 구성·고정). */
+  #poolConfig
+  /**
+   * 진행 중 트랜잭션 컨텍스트 추적기. nested 호출이 같은 클라이언트를 재사용하도록 한다.
+   * 인스턴스당 1개 — 동시 top-level 트랜잭션은 각자 `run` 으로 격리된 store 를 가진다(async race-free).
+   * @type {AsyncLocalStorage<PgTxContext>}
+   */
+  #txContext = new AsyncLocalStorage()
+
+  /**
+   * @param {PostgresConfig} [config] - services.databases.<key> 설정.
+   * @throws {import('../errors/http-errors.js').MegaValidationError} `adapter.connection_required` - url·discrete 둘 다 없음.
+   * @throws {import('../errors/http-errors.js').MegaValidationError} `adapter.connection_conflict` - url + discrete 동시 지정.
+   * @throws {import('../errors/http-errors.js').MegaValidationError} `adapter.invalid_option` - 옵션 타입/범위 오류.
+   */
+  constructor(config = /** @type {any} */ ({})) {
+    super(config)
+
+    // 연결 모드(url XOR discrete) 결정 + 충돌·필수 검증 (ADR-109 공용 헬퍼).
+    const conn = resolveConnection(config, { driver: 'postgres', dbKey: 'database', dbConflictsWithUrl: true })
+    // 공통 풀 인터페이스 → pg 풀 키 매핑 + 부팅 시 fail-fast 검증.
+    const poolOpts = normalizePool(config.pool, PG_POOL_SPEC, 'postgres')
+    assertPlainObject('options', config.options, { driver: 'postgres' })
+
+    // pg.Pool 은 connectionString 과 풀 옵션을 한 객체로 받는다. undefined 키는 pg 디폴트로 떨어진다.
+    /** @type {import('pg').PoolConfig} */
+    const poolConfig = {}
+    if (conn.url !== undefined) poolConfig.connectionString = conn.url
+    if (conn.host !== undefined) poolConfig.host = conn.host
+    if (conn.port !== undefined) poolConfig.port = conn.port
+    if (conn.user !== undefined) poolConfig.user = conn.user
+    if (conn.password !== undefined) poolConfig.password = conn.password
+    if (conn.database !== undefined) poolConfig.database = conn.database
+    // options(드라이버 특화 passthrough) 먼저, pool(정규화) 나중 — 겹치면 명시 pool 인터페이스가 이긴다.
+    if (config.options !== undefined) Object.assign(poolConfig, config.options)
+    Object.assign(poolConfig, poolOpts)
+    this.#poolConfig = poolConfig
+  }
+
+  /**
+   * `pg` Pool 생성 + `SELECT 1` 로 실제 연결 검증.
+   * driver 는 **connect 시점에 lazy import** — 모듈 import(배럴 경유 자기등록)만으로는 pg 를
+   * 로드하지 않아, 본 어댑터를 안 쓰는 환경이 pg 설치를 강제받지 않는다(Sqlite 패턴 정합, ADR-105).
+   *
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _connect() {
+    const pg = await import('pg')
+    // pg 는 CJS — ESM interop 으로 named(`pg.Pool`)·default 둘 다 노출될 수 있어 방어적으로 둘 다 본다.
+    const Pool = pg.Pool ?? /** @type {any} */ (pg.default)?.Pool
+    const pool = new Pool(this.#poolConfig)
+    // connect 직후 실제 1회 쿼리로 연결 검증 — 잘못된 자격증명/호스트를 부팅 시점에 잡는다(fail-fast).
+    // 실패하면 leak 방지를 위해 pool 을 닫고 원본 에러 전파.
+    try {
+      await pool.query('SELECT 1')
+    } catch (err) {
+      try {
+        await pool.end()
+      } catch (endErr) {
+        // 검증 실패 후 정리(pool.end) 실패는 비치명적 — 원본 연결 에러가 진짜 원인.
+        console.warn('[MegaPostgresAdapter] pool.end() failed after connect validation error (original error wins):', endErr)
+      }
+      throw err
+    }
+    this.#pool = pool
+  }
+
+  /**
+   * Pool 종료(모든 클라이언트 drain + 종료). 베이스 상태 머신이 connected 상태에서만 호출 보장.
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _disconnect() {
+    if (this.#pool !== null) {
+      const pool = this.#pool
+      this.#pool = null
+      await pool.end()
+    }
+  }
+
+  /**
+   * raw Pool handle (ADR-009). `connect()` 후에만 베이스 `native` getter 가 호출한다.
+   * @protected
+   * @returns {import('pg').Pool}
+   */
+  _native() {
+    if (this.#pool === null) {
+      // 베이스 native getter 가 state 검증을 먼저 하므로 정상 경로에선 도달 안 함 — 방어.
+      return this._notImplemented('native')
+    }
+    return this.#pool
+  }
+
+  /**
+   * 헬스 체크 — 실제 `SELECT 1` 으로 응답성 확인 (베이스 디폴트는 상태만 반영).
+   * 실패는 throw 없이 `ok:false` + 사유(베이스 계약). 비밀번호/connectionString 은 노출하지 않는다.
+   *
+   * @returns {Promise<{ ok: boolean, driver: 'postgres', state: string, error?: string }>}
+   */
+  async healthCheck() {
+    if (this.state !== 'connected' || this.#pool === null) {
+      return { ok: false, driver: 'postgres', state: this.state }
+    }
+    try {
+      const res = await this.#pool.query('SELECT 1 AS ok')
+      const ok = res.rows?.[0]?.ok === 1
+      return { ok, driver: 'postgres', state: this.state }
+    } catch (err) {
+      return {
+        ok: false,
+        driver: 'postgres',
+        state: this.state,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+
+  /**
+   * 누적 통계 + 풀 통계(total/idle/waiting). 연결 전이면 풀 통계는 0.
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, pool: { total: number, idle: number, waiting: number } }}
+   */
+  getStats() {
+    const pool = this.#pool
+    return {
+      ...super.getStats(),
+      driver: 'postgres',
+      pool: {
+        total: pool?.totalCount ?? 0,
+        idle: pool?.idleCount ?? 0,
+        waiting: pool?.waitingCount ?? 0,
+      },
+    }
+  }
+
+  /**
+   * 명시적 트랜잭션 경계 (ADR-010, ADR-106). top-level 은 풀 클라이언트 1개 위 manual
+   * `BEGIN/COMMIT/ROLLBACK`, nested 는 같은 클라이언트 위 `SAVEPOINT`(모듈 docstring 참조).
+   *
+   * `fn` 은 **트랜잭션 컨텍스트 클라이언트**(pg PoolClient)를 인자로 받는다. 성공 시 COMMIT(또는
+   * RELEASE SAVEPOINT) 후 `fn` 반환값을 그대로 돌려주고, throw 시 ROLLBACK(또는 ROLLBACK TO
+   * SAVEPOINT) 후 원본 에러를 re-throw 한다.
+   *
+   * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
+   *
+   * @template T
+   * @param {(client: import('pg').PoolClient) => Promise<T> | T} fn
+   * @returns {Promise<T>}
+   */
+  async withTransaction(fn) {
+    return this._instrument('withTransaction', { table: undefined }, async () => {
+      const existing = this.#txContext.getStore()
+      // nested — 진행 중 트랜잭션이 있으면 같은 클라이언트에 SAVEPOINT 를 건다(Sqlite 와 분기).
+      if (existing !== undefined) {
+        return this.#runSavepoint(existing, fn)
+      }
+      // top-level — 풀에서 클라이언트 1개 획득 후 BEGIN/COMMIT/ROLLBACK.
+      const pool = /** @type {import('pg').Pool} */ (this.#pool)
+      const client = await pool.connect()
+      try {
+        await client.query('BEGIN')
+        let result
+        try {
+          result = await this.#txContext.run({ client, depth: 0 }, () => fn(client))
+        } catch (err) {
+          await this.#rollback(client)
+          throw err
+        }
+        await client.query('COMMIT')
+        return result
+      } finally {
+        // 성공/실패 무관 — 반드시 풀로 반납(누수 방지).
+        client.release()
+      }
+    })
+  }
+
+  /**
+   * 계측된 SQL 쿼리 (ADR-138). 진행 중 트랜잭션이 있으면 그 컨텍스트의 클라이언트를, 없으면 풀을
+   * 통해 실행한다 — 트랜잭션 안에서 호출해도 같은 connection 을 써 격리가 유지된다(풀의 다른
+   * 커넥션을 잡아 트랜잭션 밖으로 새지 않음). `_instrument('query', …)` 가 자동 span(`postgres.query`,
+   * `db.system.name`/`db.query.text`/`mega.rows_affected`)·stats·상태 검증을 처리한다. 결과는 pg 의
+   * `QueryResult`(`{ rows, rowCount, … }`)를 그대로 돌려준다(ADR-009).
+   *
+   * @param {string} sql - 파라미터화된 SQL(placeholder `$1` 보존).
+   * @param {any[]} [params] - placeholder 바인딩 값.
+   * @returns {Promise<import('pg').QueryResult>}
+   */
+  async query(sql, params) {
+    return this._instrument(
+      'query',
+      this._queryStartAttrs(sql),
+      async () => {
+        const ctx = this.#txContext.getStore()
+        const runner = ctx !== undefined ? ctx.client : /** @type {import('pg').Pool} */ (this.#pool)
+        return runner.query(sql, params)
+      },
+      (res) => ({ 'mega.rows_affected': typeof res?.rowCount === 'number' ? res.rowCount : 0 }),
+    )
+  }
+
+  /**
+   * nested 트랜잭션 — 진행 중 컨텍스트의 클라이언트에 SAVEPOINT 를 걸어 부분 롤백을 지원한다.
+   * `depth` 는 store 에서 단조 증가하므로 SAVEPOINT 이름이 nesting 별로 유일하고, 정수라 SQL
+   * 인젝션 위험이 없다.
+   *
+   * @template T
+   * @param {PgTxContext} ctx - 진행 중 트랜잭션 컨텍스트(부모).
+   * @param {(client: import('pg').PoolClient) => Promise<T> | T} fn
+   * @returns {Promise<T>}
+   */
+  async #runSavepoint(ctx, fn) {
+    const depth = ctx.depth + 1
+    const name = `sp_${depth}`
+    const client = ctx.client
+    await client.query(`SAVEPOINT ${name}`)
+    let result
+    try {
+      result = await this.#txContext.run({ client, depth }, () => fn(client))
+    } catch (err) {
+      // 부분 롤백 — SAVEPOINT 이후 변경만 되돌리고 바깥 트랜잭션은 유지. ROLLBACK TO 실패는 격리.
+      try {
+        await client.query(`ROLLBACK TO SAVEPOINT ${name}`)
+      } catch (spErr) {
+        console.warn(`[MegaPostgresAdapter] ROLLBACK TO SAVEPOINT ${name} failed (original error wins):`, spErr)
+      }
+      throw err
+    }
+    await client.query(`RELEASE SAVEPOINT ${name}`)
+    return result
+  }
+
+  /**
+   * top-level 트랜잭션 ROLLBACK — 실패해도 원본 에러를 가리지 않도록 격리 후 무시.
+   * @param {import('pg').PoolClient} client @returns {Promise<void>}
+   */
+  async #rollback(client) {
+    try {
+      await client.query('ROLLBACK')
+    } catch (err) {
+      console.warn('[MegaPostgresAdapter] ROLLBACK failed (original error wins):', err)
+    }
+  }
+}
+
+// 빌트인 driver 자기등록 (ADR-044) — 배럴(`adapters/index.js`)이 본 모듈을 import 하면 트리거된다.
+// pg 는 _connect() 의 lazy import 까지 로드되지 않으므로 등록은 안전(미사용 환경 비강제).
+Registry.register('postgres', MegaPostgresAdapter)

package/src/adapters/redis-adapter.js

@@ -0,0 +1,331 @@
+// @ts-check
+/**
+ * MegaRedisAdapter — Redis 캐시 어댑터 (`ioredis` 래퍼, ADR-110).
+ *
+ * **첫 cache 도메인 어댑터**(`MegaCacheAdapter` 첫 구체). DB 어댑터와 달리
+ * `get/set/del/has` key-value 인터페이스를 구현하고, 트랜잭션·SQL 개념이 없다.
+ *
+ * # 표준 표면 (MegaCacheAdapter 상속)
+ *   - `_connect()`   — `new Redis({...lazyConnect})` (driver 는 connect 시점 lazy import) +
+ *                      `client.connect()` + `client.ping()` 로 실제 응답 검증.
+ *   - `_disconnect()`— `client.quit()` (진행 중 명령 flush 후 graceful 종료).
+ *   - `_native()`    — `ioredis` Redis 인스턴스(raw handle, ADR-009). 사용자가 직접 ioredis API 접근.
+ *   - `healthCheck()`— `client.ping()` 으로 실제 응답성 확인 (베이스 디폴트=상태만 → override).
+ *   - `getStats()`   — 베이스 stats + redis 특화(driver/db/연결 status).
+ *   - `get/set/del/has` — JSON 직렬화 + TTL(SETEX 의미는 `SET ... EX`).
+ *
+ * # pool 미지원 (중요 — DB 어댑터와 분기, ADR-110)
+ *   Postgres/Maria/Mongo 는 connection pool 을 쓰지만, Redis 는 **단일 연결 + (옵션) cluster** 모델이라
+ *   공통 풀 인터페이스(`{ min, max, idleTimeoutMs, ... }`)가 맞지 않는다. 따라서 본 어댑터는
+ *   `config.pool` 을 **명시적으로 거부**한다(`adapter.invalid_option`) — silent 무시가 아니라
+ *   fail-fast로, 사용자가 풀을 기대하다 동작 안 하는 혼선을 부팅 시 잡는다. cluster·동시성은
+ *   ioredis 가 단일 클라이언트로 pipelining/multiplexing 한다.
+ *
+ * # `db` = 별개 축 (connection 과 충돌 X)
+ *   Redis 의 `db`(논리 DB 번호 0~15)는 connection(url/host)과 **별개 축**이라 url 과 충돌하지 않는다
+ *   (Mongo 의 dbName 과 동일 취급, ADR-109). url path 에 `/2` 처럼 들어 있어도, 명시 `db` 가 우선한다.
+ *
+ * # 설정 (services.caches.<key>) — 통합 옵션 구조 (ADR-109/110)
+ *   ```js
+ *   services: {
+ *     caches: {
+ *       main: {
+ *         driver: 'redis',
+ *         // (a) 연결 — url 또는 discrete (host/port/user/password)
+ *         url: 'redis://:pw@host:6379/1',                  // 또는 ↓
+ *         host: 'localhost', port: 6379, user: 'default', password: '...',
+ *         // db — 논리 DB 번호 (connection 과 별개 축)
+ *         db: 1,
+ *         // (b) options — ioredis passthrough (pool 은 미지원)
+ *         options: { keyPrefix: 'app:', commandTimeout: 5000, keepAlive: 30000,
+ *                    tls: {}, retryStrategy: (n) => Math.min(n * 50, 2000) },
+ *       },
+ *     },
+ *   }
+ *   ```
+ *   `url`(또는 deprecated 별칭 `connectionString`) **XOR** discrete(host/port/user/password). `pool`
+ *   지정 시 throw(ADR-110). 비밀번호/url 은 healthCheck/getStats/에러 details 에 절대 노출하지 않는다.
+ *
+ * @module adapters/redis-adapter
+ */
+import { MegaValidationError } from '../errors/http-errors.js'
+import { MegaCacheAdapter } from './mega-cache-adapter.js'
+import { resolveConnection, assertPlainObject } from './adapter-options.js'
+import * as Registry from './registry.js'
+
+/**
+ * @typedef {object} RedisConfig
+ * @property {string} [driver] - 'redis' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} [url] - `redis://[:pw@]host:port[/db]` 연결 문자열 (discrete 와 배타).
+ * @property {string} [connectionString] - `url` 의 deprecated 별칭 (하위 호환).
+ * @property {string} [host] @property {number} [port] @property {string} [user] @property {string} [password]
+ * @property {number} [db] - 논리 DB 번호 0~15 (connection 과 별개 축, url path 보다 우선).
+ * @property {any} [pool] - 미지원 — 지정 시 `adapter.invalid_option` throw (Redis 는 풀 모델 아님, ADR-110).
+ * @property {Record<string, any>} [options] - ioredis passthrough (keyPrefix, commandTimeout, tls, retryStrategy, keepAlive, …).
+ */
+
+/**
+ * Redis URL 에서 db path(`redis://host:port/<db>`)만 제거해 반환한다. 명시 `db` 가
+ * url path db 를 이기게 하려고, url 이 db 를 주장하지 않도록 pathname 을 비운다. `new URL` 이
+ * 비밀번호/특수문자를 안전하게 보존·재직렬화한다(실측 round-trip 확인). 파싱 실패(잘못된 url)면 원본을
+ * 그대로 반환 — db 옵션은 clientOptions 에 이미 set 돼 있어 best-effort 로 적용되고, 잘못된 url 의 실제
+ * 연결 실패는 `_connect` 의 ioredis 가 surfacing 한다(여기서 throw 하면 url 의 시크릿이 노출될 수 있어 X).
+ * @param {string} url @returns {string}
+ */
+function stripUrlDb(url) {
+  let u
+  try {
+    u = new URL(url)
+  } catch {
+    // 잘못된 url 형식 — 가공하지 않고 원본 반환(db 는 옵션으로 best-effort). 시크릿 노출 방지로 throw X.
+    return url
+  }
+  u.pathname = ''
+  return u.toString()
+}
+
+export class MegaRedisAdapter extends MegaCacheAdapter {
+  /** @type {import('ioredis').Redis | null} 연결된 ioredis 클라이언트 (connect 후에만). */
+  #client = null
+  /** @type {string | undefined} 연결 URL (시크릿 포함 — 외부 노출 금지). discrete 모드면 undefined. */
+  #url
+  /** @type {import('ioredis').RedisOptions} _connect 에서 `new Redis()` 에 넘길 옵션(생성자에서 고정). */
+  #clientOptions
+  /** @type {number | undefined} 논리 DB 번호 (getStats 노출용). */
+  #db
+
+  /**
+   * @param {RedisConfig} [config] - services.caches.<key> 설정.
+   * @throws {MegaValidationError} `adapter.connection_required` - url·discrete 둘 다 없음.
+   * @throws {MegaValidationError} `adapter.connection_conflict` - url + discrete 동시 지정.
+   * @throws {MegaValidationError} `adapter.invalid_option` - pool 지정/옵션 타입 오류/db 범위 오류.
+   */
+  constructor(config = /** @type {any} */ ({})) {
+    super(config)
+
+    // Redis 는 풀 모델이 아니므로 pool 지정을 명시 거부(silent 무시 X).
+    if (config.pool !== undefined) {
+      throw new MegaValidationError(
+        'adapter.invalid_option',
+        'redis: connection pooling is not supported (Redis uses a single multiplexed connection + optional cluster). Remove "pool"; tune concurrency via ioredis "options" instead.',
+        { details: { driver: 'redis', option: 'pool' } },
+      )
+    }
+
+    // 연결 모드(url XOR discrete) 결정. db 는 connection 과 별개 축이라 url 과 충돌하지 않음(ADR-109/110).
+    const conn = resolveConnection(config, { driver: 'redis', dbConflictsWithUrl: false })
+
+    // db 번호 검증 — 0~15 정수(Redis 기본 databases 16개). 미지정이면 옵션에서 생략(ioredis 디폴트 0).
+    if (config.db !== undefined) {
+      if (!Number.isInteger(config.db) || config.db < 0 || config.db > 15) {
+        throw new MegaValidationError('adapter.invalid_option', 'redis "db" must be an integer between 0 and 15.', {
+          details: { driver: 'redis', option: 'db', value: config.db },
+        })
+      }
+      this.#db = config.db
+    }
+
+    assertPlainObject('options', config.options, { driver: 'redis' })
+
+    /** @type {import('ioredis').RedisOptions} */
+    const clientOptions = {}
+    if (config.options !== undefined) Object.assign(clientOptions, config.options)
+    // 라이프사이클은 베이스 상태 머신이 관리 — ioredis 자동 연결을 끄고 _connect() 에서 명시 연결한다.
+    // (사용자가 options 로 lazyConnect:false 를 줘도 우리 계약이 이긴다 — 마지막에 덮어쓴다.)
+    clientOptions.lazyConnect = true
+
+    if (conn.url === undefined) {
+      // discrete 모드 — host/port/username/password/db 를 옵션으로. ioredis 의 ACL 사용자 키는 `username`.
+      if (conn.host !== undefined) clientOptions.host = conn.host
+      if (conn.port !== undefined) clientOptions.port = conn.port
+      if (conn.user !== undefined) clientOptions.username = conn.user
+      if (conn.password !== undefined) clientOptions.password = conn.password
+    }
+    // db 는 url/discrete 무관 — 명시 지정 시 옵션으로 강제(url path 의 db 보다 우선, ADR-110).
+    if (this.#db !== undefined) clientOptions.db = this.#db
+
+    // ⚠️ 근본원인: ioredis `parseOptions` 는 인자를 순서대로 lodash `defaults`(=빈 키만
+    // 채움, **먼저 온 값이 이김**)로 병합한다(node_modules/ioredis/built/Redis.js, 실 소스 확인).
+    // `new Redis(url, options)` 에선 url path 의 db(`redis://…/1`)가 먼저 채워져 명시 `options.db` 가
+    // **무시**된다(ioredis 5.11 실측). ADR-110 의 "명시 db 우선" 계약을 지키려고, 명시 db 가 있으면
+    // url 에서 db path 를 제거해 url 이 db 를 주장하지 않게 한다(타입-안전: `new Redis(url, options)` 순서 유지).
+    this.#url = this.#db !== undefined && conn.url !== undefined ? stripUrlDb(conn.url) : conn.url
+    this.#clientOptions = clientOptions
+  }
+
+  /**
+   * `ioredis` 클라이언트 생성 + `connect()` + `ping()` 으로 실제 연결 검증.
+   * driver 는 **connect 시점에 lazy import** — 모듈 import(배럴 경유 자기등록)만으로는 ioredis 를
+   * 로드하지 않아, 본 어댑터를 안 쓰는 환경이 ioredis 설치를 강제받지 않는다(DB 어댑터 정합).
+   *
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _connect() {
+    const { Redis } = await import('ioredis')
+    // url 모드면 `new Redis(url, options)`, discrete 모드면 `new Redis(options)`. lazyConnect 라
+    // 생성자에서 연결을 시작하지 않으므로 아래 connect() 가 유일한 연결 시점이다. (명시 db 가 url path
+    // db 를 이기게 하는 처리는 생성자에서 url 의 db path 를 제거하는 방식으로 했다 — #stripUrlDb 참조.)
+    const client = this.#url !== undefined ? new Redis(this.#url, this.#clientOptions) : new Redis(this.#clientOptions)
+    try {
+      await client.connect()
+      // connect 직후 실제 ping 으로 응답·인증 검증 — 잘못된 자격증명/호스트를 부팅 시 잡는다(fail-fast).
+      const pong = await client.ping()
+      if (pong !== 'PONG') {
+        throw new MegaValidationError('adapter.health_failed', `redis ping returned unexpected reply: ${pong}`, {
+          details: { driver: 'redis', reply: pong },
+        })
+      }
+      this.#client = client
+    } catch (err) {
+      // 검증 실패 시 leak 방지를 위해 client 강제 종료 후 원본 에러 전파.
+      try {
+        client.disconnect()
+      } catch (closeErr) {
+        // 검증 실패 후 정리(disconnect) 실패는 비치명적 — 원본 연결 에러가 진짜 원인.
+        console.warn('[MegaRedisAdapter] client.disconnect() failed after connect validation error (original error wins):', closeErr)
+      }
+      throw err
+    }
+  }
+
+  /**
+   * ioredis 클라이언트 graceful 종료(`quit` — 진행 중 명령 flush 후 닫음).
+   * 베이스 상태 머신이 connected 상태에서만 호출을 보장한다.
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _disconnect() {
+    if (this.#client !== null) {
+      const client = this.#client
+      this.#client = null
+      await client.quit()
+    }
+  }
+
+  /**
+   * raw ioredis handle (ADR-009). `connect()` 후에만 베이스 `native` getter 가 호출한다.
+   * @protected
+   * @returns {import('ioredis').Redis}
+   */
+  _native() {
+    if (this.#client === null) {
+      // 베이스 native getter 가 state 검증을 먼저 하므로 정상 경로에선 도달 안 함 — 방어.
+      return this._notImplemented('native')
+    }
+    return this.#client
+  }
+
+  /**
+   * 헬스 체크 — 실제 `ping` 으로 응답성 확인 (베이스 디폴트는 상태만 반영).
+   * 실패는 throw 없이 `ok:false` + 사유(베이스 계약). 비밀번호/url 은 노출하지 않는다.
+   *
+   * @returns {Promise<{ ok: boolean, driver: 'redis', state: string, db?: number, error?: string }>}
+   */
+  async healthCheck() {
+    if (this.state !== 'connected' || this.#client === null) {
+      return { ok: false, driver: 'redis', state: this.state }
+    }
+    try {
+      const pong = await this.#client.ping()
+      return { ok: pong === 'PONG', driver: 'redis', state: this.state, db: this.#db }
+    } catch (err) {
+      return {
+        ok: false,
+        driver: 'redis',
+        state: this.state,
+        db: this.#db,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+
+  /**
+   * 누적 통계 + redis 특화(driver/db/연결 status). 연결 status 는 ioredis 의 connection 상태 문자열
+   * ('wait'|'connecting'|'connect'|'ready'|'close'|'end' 등) — 풀이 없어 이걸 노출한다.
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, db: number | undefined, status: string | undefined }}
+   */
+  getStats() {
+    return {
+      ...super.getStats(),
+      driver: 'redis',
+      db: this.#db,
+      // ioredis 인스턴스의 연결 상태 문자열(미연결이면 undefined).
+      status: this.#client?.status,
+    }
+  }
+
+  // ──────────────────────────────────────────────────────────────────────
+  // MegaCacheAdapter 인터페이스 — get / set / del / has (JSON 직렬화 + TTL)
+  // hook + 상태검증 + stats 는 `_instrument` 가 처리(ADR-077).
+  // ──────────────────────────────────────────────────────────────────────
+
+  /**
+   * 키 조회. 없으면 `null`(throw X, 베이스 계약). 저장된 JSON 을 파싱해 원래 값으로 복원한다.
+   * @param {string} key
+   * @returns {Promise<any>}
+   */
+  async get(key) {
+    return this._instrument('get', { key }, async () => {
+      const raw = await /** @type {import('ioredis').Redis} */ (this.#client).get(key)
+      if (raw === null) return null // miss
+      return JSON.parse(raw)
+    })
+  }
+
+  /**
+   * 키 저장. `ttl`(초) 지정 시 `SET key val EX ttl`(SETEX 의미), 없으면 `SET key val`(무한).
+   * 값은 JSON 직렬화 — 직렬화 불가(undefined/함수/심볼)면 `cache.unserializable` throw(silent 저장 X).
+   *
+   * @param {string} key
+   * @param {any} value
+   * @param {{ ttl?: number }} [opts] - `ttl` 초 단위 양의 정수(베이스 `_assertTtl` 검증).
+   * @returns {Promise<void>}
+   */
+  async set(key, value, { ttl } = {}) {
+    // TTL·직렬화 검증은 의도적으로 `_instrument` **밖**에서 한다(L-1 결정): 잘못된 인자는 네트워크
+    // I/O·hook·stats 누적 이전에 fail-fast 로 거부하는 게 맞다(인자 오류는 어댑터 "호출"이 아니라
+    // 프로그래밍 오류 — instrumented 호출 통계에 섞이면 안 됨). 정상 경로의 실제 I/O 만 _instrument 가 감싼다.
+    this._assertTtl(ttl)
+    const raw = JSON.stringify(value)
+    if (raw === undefined) {
+      // JSON.stringify(undefined/함수/심볼) === undefined — 저장 시 silent 손상 대신 명시 거부.
+      throw new MegaValidationError('cache.unserializable', `redis set("${key}"): value is not JSON-serializable (undefined/function/symbol).`, {
+        details: { key, type: typeof value },
+      })
+    }
+    return this._instrument('set', { key, ttl }, async () => {
+      const client = /** @type {import('ioredis').Redis} */ (this.#client)
+      // ttl 있으면 EX(초) 동반 — ioredis 가 SETEX 와 동등하게 atomic 처리. 없으면 무한.
+      if (ttl !== undefined) await client.set(key, raw, 'EX', ttl)
+      else await client.set(key, raw)
+    })
+  }
+
+  /**
+   * 키 삭제. 없는 키 삭제는 에러 아님(idempotent — DEL 은 0 반환).
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async del(key) {
+    return this._instrument('del', { key }, async () => {
+      await /** @type {import('ioredis').Redis} */ (this.#client).del(key)
+    })
+  }
+
+  /**
+   * 키 존재 여부 (Boolean — `has*`, ADR-036). `EXISTS` 는 존재 개수(0/1)를 반환.
+   * @param {string} key
+   * @returns {Promise<boolean>}
+   */
+  async has(key) {
+    return this._instrument('has', { key }, async () => {
+      const n = await /** @type {import('ioredis').Redis} */ (this.#client).exists(key)
+      return n === 1
+    })
+  }
+}
+
+// 빌트인 driver 자기등록 (ADR-044) — 배럴(`adapters/index.js`)이 본 모듈을 import 하면 트리거된다.
+// ioredis 는 _connect() 의 lazy import 까지 로드되지 않으므로 등록은 안전(미사용 환경 비강제).
+Registry.register('redis', MegaRedisAdapter)