mega-framework 0.1.0

package/src/adapters/mega-db-adapter.js

@@ -0,0 +1,72 @@
+// @ts-check
+/**
+ * MegaDbAdapter — SQL · Document DB 어댑터 공통 베이스 (추상, 08-class-specs §3.3).
+ *
+ * 트랜잭션을 표준화한다. 구체: `MegaPostgresAdapter` / `MegaMongoAdapter` /
+ * `MegaMariaAdapter` / `MegaSqliteAdapter`.
+ *
+ * @module adapters/mega-db-adapter
+ */
+import { MegaInternalError } from '../errors/http-errors.js'
+import { MegaAdapter } from './mega-adapter.js'
+
+export class MegaDbAdapter extends MegaAdapter {
+  /**
+   * @param {object} [config]
+   */
+  constructor(config) {
+    super(config)
+    if (new.target === MegaDbAdapter) {
+      throw new MegaInternalError(
+        'adapter.abstract_instantiation',
+        'MegaDbAdapter is abstract — use a concrete DB adapter (MegaPostgresAdapter, MegaSqliteAdapter, ...).',
+        { details: { class: 'MegaDbAdapter' } },
+      )
+    }
+  }
+
+  /**
+   * 명시적 트랜잭션 경계 (ADR-010). 성공 시 commit, throw 시 rollback.
+   * driver 별 구현 (postgres `BEGIN/COMMIT/ROLLBACK`, MongoDB `session.withTransaction`).
+   * nested 호출은 driver 별 (postgres SAVEPOINT, MongoDB throw `adapter.nested_transaction_unsupported`).
+   *
+   * @template T
+   * @param {(db: any) => Promise<T>} _fn - 트랜잭션 컨텍스트의 `db` 를 받는 콜백.
+   * @returns {Promise<T>}
+   */
+  async withTransaction(_fn) {
+    return this._notImplemented('withTransaction')
+  }
+
+  /**
+   * 계측된 SQL 쿼리 실행 (ADR-138). `_instrument('query', …)` 로 감싸므로 자동 span(`<driver>.query`,
+   * `db.system.name`/`db.query.text`/`mega.rows_affected`)·stats·상태 검증이 한 번에 처리된다.
+   * `MegaModel.db.query`(native handle 직접 호출)와 달리 트레이싱/메트릭에 잡힌다.
+   *
+   * 진행 중 트랜잭션이 있으면 **같은 connection** 위에서 실행해 격리를 유지한다(구체 어댑터가
+   * 트랜잭션 컨텍스트를 인식) — 트랜잭션 밖이면 풀/단일 연결. 결과 형태는 driver native 를 그대로
+   * 돌려준다(ADR-009 — 어댑터별 차이 허용). SQL 어댑터(postgres/maria/sqlite) 만 구현하며,
+   * Document DB(mongo) 는 SQL `query` 개념이 없어 미구현(`adapter.not_implemented`).
+   *
+   * @param {string} _sql - 파라미터화된 SQL(placeholder `$1`/`?` 보존 — 값 인터폴레이션 금지).
+   * @param {any[]} [_params] - placeholder 바인딩 값.
+   * @returns {Promise<any>} driver native 쿼리 결과.
+   */
+  async query(_sql, _params) {
+    return this._notImplemented('query')
+  }
+
+  /**
+   * `query` span 시작 속성 — 파라미터화된 SQL 만 `statement` 로 싣는다(트레이서가 `db.query.text` 로
+   * 매핑). 문자열이 아니면(쿼리 빌더 객체 등) `mega.query_unparam:true` 로 폴백 — 원본 페이로드
+   * 노출·추측 정제를 피한다(ADR-138). placeholder(`$1`/`?`)는 보존되고 바인딩 값은 싣지 않으므로
+   * 시크릿 누출·라벨 카디널리티 폭증이 없다.
+   *
+   * @protected
+   * @param {unknown} sql
+   * @returns {object}
+   */
+  _queryStartAttrs(sql) {
+    return typeof sql === 'string' ? { statement: sql } : { 'mega.query_unparam': true }
+  }
+}

