mega-framework 0.1.0

package/sample/simple/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "sample-simple",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "NODE_ENV=development mega start",
+    "start": "NODE_ENV=production mega start",
+    "scheduler": "mega scheduler",
+    "worker": "mega worker",
+    "ws-hub": "mega-ws-hub",
+    "dev:all": "NODE_ENV=development concurrently -n server,scheduler,worker -c blue,green,magenta \"mega start\" \"mega scheduler\" \"mega worker\"",
+    "test": "mega test"
+  },
+  "dependencies": {
+    "mega-framework": "file:../.."
+  },
+  "devDependencies": {
+    "concurrently": "^9.0.0",
+    "vitest": "^2.0.0"
+  }
+}

package/sample/simple/test/apps/main/index.test.js

@@ -0,0 +1,13 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import routes from '../../../apps/main/routes/index.js'
+
+describe('main app index route', () => {
+  test('GET / 등록 + hello world 반환', async () => {
+    /** @type {Function|undefined} */
+    let handler
+    routes({ http: { get: (/** @type {string} */ _p, /** @type {Function} */ h) => void (handler = h) } })
+    expect(typeof handler).toBe('function')
+    expect(await /** @type {any} */ (handler)({}, {}, {})).toEqual({ message: 'Hello from sample-simple!' })
+  })
+})

package/sample/simple/vitest.config.js

@@ -0,0 +1,8 @@
+// @ts-check
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.js', 'apps/**/*.test.js', 'shared/**/*.test.js'],
+  },
+})

package/src/adapters/adapter-manager.js

