mega-framework 0.1.9 → 0.1.11

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

@@ -0,0 +1,174 @@
+// @ts-check
+/**
+ * ClusterLockDriver — Node `cluster` IPC 기반 분산 락 driver (ADR-226).
+ *
+ * redis 가 없지만 **클러스터**(`mega start --cluster=N`)로 도는 환경용. 같은 노드의 워커들이 **master
+ * 프로세스에 위임**해 직렬화한다 — 워커가 IPC 로 master 에 acquire/release 를 요청하고, master 는
+ * {@link import('./memory-lock.js').MemoryLockDriver} 한 개로 실제 상호배제를 관리한 뒤 응답한다.
+ *
+ * # ⚠️ 멀티 노드 미보장
+ *   cluster IPC 는 **한 노드(master + 그 워커들)** 안에서만 닿는다. 노드가 여러 대면 master 도 여러 개라
+ *   서로의 락을 모른다 — **노드 간 상호배제는 보장하지 못한다**. 진짜 분산 락은 redis driver 를 쓴다.
+ *   factory 가 cluster driver 를 고를 때 이 한계를 부팅 경고로 알린다.
+ *
+ * # 구성
+ *   - **master 측**: {@link installClusterLockMaster} 를 master 프로세스에서 1회 호출 — 워커 메시지를
+ *     받아 MemoryLockDriver 로 처리하고 회신한다(`mega start` 클러스터 분기, metrics aggregator 옆).
+ *   - **worker 측**: {@link ClusterLockDriver} 가 `process.send` 로 요청하고 correlation id 로 응답을 매칭한다.
+ *     acquire 의 waitMs 대기·FIFO 큐·TTL 만료는 전부 master 의 MemoryLockDriver 가 처리하므로 worker 는
+ *     얇은 RPC 클라이언트다.
+ *
+ * # 워커 crash
+ *   워커가 락 보유 중 죽으면 master 의 메모리 락은 **TTL 만료**로 풀린다(안전망). 즉시 정리는 안 함 —
+ *   TTL 을 임계구역 예상보다 넉넉히 잡는 것이 운영 권고(memory/redis 와 동일).
+ *
+ * @module core/lock/cluster-lock
+ */
+import nodeCluster from 'node:cluster'
+import { MemoryLockDriver } from './memory-lock.js'
+
+/** IPC 메시지 마커 — 다른 cluster 메시지(metrics 등)와 섞이지 않게 한다. */
+const LOCK_MSG = 'mega:lock'
+
+/** master 에 responder 가 이미 설치됐는지(멱등 가드). @type {boolean} */
+let masterInstalled = false
+
+/**
+ * master 프로세스에 락 responder 를 설치한다(멱등). 워커들의 IPC 요청을 한 MemoryLockDriver 로 직렬화한다.
+ * `mega start` 클러스터 분기에서 master 가 1회 호출한다.
+ *
+ * @param {import('node:cluster').Cluster} [cluster] - 테스트 주입용(기본 node:cluster).
+ * @returns {MemoryLockDriver | null} 설치된 master driver(테스트/관측용). 이미 설치됐으면 null.
+ */
+export function installClusterLockMaster(cluster = nodeCluster) {
+  if (masterInstalled) return null
+  masterInstalled = true
+  const driver = new MemoryLockDriver()
+  cluster.on('message', (worker, msg) => {
+    void handleMasterMessage(driver, worker, msg)
+  })
+  return driver
+}
+
+/**
+ * master 측 메시지 1건 처리 — op 를 MemoryLockDriver 로 위임하고 결과를 워커에 회신. 절대 throw 안 함
+ * (worker 에러 응답으로 표면화). acquire 의 waitMs 대기는 driver 가 hold 하므로 응답이 그만큼 늦게 간다.
+ * @param {MemoryLockDriver} driver @param {import('node:cluster').Worker} worker @param {any} msg
+ * @returns {Promise<void>}
+ */
+async function handleMasterMessage(driver, worker, msg) {
+  if (!msg || msg.t !== LOCK_MSG || msg.id === undefined) return
+  const { id, op, key, token, ttl, opts } = msg
+  try {
+    /** @type {any} */
+    let result
+    if (op === 'acquire') result = await driver.acquire(key, opts)
+    else if (op === 'release') result = await driver.release(key, token)
+    else if (op === 'extend') result = await driver.extend(key, token, ttl)
+    else if (op === 'forceRelease') {
+      await driver.forceRelease(key)
+      result = null
+    } else if (op === 'stats') result = await driver.stats()
+    else {
+      worker.send?.({ t: LOCK_MSG, id, error: `unknown lock op: ${op}` })
+      return
+    }
+    worker.send?.({ t: LOCK_MSG, id, result })
+  } catch (e) {
+    // master 측 처리 실패 — 워커에 에러로 전달(silent 금지). 워커의 #request 가 reject 한다.
+    worker.send?.({ t: LOCK_MSG, id, error: e instanceof Error ? e.message : String(e) })
+  }
+}
+
+/** 테스트 격리용 — master responder 설치 플래그 초기화. @returns {void} */
+export function _resetClusterLockMaster() {
+  masterInstalled = false
+}
+
+/**
+ * 워커 측 cluster 락 driver — master 에 IPC 위임하는 얇은 RPC 클라이언트.
+ * driver 계약은 {@link import('./contract.js').LockDriver} 를 따른다(typedef — 런타임 implements 아님).
+ */
+export class ClusterLockDriver {
+  /** @type {Map<string, { resolve: (v: any) => void, reject: (e: any) => void }>} id → 대기 응답. */ #pending = new Map()
+  /** @type {number} 요청 시퀀스(pid 와 합쳐 전역 유일 id). */ #seq = 0
+  /** @type {NodeJS.Process} master 와의 IPC 채널(cluster 워커면 process). */ #proc
+  /** @type {(msg: any) => void} 'message' 리스너 참조(close 에서 제거). */ #onMessage
+
+  /**
+   * @param {{ proc?: NodeJS.Process }} [opts] - `proc` 테스트 주입용(기본 전역 process). cluster 워커면
+   *   `process.send` 로 master 에 닿는다.
+   * @throws {Error} proc.send 가 없으면(=cluster 워커가 아님) — factory 가 cluster 워커일 때만 생성한다.
+   */
+  constructor({ proc = process } = {}) {
+    if (typeof proc.send !== 'function') {
+      throw new Error('ClusterLockDriver requires an IPC channel (process.send) — only valid in a cluster worker.')
+    }
+    this.#proc = proc
+    this.#onMessage = (msg) => {
+      if (!msg || msg.t !== LOCK_MSG || msg.id === undefined) return
+      const p = this.#pending.get(msg.id)
+      if (!p) return
+      this.#pending.delete(msg.id)
+      if (msg.error !== undefined) p.reject(new Error(`cluster lock master error: ${msg.error}`))
+      else p.resolve(msg.result)
+    }
+    proc.on('message', this.#onMessage)
+  }
+
+  /** @type {'cluster'} */
+  get name() {
+    return 'cluster'
+  }
+
+  /**
+   * master 에 op 를 보내고 응답을 correlation id 로 기다린다.
+   * @param {string} op @param {Record<string, any>} payload @returns {Promise<any>}
+   */
+  #request(op, payload) {
+    return new Promise((resolve, reject) => {
+      const id = `${process.pid}:${++this.#seq}`
+      this.#pending.set(id, { resolve, reject })
+      try {
+        this.#proc.send?.({ t: LOCK_MSG, id, op, ...payload })
+      } catch (e) {
+        // IPC 채널 단절 등 — 즉시 reject(대기 누수 방지).
+        this.#pending.delete(id)
+        reject(e instanceof Error ? e : new Error(String(e)))
+      }
+    })
+  }
+
+  /** @param {string} key @param {import('./contract.js').NormalizedLockOpts} opts @returns {Promise<import('./contract.js').DriverLock | null>} */
+  async acquire(key, opts) {
+    return this.#request('acquire', { key, opts })
+  }
+
+  /** @param {string} key @param {string} token @returns {Promise<boolean>} */
+  async release(key, token) {
+    return this.#request('release', { key, token })
+  }
+
+  /** @param {string} key @param {string} token @param {number} ttl @returns {Promise<boolean>} */
+  async extend(key, token, ttl) {
+    return this.#request('extend', { key, token, ttl })
+  }
+
+  /** @param {string} key @returns {Promise<void>} */
+  async forceRelease(key) {
+    await this.#request('forceRelease', { key })
+  }
+
+  /** @returns {Promise<{ driver: string, active: number, waiting: number }>} */
+  async stats() {
+    const s = await this.#request('stats', {})
+    return { driver: 'cluster', active: s.active, waiting: s.waiting }
+  }
+
+  /** 정리 — IPC 리스너 제거 + 대기 요청에 null 응답(누수 방지). @returns {Promise<void>} */
+  async close() {
+    this.#proc.off?.('message', this.#onMessage)
+    for (const p of this.#pending.values()) p.resolve(null)
+    this.#pending.clear()
+  }
+}

