mega-framework 0.1.10 → 0.1.11

package/src/core/lock/index.js

@@ -0,0 +1,292 @@
+// @ts-check
+/**
+ * 분산 락 — LockManager(사용자 API) + 자동 폴백 factory + `ctx.lock` 부착 (ADR-226).
+ *
+ * # 두 층
+ *   - **driver**(redis/cluster/memory): 저수준 상호배제만(`acquire/release/extend/forceRelease/stats`).
+ *     {@link import('./contract.js').LockDriver} 계약.
+ *   - **LockManager**: driver 위에 사용자 ergonomics 를 얹는다 — `with`(자동 해제)/`acquire`(throw on
+ *     fail)/`tryAcquire`(null on fail)/watchdog 자동 연장/Lock 핸들 구성. watchdog 은 manager-level 이라
+ *     3 driver 가 공짜로 얻는다(FIFO·fence 만 driver-level).
+ *
+ * # 자동 폴백 (`driver: 'auto'`, 기본)
+ *   redis cache 어댑터 활성 → **redis**(진짜 분산). 없고 cluster 워커 → **cluster**(단일 노드 한정, 경고).
+ *   둘 다 없음 → **memory**(분산 미보장, 경고). 명시 driver 는 그대로 쓰되, 전제(redis 어댑터/cluster 모드)가
+ *   없으면 **fail-fast**(P7 — 조용한 다운그레이드로 분산 보장이 깨지는 것을 막는다).
+ *
+ * # `ctx.lock` 통합
+ *   `ctx.lock` 은 종전대로 `(alias) => MegaLockAdapter`(redlock, ADR-113) 콜러블이고, 여기에
+ *   {@link attachLockApi} 가 `.with/.acquire/.tryAcquire/.forceRelease/.stats` 를 **얹는다**. 그래서
+ *   `ctx.lock(alias)`(스케줄러 등 기존 사용처)와 `ctx.lock.with(...)`(신규)이 한 객체에 공존한다.
+ *
+ * @module core/lock
+ */
+import { MegaConflictError, MegaValidationError } from '../../errors/http-errors.js'
+import { assertLockKey, normalizeLockOpts, DEFAULT_TTL_MS, DEFAULT_WAIT_MS, WATCHDOG_RATIO } from './contract.js'
+import { MemoryLockDriver } from './memory-lock.js'
+import { ClusterLockDriver } from './cluster-lock.js'
+import { RedisLockDriver } from './redis-lock.js'
+
+export { MemoryLockDriver, ClusterLockDriver, RedisLockDriver }
+
+/** watchdog 최소 주기(ms) — 아주 짧은 ttl 에서도 폭주하지 않게 하한. */
+const MIN_WATCHDOG_MS = 50
+
+/**
+ * 프로세스 전역 활성 manager — boot 가 1회 설정하고, ctx-builder 가 `ctx.lock` 에 API 를 얹을 때 읽는다.
+ * (어댑터 매니저와 동류의 부팅-설정 싱글톤. 테스트는 setLockManager(null) 로 격리.)
+ * @type {LockManager | null}
+ */
+let activeManager = null
+
+/** 활성 락 manager 설정(boot lock 스테이지). null 로 해제(셧다운/테스트). @param {LockManager | null} manager @returns {void} */
+export function setLockManager(manager) {
+  activeManager = manager
+}
+
+/** 현재 활성 락 manager(없으면 null — `ctx.lock.with` 미부착). @returns {LockManager | null} */
+export function getLockManager() {
+  return activeManager
+}
+
+/**
+ * 사용자 분산 락 API. driver 한 개를 감싸 `with/acquire/tryAcquire/forceRelease/stats` 를 제공한다.
+ */
+export class LockManager {
+  /** @type {import('./contract.js').LockDriver} */ #driver
+  /** @type {{ ttl: number, waitMs: number, fifo: boolean }} config 유래 기본 옵션. */ #defaults
+  /** @type {any} pino 호환 로거(옵션). */ #logger
+
+  /**
+   * @param {import('./contract.js').LockDriver} driver - 선택된 저수준 driver.
+   * @param {{ defaults: { ttl: number, waitMs: number, fifo: boolean }, logger?: any }} opts
+   */
+  constructor(driver, { defaults, logger }) {
+    this.#driver = driver
+    this.#defaults = defaults
+    this.#logger = logger
+  }
+
+  /** @returns {string} 활성 driver 이름('redis'|'cluster'|'memory'). */
+  get driverName() {
+    return this.#driver.name
+  }
+
+  /**
+   * 락 획득(대기 후 실패 시 throw) — `try/finally` 로 직접 release 하는 용도.
+   * @param {string} key - 자원 키(비어있지 않은 공백 없는 문자열).
+   * @param {import('./contract.js').LockOpts} [opts] - ttl/waitMs/fifo/fence/extendable.
+   * @returns {Promise<import('./contract.js').LockHandle>}
+   * @throws {MegaConflictError} `lock.not_acquired` - waitMs 안에 못 잡음(자원이 잠겨있음 — 409).
+   * @throws {MegaValidationError} key/opts 부적합.
+   */
+  async acquire(key, opts) {
+    assertLockKey(key)
+    const n = normalizeLockOpts(this.#defaults, opts)
+    this.#logger?.debug?.({ key, driver: this.#driver.name, ttl: n.ttl, waitMs: n.waitMs }, 'lock.acquire enter')
+    const dl = await this.#driver.acquire(key, n)
+    if (!dl) {
+      this.#logger?.debug?.({ key, driver: this.#driver.name }, 'lock.acquire failed (contended)')
+      throw new MegaConflictError('lock.not_acquired', `could not acquire lock '${key}' within ${n.waitMs}ms (contended).`, { details: { key, waitMs: n.waitMs, driver: this.#driver.name } })
+    }
+    this.#logger?.debug?.({ key, driver: this.#driver.name, fence: dl.fence }, 'lock.acquire done')
+    return this.#wrap(key, dl, n)
+  }
+
+  /**
+   * 락을 즉시 1회만 시도(대기 없음) — 못 잡으면 null(throw 아님).
+   * @param {string} key @param {import('./contract.js').LockOpts} [opts]
+   * @returns {Promise<import('./contract.js').LockHandle | null>}
+   */
+  async tryAcquire(key, opts) {
+    assertLockKey(key)
+    const n = normalizeLockOpts(this.#defaults, { ...opts, waitMs: 0 }) // waitMs 강제 0.
+    const dl = await this.#driver.acquire(key, n)
+    return dl ? this.#wrap(key, dl, n) : null
+  }
+
+  /**
+   * 락 보호 임계구역 실행 — 획득 → fn 실행 → **반드시 해제**(성공/예외 무관). 가장 권장되는 사용법.
+   * @template T
+   * @param {string} key
+   * @param {import('./contract.js').LockOpts | ((lock: import('./contract.js').LockHandle) => Promise<T> | T)} optsOrFn -
+   *   옵션, 또는 옵션을 생략하고 바로 fn(2-인자 형태 `with(key, fn)`).
+   * @param {(lock: import('./contract.js').LockHandle) => Promise<T> | T} [maybeFn] - 3-인자 형태의 fn.
+   * @returns {Promise<T>} fn 의 반환값.
+   */
+  async with(key, optsOrFn, maybeFn) {
+    const fn = typeof optsOrFn === 'function' ? optsOrFn : maybeFn
+    const opts = typeof optsOrFn === 'function' ? undefined : optsOrFn
+    if (typeof fn !== 'function') {
+      throw new MegaValidationError('lock.invalid_callback', 'ctx.lock.with(key, [opts], fn) requires a function. Got: ' + typeof fn)
+    }
+    const lock = await this.acquire(key, opts)
+    try {
+      return await fn(lock)
+    } finally {
+      await lock.release()
+    }
+  }
+
+  /**
+   * 관리용 강제 해제(토큰 무관) — 운영 개입(고아 락 정리)용. 주의: 정상 보유자의 임계구역을 깰 수 있다.
+   * @param {string} key @returns {Promise<void>}
+   */
+  async forceRelease(key) {
+    assertLockKey(key)
+    this.#logger?.warn?.({ key, driver: this.#driver.name }, 'lock.forceRelease — admin override')
+    await this.#driver.forceRelease(key)
+  }
+
+  /** @returns {Promise<{ driver: string, active: number, waiting: number }>} 현재 보유/대기 수. */
+  async stats() {
+    return this.#driver.stats()
+  }
+
+  /** 정리 — driver 자원(타이머·구독·IPC) 해제. graceful shutdown 에서 호출. @returns {Promise<void>} */
+  async close() {
+    await this.#driver.close()
+  }
+
+  /**
+   * driver 결과를 사용자 Lock 핸들로 감싼다 — release(idempotent + watchdog 정지)/extend, extendable 이면
+   * watchdog 자동 연장 타이머 부착.
+   * @param {string} key @param {import('./contract.js').DriverLock} dl @param {import('./contract.js').NormalizedLockOpts} n
+   * @returns {import('./contract.js').LockHandle}
+   */
+  #wrap(key, dl, n) {
+    const driver = this.#driver
+    const logger = this.#logger
+    let released = false
+    /** @type {ReturnType<typeof setInterval> | null} */
+    let watchdog = null
+    const stopWatchdog = () => {
+      if (watchdog) {
+        clearInterval(watchdog)
+        watchdog = null
+      }
+    }
+    if (n.extendable) {
+      const periodMs = Math.max(MIN_WATCHDOG_MS, Math.floor(n.ttl * WATCHDOG_RATIO))
+      watchdog = setInterval(() => {
+        // 비동기 — interval 콜백은 await 불가라 then/catch 로(부유 프라미스 방지).
+        driver
+          .extend(key, dl.token, n.ttl)
+          .then((ok) => {
+            if (!ok) {
+              stopWatchdog()
+              logger?.warn?.({ key, driver: driver.name }, 'lock watchdog: extend returned false — lock lost, critical section no longer protected')
+            }
+          })
+          .catch((e) => {
+            stopWatchdog()
+            logger?.error?.({ key, driver: driver.name, err: e }, 'lock watchdog: extend threw — stopping auto-extension')
+          })
+      }, periodMs)
+      watchdog.unref?.()
+    }
+    /** @type {import('./contract.js').LockHandle} */
+    const handle = {
+      key,
+      token: dl.token,
+      extend: async (ttl) => driver.extend(key, dl.token, ttl ?? n.ttl),
+      release: async () => {
+        if (released) return // idempotent — 중복 release 안전.
+        released = true
+        stopWatchdog()
+        await driver.release(key, dl.token)
+      },
+    }
+    if (dl.fence !== undefined) handle.fence = dl.fence
+    return handle
+  }
+}
+
+/**
+ * config 의 lock 섹션에서 manager 기본 옵션을 뽑는다.
+ * @param {{ ttl?: number, waitMs?: number, fifo?: boolean }} lockConfig
+ * @returns {{ ttl: number, waitMs: number, fifo: boolean }}
+ */
+function resolveDefaults(lockConfig) {
+  return {
+    ttl: Number.isInteger(lockConfig.ttl) ? /** @type {number} */ (lockConfig.ttl) : DEFAULT_TTL_MS,
+    waitMs: Number.isInteger(lockConfig.waitMs) ? /** @type {number} */ (lockConfig.waitMs) : DEFAULT_WAIT_MS,
+    fifo: lockConfig.fifo === true,
+  }
+}
+
+/**
+ * 요청 driver(또는 'auto')와 가용 자원으로 실제 driver 를 고른다.
+ * @param {string} requested - 'auto'|'redis'|'cluster'|'memory'.
+ * @param {{ logger?: any, redisClient: any, isClusterWorker: boolean }} env
+ * @returns {import('./contract.js').LockDriver}
+ * @throws {MegaValidationError} 명시 driver 의 전제가 없거나(P7 fail-fast) 알 수 없는 driver.
+ */
+function selectDriver(requested, { logger, redisClient, isClusterWorker }) {
+  switch (requested) {
+    case 'memory':
+      return new MemoryLockDriver()
+    case 'cluster':
+      if (!isClusterWorker) {
+        throw new MegaValidationError('lock.driver_unavailable', "lock.driver='cluster' requires running as a cluster worker (mega start --cluster=N). Use 'auto' or 'memory' for single-process.", { details: { requested } })
+      }
+      return new ClusterLockDriver()
+    case 'redis':
+      if (!redisClient) {
+        throw new MegaValidationError('lock.driver_unavailable', "lock.driver='redis' requires a redis cache adapter — set config lock.cache to a redis cache alias.", { details: { requested } })
+      }
+      return new RedisLockDriver({ client: redisClient })
+    case 'auto': {
+      if (redisClient) {
+        logger?.debug?.({ driver: 'redis' }, 'lock: auto-selected redis driver')
+        return new RedisLockDriver({ client: redisClient })
+      }
+      if (isClusterWorker) {
+        logger?.warn?.('lock: auto-selected cluster driver (no redis cache) — mutual exclusion is single-node only, NOT across nodes. Use redis for true distributed locking.')
+        return new ClusterLockDriver()
+      }
+      logger?.warn?.('lock: auto-selected memory driver (no redis, no cluster) — NOT safe for distributed/multi-process deployments. Use redis (or cluster) in production.')
+      return new MemoryLockDriver()
+    }
+    default:
+      throw new MegaValidationError('lock.invalid_driver', `unknown lock.driver '${requested}'. Use 'auto' | 'redis' | 'cluster' | 'memory'.`, { details: { requested } })
+  }
+}
+
+/**
+ * 분산 락 manager 를 만든다 — driver 자동 폴백 포함. boot 가 1회 호출해 `ctx.lock` 에 부착한다.
+ *
+ * @param {{ driver?: string, ttl?: number, waitMs?: number, fifo?: boolean, cache?: string }} [lockConfig] -
+ *   config 의 `lock` 섹션. `cache` 는 redis driver 가 빌릴 cache 어댑터 alias(redis/auto 일 때 의미).
+ * @param {{ logger?: any, redisClient?: any, isClusterWorker?: boolean }} [deps] -
+ *   - `redisClient` boot 가 cache 어댑터에서 빌려 넘긴 ioredis 클라이언트(없으면 null).
+ *   - `isClusterWorker` 현재 프로세스가 cluster 워커인지(`cluster.isWorker`).
+ * @returns {LockManager}
+ */
+export function createLockManager(lockConfig = {}, deps = {}) {
+  const { logger, redisClient = null, isClusterWorker = false } = deps
+  const requested = lockConfig.driver ?? 'auto'
+  const driver = selectDriver(requested, { logger, redisClient, isClusterWorker })
+  const manager = new LockManager(driver, { defaults: resolveDefaults(lockConfig), logger })
+  logger?.debug?.({ requested, selected: driver.name }, 'lock: manager created')
+  return manager
+}
+
+/**
+ * `ctx.lock` 콜러블에 사용자 API 메서드를 얹는다 — `ctx.lock(alias)`(기존)와 `ctx.lock.with(...)`(신규) 공존.
+ * boot 가 manager 생성 후 각 앱의 lock accessor 에 1회 호출한다.
+ *
+ * @param {Function & Record<string, any>} lockAccessor - `(alias) => MegaLockAdapter` 콜러블(ctx-builder 산출).
+ * @param {LockManager} manager
+ * @returns {Function & Record<string, any>} 같은 accessor(체이닝용).
+ */
+export function attachLockApi(lockAccessor, manager) {
+  // manager 메서드로 바로 위임(얇은 forwarder). 콜러블 함수 객체에 메서드를 얹어 `ctx.lock(alias)`(함수
+  // 호출)와 `ctx.lock.with(...)`(메서드)을 공존시킨다 — manager 메서드를 bind 해 this 고정.
+  lockAccessor.with = manager.with.bind(manager)
+  lockAccessor.acquire = manager.acquire.bind(manager)
+  lockAccessor.tryAcquire = manager.tryAcquire.bind(manager)
+  lockAccessor.forceRelease = manager.forceRelease.bind(manager)
+  lockAccessor.stats = manager.stats.bind(manager)
+  return lockAccessor
+}

package/src/core/lock/memory-lock.js

@@ -0,0 +1,162 @@
+// @ts-check
+/**
+ * MemoryLockDriver — 단일 프로세스 in-memory 분산 락 driver (ADR-226).
+ *
+ * `Map` 기반 상호배제. **단일 프로세스 안에서만** 직렬화하므로 멀티 프로세스·멀티 노드에서는 상호배제를
+ * 보장하지 못한다 — 그래서 factory 가 memory 를 고를 때 부팅 경고를 낸다(`src/core/lock/index.js`).
+ * 개발/테스트, 또는 분산이 불필요한 단일 인스턴스 배포용. JS 단일 스레드라 acquire/release 사이에 끼어드는
+ * race 가 없다(이벤트루프 원자성).
+ *
+ * # FIFO — 항상 공정
+ *   대기자를 **도착 순서 큐**로 관리해, 보유자가 풀리거나 TTL 만료되면 큐의 맨 앞 대기자에게 넘긴다.
+ *   따라서 memory driver 는 `fifo` 옵션과 무관하게 늘 FIFO(공정) — 기아가 없다. `fifo:true` 의 순서
+ *   보장은 그대로 만족하고, `fifo:false` 도 더 강한 보장(공정)을 줄 뿐이다.
+ *
+ * # TTL 만료
+ *   보유 시 `setTimeout(ttl)` 로 만료 타이머를 건다(unref — 프로세스 종료를 막지 않음). 만료되면 보유를
+ *   비우고 다음 대기자에게 넘긴다. `extend` 는 타이머를 재설정한다.
+ *
+ * driver 계약은 {@link import('./contract.js').LockDriver} 를 따른다(typedef — 런타임 implements 아님).
+ * @module core/lock/memory-lock
+ */
+import { generateToken } from './contract.js'
+
+/**
+ * @typedef {Object} HeldLock - 보유 중 락 레코드.
+ * @property {string} token @property {number} expiresAt @property {ReturnType<typeof setTimeout>} timer @property {number} [fence]
+ */
+
+/**
+ * @typedef {Object} Waiter - 대기 큐 항목.
+ * @property {number} ttl @property {boolean} fence @property {(lock: import('./contract.js').DriverLock | null) => void} resolve
+ * @property {ReturnType<typeof setTimeout> | null} timer
+ */
+
+export class MemoryLockDriver {
+  /** @type {Map<string, HeldLock>} key → 보유 락. */ #held = new Map()
+  /** @type {Map<string, Waiter[]>} key → FIFO 대기 큐. */ #queues = new Map()
+  /** @type {Map<string, number>} key → fence 카운터(단조 증가, 보유 사이클 무관 유지). */ #fences = new Map()
+
+  /** @type {'memory'} */
+  get name() {
+    return 'memory'
+  }
+
+  /**
+   * 락 획득 — 즉시 가능하면 grant, 아니면 waitMs 안에서 FIFO 큐 대기.
+   * @param {string} key @param {import('./contract.js').NormalizedLockOpts} opts
+   * @returns {Promise<import('./contract.js').DriverLock | null>}
+   */
+  async acquire(key, { ttl, waitMs, fence }) {
+    if (!this.#held.has(key)) return this.#grant(key, ttl, fence)
+    if (waitMs === 0) return null // tryAcquire — 즉시 실패.
+    return new Promise((resolve) => {
+      /** @type {Waiter} */
+      const waiter = { ttl, fence, resolve, timer: null }
+      waiter.timer = setTimeout(() => {
+        // waitMs 초과 — 큐에서 빼고 null(획득 실패). 경합은 정상 결과라 throw 안 함.
+        const q = this.#queues.get(key)
+        if (q) {
+          const i = q.indexOf(waiter)
+          if (i >= 0) q.splice(i, 1)
+          if (q.length === 0) this.#queues.delete(key)
+        }
+        resolve(null)
+      }, waitMs)
+      waiter.timer.unref?.()
+      const q = this.#queues.get(key) ?? []
+      q.push(waiter)
+      this.#queues.set(key, q)
+    })
+  }
+
+  /**
+   * 락 부여 — 토큰 생성 + 만료 타이머 + (fence 면) 단조 카운터 증가.
+   * @param {string} key @param {number} ttl @param {boolean} fence
+   * @returns {import('./contract.js').DriverLock}
+   */
+  #grant(key, ttl, fence) {
+    const token = generateToken()
+    /** @type {number | undefined} */
+    let fenceVal
+    if (fence) {
+      fenceVal = (this.#fences.get(key) ?? 0) + 1
+      this.#fences.set(key, fenceVal)
+    }
+    const timer = setTimeout(() => this.#expire(key), ttl)
+    timer.unref?.()
+    this.#held.set(key, { token, expiresAt: Date.now() + ttl, timer, fence: fenceVal })
+    return fenceVal === undefined ? { token } : { token, fence: fenceVal }
+  }
+
+  /** 만료/해제 후 다음 대기자에게 넘긴다(FIFO). @param {string} key @returns {void} */
+  #grantNextWaiter(key) {
+    const q = this.#queues.get(key)
+    if (!q || q.length === 0) return
+    const waiter = /** @type {Waiter} */ (q.shift())
+    if (q.length === 0) this.#queues.delete(key)
+    if (waiter.timer) clearTimeout(waiter.timer)
+    waiter.resolve(this.#grant(key, waiter.ttl, waiter.fence))
+  }
+
+  /** TTL 만료 — 보유 비우고 다음 대기자에게. @param {string} key @returns {void} */
+  #expire(key) {
+    this.#held.delete(key)
+    this.#grantNextWaiter(key)
+  }
+
+  /**
+   * 락 해제 — 토큰이 현재 보유자일 때만. 해제 후 다음 대기자 승계.
+   * @param {string} key @param {string} token @returns {Promise<boolean>}
+   */
+  async release(key, token) {
+    const h = this.#held.get(key)
+    if (!h || h.token !== token) return false // 이미 만료/타인 보유 — idempotent.
+    clearTimeout(h.timer)
+    this.#held.delete(key)
+    this.#grantNextWaiter(key)
+    return true
+  }
+
+  /**
+   * TTL 연장 — 토큰이 보유자일 때만 만료 타이머 재설정.
+   * @param {string} key @param {string} token @param {number} ttl @returns {Promise<boolean>}
+   */
+  async extend(key, token, ttl) {
+    const h = this.#held.get(key)
+    if (!h || h.token !== token) return false // 락을 잃음(만료/탈취) — watchdog 가 false 로 인지.
+    clearTimeout(h.timer)
+    h.expiresAt = Date.now() + ttl
+    h.timer = setTimeout(() => this.#expire(key), ttl)
+    h.timer.unref?.()
+    return true
+  }
+
+  /** 강제 해제(관리용, 토큰 무관) — 보유 비우고 다음 대기자 승계. @param {string} key @returns {Promise<void>} */
+  async forceRelease(key) {
+    const h = this.#held.get(key)
+    if (h) clearTimeout(h.timer)
+    this.#held.delete(key)
+    this.#grantNextWaiter(key)
+  }
+
+  /** @returns {Promise<{ driver: string, active: number, waiting: number }>} 보유/대기 수. */
+  async stats() {
+    let waiting = 0
+    for (const q of this.#queues.values()) waiting += q.length
+    return { driver: 'memory', active: this.#held.size, waiting }
+  }
+
+  /** 정리 — 모든 만료 타이머 해제 + 대기자에 null 응답(graceful shutdown). @returns {Promise<void>} */
+  async close() {
+    for (const h of this.#held.values()) clearTimeout(h.timer)
+    for (const q of this.#queues.values()) {
+      for (const w of q) {
+        if (w.timer) clearTimeout(w.timer)
+        w.resolve(null)
+      }
+    }
+    this.#held.clear()
+    this.#queues.clear()
+  }
+}