@@ -0,0 +1,305 @@
+// @ts-check
+/**
+ * MegaAdapterManager — 전역 어댑터 인스턴스 매니저 (ADR-102).
+ *
+ * **글로벌 공유 모델**(오너 확정): 어댑터 인스턴스는 `mega.config.js` 의
+ * `services.databases/caches/buses.<globalKey>` 에 **딱 한 번** 정의되고, 부팅 시 본 매니저가
+ * driver 레지스트리로 인스턴스화해 보관한다. 여러 앱이 같은 backend 를 써도 인스턴스는 1개
+ * (앱은 `app.config.js` 의 `databases: { alias: globalKey }` 로 **별명 참조**만 함, ADR-064).
+ *
+ * registry / mega-health / mega-shutdown 과 같은 **모듈 레벨 싱글톤** 패턴이다 — 전역 자원을
+ * 한 군데서 관리하므로 import 만으로 어디서든 같은 인스턴스를 본다.
+ *
+ * # 부팅·종료 (08-class-specs §3.2, docs/10 DisconnectingAdapters)
+ *   1. `buildFromGlobalConfig(global)` — driver 매핑으로 `new AdapterClass(cfg)` (lifecycle 1단계).
+ *      동시에 LIFO shutdown hook 을 **MegaApp 생성보다 먼저** 등록한다(아래 "종료 순서" 주석).
+ *   2. `connectAll({ ping })` — 모든 인스턴스 `connect()` 병렬. 하나라도 실패하면 부팅 abort(fail-fast)
+ *      하되, 그 전에 이미 connect 된 어댑터를 LIFO 자동 cleanup 해 leak 방지(ADR-102 QA M-A).
+ *      `ping:true` 면 connect 후 `healthCheck()` 까지 검증.
+ *   3. `disconnectAll()` — 등록 **역순(LIFO)** disconnect. shutdown 중이므로 개별 실패는 warn 후 계속.
+ *
+ * # `ctx.db/cache/bus` 와의 관계
+ *   `ctx.<domain>(alias)` 는 앱 별명을 globalKey 로 바꾼 뒤 {@link get} 으로 본 매니저의 공유
+ *   인스턴스를 돌려준다 (src/core/ctx-builder.js). 등록 안 된 키는 즉시 throw (silent X).
+ *
+ * @module adapters/adapter-manager
+ */
+import { MegaConfigError } from '../errors/config-error.js'
+import { MegaShutdown } from '../lib/mega-shutdown.js'
+import { buildAdapterEnvConfig } from '../lib/env-mapper.js'
+import * as Registry from './registry.js'
+import { MegaDbAdapter } from './mega-db-adapter.js'
+import { MegaCacheAdapter } from './mega-cache-adapter.js'
+import { MegaBusAdapter } from './mega-bus-adapter.js'
+import { MegaLockAdapter } from './mega-lock-adapter.js'
+
+/**
+ * ctx 도메인 ↔ config 키 ↔ 도메인 베이스 매핑 (canonical: db/cache/bus + lock, docs/03 §581 + ADR-113).
+ * `expect` 는 driver 가 엉뚱한 도메인에 등록되는 사고를 부팅 시 잡기 위한 instanceof 검증용 (도메인 베이스).
+ * @type {Record<'db'|'cache'|'bus'|'lock', { configKey: 'databases'|'caches'|'buses'|'locks', expect: typeof import('./mega-adapter.js').MegaAdapter }>}
+ */
+const DOMAIN_SPEC = {
+  db: { configKey: 'databases', expect: MegaDbAdapter },
+  cache: { configKey: 'caches', expect: MegaCacheAdapter },
+  bus: { configKey: 'buses', expect: MegaBusAdapter },
+  lock: { configKey: 'locks', expect: MegaLockAdapter },
+}
+
+/** shutdown hook 이름 — 재빌드/리셋 시 중복 등록 방지용 고정 키. */
+const SHUTDOWN_HOOK = 'adapters:disconnect'
+
+/**
+ * @typedef {object} AdapterEntry
+ * @property {'db'|'cache'|'bus'|'lock'} domain
+ * @property {string} key - globalKey (services.<configKey>.<key>).
+ * @property {string} driver
+ * @property {import('./mega-adapter.js').MegaAdapter} adapter
+ */
+
+/** @type {Map<string, AdapterEntry>} `${domain}:${key}` → entry. */
+let instances = new Map()
+/** @type {string[]} 삽입(=connect) 순서 — disconnect LIFO 용. */
+let order = []
+
+/**
+ * `${domain}:${key}` 합성 id.
+ * @param {string} domain @param {string} key @returns {string}
+ */
+function idOf(domain, key) {
+  return `${domain}:${key}`
+}
+
+/**
+ * 전역 config(`services.databases/caches/buses`)로부터 어댑터 인스턴스를 만든다 (lifecycle 1단계).
+ *
+ * 각 도메인의 `<globalKey>: { driver, ...opts }` 마다 `registry.resolve(driver)` → `new Cls(opts)`.
+ * driver 미등록(빌트인은 import 시 자기등록)·미지정·도메인 불일치는 즉시 throw (부팅 abort, fail-fast).
+ *
+ * # 종료 순서 (중요)
+ *   본 함수가 LIFO shutdown hook 을 등록하므로, **MegaApp 생성보다 먼저** 호출해야 한다. MegaShutdown
+ *   은 LIFO(나중 등록이 먼저 실행) — 어댑터 hook 을 앱 hook 보다 먼저 등록하면, 종료 시 앱(HTTP/WS)이
+ *   먼저 닫히고 그 다음 어댑터가 끊긴다(docs/10: ClosingHttp → … → DisconnectingAdapters).
+ *
+ * @param {{ services?: Record<string, any> }} [globalConfig] - mega.config.js (default export).
+ * @param {{ registerShutdownHook?: boolean }} [opts] - 테스트 격리용으로 hook 등록을 끌 수 있음(기본 on).
+ * @returns {void}
+ */
+export function buildFromGlobalConfig(globalConfig, { registerShutdownHook = true } = {}) {
+  const services = globalConfig?.services ?? {}
+  for (const [domain, { configKey, expect }] of Object.entries(DOMAIN_SPEC)) {
+    const map = services[configKey]
+    if (map === undefined || map === null) continue
+    if (typeof map !== 'object' || Array.isArray(map)) {
+      throw new MegaConfigError(
+        'adapter.invalid_services',
+        `services.${configKey} must be a plain object of { key: { driver, ... } }.`,
+        { details: { configKey, type: Array.isArray(map) ? 'array' : typeof map } },
+      )
+    }
+    for (const [key, cfg] of Object.entries(map)) {
+      if (!cfg || typeof cfg !== 'object' || typeof (/** @type {any} */ (cfg).driver) !== 'string') {
+        throw new MegaConfigError(
+          'adapter.missing_driver',
+          `services.${configKey}.${key} must specify a string "driver".`,
+          { details: { domain, key } },
+        )
+      }
+      const driver = /** @type {any} */ (cfg).driver
+      const AdapterClass = Registry.resolve(driver) // 미등록 → adapter.unknown_driver
+      // .env 자동 주입 (12-factor, ADR-109) — `envPrefix` 지정 시 MEGA_<PREFIX>_* 를 어댑터 옵션으로
+      // 매핑해 파일 config 위에 병합(env 가 우선). 미지정이면 무시(기존 동작 무변경).
+      const effectiveCfg = mergeEnvConfig(/** @type {Record<string, any>} */ (cfg))
+      const adapter = new AdapterClass(effectiveCfg)
+      // driver 가 엉뚱한 도메인 키에 들어간 사고(예: redis 를 databases 에)를 부팅 시 잡는다.
+      if (!(adapter instanceof expect)) {
+        throw new MegaConfigError(
+          'adapter.domain_mismatch',
+          `driver "${driver}" (services.${configKey}.${key}) is not a ${expect.name}.`,
+          { details: { domain, key, driver, expected: expect.name } },
+        )
+      }
+      const id = idOf(domain, key)
+      instances.set(id, { domain: /** @type {'db'|'cache'|'bus'|'lock'} */ (domain), key, driver, adapter })
+      order.push(id)
+    }
+  }
+
+  if (registerShutdownHook) {
+    // 재빌드 안전 — 항상 1개만 유지(MegaApp 의 hublink hook 패턴과 동일).
+    MegaShutdown.unregister(SHUTDOWN_HOOK)
+    MegaShutdown.register(SHUTDOWN_HOOK, async () => disconnectAll())
+  }
+}
+
+/**
+ * `envPrefix` 가 있으면 `MEGA_<PREFIX>_*` 환경변수를 어댑터 옵션으로 매핑해 파일 config 위에 병합한다
+ * (12-factor, ADR-109). env 가 파일 값을 **덮어쓴다**(배포별 오버라이드). pool/options 는 1단계 deep-merge.
+ * `envPrefix` 키는 어댑터에 넘기지 않는다(드라이버 무관 메타).
+ *
+ * `cfg.driver` 를 env-mapper 에 전달해 OPTIONS_* 키를 driver 표기(camel/snake)로 변환한다
+ * (camelCase 드라이버에 snake 키가 조용히 무시되던 버그 교정).
+ *
+ * @param {Record<string, any>} cfg - services.<configKey>.<key> 설정.
+ * @returns {Record<string, any>} 병합된 config (envPrefix 없으면 cfg 그대로).
+ */
+function mergeEnvConfig(cfg) {
+  const envPrefix = cfg.envPrefix
+  if (typeof envPrefix !== 'string' || envPrefix.length === 0) return cfg
+  const envCfg = buildAdapterEnvConfig(envPrefix, process.env, { driver: cfg.driver })
+  const merged = { ...cfg, ...envCfg }
+  if (cfg.pool || envCfg.pool) merged.pool = { ...(cfg.pool ?? {}), ...(envCfg.pool ?? {}) }
+  if (cfg.options || envCfg.options) merged.options = { ...(cfg.options ?? {}), ...(envCfg.options ?? {}) }
+  delete merged.envPrefix
+  return merged
+}
+
+/**
+ * 도메인+globalKey 로 공유 어댑터 인스턴스 조회. 없으면 `adapter.not_registered` throw (silent X).
+ *
+ * @param {'db'|'cache'|'bus'|'lock'} domain
+ * @param {string} key - globalKey.
+ * @returns {import('./mega-adapter.js').MegaAdapter}
+ */
+export function get(domain, key) {
+  const entry = instances.get(idOf(domain, key))
+  if (entry === undefined) {
+    throw new MegaConfigError(
+      'adapter.not_registered',
+      `No ${domain} adapter registered for key "${key}". Registered ${domain}: [${listDomain(domain).join(', ') || '(none)'}].`,
+      { details: { domain, key, registered: listDomain(domain) } },
+    )
+  }
+  return entry.adapter
+}
+
+/**
+ * 등록 여부 (Boolean — `has*`, ADR-036).
+ * @param {'db'|'cache'|'bus'|'lock'} domain @param {string} key @returns {boolean}
+ */
+export function has(domain, key) {
+  return instances.has(idOf(domain, key))
+}
+
+/**
+ * 한 도메인에 등록된 globalKey 목록.
+ * @param {'db'|'cache'|'bus'|'lock'} domain @returns {string[]}
+ */
+function listDomain(domain) {
+  return order.filter((id) => instances.get(id)?.domain === domain).map((id) => /** @type {AdapterEntry} */ (instances.get(id)).key)
+}
+
+/**
+ * 전체 인스턴스 스냅샷 (디버그·테스트·헬스용). 등록 순서대로.
+ * @returns {Array<{ domain: 'db'|'cache'|'bus'|'lock', key: string, driver: string, state: string }>}
+ */
+export function list() {
+  return order.map((id) => {
+    const e = /** @type {AdapterEntry} */ (instances.get(id))
+    return { domain: e.domain, key: e.key, driver: e.driver, state: e.adapter.state }
+  })
+}
+
+/**
+ * 전체 어댑터 엔트리(인스턴스 포함)를 등록 순서대로 반환 — 외부 부착자(`MegaTracing`)가
+ * 모든 공유 어댑터에 hook 리스너를 일괄 구독할 때 쓴다. {@link list} 와 달리 raw 어댑터 인스턴스를
+ * 노출하므로 디버그·트레이싱 부착 외 용도로는 신중히 사용.
+ *
+ * @returns {AdapterEntry[]}
+ */
+export function entries() {
+  return order.map((id) => /** @type {AdapterEntry} */ (instances.get(id)))
+}
+
+/**
+ * 모든 어댑터 connect (부팅 6단계). 병렬 시도하되 **fail-fast + 자동 cleanup** (ADR-102 QA M-A).
+ * 하나라도 실패하면 부팅을 abort 하기 위해 첫 실패 에러를 throw 하는데, 그 전에 이미 connect 된
+ * 어댑터를 **등록 역순(LIFO)으로 best-effort disconnect** 해서 연결 풀 leak 을 막는다 — 호출자가
+ * catch 안 해도 매니저 레벨에서 자원을 회수한다(call-site CLI 책임에만 의존하지 않음).
+ *
+ * `ping:true` 면 connect 직후 `healthCheck()` 를 1회 호출해 ok=false 면 `adapter.health_failed`
+ * throw (헬스까지 검증). ping 실패 어댑터도 connect 자체는 성공했으므로 cleanup 대상에 포함된다.
+ *
+ * cleanup 중 disconnect 가 실패해도 원래 connect 실패 에러를 우선 전파한다 — cleanup 실패는
+ * 비치명적이라 warn 로그만 남기고 삼킨다(부팅 abort 정리 중 한 어댑터 정리 실패가
+ * 진짜 원인(connect 실패)을 덮으면 안 됨).
+ *
+ * @param {{ logger?: any, ping?: boolean }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function connectAll({ logger, ping = false } = {}) {
+  /** @type {Set<number>} connect() 성공한 어댑터의 order 인덱스 (ping 전 기준 — ping 실패도 cleanup). */
+  const connectedIdx = new Set()
+  // canonical 병렬이되 reject 를 즉시 전파하지 않고 allSettled 로 전부 수집 — 부분 성공분을
+  // cleanup 한 뒤 첫 실패를 던지기 위함.
+  const results = await Promise.allSettled(
+    order.map(async (id, idx) => {
+      const e = /** @type {AdapterEntry} */ (instances.get(id))
+      await e.adapter.connect()
+      connectedIdx.add(idx) // connect 성공 — ping 실패하더라도 cleanup 대상.
+      if (ping) {
+        const health = await e.adapter.healthCheck()
+        if (!health?.ok) {
+          throw new MegaConfigError(
+            'adapter.health_failed',
+            `boot ping failed for ${e.domain}:${e.key} (${e.driver}).`,
+            { details: { domain: e.domain, key: e.key, driver: e.driver, health } },
+          )
+        }
+      }
+      logger?.info?.(
+        { adapter: e.adapter.constructor.name, domain: e.domain, key: e.key, driver: e.driver, state: e.adapter.state },
+        'adapter connected',
+      )
+    }),
+  )
+
+  const firstRejected = results.find((r) => r.status === 'rejected')
+  if (firstRejected === undefined) return // 전원 성공
+
+  // fail-fast cleanup: 이미 connect 된 어댑터를 등록 역순(LIFO)으로 disconnect (best-effort).
+  for (let i = order.length - 1; i >= 0; i--) {
+    if (!connectedIdx.has(i)) continue
+    const e = /** @type {AdapterEntry} */ (instances.get(order[i]))
+    try {
+      await e.adapter.disconnect()
+      logger?.debug?.({ domain: e.domain, key: e.key }, 'adapter cleanup disconnected (connectAll abort)')
+    } catch (cleanupErr) {
+      // cleanup 실패는 비치명적 — 원본 connect 실패 에러를 우선 전파해야 하므로 여기선 throw 하지 않음.
+      logger?.warn?.(
+        { err: cleanupErr, domain: e.domain, key: e.key },
+        'adapter cleanup disconnect failed during connectAll abort (continuing, original connect error wins)',
+      )
+    }
+  }
+  // 원래 부팅 실패 원인(첫 connect/ping 에러)을 그대로 전파 → 호출자는 동일한 fail-fast 동작을 본다.
+  throw /** @type {PromiseRejectedResult} */ (firstRejected).reason
+}
+
+/**
+ * 모든 어댑터 disconnect — 등록 **역순(LIFO)** (docs/10 §6, 07-sequence-diagrams §6). graceful
+ * shutdown 중이므로 개별 disconnect 실패는 비치명적: warn 후 다음 어댑터로 계속한다( * 한 어댑터 정리 실패가 나머지 정리를 막으면 안 됨).
+ *
+ * @param {{ logger?: any }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function disconnectAll({ logger } = {}) {
+  for (let i = order.length - 1; i >= 0; i--) {
+    const e = /** @type {AdapterEntry} */ (instances.get(order[i]))
+    try {
+      await e.adapter.disconnect()
+      logger?.debug?.({ domain: e.domain, key: e.key }, 'adapter disconnected')
+    } catch (err) {
+      logger?.warn?.({ err, domain: e.domain, key: e.key }, 'adapter disconnect failed (continuing shutdown)')
+    }
+  }
+}
+
+/**
+ * 테스트용 reset — 인스턴스 비우고 shutdown hook 해제.
+ * @returns {void}
+ */
+export function _reset() {
+  instances = new Map()
+  order = []
+  MegaShutdown.unregister(SHUTDOWN_HOOK)
+}