package/src/adapters/mega-lock-adapter.js

@@ -0,0 +1,118 @@
+// @ts-check
+/**
+ * MegaLockAdapter — 분산 락(distributed lock) 표준 인터페이스 (추상, ADR-101/113).
+ *
+ * **첫 lock 도메인 어댑터 베이스**. DB(트랜잭션)·cache(key-value)·bus(메시징)와 구분되는
+ * 4번째 도메인으로, 여러 프로세스·인스턴스가 같은 자원을 동시에 건드리지 못하게 하는 상호배제를
+ * 표준화한다. `ctx.lock(alias)` 가 본 베이스 인스턴스를 반환한다 (ADR-102 글로벌 공유 모델 확장).
+ *
+ * # 표준 표면 (구체가 override)
+ *   - `acquire(key, opts?)`  — 락 획득. 경합 시 retry(opts) 소진 후 실패하면 throw. 성공 시 `Lock` 핸들.
+ *   - `release(lock)`        — 락 해제 (idempotent 권장 — 이미 만료/해제돼도 비치명적).
+ *   - `extend(lock, ttl)`    — 락 TTL 연장. **연장된 새 핸들을 반환**(구체 driver 가 새 핸들을 줄 수
+ *                              있으므로 — redlock 이 그 예. void 로 두면 새 핸들이 유실됨, ADR-113).
+ *   - `withLock(key, opts, fn)` — convenience: 획득→fn 실행→해제 보장(throw 시에도). 구체 driver 가
+ *                              자동 연장(auto-extension)을 지원하면 fn 에 중단 신호를 넘길 수 있다(redlock `using`).
+ *
+ * # 구체 어댑터
+ *   `MegaRedlockAdapter` (`redlock`, Redis 단일 노드, ADR-113). 다른 backend(Zookeeper/etcd 등)도
+ *   본 베이스를 상속해 동일 표면으로 끼울 수 있다.
+ *
+ * # TTL 단위 = 밀리초 (cache 와 다름)
+ *   cache 의 ttl 은 **초**(Redis `EX`)지만, 분산 락 라이브러리(redlock)는 **밀리초**를 쓴다. 락은
+ *   임계구역 보호 시간이 보통 초 미만이라 ms 해상도가 필요하다. 혼동 방지로 {@link _assertLockTtl} 이
+ *   양의 정수 ms 만 통과시킨다 (cache 의 `_assertTtl` 과 의도적으로 분리 — 단위가 다름).
+ *
+ * @module adapters/mega-lock-adapter
+ */
+import { MegaInternalError, MegaValidationError } from '../errors/http-errors.js'
+import { MegaAdapter } from './mega-adapter.js'
+
+export class MegaLockAdapter extends MegaAdapter {
+  /**
+   * @param {object} [config]
+   */
+  constructor(config) {
+    super(config)
+    if (new.target === MegaLockAdapter) {
+      throw new MegaInternalError(
+        'adapter.abstract_instantiation',
+        'MegaLockAdapter is abstract — use a concrete lock adapter (MegaRedlockAdapter).',
+        { details: { class: 'MegaLockAdapter' } },
+      )
+    }
+  }
+
+  /**
+   * 락 획득. `key` 에 대한 상호배제 락을 `opts.ttl`(ms) 동안 잡는다. 이미 다른 곳이 잡고 있으면
+   * retry 설정(opts)만큼 재시도하고, 그래도 못 잡으면 throw(경합은 정상 도메인 결과 — 호출부가 처리).
+   *
+   * @param {string} _key - 락 자원 키.
+   * @param {{ ttl?: number, retryCount?: number, retryDelay?: number, retryJitter?: number }} [_opts]
+   *   - `ttl`(ms, 필수에 준함) 보유 시간. `retryCount/retryDelay/retryJitter` 는 경합 시 재시도 정책(driver 별).
+   * @returns {Promise<any>} 락 핸들(release/extend 에 전달).
+   */
+  async acquire(_key, _opts) {
+    return this._notImplemented('acquire')
+  }
+
+  /**
+   * 락 해제. 이미 만료/해제됐어도 비치명적(자동 만료가 안전망) — 구체 어댑터는 best-effort 로 처리.
+   * @param {any} _lock - {@link acquire} 가 돌려준 핸들.
+   * @returns {Promise<void>}
+   */
+  async release(_lock) {
+    return this._notImplemented('release')
+  }
+
+  /**
+   * 락 TTL 연장. 임계구역이 길어질 때 만료 전에 보유 시간을 늘린다.
+   *
+   * **반환된 핸들을 이후 release/extend 에 써야 한다** — 구체 driver(redlock)가 연장 시 **새 핸들**을
+   * 만들 수 있어, 기존 핸들은 무효가 될 수 있다(ADR-113). 그래서 베이스 계약을 `Promise<void>` 가
+   * 아니라 연장된 핸들 반환으로 둔다.
+   *
+   * @param {any} _lock @param {number} _ttl - 추가 보유 시간(ms).
+   * @returns {Promise<any>} 연장된 락 핸들.
+   */
+  async extend(_lock, _ttl) {
+    return this._notImplemented('extend')
+  }
+
+  /**
+   * convenience — 락을 잡고 `fn` 을 실행한 뒤 **반드시 해제**한다(fn 이 throw 해도 release 보장).
+   *
+   * 구체 driver 가 자동 연장을 지원하면(redlock `using`) fn 실행 중 만료가 임박할 때 자동으로 TTL 을
+   * 늘리고, 연장 실패 시 fn 에 중단 신호(abort signal)를 전달한다 — 이 경우 fn 시그니처는 `(signal)`
+   * 이고, 자동 연장이 없는 단순 구현이면 `(lock)` 을 받는다(구체 어댑터 JSDoc 참조).
+   *
+   * @template T
+   * @param {string} _key @param {{ ttl?: number }} _opts @param {(arg: any) => Promise<T>} _fn
+   * @returns {Promise<T>}
+   */
+  async withLock(_key, _opts, _fn) {
+    return this._notImplemented('withLock')
+  }
+
+  /**
+   * 락 ttl 검증 헬퍼 (구체 어댑터의 acquire/extend/withLock 에서 사용). **밀리초** 양의 정수만 통과.
+   *
+   * cache 의 `_assertTtl`(초 단위, undefined=무한 허용)과 달리 락 ttl 은:
+   *   - **필수** — 무한 락은 데드락 위험이라 허용하지 않는다(undefined 거부).
+   *   - **밀리초** 양의 정수 — 0/음수/소수/비숫자 거부.
+   *
+   * @protected
+   * @param {number} [ttl] - 보유 시간(ms).
+   * @returns {void}
+   * @throws {MegaValidationError} `lock.invalid_ttl`
+   */
+  _assertLockTtl(ttl) {
+    if (typeof ttl !== 'number' || Number.isNaN(ttl) || !Number.isInteger(ttl) || ttl <= 0) {
+      throw new MegaValidationError(
+        'lock.invalid_ttl',
+        `lock ttl must be a positive integer number of milliseconds (got: ${ttl}). Infinite locks are not allowed (deadlock risk).`,
+        { details: { ttl } },
+      )
+    }
+  }
+}

