mega-framework 0.1.0

package/src/adapters/mongo-adapter.js

@@ -0,0 +1,396 @@
+// @ts-check
+/**
+ * MegaMongoAdapter — MongoDB 어댑터 (`mongodb` 공식 driver 래퍼, ADR-108).
+ *
+ * **첫 Document DB 어댑터**. SQL 어댑터(Sqlite/Postgres/Maria)와 API 패턴과
+ * 트랜잭션 모델이 다르다 — `db.collection(...)` 도큐먼트 API + `session.withTransaction`.
+ *
+ * # 표준 표면 (MegaDbAdapter 상속)
+ *   - `_connect()`   — `new MongoClient(uri, opts)` + `client.connect()` + `db.command({ ping })` 검증
+ *                      (driver 는 connect 시점 lazy import — SQL 어댑터 패턴 정합, ADR-105/106/107).
+ *   - `_disconnect()`— `client.close()`.
+ *   - `_native()`    — `Db` 인스턴스(raw handle, ADR-009). `MegaModel.db` 가 노출 →
+ *                      사용자는 `this.db.collection(table)` 로 도큐먼트 API 접근.
+ *   - `healthCheck()`— `db.command({ ping: 1 })` 실행으로 실제 응답성 확인.
+ *   - `getStats()`   — 베이스 stats + mongo 특화(driver/dbName + CMAP 이벤트 기반 풀 카운터).
+ *   - `withTransaction(fn)` — 명시적 트랜잭션 경계 (ADR-010). 아래 "트랜잭션 패턴" 참조.
+ *
+ * # 트랜잭션 패턴 — `session.withTransaction` 위임 (driver 가 commit/retry 관리)
+ *   `client.startSession()` 으로 세션 1개를 잡아 `session.withTransaction(() => fn(db, session))`
+ *   로 위임한다. driver v6 의 `withTransaction` 은 **콜백 반환값을 그대로 반환**하고(공식 문서),
+ *   콜백 성공 시 commit / throw 시 abort 를 driver 가 처리한다. 또한 `TransientTransactionError`/
+ *   `UnknownTransactionCommitResult` 발생 시 **exponential backoff 자동 retry** 도 driver 위임이다
+ *   (우리가 따로 retry 루프를 만들지 않는다). `session.endSession()` 은 성공/실패 무관 `finally` 에서
+ *   반드시 호출해 세션 leak 을 막는다.
+ *
+ *   `fn` 은 `(db, session)` 두 인자를 받는다 — 사용자는 도큐먼트 연산에 `{ session }` 을 넘겨야
+ *   해당 연산이 트랜잭션에 묶인다. 예:
+ *   ```js
+ *   await User.withTransaction(async (db, session) => {
+ *     await db.collection('users').insertOne({ name: 'kim' }, { session })
+ *     await db.collection('logs').insertOne({ event: 'signup' }, { session })
+ *   })
+ *   ```
+ *
+ * # nested 트랜잭션 정책 — 재진입 거부 (Sqlite 와 동일, Postgres SAVEPOINT 와 분기, ADR-108)
+ *   진행 중 트랜잭션 위에서 `withTransaction` 을 다시 부르면 즉시
+ *   `adapter.nested_transaction_unsupported` 를 throw 한다(Sqlite 어댑터와 **동일 에러 코드**).
+ *   진행 중 여부는 **`AsyncLocalStorage`** 로 추적한다(Postgres 패턴 정합) — `withTransaction` 진입
+ *   시 store 가 있으면 nested 로 판정. MongoDB 는 단일 세션 내 트랜잭션 nesting 을 지원하지 않으며
+ *   (한 세션에 트랜잭션은 하나), 매 nested 마다 새 세션을 따로 잡으면 별개 트랜잭션이 되어 부분
+ *   롤백 의미가 깨지므로(바깥 abort 가 안쪽에 전파 안 됨) **명시적 거부**가 silent 혼선보다 안전.
+ *   SAVEPOINT 동등물이 도큐먼트 모델에 없어 Postgres 의 nested 와 분기한다.
+ *
+ *   ⚠️ ALS 격리는 **서로 다른 top-level 호출 사이**의 동시성에만 race-free 를 보장한다(Postgres와
+ *   동일 경계). 단일 트랜잭션 내부에서 sibling 을 `Promise.all` 로 병렬 실행하는 것은
+ *   nested 거부 대상이며 애초에 지원하지 않는다 — nested 는 항상 순차여야 하고 본 어댑터는 거부한다.
+ *
+ * # replica set 요구사항 (중요)
+ *   MongoDB 트랜잭션은 **replica set(또는 mongos)** 에서만 동작한다 — standalone 은 미지원
+ *   (server 에러: "Transaction numbers are only allowed on a replica set member or mongos").
+ *   `withTransaction` 자체 코드는 standalone 에서도 nested 거부까지는 동작하나, 실제 commit 은
+ *   replica set 이 필요하다. docker-compose 의 `mongo:7` 은 standalone 이므로 트랜잭션 통합
+ *   테스트는 replica set Mongo(예: URL 에 `?replicaSet=rs0`)를 `MEGA_MONGO_URL` 로 주입할 때만
+ *   실행되고, 그 외엔 자동 skip 된다(ADR-108).
+ *
+ * # 설정 (services.databases.<key>) — 통합 옵션 구조 (ADR-109)
+ *   ```js
+ *   services: {
+ *     databases: {
+ *       primary: {
+ *         driver: 'mongodb',
+ *         // (a) 연결 — url 또는 discrete (host/port/user/password)
+ *         url: 'mongodb://user:pw@host:27017/mega_test?authSource=admin',  // 또는 ↓
+ *         host: 'localhost', port: 27017, user: 'mega', password: '...',
+ *         // dbName — 선택할 DB. url 의 path 에 있으면 추출, 명시 지정이 우선. (url 과 충돌 X)
+ *         dbName: 'mega_test',
+ *         // (b) pool — 공통 풀 인터페이스
+ *         pool: { min: 0, max: 10, idleTimeoutMs: 60000, acquireTimeoutMs: 10000 },
+ *         // (c) options — MongoClient passthrough
+ *         options: { authSource: 'admin', replicaSet: 'rs0', tls: true, readPreference: 'primary',
+ *                    serverSelectionTimeoutMS: 5000, connectTimeoutMS: 10000 },
+ *       },
+ *     },
+ *   }
+ *   ```
+ *   `url`(또는 deprecated 별칭 `connectionString`) **XOR** discrete(host/port/user/password). `dbName`
+ *   은 connection 과 **별개 축**(client.db 선택)이라 url 과 충돌하지 않으며, url path 에 db 가 있으면
+ *   거기서 추출(명시 `dbName` 우선). 연결·dbName 둘 다 없으면 `adapter.connection_required`/
+ *   `adapter.dbname_required`. pool 매핑: min→minPoolSize, max→maxPoolSize, idleTimeoutMs→maxIdleTimeMS,
+ *   acquireTimeoutMs→waitQueueTimeoutMS. `maxLifetimeMs` 는 mongo 미지원(throw). 비밀번호/url 은
+ *   healthCheck/getStats/에러 details 에 절대 노출하지 않는다(정합).
+ *
+ * @module adapters/mongo-adapter
+ */
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { MegaInternalError, MegaValidationError } from '../errors/http-errors.js'
+import { MegaDbAdapter } from './mega-db-adapter.js'
+import { resolveConnection, normalizePool, assertPlainObject, MONGO_POOL_SPEC } from './adapter-options.js'
+import * as Registry from './registry.js'
+
+/**
+ * @typedef {object} MongoConfig
+ * @property {string} [driver] - 'mongodb' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} [url] - `mongodb://...` 연결 문자열 (discrete 와 배타).
+ * @property {string} [connectionString] - `url` 의 deprecated 별칭 (하위 호환).
+ * @property {string} [host] @property {number} [port] @property {string} [user] @property {string} [password]
+ * @property {string} [dbName] - 선택할 DB (url path 에서 추출 가능, 명시 우선).
+ * @property {{ min?: number, max?: number, idleTimeoutMs?: number, acquireTimeoutMs?: number }} [pool] - 공통 풀 인터페이스.
+ * @property {Record<string, any>} [options] - MongoClient passthrough (authSource, replicaSet, tls, readPreference, serverSelectionTimeoutMS, …).
+ */
+
+/**
+ * url path 에서 dbName 추출 (명시 dbName 없을 때 폴백). multi-host/SRV 등 WHATWG URL 파싱 실패는
+ * undefined 폴백 → 상위에서 dbName 명시 요구로 처리.
+ * @param {string} url @returns {string | undefined}
+ */
+function extractMongoDbName(url) {
+  try {
+    const db = new URL(url).pathname.replace(/^\//, '')
+    return db.length > 0 ? db : undefined
+  } catch {
+    // multi-host(`h1,h2`)/SRV URL 은 표준 URL 파서가 거부할 수 있음 — 추출 실패 시 dbName 명시 요구로 폴백.
+    return undefined
+  }
+}
+
+/**
+ * discrete 연결필드(host/port/user/password)로 mongodb:// URI 구성. authSource 등은 options 로.
+ * @param {{ host?: string, port?: number, user?: string, password?: string }} conn @returns {string}
+ */
+function buildMongoUri({ host, port, user, password }) {
+  const auth = user !== undefined ? `${encodeURIComponent(user)}${password !== undefined ? ':' + encodeURIComponent(password) : ''}@` : ''
+  const hostPart = host ?? 'localhost'
+  const portPart = port !== undefined ? `:${port}` : ''
+  return `mongodb://${auth}${hostPart}${portPart}`
+}
+
+/**
+ * @typedef {object} MongoTxContext - AsyncLocalStorage 에 담기는 트랜잭션 컨텍스트.
+ * @property {import('mongodb').ClientSession} session - 진행 중 트랜잭션을 소유한 세션.
+ */
+
+/**
+ * CMAP(Connection Monitoring and Pooling) 이벤트 누적 카운터. mongodb driver 는 풀 통계를
+ * 직접 노출하는 공개 API 가 없어(`topology` 는 비공개 내부), 표준 CMAP 이벤트(기본 발생)를
+ * 구독해 누적한다. open=created-closed, inUse=checkedOut-checkedIn 으로 파생.
+ * @typedef {object} PoolCounters
+ * @property {number} created @property {number} closed
+ * @property {number} checkedOut @property {number} checkedIn
+ */
+
+export class MegaMongoAdapter extends MegaDbAdapter {
+  /** @type {import('mongodb').MongoClient | null} 연결된 MongoClient (connect 후에만). */
+  #client = null
+  /** @type {import('mongodb').Db | null} 선택된 Db 인스턴스 (connect 후에만). */
+  #db = null
+  /** @type {string} 연결 문자열 (시크릿 포함 — 외부 노출 금지). */
+  #connectionString
+  /** @type {string} 데이터베이스 이름. */
+  #dbName
+  /** @type {import('mongodb').MongoClientOptions} _connect 에서 `new MongoClient()` 에 넘길 옵션. */
+  #clientOptions
+  /**
+   * 진행 중 트랜잭션 추적기 — nested 호출을 감지해 거부한다(인스턴스 카운터 X).
+   * 동시 top-level 트랜잭션은 각자 `run` 으로 격리된 store 를 가진다(async race-free, Postgres 정합).
+   * @type {AsyncLocalStorage<MongoTxContext>}
+   */
+  #txContext = new AsyncLocalStorage()
+  /** @type {PoolCounters} CMAP 이벤트 누적 풀 카운터. */
+  #pool = { created: 0, closed: 0, checkedOut: 0, checkedIn: 0 }
+  /**
+   * 등록한 CMAP 리스너 — disconnect 시 정확히 제거하기 위해 보관(누수·재연결 시 중복 방지).
+   * @type {Array<[string, (...args: any[]) => void]>}
+   */
+  #poolListeners = []
+
+  /**
+   * @param {MongoConfig} [config] - services.databases.<key> 설정.
+   * @throws {MegaValidationError} `adapter.connection_required` - url·discrete 둘 다 없음.
+   * @throws {MegaValidationError} `adapter.connection_conflict` - url + discrete 동시 지정.
+   * @throws {MegaValidationError} `adapter.dbname_required` - dbName 누락 + url path 에도 없음.
+   * @throws {MegaValidationError} `adapter.invalid_option` - 옵션 타입/범위 오류.
+   */
+  constructor(config = /** @type {any} */ ({})) {
+    super(config)
+
+    // 연결 모드(url XOR discrete) 결정. dbName 은 connection 과 별개 축이라 url 과 충돌하지 않음(ADR-109).
+    const conn = resolveConnection(config, { driver: 'mongodb', dbConflictsWithUrl: false })
+    const uri = conn.url !== undefined ? conn.url : buildMongoUri(conn)
+
+    // dbName: 명시 우선, 없으면 url path 에서 추출. 둘 다 없으면 fail-fast(client.db(dbName) 필수).
+    let dbName = config.dbName
+    if ((dbName === undefined || dbName === null) && conn.url !== undefined) {
+      dbName = extractMongoDbName(conn.url)
+    }
+    if (typeof dbName !== 'string' || dbName.length === 0) {
+      throw new MegaValidationError(
+        'adapter.dbname_required',
+        'mongodb: "dbName" is required (the database to select via client.db(dbName)). Provide it explicitly or include a path in the url (mongodb://host/<dbName>).',
+        { details: { driver: 'mongodb', dbName: dbName ?? null } },
+      )
+    }
+    this.#connectionString = uri
+    this.#dbName = dbName
+
+    // 공통 풀 인터페이스 → mongo 풀 키 매핑 + options passthrough.
+    const poolOpts = normalizePool(config.pool, MONGO_POOL_SPEC, 'mongodb')
+    assertPlainObject('options', config.options, { driver: 'mongodb' })
+    /** @type {import('mongodb').MongoClientOptions} */
+    const clientOptions = {}
+    if (config.options !== undefined) Object.assign(clientOptions, config.options)
+    Object.assign(clientOptions, poolOpts) // pool(정규화) 나중 — 겹치면 명시 pool 인터페이스가 이긴다.
+    this.#clientOptions = clientOptions
+  }
+
+  /**
+   * `MongoClient` 생성 + connect + `ping` 으로 실제 연결 검증.
+   * driver 는 **connect 시점에 lazy import** — 모듈 import(배럴 경유 자기등록)만으로는 mongodb 를
+   * 로드하지 않아, 본 어댑터를 안 쓰는 환경이 mongodb 설치를 강제받지 않는다(SQL 어댑터 정합).
+   *
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _connect() {
+    const { MongoClient } = await import('mongodb')
+    const client = new MongoClient(this.#connectionString, this.#clientOptions)
+    // CMAP 풀 이벤트 구독은 connect 전에 — 초기 연결 생성/체크아웃 이벤트도 빠짐없이 카운트.
+    this.#subscribePoolEvents(client)
+    try {
+      await client.connect()
+      const db = client.db(this.#dbName)
+      // connect 직후 실제 ping 으로 연결·인증 검증 — 잘못된 자격증명/호스트를 부팅 시 잡는다(fail-fast).
+      await db.command({ ping: 1 })
+      this.#client = client
+      this.#db = db
+    } catch (err) {
+      // 검증 실패 시 leak 방지를 위해 client 정리 후 원본 에러 전파.
+      this.#unsubscribePoolEvents(client)
+      try {
+        await client.close()
+      } catch (closeErr) {
+        // 검증 실패 후 정리(close) 실패는 비치명적 — 원본 연결 에러가 진짜 원인.
+        console.warn('[MegaMongoAdapter] client.close() failed after connect validation error (original error wins):', closeErr)
+      }
+      throw err
+    }
+  }
+
+  /**
+   * MongoClient 종료(모든 연결 정리). 베이스 상태 머신이 connected 상태에서만 호출 보장.
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _disconnect() {
+    if (this.#client !== null) {
+      const client = this.#client
+      this.#client = null
+      this.#db = null
+      this.#unsubscribePoolEvents(client)
+      await client.close()
+    }
+  }
+
+  /**
+   * raw Db handle (ADR-009). `connect()` 후에만 베이스 `native` getter 가 호출한다.
+   * @protected
+   * @returns {import('mongodb').Db}
+   */
+  _native() {
+    if (this.#db === null) {
+      // 베이스 native getter 가 state 검증을 먼저 하므로 정상 경로에선 도달 안 함 — 방어.
+      return this._notImplemented('native')
+    }
+    return this.#db
+  }
+
+  /**
+   * 헬스 체크 — 실제 `ping` 으로 응답성 확인 (베이스 디폴트는 상태만 반영).
+   * 실패는 throw 없이 `ok:false` + 사유(베이스 계약). 비밀번호/connectionString 은 노출하지 않는다.
+   *
+   * @returns {Promise<{ ok: boolean, driver: 'mongodb', state: string, dbName?: string, error?: string }>}
+   */
+  async healthCheck() {
+    if (this.state !== 'connected' || this.#db === null) {
+      return { ok: false, driver: 'mongodb', state: this.state }
+    }
+    try {
+      const res = await this.#db.command({ ping: 1 })
+      // mongo ping 응답은 `{ ok: 1 }`.
+      const ok = res?.ok === 1
+      return { ok, driver: 'mongodb', state: this.state, dbName: this.#dbName }
+    } catch (err) {
+      return {
+        ok: false,
+        driver: 'mongodb',
+        state: this.state,
+        dbName: this.#dbName,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+
+  /**
+   * 누적 통계 + mongo 특화(driver/dbName + CMAP 풀 카운터). 연결 전이면 카운터는 0.
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, dbName: string, pool: { created: number, closed: number, checkedOut: number, checkedIn: number, open: number, inUse: number } }}
+   */
+  getStats() {
+    const { created, closed, checkedOut, checkedIn } = this.#pool
+    return {
+      ...super.getStats(),
+      driver: 'mongodb',
+      dbName: this.#dbName,
+      pool: {
+        created,
+        closed,
+        checkedOut,
+        checkedIn,
+        // 파생값 — open=살아있는 연결 수, inUse=현재 체크아웃된(작업 중) 연결 수.
+        open: created - closed,
+        inUse: checkedOut - checkedIn,
+      },
+    }
+  }
+
+  /**
+   * 명시적 트랜잭션 경계 (ADR-010, ADR-108). `session.withTransaction` 에 위임한다 —
+   * driver 가 commit/abort + transient 에러 자동 retry 를 관리(모듈 docstring 참조).
+   *
+   * `fn` 은 `(db, session)` 을 받는다. 성공 시 driver 가 commit 후 `fn` 반환값을 그대로 돌려주고,
+   * throw 시 abort 후 원본 에러를 re-throw 한다. nested 호출은 ALS 로 감지해 거부(Sqlite 와 동일).
+   * `session.endSession()` 은 `finally` 에서 반드시 호출(leak 방지).
+   *
+   * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
+   *
+   * @template T
+   * @param {(db: import('mongodb').Db, session: import('mongodb').ClientSession) => Promise<T> | T} fn
+   * @returns {Promise<T>}
+   * @throws {MegaInternalError} `adapter.nested_transaction_unsupported` - 이미 트랜잭션 진행 중.
+   */
+  async withTransaction(fn) {
+    return this._instrument('withTransaction', { table: undefined }, async () => {
+      // nested 거부 — 진행 중 트랜잭션이 있으면 즉시 throw (Sqlite 와 동일 정책·에러 코드, ADR-108).
+      // 검사를 driver 호출 전에 두어, standalone(트랜잭션 미지원)에서도 nested 거부는 동작한다.
+      if (this.#txContext.getStore() !== undefined) {
+        throw new MegaInternalError(
+          'adapter.nested_transaction_unsupported',
+          `${this.constructor.name}.withTransaction() cannot nest — a transaction is already in progress on this session (ADR-108). MongoDB does not support nested transactions within one session.`,
+          { details: { adapter: this.constructor.name, dbName: this.#dbName } },
+        )
+      }
+      const client = /** @type {import('mongodb').MongoClient} */ (this.#client)
+      const db = /** @type {import('mongodb').Db} */ (this.#db)
+      const session = client.startSession()
+      try {
+        // ALS 로 세션을 격리 — 내부에서 withTransaction 재호출 시 store 가 보여 nested 거부됨.
+        // session.withTransaction(v6)은 콜백 반환값을 그대로 반환한다(공식 문서).
+        return await this.#txContext.run({ session }, () => session.withTransaction(async () => fn(db, session)))
+      } finally {
+        // 성공/실패 무관 — 세션 반드시 정리(leak 방지). endSession 실패는 원본 결과/에러를
+        // 가리지 않도록 격리 후 경고만.
+        try {
+          await session.endSession()
+        } catch (endErr) {
+          console.warn('[MegaMongoAdapter] session.endSession() failed (original result/error wins):', endErr)
+        }
+      }
+    })
+  }
+
+  /**
+   * CMAP 풀 이벤트(기본 발생)를 구독해 풀 카운터를 누적한다. mongodb driver 가 풀 통계를 직접
+   * 노출하지 않으므로 표준 이벤트로 대체(getStats 의 pool 필드). 리스너는 disconnect 시 제거한다.
+   *
+   * @param {import('mongodb').MongoClient} client
+   * @returns {void}
+   */
+  #subscribePoolEvents(client) {
+    /** @type {Array<[string, () => void]>} */
+    const listeners = [
+      ['connectionCreated', () => (this.#pool.created += 1)],
+      ['connectionClosed', () => (this.#pool.closed += 1)],
+      ['connectionCheckedOut', () => (this.#pool.checkedOut += 1)],
+      ['connectionCheckedIn', () => (this.#pool.checkedIn += 1)],
+    ]
+    for (const [event, handler] of listeners) {
+      client.on(event, handler)
+      this.#poolListeners.push([event, handler])
+    }
+  }
+
+  /**
+   * 구독했던 CMAP 리스너를 정확히 제거(누수·재연결 중복 방지).
+   * @param {import('mongodb').MongoClient} client
+   * @returns {void}
+   */
+  #unsubscribePoolEvents(client) {
+    for (const [event, handler] of this.#poolListeners) {
+      client.off(event, handler)
+    }
+    this.#poolListeners = []
+  }
+}
+
+// 빌트인 driver 자기등록 (ADR-044) — 배럴(`adapters/index.js`)이 본 모듈을 import 하면 트리거된다.
+// mongodb 는 _connect() 의 lazy import 까지 로드되지 않으므로 등록은 안전(미사용 환경 비강제).
+Registry.register('mongodb', MegaMongoAdapter)