package/src/adapters/adapter-options.js

@@ -0,0 +1,208 @@
+// @ts-check
+/**
+ * 어댑터 옵션 표준화 공용 헬퍼 (ADR-109).
+ *
+ * Postgres/Maria/Mongo 3 어댑터가 공유하는 **통합 옵션 구조**의 파싱·검증 로직을 한 곳에 모은다.
+ * 각 어댑터가 같은 시그니처를 받도록 해 12-factor(.env 외부 주입) + advanced 옵션(pool/options) 을
+ * 일관되게 지원한다.
+ *
+ * # 통합 시그니처
+ *   ```js
+ *   {
+ *     driver,                              // 매니저가 사용 — 어댑터는 무시
+ *     url? | connectionString?,            // 연결 URL (connectionString 은 deprecated 별칭)
+ *     host?, port?, user?, password?,      // discrete 연결 (url 과 상호 배타)
+ *     database? | dbName?,                 // SQL=database / Mongo=dbName
+ *     pool?: { min?, max?, idleTimeoutMs?, acquireTimeoutMs?, maxLifetimeMs? },  // 공통 풀 인터페이스
+ *     options?: { ...driver-native passthrough }   // 드라이버 특화 옵션 그대로 전달
+ *   }
+ *   ```
+ *
+ * # 연결 모드 충돌·필수 (모호하면 부팅 시 fail-fast)
+ *   - `url` + discrete 연결필드(host/port/user/password[/database]) 동시 지정 → `adapter.connection_conflict`.
+ *   - `url`·discrete 둘 다 없음 → `adapter.connection_required`.
+ *   - `url` + `pool`/`options` 조합은 **허용** — url 은 connection 정보만, pool/options 는 별도 축.
+ *
+ * # 공통 풀 인터페이스 → 드라이버 풀 옵션 매핑 (단위 주의, 드라이버 타입 직접 확인)
+ *   | 공통 키            | pg                         | mariadb                  | mongodb            |
+ *   |--------------------|----------------------------|--------------------------|--------------------|
+ *   | min                | min                        | minimumIdle              | minPoolSize        |
+ *   | max                | max                        | connectionLimit          | maxPoolSize        |
+ *   | idleTimeoutMs (ms) | idleTimeoutMillis (ms)     | idleTimeout (**초**)     | maxIdleTimeMS (ms) |
+ *   | acquireTimeoutMs   | connectionTimeoutMillis(ms)| acquireTimeout (ms)      | waitQueueTimeoutMS |
+ *   | maxLifetimeMs (ms) | maxLifetimeSeconds (**초**)| (미지원)                 | (미지원)           |
+ *   `idleTimeoutMs`→mariadb·`maxLifetimeMs`→pg 는 ms→초 변환(÷1000, floor). mariadb/mongo 는
+ *   풀 maxLifetime 동등물이 없어 `maxLifetimeMs` 지정 시 `adapter.invalid_option` throw(silent 무시 X).
+ *
+ * @module adapters/adapter-options
+ */
+import { MegaValidationError } from '../errors/http-errors.js'
+
+/**
+ * `adapter.invalid_option` 생성 헬퍼.
+ * @param {string} message @param {Record<string, unknown>} details
+ * @returns {MegaValidationError}
+ */
+function invalidOption(message, details) {
+  return new MegaValidationError('adapter.invalid_option', message, { details })
+}
+
+/**
+ * 양의 정수(> 0) 검증 (undefined 통과). 위반 시 `adapter.invalid_option` throw.
+ * @param {string} name @param {unknown} value @param {Record<string, unknown>} [extra] @returns {void}
+ */
+export function assertPositiveInt(name, value, extra = {}) {
+  if (value === undefined) return
+  if (!Number.isInteger(value) || /** @type {number} */ (value) <= 0) {
+    throw invalidOption(`"${name}" must be a positive integer.`, { option: name, value, ...extra })
+  }
+}
+
+/**
+ * 음 아닌 정수(>= 0) 검증 (undefined 통과). 0 은 드라이버에서 "무제한/즉시/never" 의미로 허용.
+ * @param {string} name @param {unknown} value @param {Record<string, unknown>} [extra] @returns {void}
+ */
+export function assertNonNegativeInt(name, value, extra = {}) {
+  if (value === undefined) return
+  if (!Number.isInteger(value) || /** @type {number} */ (value) < 0) {
+    throw invalidOption(`"${name}" must be a non-negative integer.`, { option: name, value, ...extra })
+  }
+}
+
+/**
+ * 플레인 객체 검증 (undefined 통과). 배열·null·non-object 거부.
+ * @param {string} name @param {unknown} value @param {Record<string, unknown>} [extra] @returns {void}
+ */
+export function assertPlainObject(name, value, extra = {}) {
+  if (value === undefined) return
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw invalidOption(`"${name}" must be a plain object.`, { option: name, type: Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value, ...extra })
+  }
+}
+
+/**
+ * 연결 모드 결정(url XOR discrete) + 충돌·필수 검증.
+ *
+ * @param {Record<string, any>} config - 어댑터 생성자 config.
+ * @param {object} opts
+ * @param {string} opts.driver - 에러 details 용 드라이버명('postgres'|'mariadb'|'mongodb').
+ * @param {string} [opts.dbKey] - discrete db 키 이름(SQL='database', 기본값). Mongo 는 'dbName' 을
+ *   url 과 충돌시키지 않으므로 별도 처리(아래 dbConflictsWithUrl 참조).
+ * @param {boolean} [opts.dbConflictsWithUrl] - db 키가 url 과 상호 배타인지(SQL=true). Mongo 의 dbName 은
+ *   url(=connection)과 별개(=db 선택)라 false.
+ * @returns {{ url?: string, host?: string, port?: number, user?: string, password?: string, database?: string }}
+ *   url 모드면 `{ url }`, discrete 모드면 존재하는 연결필드만. (database 는 dbConflictsWithUrl=true 일 때만 포함.)
+ * @throws {MegaValidationError} `adapter.connection_conflict` / `adapter.connection_required` / `adapter.invalid_option`
+ */
+export function resolveConnection(config, { driver, dbKey = 'database', dbConflictsWithUrl = true }) {
+  // url 또는 deprecated 별칭 connectionString.
+  const url = config.url ?? config.connectionString
+  const hasUrl = url !== undefined && url !== null
+  if (hasUrl && (typeof url !== 'string' || url.length === 0)) {
+    throw invalidOption(`${driver} "url" (or "connectionString") must be a non-empty string.`, { driver, option: 'url', type: typeof url })
+  }
+
+  const discreteKeys = ['host', 'port', 'user', 'password']
+  if (dbConflictsWithUrl) discreteKeys.push(dbKey)
+  const present = discreteKeys.filter((k) => config[k] !== undefined)
+
+  if (hasUrl && present.length > 0) {
+    // url 은 connection 정보를 모두 담으므로 discrete 와 섞으면 어느 쪽이 이기는지 모호 → 명시 거부.
+    throw new MegaValidationError(
+      'adapter.connection_conflict',
+      `${driver}: "url" cannot be combined with discrete connection fields (${present.join(', ')}). Use one connection mode (pool/options are allowed with either).`,
+      { details: { driver, discreteKeys: present } },
+    )
+  }
+  if (!hasUrl && present.length === 0) {
+    throw new MegaValidationError(
+      'adapter.connection_required',
+      `${driver}: a "url" or discrete connection fields (host/port/user/password${dbConflictsWithUrl ? '/' + dbKey : ''}) are required.`,
+      { details: { driver } },
+    )
+  }
+
+  assertPositiveInt('port', config.port, { driver })
+
+  /** @type {Record<string, any>} */
+  const out = {}
+  if (hasUrl) {
+    out.url = url
+    return out
+  }
+  for (const k of ['host', 'port', 'user', 'password']) if (config[k] !== undefined) out[k] = config[k]
+  if (dbConflictsWithUrl && config[dbKey] !== undefined) out[dbKey] = config[dbKey]
+  return out
+}
+
+/**
+ * pg 풀 매핑 — 값이 null 이면 미지원(throw), `{ key, divideBy? }` 면 키 이름 변경(+단위 변환).
+ * @type {Record<string, { key: string, divideBy?: number } | null>}
+ */
+export const PG_POOL_SPEC = {
+  min: { key: 'min' },
+  max: { key: 'max' },
+  idleTimeoutMs: { key: 'idleTimeoutMillis' },
+  acquireTimeoutMs: { key: 'connectionTimeoutMillis' },
+  maxLifetimeMs: { key: 'maxLifetimeSeconds', divideBy: 1000 }, // pg 는 초 단위
+}
+
+/**
+ * mariadb 풀 매핑 — idleTimeout 은 초 단위(ms÷1000). maxLifetime 동등물 없음(미지원).
+ * @type {Record<string, { key: string, divideBy?: number } | null>}
+ */
+export const MARIA_POOL_SPEC = {
+  min: { key: 'minimumIdle' },
+  max: { key: 'connectionLimit' },
+  idleTimeoutMs: { key: 'idleTimeout', divideBy: 1000 }, // mariadb idleTimeout 은 초 단위
+  acquireTimeoutMs: { key: 'acquireTimeout' },
+  maxLifetimeMs: null, // 미지원
+}
+
+/**
+ * mongodb 풀 매핑 — 전부 ms. maxLifetime 동등물 없음(미지원).
+ * @type {Record<string, { key: string, divideBy?: number } | null>}
+ */
+export const MONGO_POOL_SPEC = {
+  min: { key: 'minPoolSize' },
+  max: { key: 'maxPoolSize' },
+  idleTimeoutMs: { key: 'maxIdleTimeMS' },
+  acquireTimeoutMs: { key: 'waitQueueTimeoutMS' },
+  maxLifetimeMs: null, // 미지원
+}
+
+/**
+ * 공통 풀 인터페이스(`{ min, max, idleTimeoutMs, acquireTimeoutMs, maxLifetimeMs }`)를 드라이버
+ * 풀 옵션 객체로 변환·검증한다.
+ *
+ * - 알 수 없는 풀 키 → `adapter.invalid_option`(오타 fail-fast).
+ * - 드라이버 미지원 키(spec 값 null, 예: mariadb/mongo 의 maxLifetimeMs) → `adapter.invalid_option`(silent 무시 X).
+ * - `max` 는 양의 정수, 그 외(min·*Ms)는 음 아닌 정수.
+ * - `divideBy` 가 있으면 ms→초 변환(floor).
+ *
+ * @param {unknown} pool - config.pool.
+ * @param {Record<string, { key: string, divideBy?: number } | null>} spec - 드라이버 풀 매핑.
+ * @param {string} driver - 에러 details 용 드라이버명.
+ * @returns {Record<string, number>} 드라이버 풀 옵션 객체(빈 객체 가능).
+ */
+export function normalizePool(pool, spec, driver) {
+  if (pool === undefined) return {}
+  assertPlainObject('pool', pool, { driver })
+  /** @type {Record<string, number>} */
+  const out = {}
+  for (const [key, value] of Object.entries(/** @type {Record<string, unknown>} */ (pool))) {
+    if (value === undefined) continue
+    const map = spec[key]
+    if (map === undefined) {
+      throw invalidOption(`${driver}: unknown pool option "${key}". Known: ${Object.keys(spec).join(', ')}.`, { driver, option: `pool.${key}` })
+    }
+    if (map === null) {
+      throw invalidOption(`${driver}: pool.${key} is not supported by the ${driver} driver.`, { driver, option: `pool.${key}` })
+    }
+    if (key === 'max') assertPositiveInt(`pool.${key}`, value, { driver })
+    else assertNonNegativeInt(`pool.${key}`, value, { driver })
+    const num = /** @type {number} */ (value)
+    out[map.key] = map.divideBy ? Math.floor(num / map.divideBy) : num
+  }
+  return out
+}