package/src/adapters/mega-log-sink-adapter.js

@@ -0,0 +1,46 @@
+// @ts-check
+/**
+ * MegaLogSinkAdapter — 로그 sink 표준 인터페이스 (추상, 08-class-specs §3.6, ADR-023).
+ *
+ * pino 의 multi-sink 백엔드. 구체: `MegaConsoleSink` / `MegaFileSink` / `MegaTelegramSink`
+ * `write` 는 **동기** (메인 이벤트루프 blocking 금지 — 무거운 IO 는 worker thread).
+ * `connect` 는 보통 no-op, `disconnect` ≡ `close`.
+ *
+ * @module adapters/mega-log-sink-adapter
+ */
+import { MegaInternalError } from '../errors/http-errors.js'
+import { MegaAdapter } from './mega-adapter.js'
+
+export class MegaLogSinkAdapter extends MegaAdapter {
+  /**
+   * @param {object} [config]
+   */
+  constructor(config) {
+    super(config)
+    if (new.target === MegaLogSinkAdapter) {
+      throw new MegaInternalError(
+        'adapter.abstract_instantiation',
+        'MegaLogSinkAdapter is abstract — use a concrete sink (MegaConsoleSink, MegaFileSink, MegaTelegramSink).',
+        { details: { class: 'MegaLogSinkAdapter' } },
+      )
+    }
+  }
+
+  /**
+   * 로그 레코드 기록 (동기). 비동기 IO 가 필요하면 내부 큐잉 + worker thread (구체별).
+   * @param {object} _record - pino 표준 record.
+   * @returns {void}
+   */
+  write(_record) {
+    this._notImplemented('write')
+  }
+
+  /**
+   * 큐 drain + flush 보장. shutdown 마지막 단계 (07-sequence-diagrams §6).
+   * 디폴트는 `disconnect()` 위임 — 구체가 큐 drain 으로 override.
+   * @returns {Promise<void>}
+   */
+  async close() {
+    return this.disconnect()
+  }
+}