package/src/core/lock/contract.js

@@ -0,0 +1,123 @@
+// @ts-check
+/**
+ * 분산 락 공통 contract — driver 인터페이스 + Lock 핸들 shape + opts 검증 + 토큰 생성 (ADR-226).
+ *
+ * `ctx.lock.with/.acquire/.tryAcquire` 사용자 API 는 {@link import('./index.js').LockManager} 가 제공하고,
+ * 실제 상호배제는 **driver**(redis/cluster/memory)가 담당한다. driver 는 저장/조정만 하고(아래 LockDriver),
+ * watchdog 자동 연장·Lock 핸들 구성·tryAcquire(=waitMs 0) 같은 사용자 ergonomics 는 manager 가 driver
+ * 위에 얹는다. 그래서 FIFO·fence 처럼 저장소-특화 동작만 driver 가 구현하고, 나머지는 한 곳(manager)에서
+ * 모든 driver 에 공통 적용된다.
+ *
+ * # 기존 `ctx.lock(alias)` 와의 관계 (ADR-113 ↔ ADR-226)
+ *   `ctx.lock` 은 **callable object** 다 — `ctx.lock(alias)` 는 종전대로 설정된 `MegaLockAdapter`(redlock)를
+ *   반환하고(스케줄러·기존 사용처 무변경), 거기에 `.with/.acquire/...` 메서드가 붙어 사용자 분산 락 API 가
+ *   된다. 둘은 별개 하위시스템이다(전자=설정형 alias 어댑터, 후자=자동폴백 driver).
+ *
+ * @module core/lock/contract
+ */
+import { randomBytes } from 'node:crypto'
+import { MegaValidationError } from '../../errors/http-errors.js'
+
+/** 락 TTL 디폴트(ms) — 임계구역 보호 시간. config `lock.ttl` 로 조정. */
+export const DEFAULT_TTL_MS = 5000
+/** 획득 대기 디폴트(ms) — 경합 시 이만큼 기다린다(0=즉시 실패). config `lock.waitMs` 로 조정. */
+export const DEFAULT_WAIT_MS = 1000
+/** watchdog 자동 연장 주기 = ttl × 이 비율. 만료 전에 넉넉히 갱신(절반). */
+export const WATCHDOG_RATIO = 0.5
+
+/**
+ * @typedef {Object} LockOpts - acquire/with/tryAcquire 옵션(정규화 전).
+ * @property {number} [ttl] - 락 보유 시간(ms, 양의 정수). 미지정 시 manager 디폴트.
+ * @property {number} [waitMs] - 획득 대기 상한(ms, 0 이상). 0 = 즉시(tryAcquire 와 동일). 미지정 시 디폴트.
+ * @property {boolean} [fifo] - true 면 대기자를 도착 순서대로 깨운다(기아 방지). driver 가 지원해야 함.
+ * @property {boolean} [fence] - true 면 단조 증가 fence 토큰을 함께 반환(외부 시스템의 stale-writer 차단용).
+ * @property {boolean} [extendable] - true 면 manager 가 watchdog 으로 ttl 절반마다 자동 연장(긴 임계구역).
+ */
+
+/**
+ * @typedef {Object} NormalizedLockOpts - 검증·기본값 적용된 옵션.
+ * @property {number} ttl @property {number} waitMs @property {boolean} fifo @property {boolean} fence @property {boolean} extendable
+ */
+
+/**
+ * @typedef {Object} DriverLock - driver.acquire 성공 결과(저수준 — manager 가 LockHandle 로 감싼다).
+ * @property {string} token - 이 보유를 식별하는 랜덤 토큰(release/extend 가 소유 검증에 쓴다).
+ * @property {number} [fence] - fence 토큰(단조 증가). `fence:true` 일 때만.
+ */
+
+/**
+ * @typedef {Object} LockHandle - 사용자에게 반환되는 락 핸들(manager 구성).
+ * @property {string} key - 잠근 자원 키.
+ * @property {string} token - 보유 토큰.
+ * @property {number} [fence] - fence 토큰(`fence:true` 일 때만).
+ * @property {() => Promise<void>} release - 락 해제(idempotent — 이미 풀렸어도 안전). watchdog 도 멈춘다.
+ * @property {(ttl?: number) => Promise<boolean>} extend - TTL 연장. 아직 보유 중이면 true, 잃었으면 false.
+ */
+
+/**
+ * @typedef {Object} LockDriver - driver 가 구현하는 저수준 인터페이스(manager 가 호출).
+ * @property {string} name - 'redis' | 'cluster' | 'memory'.
+ * @property {(key: string, opts: NormalizedLockOpts) => Promise<DriverLock | null>} acquire -
+ *   waitMs 안에 획득하면 `{token, fence?}`, 못 잡으면 `null`(throw 아님 — 경합은 정상 결과).
+ * @property {(key: string, token: string) => Promise<boolean>} release - 토큰이 현재 보유자면 풀고 true,
+ *   아니면(이미 만료/타인 보유) false. 절대 throw 안 함.
+ * @property {(key: string, token: string, ttl: number) => Promise<boolean>} extend - 토큰이 보유자면 ttl
+ *   갱신 후 true, 아니면 false.
+ * @property {(key: string) => Promise<void>} forceRelease - 관리용 강제 해제(토큰 무관). 대기자 깨움 포함.
+ * @property {() => Promise<{ driver: string, active: number, waiting: number }>} stats - 현재 보유/대기 수.
+ * @property {() => Promise<void>} close - 타이머·구독·연결참조 정리(graceful shutdown).
+ */
+
+/**
+ * 락 보유 토큰 생성 — 충돌 사실상 불가한 랜덤 24-hex. release/extend 가 소유권 검증에 쓴다.
+ * @returns {string}
+ */
+export function generateToken() {
+  return randomBytes(12).toString('hex')
+}
+
+/**
+ * acquire/with/tryAcquire 옵션을 검증·정규화한다(fail-fast — 잘못된 입력은 락 시도 전에 throw).
+ * @param {{ ttl: number, waitMs: number, fifo: boolean }} defaults - manager 디폴트(config 유래).
+ * @param {LockOpts} [opts] - 사용자 옵션.
+ * @returns {NormalizedLockOpts}
+ * @throws {MegaValidationError} `lock.invalid_opts` - ttl/waitMs 가 정수 범위를 벗어나거나 boolean 아닌 플래그.
+ */
+export function normalizeLockOpts(defaults, opts = {}) {
+  const ttl = opts.ttl ?? defaults.ttl
+  if (!Number.isInteger(ttl) || ttl <= 0) {
+    throw new MegaValidationError('lock.invalid_opts', `lock ttl must be a positive integer (ms). Got: ${ttl}.`, { details: { ttl } })
+  }
+  const waitMs = opts.waitMs ?? defaults.waitMs
+  if (!Number.isInteger(waitMs) || waitMs < 0) {
+    throw new MegaValidationError('lock.invalid_opts', `lock waitMs must be an integer >= 0 (ms, 0 = no wait). Got: ${waitMs}.`, { details: { waitMs } })
+  }
+  for (const flag of /** @type {const} */ (['fifo', 'fence', 'extendable'])) {
+    if (opts[flag] !== undefined && typeof opts[flag] !== 'boolean') {
+      throw new MegaValidationError('lock.invalid_opts', `lock '${flag}' must be a boolean. Got: ${typeof opts[flag]}.`, { details: { flag, value: opts[flag] } })
+    }
+  }
+  return {
+    ttl,
+    waitMs,
+    fifo: opts.fifo ?? defaults.fifo,
+    fence: opts.fence === true,
+    extendable: opts.extendable === true,
+  }
+}
+
+/**
+ * 락 key 검증 — 비어있지 않은 문자열. 저장소 키/redis subject 로 쓰이므로 제어문자·공백을 막는다.
+ * @param {string} key
+ * @returns {void}
+ * @throws {MegaValidationError} `lock.invalid_key`
+ */
+export function assertLockKey(key) {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new MegaValidationError('lock.invalid_key', `lock key must be a non-empty string. Got: ${typeof key}.`, { details: { key } })
+  }
+  if (/\s/.test(key)) {
+    // 공백·제어문자만 금지(redis 키/pub-sub 채널 안전). ':' '.' '-' 같은 일반 키 구분자는 허용.
+    throw new MegaValidationError('lock.invalid_key', `lock key must not contain whitespace or control characters. Got: ${JSON.stringify(key)}.`, { details: { key } })
+  }
+}

