mega-framework 0.1.0

package/src/adapters/maria-adapter.js

@@ -0,0 +1,425 @@
+// @ts-check
+/**
+ * MegaMariaAdapter — MariaDB 어댑터 (`mariadb` = node-mariadb 래퍼, ADR-107).
+ *
+ * Postgres(ADR-106)에 이은 두 번째 SQL 어댑터. 풀 + manual 트랜잭션 + SAVEPOINT nested
+ * 구조를 Postgres 와 대칭으로 맞추되, mariadb 드라이버의 표면(트랜잭션 메서드·풀 통계·연결 옵션)에
+ * 정합한다.
+ *
+ * # 표준 표면 (MegaDbAdapter 상속)
+ *   - `_connect()`   — `createPool(cfg)` (driver 는 connect 시점 lazy import) + `SELECT 1` 검증.
+ *   - `_disconnect()`— `pool.end()` (모든 연결 종료).
+ *   - `_native()`    — `mariadb` Pool 인스턴스(raw handle, ADR-009). `MegaModel.db` 가 노출.
+ *   - `healthCheck()`— `pool.query('SELECT 1')` 실행으로 실제 응답성 확인.
+ *   - `getStats()`   — 베이스 stats + 풀 통계(total/idle/active/queue).
+ *   - `withTransaction(fn)` — 명시적 트랜잭션 경계 (ADR-010). 아래 "트랜잭션 패턴" 참조.
+ *
+ * # 트랜잭션 패턴 — 풀 연결 1개 + `beginTransaction/commit/rollback`
+ *   `pool.getConnection()` 으로 연결 1개를 잡아 `conn.beginTransaction() → fn(conn) → conn.commit()`
+ *   (성공) / `conn.rollback()`(실패) 한다. `fn` 에는 **트랜잭션 컨텍스트 연결**(같은 connection)을
+ *   넘긴다. `conn.release()`(async)는 finally 에서 반드시 호출해 풀로 반납한다. rollback 자체 실패는
+ *   원본 에러를 가리지 않도록 격리 후 원본 re-throw.
+ *
+ * # nested 트랜잭션 정책 — SAVEPOINT (Sqlite 와 분기, ADR-107)
+ *   MariaDB 도 SAVEPOINT 를 지원하므로 nested 를 **거부하지 않고**(Sqlite, ADR-105 와 분기) 같은
+ *   연결에 `SAVEPOINT sp_<depth>` 를 건다 — 성공 시 `RELEASE SAVEPOINT`, 실패 시 `ROLLBACK TO
+ *   SAVEPOINT` 후 re-throw. 컨텍스트 추적은 Postgres 어댑터와 **동일하게 `AsyncLocalStorage`** 로
+ *   하며, store 의 `depth` 가 SAVEPOINT 이름을 nesting 별로 유일하게 만든다(동시 top-level
+ *   트랜잭션은 각자 독립 store → async race-free). 별도 풀 연결을 잡지 않아 `connectionLimit:1`
+ *   에서도 nested 가 deadlock 되지 않는다.
+ *
+ *   ⚠️ **"race-free" 의 경계**: race-free 는 **서로 다른 top-level 호출 사이**에만
+ *   해당한다. **단일 트랜잭션 내부**에서 sibling nested 를 `Promise.all` 등으로 **병렬** 실행하는 것은
+ *   **미지원** — 같은 연결(단일 connection) 위 SAVEPOINT 이름이 `depth` 로만 결정되므로 두 sibling 이
+ *   동시에 `depth+1` 을 보면 둘 다 `sp_1` 을 만들어 충돌하고, mariadb 단일 connection 도 쿼리를
+ *   직렬화하므로 병렬 이득이 없다. nested 는 **순차 호출**(await 로 한 번에 하나)할 것.
+ *
+ * # 설정 (services.databases.<key>) — 통합 옵션 구조 (ADR-109)
+ *   ```js
+ *   services: {
+ *     databases: {
+ *       primary: {
+ *         driver: 'mariadb',
+ *         // (a) 연결 — url 또는 discrete (상호 배타)
+ *         url: 'mariadb://user:pw@host:3306/db',            // 또는 ↓
+ *         host: 'localhost', port: 3306, user: 'mega', password: '...', database: 'mega_test',
+ *         // (b) pool — 공통 풀 인터페이스
+ *         pool: { min: 0, max: 10, idleTimeoutMs: 1800000, acquireTimeoutMs: 10000 },
+ *         // (c) options — mariadb 특화 passthrough + bigIntStrategy
+ *         options: { bigIntStrategy: 'number', charset: 'utf8mb4', multipleStatements: false },
+ *       },
+ *     },
+ *   }
+ *   ```
+ *   `url`(또는 deprecated 별칭 `connectionString`) **XOR** discrete 연결필드. 둘 다 없으면
+ *   `adapter.connection_required`, 동시 지정은 `adapter.connection_conflict`. pool/options 는 어느
+ *   모드와도 조합 가능. pool 매핑: min→minimumIdle, max→connectionLimit, idleTimeoutMs→idleTimeout
+ *   (**초**, ms÷1000), acquireTimeoutMs→acquireTimeout. `maxLifetimeMs` 는 mariadb 미지원(throw).
+ *
+ *   **url + pool/options 조합**: mariadb `createPool` 은 문자열(URI) XOR 객체만 받으므로, url 을 받으면
+ *   `new URL` 로 discrete 연결필드(host/port/user/password/database)로 **파싱해 항상 객체**로 구성한다.
+ *   따라서 url 의 **query string 파라미터는 미지원** — 있으면 `adapter.invalid_option` throw(옵션은
+ *   `options` 로 넘길 것). bigIntStrategy 디폴트('number')를 적용하려면 객체 구성이 필수이기도 하다.
+ *
+ *   **bigIntStrategy** (`options.bigIntStrategy`, 디폴트 `'number'`): MariaDB BIGINT 를 JS 로 받는 전략.
+ *   - `'number'`(디폴트) → `bigIntAsNumber:true`. JS Number 편의성. ⚠️ **2^53(9,007,199,254,740,992)
+ *     초과 정수는 정밀도 손실** (IEEE-754 double 한계). 큰 ID/카운터는 'bigint'/'string' 권장.
+ *   - `'bigint'` → `bigIntAsNumber:false`. 드라이버가 BigInt 반환(정밀도 무손실, 산술 시 BigInt 취급 필요).
+ *   - `'string'` → `supportBigNumbers:true, bigNumberStrings:true, insertIdAsNumber:false`. 문자열 반환
+ *     (무손실, 직렬화 친화). mariadb@3 에서 `bigNumberStrings` 단독은 BigInt 라 `supportBigNumbers` 동반 필수(실 서버 검증, ADR-109).
+ *
+ *   비밀번호/url 은 healthCheck/getStats/에러 details 에 노출하지 않는다(정합).
+ *
+ * @module adapters/maria-adapter
+ */
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { MegaValidationError } from '../errors/http-errors.js'
+import { MegaDbAdapter } from './mega-db-adapter.js'
+import { resolveConnection, normalizePool, assertPlainObject, MARIA_POOL_SPEC } from './adapter-options.js'
+import * as Registry from './registry.js'
+
+/**
+ * @typedef {object} MariaConfig
+ * @property {string} [driver] - 'mariadb' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} [url] - `mariadb://user:pw@host:port/db` (discrete 필드와 배타, query string 미지원).
+ * @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 }} [pool] - 공통 풀 인터페이스.
+ * @property {Record<string, any> & { bigIntStrategy?: 'number' | 'bigint' | 'string' }} [options] - mariadb passthrough + bigIntStrategy.
+ */
+
+/**
+ * @typedef {object} MariaTxContext - AsyncLocalStorage 에 담기는 트랜잭션 컨텍스트.
+ * @property {import('mariadb').PoolConnection} conn - 이 트랜잭션을 소유한 풀 연결.
+ * @property {number} depth - nesting 깊이 (top-level=0, 첫 nested=1, ...).
+ */
+
+/**
+ * bigIntStrategy → mariadb 드라이버 플래그 (ADR-109, 디폴트 'number'=JS Number 편의성).
+ *
+ * ⚠️ `'string'` 은 `supportBigNumbers:true` 가 **반드시 함께** 있어야 BIGINT 가 문자열로 온다 —
+ * mariadb@3 에서 `bigNumberStrings:true` 단독은 BigInt 를 반환한다(실 서버로 검증, ADR-109).
+ */
+const BIGINT_STRATEGIES = /** @type {const} */ ({
+  number: { bigIntAsNumber: true },
+  bigint: { bigIntAsNumber: false },
+  string: { supportBigNumbers: true, bigNumberStrings: true, insertIdAsNumber: false },
+})
+
+/**
+ * mariadb URL 을 discrete 연결필드로 파싱 (createPool 객체 모드용). query string 은 미지원(throw).
+ * @param {string} url @returns {Record<string, any>}
+ * @throws {MegaValidationError} `adapter.invalid_option` - 잘못된 URL 또는 query string 존재.
+ */
+function parseMariaUrl(url) {
+  let u
+  try {
+    u = new URL(url)
+  } catch {
+    // url 값은 비밀번호를 포함할 수 있어 메시지·details 어디에도 노출하지 않는다(L-1, ADR-106/107 정합).
+    // 디버깅엔 타입만으로 충분(잘못된 타입/형식 식별).
+    throw new MegaValidationError('adapter.invalid_option', 'mariadb "url" is not a valid URL', {
+      details: { driver: 'mariadb', option: 'url', type: typeof url },
+    })
+  }
+  if ([...u.searchParams.keys()].length > 0) {
+    // createPool 객체 모드로 변환하므로 URI query 파라미터를 옮길 표준 경로가 없다 — 명시 거부.
+    throw new MegaValidationError(
+      'adapter.invalid_option',
+      'mariadb: URL query parameters are not supported with the standardized signature; pass them via the "options" field instead.',
+      { details: { driver: 'mariadb', option: 'url', params: [...u.searchParams.keys()] } },
+    )
+  }
+  /** @type {Record<string, any>} */
+  const out = {}
+  if (u.hostname) out.host = u.hostname
+  if (u.port) out.port = Number(u.port)
+  if (u.username) out.user = decodeURIComponent(u.username)
+  if (u.password) out.password = decodeURIComponent(u.password)
+  const db = u.pathname.replace(/^\//, '')
+  if (db) out.database = db
+  return out
+}
+
+/**
+ * options 에서 bigIntStrategy 를 뽑아 드라이버 플래그로 변환하고 나머지 passthrough 와 분리한다.
+ * 디폴트 'number'. env snake 별칭(`big_int_strategy`)도 인식(env-mapper OPTIONS_ 는 snake_case).
+ * @param {Record<string, any> | undefined} options
+ * @returns {{ flags: Record<string, boolean>, rest: Record<string, any> }}
+ * @throws {MegaValidationError} `adapter.invalid_option` - 알 수 없는 전략.
+ */
+function resolveBigIntStrategy(options) {
+  const rest = { ...(options ?? {}) }
+  const strategy = rest.bigIntStrategy ?? rest.big_int_strategy ?? 'number'
+  delete rest.bigIntStrategy
+  delete rest.big_int_strategy
+  if (typeof strategy !== 'string' || !Object.prototype.hasOwnProperty.call(BIGINT_STRATEGIES, strategy)) {
+    throw new MegaValidationError(
+      'adapter.invalid_option',
+      `mariadb: options.bigIntStrategy must be one of 'number' | 'bigint' | 'string'. Got ${JSON.stringify(strategy)}.`,
+      { details: { driver: 'mariadb', option: 'options.bigIntStrategy', value: strategy } },
+    )
+  }
+  return { flags: { ...BIGINT_STRATEGIES[/** @type {keyof typeof BIGINT_STRATEGIES} */ (strategy)] }, rest }
+}
+
+export class MegaMariaAdapter extends MegaDbAdapter {
+  /** @type {import('mariadb').Pool | null} 연결된 Pool 인스턴스 (connect 후에만). */
+  #pool = null
+  /** @type {Record<string, unknown>} _connect 의 `createPool()` 인자 (url 도 discrete 로 파싱해 항상 객체, ADR-109). */
+  #poolArg
+  /**
+   * 진행 중 트랜잭션 컨텍스트 추적기 (Postgres 어댑터와 동일 전략). nested 가 같은 연결을 재사용한다.
+   * @type {AsyncLocalStorage<MariaTxContext>}
+   */
+  #txContext = new AsyncLocalStorage()
+
+  /**
+   * @param {MariaConfig} [config] - services.databases.<key> 설정.
+   * @throws {MegaValidationError} `adapter.connection_required` - url·discrete 둘 다 없음.
+   * @throws {MegaValidationError} `adapter.connection_conflict` - url + discrete 동시 지정.
+   * @throws {MegaValidationError} `adapter.invalid_option` - 옵션 타입/범위 오류(bigIntStrategy 포함).
+   */
+  constructor(config = /** @type {any} */ ({})) {
+    super(config)
+
+    // 연결 모드(url XOR discrete) 결정 + 충돌·필수 검증 (ADR-109 공용 헬퍼).
+    const conn = resolveConnection(config, { driver: 'mariadb', dbKey: 'database', dbConflictsWithUrl: true })
+    const poolOpts = normalizePool(config.pool, MARIA_POOL_SPEC, 'mariadb')
+    assertPlainObject('options', config.options, { driver: 'mariadb' })
+
+    // mariadb createPool 은 string XOR 객체 — url+pool/options 조합 + bigIntStrategy 디폴트 적용을 위해
+    // 항상 객체로 구성한다(url 은 discrete 로 파싱).
+    /** @type {Record<string, any>} */
+    const poolConfig = {}
+    if (conn.url !== undefined) Object.assign(poolConfig, parseMariaUrl(conn.url))
+    else {
+      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
+    }
+    // bigIntStrategy 분리 → 드라이버 플래그 + 나머지 options passthrough.
+    const { flags, rest } = resolveBigIntStrategy(config.options)
+    Object.assign(poolConfig, rest, flags)
+    // pool(정규화) 나중 — 겹치면 명시 pool 인터페이스가 이긴다.
+    Object.assign(poolConfig, poolOpts)
+    this.#poolArg = poolConfig
+  }
+
+  /**
+   * `mariadb` Pool 생성 + `SELECT 1` 로 실제 연결 검증.
+   * driver 는 **connect 시점에 lazy import** — Sqlite/Postgres 패턴 정합(미사용 환경 비강제).
+   *
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _connect() {
+    const mariadb = await import('mariadb')
+    // mariadb 는 named export(`createPool`) — default 는 비어 있을 수 있어 방어적으로 둘 다 본다.
+    const createPool = mariadb.createPool ?? /** @type {any} */ (mariadb).default?.createPool
+    const pool = createPool(/** @type {any} */ (this.#poolArg))
+    // connect 직후 실제 연결 1개를 잡아 SELECT 1 — 잘못된 자격증명/호스트를 부팅 시점에 잡는다(fail-fast).
+    try {
+      const conn = await pool.getConnection()
+      try {
+        await conn.query('SELECT 1')
+      } finally {
+        await conn.release()
+      }
+    } catch (err) {
+      try {
+        await pool.end()
+      } catch (endErr) {
+        // 검증 실패 후 정리(pool.end) 실패는 비치명적 — 원본 연결 에러가 진짜 원인.
+        console.warn('[MegaMariaAdapter] pool.end() failed after connect validation error (original error wins):', endErr)
+      }
+      throw err
+    }
+    this.#pool = pool
+  }
+
+  /**
+   * Pool 종료(모든 연결 종료). 베이스 상태 머신이 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('mariadb').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: 'mariadb', state: string, error?: string }>}
+   */
+  async healthCheck() {
+    if (this.state !== 'connected' || this.#pool === null) {
+      return { ok: false, driver: 'mariadb', state: this.state }
+    }
+    try {
+      const rows = await this.#pool.query('SELECT 1 AS ok')
+      // mariadb SELECT 1 은 BIGINT 라 드라이버 설정에 따라 BigInt 일 수 있어 Number 로 정규화.
+      const ok = Number(rows?.[0]?.ok) === 1
+      return { ok, driver: 'mariadb', state: this.state }
+    } catch (err) {
+      return {
+        ok: false,
+        driver: 'mariadb',
+        state: this.state,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+
+  /**
+   * 누적 통계 + 풀 통계(total/idle/active/queue). 연결 전이면 풀 통계는 0.
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, pool: { total: number, idle: number, active: number, queue: number } }}
+   */
+  getStats() {
+    const pool = this.#pool
+    return {
+      ...super.getStats(),
+      driver: 'mariadb',
+      pool: {
+        total: pool?.totalConnections() ?? 0,
+        idle: pool?.idleConnections() ?? 0,
+        active: pool?.activeConnections() ?? 0,
+        queue: pool?.taskQueueSize() ?? 0,
+      },
+    }
+  }
+
+  /**
+   * 명시적 트랜잭션 경계 (ADR-010, ADR-107). top-level 은 풀 연결 1개 위
+   * `beginTransaction/commit/rollback`, nested 는 같은 연결 위 `SAVEPOINT`(모듈 docstring 참조).
+   *
+   * `fn` 은 **트랜잭션 컨텍스트 연결**(mariadb PoolConnection)을 인자로 받는다. 성공 시 commit(또는
+   * RELEASE SAVEPOINT) 후 반환값을 그대로 돌려주고, throw 시 rollback(또는 ROLLBACK TO SAVEPOINT)
+   * 후 원본 에러 re-throw.
+   *
+   * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
+   *
+   * @template T
+   * @param {(conn: import('mariadb').PoolConnection) => 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개 획득 후 beginTransaction/commit/rollback.
+      const pool = /** @type {import('mariadb').Pool} */ (this.#pool)
+      const conn = await pool.getConnection()
+      try {
+        await conn.beginTransaction()
+        let result
+        try {
+          result = await this.#txContext.run({ conn, depth: 0 }, () => fn(conn))
+        } catch (err) {
+          await this.#rollback(conn)
+          throw err
+        }
+        await conn.commit()
+        return result
+      } finally {
+        // 성공/실패 무관 — 반드시 풀로 반납(누수 방지). mariadb release 는 async.
+        await conn.release()
+      }
+    })
+  }
+
+  /**
+   * 계측된 SQL 쿼리 (ADR-138). 진행 중 트랜잭션이 있으면 그 컨텍스트의 연결을, 없으면 풀을 통해
+   * 실행한다 — 트랜잭션 안에서 호출해도 같은 connection 을 써 격리가 유지된다. `_instrument('query', …)`
+   * 가 자동 span(`mariadb.query`, `db.system.name`/`db.query.text`/`mega.rows_affected`)·stats·상태 검증을
+   * 처리한다. 결과는 mariadb native 를 그대로 돌려준다 — SELECT 는 row 배열, DML 은 `{ affectedRows, … }`(ADR-009).
+   *
+   * @param {string} sql - 파라미터화된 SQL(placeholder `?` 보존).
+   * @param {any[]} [params] - placeholder 바인딩 값.
+   * @returns {Promise<any>}
+   */
+  async query(sql, params) {
+    return this._instrument(
+      'query',
+      this._queryStartAttrs(sql),
+      async () => {
+        const ctx = this.#txContext.getStore()
+        const runner = ctx !== undefined ? ctx.conn : /** @type {import('mariadb').Pool} */ (this.#pool)
+        return runner.query(sql, params)
+      },
+      // SELECT 는 row 배열 길이, DML 은 affectedRows. BigInt 설정 대비 Number 강제.
+      (res) => ({ 'mega.rows_affected': Array.isArray(res) ? res.length : Number(res?.affectedRows ?? 0) }),
+    )
+  }
+
+  /**
+   * nested 트랜잭션 — 진행 중 컨텍스트의 연결에 SAVEPOINT 를 걸어 부분 롤백을 지원한다.
+   * `depth` 는 store 에서 단조 증가하므로 SAVEPOINT 이름이 nesting 별로 유일하고, 정수라 SQL
+   * 인젝션 위험이 없다.
+   *
+   * @template T
+   * @param {MariaTxContext} ctx - 진행 중 트랜잭션 컨텍스트(부모).
+   * @param {(conn: import('mariadb').PoolConnection) => Promise<T> | T} fn
+   * @returns {Promise<T>}
+   */
+  async #runSavepoint(ctx, fn) {
+    const depth = ctx.depth + 1
+    const name = `sp_${depth}`
+    const conn = ctx.conn
+    await conn.query(`SAVEPOINT ${name}`)
+    let result
+    try {
+      result = await this.#txContext.run({ conn, depth }, () => fn(conn))
+    } catch (err) {
+      // 부분 롤백 — SAVEPOINT 이후 변경만 되돌리고 바깥 트랜잭션은 유지. ROLLBACK TO 실패는 격리.
+      try {
+        await conn.query(`ROLLBACK TO SAVEPOINT ${name}`)
+      } catch (spErr) {
+        console.warn(`[MegaMariaAdapter] ROLLBACK TO SAVEPOINT ${name} failed (original error wins):`, spErr)
+      }
+      throw err
+    }
+    await conn.query(`RELEASE SAVEPOINT ${name}`)
+    return result
+  }
+
+  /**
+   * top-level 트랜잭션 rollback — 실패해도 원본 에러를 가리지 않도록 격리 후 무시.
+   * @param {import('mariadb').PoolConnection} conn @returns {Promise<void>}
+   */
+  async #rollback(conn) {
+    try {
+      await conn.rollback()
+    } catch (err) {
+      console.warn('[MegaMariaAdapter] rollback failed (original error wins):', err)
+    }
+  }
+}
+
+// 빌트인 driver 자기등록 (ADR-044) — 배럴(`adapters/index.js`)이 본 모듈을 import 하면 트리거된다.
+// mariadb 는 _connect() 의 lazy import 까지 로드되지 않으므로 등록은 안전(미사용 환경 비강제).
+Registry.register('mariadb', MegaMariaAdapter)