mega-framework 0.1.10 → 0.1.11

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

@@ -0,0 +1,276 @@
+// @ts-check
+/**
+ * RedisLockDriver — redis 기반 **진짜 분산** 락 driver (ADR-226).
+ *
+ * 멀티 프로세스·멀티 노드에서 상호배제를 보장하는 유일한 driver. 단일 redis 노드에 대한 Redlock 단일-인스턴스
+ * 알고리즘(`SET key token NX PX ttl` + 소유 토큰 + Lua 원자 해제)을 raw ioredis 클라이언트로 직접 구현한다.
+ * 기존 {@link import('../../adapters/redlock-adapter.js')}(redlock 라이브러리, `ctx.lock(alias)`)와 별개 —
+ * 이쪽은 fence/FIFO/watchdog 를 위해 명령을 직접 제어해야 해서 raw 클라이언트를 쓴다(라이브러리 미경유).
+ * redis 클라이언트는 cache 어댑터가 소유한 것을 **빌려** 쓴다(연결 생애주기는 cache 가 관리 — close 에서
+ * quit 하지 않음). 단, Pub/Sub 구독은 별도 연결이 필요하므로 `duplicate()` 한 구독 연결만 이 driver 가 소유한다.
+ *
+ * # 키 네임스페이스(`mega:lock:` 접두)
+ *   - `…:v:{key}` 락 값(member=token, PX ttl) · `…:f:{key}` fence 카운터(INCR) ·
+ *     `…:w:{key}` FIFO 대기열 zset · `…:c:{key}` 해제 알림 Pub/Sub 채널.
+ *
+ * # 대기(waitMs) — Pub/Sub 깨우기
+ *   경합 시 폴링 대신 해제 채널을 구독해 깨어난다. 구독은 `PSUBSCRIBE …:c:*` 하나로 모든 키를 받고
+ *   채널에서 key 를 역산해 해당 대기자만 깨운다. 깨우기 누락(메시지 유실) 대비로 짧은 안전 폴링도 병행한다.
+ *
+ * # fence / FIFO / watchdog
+ *   - fence: 획득 직후 `INCR …:f:{key}` — 단조 증가 토큰(외부 시스템의 stale-writer 차단). 카운터는 영속.
+ *   - FIFO: {@link import('./fifo-waitlist.js').FifoWaitlist}(zset) — head 가 됐을 때만 SET 시도.
+ *   - watchdog(extendable): manager 가 `extend` 를 주기 호출(Lua PEXPIRE) — driver 는 1회 연장만 책임.
+ *
+ * driver 계약은 {@link import('./contract.js').LockDriver} 를 따른다(typedef — 런타임 implements 아님).
+ * @module core/lock/redis-lock
+ */
+import { generateToken } from './contract.js'
+import { FifoWaitlist } from './fifo-waitlist.js'
+
+/** 키 접두 — 다른 redis 사용처(cache 등)와 충돌 방지. */
+const PREFIX = 'mega:lock'
+/** Pub/Sub 깨우기를 놓쳐도 진행하도록 하는 안전 폴링 간격(ms). */
+const SAFETY_POLL_MS = 50
+
+/** 소유 토큰일 때만 삭제 + 해제 알림(원자). KEYS=[lock, channel] ARGV=[token]. @type {string} */
+const RELEASE_LUA = `
+if redis.call('get', KEYS[1]) == ARGV[1] then
+  redis.call('del', KEYS[1])
+  redis.call('publish', KEYS[2], '1')
+  return 1
+else
+  return 0
+end`
+
+/** 소유 토큰일 때만 PEXPIRE 연장(원자). KEYS=[lock] ARGV=[token, ttl]. @type {string} */
+const EXTEND_LUA = `
+if redis.call('get', KEYS[1]) == ARGV[1] then
+  return redis.call('pexpire', KEYS[1], ARGV[2])
+else
+  return 0
+end`
+
+export class RedisLockDriver {
+  /** @type {any} ioredis 호환 명령 클라이언트(cache 어댑터 소유 — 빌림). */ #client
+  /** @type {any} duplicate() 한 구독 연결(이 driver 소유 — close 에서 quit). */ #sub = null
+  /** @type {(() => any) | null} 구독 연결 생성자(테스트 주입). */ #createSub
+  /** @type {FifoWaitlist} */ #waitlist
+  /** @type {Map<string, Set<() => void>>} key → 해제 알림 대기 콜백. */ #wakers = new Map()
+  /** @type {boolean} PSUBSCRIBE 완료 여부(최초 대기 때 1회). */ #subscribed = false
+  /** @type {Promise<void> | null} 구독 진행 중 락(중복 구독 방지). */ #subscribing = null
+
+  /**
+   * @param {{ client: any, createSubscriber?: () => any }} opts
+   *   - `client` ioredis 호환 클라이언트(`set`/`eval`/`incr`/`zadd`… 보유). cache 어댑터의 `.native`.
+   *   - `createSubscriber` Pub/Sub 구독 연결 생성자(기본 `client.duplicate()`). 테스트 주입용.
+   */
+  constructor({ client, createSubscriber }) {
+    this.#client = client
+    this.#createSub = createSubscriber ?? (() => client.duplicate())
+    this.#waitlist = new FifoWaitlist(client, { zkey: (key) => `${PREFIX}:w:${key}`, seqKey: `${PREFIX}:seq` })
+  }
+
+  /** @type {'redis'} */
+  get name() {
+    return 'redis'
+  }
+
+  /** @param {string} key @returns {string} 락 값 키. */
+  #lockKey(key) {
+    return `${PREFIX}:v:${key}`
+  }
+
+  /** @param {string} key @returns {string} 해제 알림 채널. */
+  #chan(key) {
+    return `${PREFIX}:c:${key}`
+  }
+
+  /**
+   * 락 획득 — fifo 면 대기열 head 일 때만, 아니면 즉시 SET 후 경합 시 Pub/Sub 대기.
+   * @param {string} key @param {import('./contract.js').NormalizedLockOpts} opts
+   * @returns {Promise<import('./contract.js').DriverLock | null>}
+   */
+  async acquire(key, { ttl, waitMs, fifo, fence }) {
+    const token = generateToken()
+    const acquired = fifo
+      ? await this.#acquireFifo(key, token, ttl, waitMs)
+      : await this.#acquirePlain(key, token, ttl, waitMs)
+    if (!acquired) return null
+    if (!fence) return { token }
+    // fence: 락을 쥔 상태에서만 INCR — 단조 증가 보장(외부 시스템 stale-writer 차단용).
+    const fenceVal = Number(await this.#client.incr(`${PREFIX}:f:${key}`))
+    return { token, fence: fenceVal }
+  }
+
+  /**
+   * 비-FIFO 획득 — SET NX 즉시 시도, 실패 시 waitMs 안에서 해제 알림 받으며 재시도.
+   * @param {string} key @param {string} token @param {number} ttl @param {number} waitMs @returns {Promise<boolean>}
+   */
+  async #acquirePlain(key, token, ttl, waitMs) {
+    if (await this.#trySet(key, token, ttl)) return true
+    if (waitMs === 0) return false
+    const deadline = Date.now() + waitMs
+    while (Date.now() < deadline) {
+      await this.#waitForRelease(key, Math.min(SAFETY_POLL_MS, deadline - Date.now()))
+      if (await this.#trySet(key, token, ttl)) return true
+    }
+    return false
+  }
+
+  /**
+   * FIFO 획득 — 대기열 합류 후, 내가 head 이고 락이 비었을 때만 SET. waitMs 초과 시 이탈하고 실패.
+   * @param {string} key @param {string} token @param {number} ttl @param {number} waitMs @returns {Promise<boolean>}
+   */
+  async #acquireFifo(key, token, ttl, waitMs) {
+    const deadline = Date.now() + waitMs
+    // member 에 deadline 을 실어 합류 — 죽은 대기자를 head reaping 으로 청소할 수 있게(fifo-waitlist).
+    // waitMs=0(tryAcquire)이라도 head 검사 위해 잠깐 합류했다 finally 에서 바로 이탈.
+    const member = await this.#waitlist.join(key, token, deadline)
+    try {
+      for (;;) {
+        if (await this.#waitlist.isHead(key, token, Date.now())) {
+          if (await this.#trySet(key, token, ttl)) return true
+        }
+        if (Date.now() >= deadline) return false
+        await this.#waitForRelease(key, Math.min(SAFETY_POLL_MS, deadline - Date.now()))
+      }
+    } finally {
+      await this.#waitlist.leave(key, member)
+    }
+  }
+
+  /** SET NX PX 1회 시도. @param {string} key @param {string} token @param {number} ttl @returns {Promise<boolean>} */
+  async #trySet(key, token, ttl) {
+    const res = await this.#client.set(this.#lockKey(key), token, 'PX', ttl, 'NX')
+    return res === 'OK'
+  }
+
+  /**
+   * 해제 알림(Pub/Sub)을 timeoutMs 안에서 기다린다 — 알림 오면 즉시, 아니면 timeout 후 resolve(안전 폴링).
+   * @param {string} key @param {number} timeoutMs @returns {Promise<void>}
+   */
+  async #waitForRelease(key, timeoutMs) {
+    await this.#ensureSubscribed()
+    await new Promise((resolve) => {
+      let done = false
+      const finish = () => {
+        if (done) return
+        done = true
+        clearTimeout(timer)
+        const set = this.#wakers.get(key)
+        if (set) {
+          set.delete(waker)
+          if (set.size === 0) this.#wakers.delete(key)
+        }
+        resolve(undefined)
+      }
+      const waker = () => finish()
+      const timer = setTimeout(finish, Math.max(1, timeoutMs))
+      timer.unref?.()
+      const set = this.#wakers.get(key) ?? new Set()
+      set.add(waker)
+      this.#wakers.set(key, set)
+    })
+  }
+
+  /** 최초 대기 시 구독 연결 1회 PSUBSCRIBE. 동시 진입은 #subscribing 으로 직렬화. @returns {Promise<void>} */
+  async #ensureSubscribed() {
+    if (this.#subscribed) return
+    if (this.#subscribing) return this.#subscribing
+    this.#subscribing = (async () => {
+      const sub = this.#createSub()
+      sub.on('pmessage', (/** @type {string} */ _pattern, /** @type {string} */ channel) => {
+        // 채널 …:c:{key} 에서 key 역산 → 해당 대기자 전부 깨움(head 가 재시도).
+        const prefix = `${PREFIX}:c:`
+        if (!channel.startsWith(prefix)) return
+        const key = channel.slice(prefix.length)
+        const set = this.#wakers.get(key)
+        if (!set) return
+        for (const waker of [...set]) waker()
+      })
+      await sub.psubscribe(`${PREFIX}:c:*`)
+      this.#sub = sub
+      this.#subscribed = true
+    })()
+    try {
+      await this.#subscribing
+    } finally {
+      this.#subscribing = null
+    }
+  }
+
+  /**
+   * 해제 — 소유 토큰일 때만 DEL + 해제 알림(Lua 원자).
+   * @param {string} key @param {string} token @returns {Promise<boolean>}
+   */
+  async release(key, token) {
+    const res = await this.#client.eval(RELEASE_LUA, 2, this.#lockKey(key), this.#chan(key), token)
+    return Number(res) === 1
+  }
+
+  /**
+   * 연장 — 소유 토큰일 때만 PEXPIRE(Lua 원자).
+   * @param {string} key @param {string} token @param {number} ttl @returns {Promise<boolean>}
+   */
+  async extend(key, token, ttl) {
+    const res = await this.#client.eval(EXTEND_LUA, 1, this.#lockKey(key), token, String(ttl))
+    return Number(res) === 1
+  }
+
+  /** 강제 해제(관리용, 토큰 무관) — DEL + 해제 알림(대기자 깨움). @param {string} key @returns {Promise<void>} */
+  async forceRelease(key) {
+    await this.#client.del(this.#lockKey(key))
+    await this.#client.publish(this.#chan(key), '1')
+  }
+
+  /**
+   * 통계(best-effort) — `…:v:*`/`…:w:*` 키를 SCAN 으로 센다. O(키 수) 라 운영 관측용(고빈도 호출 비권장).
+   * @returns {Promise<{ driver: string, active: number, waiting: number }>}
+   */
+  async stats() {
+    const active = await this.#scanCount(`${PREFIX}:v:*`)
+    let waiting = 0
+    for (const wkey of await this.#scanKeys(`${PREFIX}:w:*`)) {
+      waiting += Number(await this.#client.zcard(wkey))
+    }
+    return { driver: 'redis', active, waiting }
+  }
+
+  /** MATCH 패턴 키 수를 SCAN 으로 센다. @param {string} match @returns {Promise<number>} */
+  async #scanCount(match) {
+    return (await this.#scanKeys(match)).length
+  }
+
+  /** MATCH 패턴 키를 SCAN 으로 모은다(커서 순회). @param {string} match @returns {Promise<string[]>} */
+  async #scanKeys(match) {
+    /** @type {string[]} */
+    const keys = []
+    let cursor = '0'
+    do {
+      const [next, batch] = await this.#client.scan(cursor, 'MATCH', match, 'COUNT', 100)
+      cursor = next
+      keys.push(...batch)
+    } while (cursor !== '0')
+    return keys
+  }
+
+  /** 정리 — 구독 연결만 quit(명령 클라이언트는 cache 소유라 건드리지 않음). @returns {Promise<void>} */
+  async close() {
+    for (const set of this.#wakers.values()) for (const waker of [...set]) waker()
+    this.#wakers.clear()
+    if (this.#sub) {
+      try {
+        await this.#sub.punsubscribe(`${PREFIX}:c:*`)
+        await this.#sub.quit()
+      } catch (e) {
+        // graceful quit 실패 → 강제 disconnect 로 소켓이라도 끊고, 에러는 wrap 해 상위로(매니저가 로깅).
+        if (typeof this.#sub.disconnect === 'function') this.#sub.disconnect()
+        throw new Error(`redis lock subscriber close failed: ${e instanceof Error ? e.message : String(e)}`, { cause: e })
+      } finally {
+        this.#sub = null
+        this.#subscribed = false
+      }
+    }
+  }
+}

package/src/core/mega-app.js

@@ -620,6 +620,35 @@ export class MegaApp {
     return this._adapterAccessors
   }
 
+  // ── ctx 없는 영역(getApp())용 표면 (ADR-228) ─────────────────────────────────
+  // 요청 ctx 가 없는 곳(백그라운드 타이머·외부 콜백·테스트)에서 ctx.lock/ctx.bus 와 **동일 표면**으로 쓰도록
+  // process-level 자원만 노출한다. 요청-스코프(req/user/session/요청 locale t)는 ctx 전용이라 여기 없다.
+
+  /** 분산 락 사용자 API(ADR-226) — `ctx.lock` 과 같은 process manager(콜러블 + .with/.acquire/...). @returns {any} */
+  get lock() {
+    return this._adapterAccessors.lock
+  }
+
+  /** 메시지 버스 사용자 API(ADR-227) — `ctx.bus` 와 같은 process manager(콜러블 + .emit/.on/.request/...). @returns {any} */
+  get bus() {
+    return this._adapterAccessors.bus
+  }
+
+  /** 앱 별명 → 공유 DB 어댑터(ADR-102). 미선언 별명은 throw. @param {string} alias @returns {import('../adapters/mega-adapter.js').MegaAdapter} */
+  db(alias) {
+    return this._adapterAccessors.db(alias)
+  }
+
+  /** 앱 별명 → 공유 캐시 어댑터(ADR-102). 미선언 별명은 throw. @param {string} alias @returns {import('../adapters/mega-adapter.js').MegaAdapter} */
+  cache(alias) {
+    return this._adapterAccessors.cache(alias)
+  }
+
+  /** 앱 로거(pino, ADR-141) — `ctx.log` 의 요청 바인딩 없는 베이스 로거. @returns {any} */
+  get log() {
+    return this.fastify.log
+  }
+
   /**
    * 이 앱의 서비스 레지스트리(name → 클래스, ADR-148). 요청 ctx 빌더가 `ctx.services.<name>` lazy DI 의
    * 클래스 lookup 출처로 읽는다. 부팅 orchestrator 가 `setServiceRegistry` 로 채운다.

package/src/core/migration/generate.js

@@ -330,7 +330,7 @@ async function generateInner(projectRoot, opts, lock) {
   const allCandidates = diffs.flatMap((d) => d.candidates)
   if (allCandidates.length > 0 && !check) {
     /** @type {Record<string, Record<string, string>> | null} */
-    let mapping = null
+    let mapping
     if (renames !== undefined) {
       mapping = parseRenamesSpec(renames, allCandidates)
     } else {

package/src/core/migration/journal.js

@@ -127,7 +127,7 @@ export function acquireGenerateLock(projectRoot) {
       if (/** @type {any} */ (cleanupErr).code !== 'ENOENT') throw cleanupErr
     }
     if (/** @type {any} */ (err).code !== 'EEXIST') throw err
-    let holder = ''
+    let holder
     try {
       holder = readFileSync(file, 'utf8').trim()
     } catch {

package/src/core/scope-registry.js

@@ -12,6 +12,8 @@ export const GLOBAL_ONLY_KEYS = Object.freeze([
   'server', // port, cluster, sessionSecret
   'wsHub', // mega ws-hub 명령용 (ADR-068)
   'wsCluster', // NATS 기반 WS 클러스터 broadcast/roster 자동배선 (ADR-176)
+  'lock', // 분산 락 driver 자동폴백 + 기본 옵션 — ctx.lock.with/.acquire (ADR-226)
+  'bus', // 메시지 버스 driver 자동폴백 + 기본 옵션 — ctx.bus.emit/.on/.request (ADR-227)
   'logger', // 전역 로거 sinks
   'apps', // 활성 앱 whitelist (ADR-066)
   'asp', // masterSecret 등 시크릿
@@ -50,5 +52,12 @@ export const APP_ONLY_KEYS = Object.freeze([
 /** Shared-Reference 키 — 전역 services 의 키만 참조 가능 */
 export const SHARED_REFERENCE_KEYS = Object.freeze(['databases', 'caches', 'buses'])
 
+/**
+ * Dual-scope 키 — 글로벌(mega.config.js)과 앱(app.config.js) **양쪽**에 정의 가능 (ADR-229).
+ * 글로벌은 fallback, 앱별 정의가 있으면 그 앱은 자기 manager 를 쓴다(앱별 lock/bus backend 분리). GLOBAL_ONLY_KEYS
+ * 에도 그대로 남겨(글로벌 정의 허용) 두고, validateAppConfig 가 이 목록을 wrong_scope 예외로 둔다.
+ */
+export const DUAL_SCOPE_KEYS = Object.freeze(['lock', 'bus'])
+
 export const ALL_GLOBAL_KEYS = Object.freeze(GLOBAL_ONLY_KEYS)
 export const ALL_APP_KEYS = Object.freeze(APP_ONLY_KEYS)

package/src/eslint-plugin/no-direct-model-import.js

@@ -65,7 +65,7 @@ const rule = {
   },
 
   create(context) {
-    const filename = context.filename ?? context.getFilename?.() ?? ''
+    const filename = context.filename ?? ''
     if (!isControllerOrRouteFile(filename)) return {}
 
     /**
@@ -77,7 +77,7 @@ const rule = {
         context.report({
           node,
           messageId: 'direct',
-          data: { source: sourceValue },
+          data: { source: String(sourceValue) },
         })
       }
     }

package/src/index.js

@@ -2,6 +2,8 @@
 export { MegaApp, MegaServer, Router, loadAndValidateConfig, loadRoutes } from './core/index.js'
 // 중앙 부팅 orchestrator + CLI (ADR-123)
 export { bootApp, buildBootContext } from './core/index.js'
+// ctx 없는 영역(백그라운드 타이머·외부 SDK 콜백·테스트)에서 booted 앱의 lock/bus/db/cache 접근 (ADR-228)
+export { getApp, hasApp } from './core/index.js'
 export { runCli, parseArgs, runWorkerHost, runSchedulerHost, dispatchPluginCommand, USAGE } from './cli/index.js'
 export { MegaService } from './core/index.js'
 export { MegaCluster } from './core/index.js'