package/src/adapters/mega-session-adapter.js

@@ -0,0 +1,72 @@
+// @ts-check
+/**
+ * MegaSessionAdapter — 세션 저장소 표준 인터페이스 (추상, 08-class-specs §3.7, ADR-046).
+ *
+ * file / Redis 양쪽 같은 표면. 구체: `MegaFileSessionAdapter` / `MegaRedisSessionAdapter`
+ * `sessionId` 는 ULID (외부 wire 에는 HMAC sign — 본 어댑터는 평문 sid 로만 동작).
+ * file 드라이버 `cleanup()` 은 `mega scheduler` 가 cron 으로 호출, Redis 는 TTL 자동.
+ *
+ * @module adapters/mega-session-adapter
+ */
+import { MegaInternalError } from '../errors/http-errors.js'
+import { MegaAdapter } from './mega-adapter.js'
+
+export class MegaSessionAdapter extends MegaAdapter {
+  /**
+   * @param {object} [config]
+   */
+  constructor(config) {
+    super(config)
+    if (new.target === MegaSessionAdapter) {
+      throw new MegaInternalError(
+        'adapter.abstract_instantiation',
+        'MegaSessionAdapter is abstract — use a concrete session adapter (MegaFileSessionAdapter, MegaRedisSessionAdapter).',
+        { details: { class: 'MegaSessionAdapter' } },
+      )
+    }
+  }
+
+  /**
+   * @param {string} _sessionId
+   * @returns {Promise<object | null>} 세션 record — 없으면 `null`.
+   */
+  async load(_sessionId) {
+    return this._notImplemented('load')
+  }
+
+  /**
+   * @param {string} _sessionId
+   * @param {object} _record
+   * @returns {Promise<void>}
+   */
+  async save(_sessionId, _record) {
+    return this._notImplemented('save')
+  }
+
+  /**
+   * @param {string} _sessionId
+   * @returns {Promise<void>}
+   */
+  async destroy(_sessionId) {
+    return this._notImplemented('destroy')
+  }
+
+  /**
+   * rolling TTL 갱신 (매 요청, ADR-046).
+   * @param {string} _sessionId
+   * @param {number} _ttlMs
+   * @returns {Promise<void>}
+   */
+  async touch(_sessionId, _ttlMs) {
+    return this._notImplemented('touch')
+  }
+
+  /**
+   * 만료 세션 정리. file 드라이버는 스캔 후 삭제, Redis 는 TTL 자동(no-op). `MegaSchedule` 로 자동 등록
+   * 가능(ADR-129/046).
+   * @returns {Promise<number>} 정리된(삭제된) 세션 수.
+   */
+  async cleanup() {
+    return this._notImplemented('cleanup')
+  }
+}