package/src/core/lock/fifo-waitlist.js

@@ -0,0 +1,93 @@
+// @ts-check
+/**
+ * FifoWaitlist — redis Sorted Set 기반 FIFO 대기열 (ADR-226, redis-lock driver 전용).
+ *
+ * `fifo:true` 락은 경합 시 **도착 순서**대로 깨워야 한다(기아 방지). redis 에는 프로세스 경계를 넘는
+ * 공유 큐가 필요하므로 **Sorted Set** 으로 순서를 매기고, 대기자는 자신이 **큐의 맨 앞(head)** 이 됐을
+ * 때만 락 `SET NX` 를 시도한다. 해제 알림은 redis Pub/Sub 가 깨운다(redis-lock.js).
+ *
+ * # 점수 = 전역 INCR 시퀀스 (ms 타임스탬프 아님)
+ *   타임스탬프(ms)를 점수로 쓰면 같은 ms 에 합류한 대기자들의 순서가 비결정적(점수 동률 → member 사전순)이
+ *   되어 FIFO 가 깨진다. 그래서 점수는 redis `INCR <seqKey>` 의 **전역 단조 시퀀스**를 쓴다 — 모든
+ *   프로세스가 한 카운터를 공유하므로 합류 순서가 곧 전역 총순서다(진짜 분산 FIFO).
+ *
+ * # stale 항목 reaping (member 에 deadline 인코딩)
+ *   대기자 프로세스가 `leave` 전에 죽으면 그 항목이 head 에 남아 뒤를 막는다. 시퀀스 점수로는 "오래됨"을
+ *   판단할 수 없으므로, member 를 `"<token>:<deadlineMs>"` 로 인코딩한다. head 의 deadline 이 현재보다
+ *   과거면(대기 시한 초과 — 정상 대기자라면 스스로 떠났을 것) 버려진 것으로 보고 `ZREM` 후 다음 head 를 본다.
+ *
+ * @module core/lock/fifo-waitlist
+ */
+
+/**
+ * @typedef {Object} RedisLike - 이 헬퍼가 쓰는 ioredis 메서드 부분집합(테스트 fake 도 충족).
+ * @property {(key: string) => Promise<number>} incr
+ * @property {(key: string, score: number, member: string) => Promise<any>} zadd
+ * @property {(key: string, member: string) => Promise<any>} zrem
+ * @property {(key: string, start: number, stop: number) => Promise<string[]>} zrange
+ * @property {(key: string) => Promise<number>} zcard
+ */
+
+/** reaping 무한루프 방지 상한(연속 stale head 청소 횟수). */
+const MAX_REAP_PER_CHECK = 16
+
+export class FifoWaitlist {
+  /** @type {RedisLike} */ #client
+  /** @type {(key: string) => string} key → waitlist zset 키. */ #zkey
+  /** @type {string} 전역 시퀀스 카운터 키(INCR). */ #seqKey
+
+  /**
+   * @param {RedisLike} client - ioredis 호환 클라이언트(명령용, redis-lock 과 공유).
+   * @param {{ zkey: (key: string) => string, seqKey: string }} opts -
+   *   `zkey` 락 key → zset 키 매퍼, `seqKey` 전역 시퀀스 카운터 키(네임스페이스 일원화).
+   */
+  constructor(client, { zkey, seqKey }) {
+    this.#client = client
+    this.#zkey = zkey
+    this.#seqKey = seqKey
+  }
+
+  /**
+   * 대기열에 합류 — 전역 INCR 시퀀스를 점수로 부여해 도착 순서를 확정한다.
+   * @param {string} key @param {string} token @param {number} deadlineMs - 이 대기자의 시한(now+waitMs); reaping 판정용.
+   * @returns {Promise<string>} 등록된 member 문자열(leave 에 그대로 넘겨 정확히 제거).
+   */
+  async join(key, token, deadlineMs) {
+    const seq = Number(await this.#client.incr(this.#seqKey))
+    const member = `${token}:${deadlineMs}`
+    await this.#client.zadd(this.#zkey(key), seq, member)
+    return member
+  }
+
+  /**
+   * 내가 큐의 head 인지 — 시한 지난(버려진) head 를 청소한 뒤 맨 앞 token 과 비교.
+   * @param {string} key @param {string} token @param {number} nowMs - 현재 시각(Date.now()).
+   * @returns {Promise<boolean>}
+   */
+  async isHead(key, token, nowMs) {
+    for (let i = 0; i < MAX_REAP_PER_CHECK; i++) {
+      const head = await this.#client.zrange(this.#zkey(key), 0, 0)
+      if (head.length === 0) return false
+      const member = head[0]
+      const sep = member.lastIndexOf(':')
+      const deadline = Number(member.slice(sep + 1))
+      if (deadline && deadline < nowMs) {
+        // 시한 초과 head = 떠나지 못하고 죽은 대기자 → 청소하고 다음 head 확인.
+        await this.#client.zrem(this.#zkey(key), member)
+        continue
+      }
+      return member.slice(0, sep) === token
+    }
+    return false
+  }
+
+  /** 대기열에서 이탈(획득 성공/타임아웃/취소 시). @param {string} key @param {string} member - join 이 돌려준 값. @returns {Promise<void>} */
+  async leave(key, member) {
+    await this.#client.zrem(this.#zkey(key), member)
+  }
+
+  /** 현재 대기자 수. @param {string} key @returns {Promise<number>} */
+  async size(key) {
+    return this.#client.zcard(this.#zkey(key))
+  }
+}