mega-framework 0.1.6 → 0.1.7

package/src/{cli → lib}/ws-hub.js

@@ -23,7 +23,7 @@
  *   ADR-094 의 ASP echo 데모 hub 를 본 12-타입 hub 로 교체(ADR-097). 클라↔bridge ASP
  *   round-trip 검증은 embedded 종단(`core/ws-upgrade.js`, ws-upgrade.integration)으로 이전됨.
  *
- * @module cli/ws-hub
+ * @module lib/ws-hub
  */
 import { createHash, timingSafeEqual } from 'node:crypto'
 import { WebSocketServer } from 'ws'
@@ -32,8 +32,10 @@ import { buildPerMessageDeflate, COMPRESSION_DEFAULTS } from '../core/ws-compres
 import {
   HUB_MESSAGE_TYPES,
   HUB_CLOSE_CODES,
+  HUB_PROTOCOL_VERSION,
   createHubMessage,
   validateHubMessage,
+  negotiateHubProtocolVersion,
 } from '../lib/hub-protocol.js'
 import { MegaShutdown } from '../lib/mega-shutdown.js'
 
@@ -45,6 +47,12 @@ export const DEFAULT_HEARTBEAT_MS = 25_000
 /** 기본 최대 프레임 크기 (bytes, L3). 1 MiB — 정상 envelope 은 수 KB 이므로 넉넉하다. */
 export const DEFAULT_MAX_PAYLOAD_BYTES = 1_048_576
 
+/**
+ * bridge 별 송신 버퍼(bufferedAmount) 기본 상한(바이트) — 16 MiB. 초과 = 느린 bridge 가 fan-out 을 못
+ * 따라오는 것 → terminate(백프레셔). 클라↔bridge 종단(`ws-upgrade.js` DEFAULT_MAX_BUFFERED_BYTES)과 대칭.
+ */
+export const DEFAULT_MAX_BUFFERED_BYTES = 16 * 1024 * 1024
+
 /**
  * 토큰 timing-safe 비교 — sha256 으로 길이 정규화 후 `timingSafeEqual`. 후보 전체를 순회하여
  * 조기 반환 timing 누출도 줄인다(early-return 안 함).
@@ -68,19 +76,23 @@ export class MegaWsHub {
    * @param {string[]} [opts.acceptedTokens] - Bridge Bearer 토큰 화이트리스트 (비거나 누락 시 throw).
    * @param {number} [opts.heartbeatMs=25000] - register_ok 로 알려줄 heartbeat 주기.
    * @param {number} [opts.maxPayloadBytes=1048576] - WS 프레임 최대 크기(L3). 초과 시 ws 가 1009 close.
+   * @param {number} [opts.maxBufferedBytes=16777216] - bridge 별 송신 버퍼(bufferedAmount) 상한(바이트).
+   *   초과한 bridge 는 느린 소비자로 보고 terminate 한다 — fan-out 허브에서 bridge 1개가 느려도 모든
+   *   채널 메시지가 그 소켓 버퍼(힙)에 무한 적재돼 OOM 으로 가는 것을 막는다(백프레셔).
    * @param {string} [opts.hubId] - hub 식별자. 기본 ULID 자동 생성.
    * @param {import('../core/ws-compression.js').WsCompressionConfig} [opts.compression] - Bridge↔Hub
    *   link per-message deflate 압축(ADR-078 / wsHub.compression). 디폴트 OFF.
    *   bridge(MegaHubLink)와 양쪽이 협상해야 활성. 잘못된 threshold/windowBits 면 즉시 throw.
    * @param {{ warn?: Function, debug?: Function, info?: Function, error?: Function }} [opts.logger]
    */
-  constructor({ acceptedTokens, heartbeatMs = DEFAULT_HEARTBEAT_MS, maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES, hubId, compression, logger } = {}) {
+  constructor({ acceptedTokens, heartbeatMs = DEFAULT_HEARTBEAT_MS, maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES, maxBufferedBytes = DEFAULT_MAX_BUFFERED_BYTES, hubId, compression, logger } = {}) {
     if (!Array.isArray(acceptedTokens) || acceptedTokens.length === 0) {
       throw new Error('MegaWsHub: acceptedTokens must be a non-empty array (ADR-059).')
     }
     this._acceptedTokens = [...acceptedTokens]
     this._heartbeatMs = Number.isInteger(heartbeatMs) && heartbeatMs > 0 ? heartbeatMs : DEFAULT_HEARTBEAT_MS
     this._maxPayloadBytes = Number.isInteger(maxPayloadBytes) && maxPayloadBytes > 0 ? maxPayloadBytes : DEFAULT_MAX_PAYLOAD_BYTES
+    this._maxBufferedBytes = Number.isInteger(maxBufferedBytes) && maxBufferedBytes > 0 ? maxBufferedBytes : DEFAULT_MAX_BUFFERED_BYTES
     this._hubId = typeof hubId === 'string' && hubId.length > 0 ? hubId : `hub-${generateMessageId()}`
     // Bridge↔Hub link 압축(ADR-078). enabled=false → false. 잘못된 값은 생성자에서 즉시 throw.
     /** @type {false | Object} WebSocketServer perMessageDeflate 로 전달(start). */
@@ -91,7 +103,7 @@ export class MegaWsHub {
     this._wss = null
     /** heartbeat liveness 체크 interval (M3). @type {ReturnType<typeof setInterval> | null} */
     this._livenessTimer = null
-    /** 등록된 bridge 연결. connId → { socket, lastSeen }. @type {Map<string, { socket: import('ws').WebSocket, lastSeen: number }>} */
+    /** 등록된 bridge 연결. connId → { socket, lastSeen, protocolVersion }. @type {Map<string, { socket: import('ws').WebSocket, lastSeen: number, protocolVersion?: number }>} */
     this._bridges = new Map()
     /** presence. sessionId → { bridgeConnId, userId, channels:Set, metadata }. @type {Map<string, { bridgeConnId: string, userId: string, channels: Set<string>, metadata: Object }>} */
     this._sessions = new Map()
@@ -209,16 +221,30 @@ export class MegaWsHub {
    * @private
    */
   _handleRegister(connId, socket, msg) {
-    const payload = /** @type {{ instanceId: string, token: string, capabilities: string[] }} */ (/** @type {any} */ (msg).payload)
+    const payload = /** @type {{ instanceId: string, token: string, capabilities: string[], protocolVersion?: number }} */ (/** @type {any} */ (msg).payload)
     if (!isTokenAccepted(payload.token, this._acceptedTokens)) {
       this._log?.warn?.({ connId, instanceId: payload.instanceId }, 'ws-hub register denied — bad token (ADR-059)')
       this._safeSend(socket, createHubMessage({ type: T.ERROR, error: { code: 'hub.unauthorized', message: 'invalid bridge token' }, ref: /** @type {any} */ (msg).id }))
       socket.close(1008, 'unauthorized') // RFC 6455 1008 = policy violation
       return false
     }
-    this._bridges.set(connId, { socket, lastSeen: Date.now() })
-    this._log?.info?.({ connId, instanceId: payload.instanceId, hubId: this._hubId }, 'ws-hub bridge registered')
-    this._safeSend(socket, createHubMessage({ type: T.REGISTER_OK, payload: { hubId: this._hubId, acceptedAt: Date.now(), heartbeatMs: this._heartbeatMs } }))
+    // 프로토콜 버전 협상 — bridge 가 최대 지원 버전을 실으면 상호 최고 버전(min)을 채택해 회신한다.
+    // 부재 = 레거시 bridge → v1 고정 + register_ok 에 필드 미포함(strict 스키마 bridge 가 안 깨지게).
+    const hasVersionRequest = payload.protocolVersion !== undefined
+    const protocolVersion = hasVersionRequest
+      ? negotiateHubProtocolVersion(payload.protocolVersion)
+      : HUB_PROTOCOL_VERSION
+    this._bridges.set(connId, { socket, lastSeen: Date.now(), protocolVersion })
+    this._log?.info?.({ connId, instanceId: payload.instanceId, hubId: this._hubId, protocolVersion }, 'ws-hub bridge registered')
+    this._safeSend(socket, createHubMessage({
+      type: T.REGISTER_OK,
+      payload: {
+        hubId: this._hubId,
+        acceptedAt: Date.now(),
+        heartbeatMs: this._heartbeatMs,
+        ...(hasVersionRequest ? { protocolVersion } : {}),
+      },
+    }))
     return true
   }
 
@@ -478,6 +504,22 @@ export class MegaWsHub {
    * @private
    */
   _sendSerialized(socket, serialized) {
+    // 느린 bridge 백프레셔 가드: 송신 버퍼가 상한을 넘으면 더 쌓지 않고 연결을 끊는다 — fan-out 허브는
+    // bridge 1개만 느려도 모든 채널 메시지가 그 소켓 버퍼(힙)에 적재돼 OOM 으로 가는 최악 지점이다.
+    // terminate 후 'close' 이벤트가 `_handleBridgeGone` 을 불러 presence 정리 + BULK_LEAVE fan-out 이
+    // 따라온다(재연결은 bridge 의 retry 책임, ADR-098).
+    if (socket.bufferedAmount > this._maxBufferedBytes) {
+      this._log?.warn?.(
+        { bufferedAmount: socket.bufferedAmount, max: this._maxBufferedBytes },
+        'ws-hub slow bridge — terminating (backpressure)',
+      )
+      try {
+        socket.terminate()
+      } catch (err) {
+        this._log?.debug?.({ err }, 'ws-hub backpressure terminate failed (already closing)')
+      }
+      return
+    }
     try {
       socket.send(serialized)
     } catch (err) {
@@ -575,7 +617,8 @@ export async function runWsHubCli() {
   const hub = new MegaWsHub({ acceptedTokens, heartbeatMs, maxPayloadBytes, compression, logger: console })
   const addr = await hub.start({ port, host })
   // 독립 hub 프로세스 graceful shutdown(L2 + drain) — SIGTERM/SIGINT → hub.stop({ drain: true }).
-  MegaShutdown.register('mega-ws-hub', async () => hub.stop({ drain: true }))
+  // 'server' stage — hub 도 수용 종단이라 가장 먼저 drain 종료한다.
+  MegaShutdown.register('mega-ws-hub', async () => hub.stop({ drain: true }), { stage: 'server' })
   MegaShutdown.setupSignals()
   console.log(`[mega:ws-hub] listening on ${addr.host}:${addr.port} (hubId=${hub.hubId})`)
   return hub

package/src/models/crud-sql-builder.js

@@ -0,0 +1,133 @@
+// @ts-check
+/**
+ * CRUD SQL 조각 빌더 (ADR-212) — **순수 함수**(DB·어댑터 불요, 단위 테스트 용이).
+ *
+ * 모든 식별자(컬럼·테이블)는 `static schema` 화이트리스트에서만 도출하고 `dialect.quoteIdent` 로 인용한다.
+ * 값은 100% 파라미터 바인딩(`dialect.placeholder(i)` + params). **문자열 인터폴레이션 0**(ADR-009 안전 경계).
+ *
+ * @module models/crud-sql-builder
+ */
+import { MegaInternalError } from '../errors/http-errors.js'
+
+/**
+ * @typedef {Object} CrudDialect - dialect 모듈의 DML facet(ADR-212) 일부.
+ * @property {(name: string) => string} quoteIdent
+ * @property {(i: number) => string} placeholder
+ */
+
+/** 컬럼이 schema 화이트리스트에 있는지 — 없으면 throw. @param {string} col @param {Set<string>} cols @param {string} model @param {string} where */
+export function assertColumn(col, cols, model, where) {
+  if (!cols.has(col)) {
+    throw new MegaInternalError(
+      'model.unknown_column',
+      `${model}: '${col}' 은 static schema 컬럼이 아닙니다(${where}). 선언된 컬럼만 CRUD 에 쓸 수 있습니다 — 임의 SQL 은 this.query 사용.`,
+      { details: { model, column: col, where } },
+    )
+  }
+}
+
+/** limit/offset 정수 검증 — 음수/비정수 throw, 통과하면 그 정수 반환. @param {unknown} v @param {string} name @param {string} model @returns {number} */
+export function assertNonNegInt(v, name, model) {
+  if (!Number.isInteger(v) || /** @type {number} */ (v) < 0) {
+    throw new MegaInternalError(
+      'model.invalid_pagination',
+      `${model}: ${name} 은 0 이상의 정수여야 합니다(got ${JSON.stringify(v)}).`,
+      {
+        details: { model, [name]: v },
+      },
+    )
+  }
+  return /** @type {number} */ (v)
+}
+
+/**
+ * filter → WHERE 조각(접두 'WHERE' 없음) + params + 다음 placeholder 인덱스.
+ * 등호 AND + `IN`(배열) + `IS NULL`(null) 만(ADR-212 경계). `undefined` 값은 throw, 빈 배열은 `1=0`(매칭 0).
+ *
+ * @param {Record<string, any>} filter
+ * @param {Set<string>} cols - schema 컬럼 화이트리스트
+ * @param {CrudDialect} dialect
+ * @param {string} model - 에러 메시지용
+ * @param {number} [startIndex=1] - placeholder 시작 인덱스(SET 뒤 WHERE 처럼 이어붙일 때)
+ * @returns {{ clause: string, params: any[], nextIndex: number }}
+ */
+export function buildWhere(filter, cols, dialect, model, startIndex = 1) {
+  /** @type {string[]} */
+  const parts = []
+  /** @type {any[]} */
+  const params = []
+  let i = startIndex
+  for (const key of Object.keys(filter)) {
+    assertColumn(key, cols, model, 'filter')
+    const v = filter[key]
+    const id = dialect.quoteIdent(key)
+    if (v === undefined) {
+      throw new MegaInternalError(
+        'model.invalid_filter',
+        `${model}: filter['${key}'] 가 undefined 입니다(null 과 구분 — 의도 모호).`,
+        {
+          details: { model, column: key },
+        },
+      )
+    }
+    if (v === null) {
+      parts.push(`${id} IS NULL`)
+      continue
+    }
+    if (Array.isArray(v)) {
+      if (v.length === 0) {
+        parts.push('1=0') // 빈 IN → 매칭 0(안전).
+        continue
+      }
+      const phs = v.map(() => dialect.placeholder(i++))
+      parts.push(`${id} IN (${phs.join(', ')})`)
+      params.push(...v)
+      continue
+    }
+    parts.push(`${id} = ${dialect.placeholder(i++)}`)
+    params.push(v)
+  }
+  return { clause: parts.join(' AND '), params, nextIndex: i }
+}
+
+/**
+ * orderBy 옵션 → `ORDER BY ...` 조각(없으면 ''). 컬럼 화이트리스트 + dir enum.
+ * @param {string | Array<{ column: string, dir?: 'asc'|'desc' }> | undefined} orderBy
+ * @param {Set<string>} cols @param {CrudDialect} dialect @param {string} model
+ * @returns {string}
+ */
+export function buildOrderBy(orderBy, cols, dialect, model) {
+  if (orderBy === undefined) return ''
+  const list = typeof orderBy === 'string' ? [{ column: orderBy }] : orderBy
+  if (!Array.isArray(list) || list.length === 0) return ''
+  const items = list.map((o) => {
+    const col = typeof o === 'string' ? o : o.column
+    assertColumn(col, cols, model, 'orderBy')
+    const dir = typeof o === 'string' ? 'asc' : (o.dir ?? 'asc')
+    if (dir !== 'asc' && dir !== 'desc') {
+      throw new MegaInternalError(
+        'model.invalid_pagination',
+        `${model}: orderBy dir 은 'asc'|'desc' 만 — got '${dir}'.`,
+        { details: { model, dir } },
+      )
+    }
+    return `${dialect.quoteIdent(col)} ${dir.toUpperCase()}`
+  })
+  return ` ORDER BY ${items.join(', ')}`
+}
+
+/**
+ * select 옵션 → 컬럼 목록 조각(`*` 또는 인용 컬럼). 화이트리스트 검증.
+ * @param {string[] | undefined} select @param {Set<string>} cols @param {CrudDialect} dialect @param {string} model
+ * @returns {string}
+ */
+export function buildSelectList(select, cols, dialect, model) {
+  if (select === undefined) return '*'
+  if (!Array.isArray(select) || select.length === 0) return '*'
+  return select
+    .map((c) => {
+      assertColumn(c, cols, model, 'select')
+      return dialect.quoteIdent(c)
+    })
+    .join(', ')
+}

package/src/models/mega-model.js

@@ -41,6 +41,7 @@
  */
 import { MegaInternalError } from '../errors/http-errors.js'
 import * as MegaAdapterManager from '../adapters/adapter-manager.js'
+import * as crud from './model-crud.js'
 
 export class MegaModel {
   /**
@@ -85,12 +86,16 @@ export class MegaModel {
    * `fn` 인자 수는 어댑터별로 다르다 — SQL 어댑터는 `(client)` 1개, Mongo 어댑터는 `(db, session)`
    * 2개를 넘긴다(ADR-108). 따라서 가변 인자로 타입을 둔다(어댑터가 인자 형태의 정본).
    *
+   * `opts.isolation`(ADR-190) — SQL 격리수준 옵트인. driver 별 지원·제약은 어댑터가 정본
+   * (postgres/maria=top-level 만, sqlite='serializable' 만, mongodb=미지원 throw).
+   *
    * @template T
    * @param {(...args: any[]) => Promise<T>} fn - 트랜잭션 컨텍스트 native handle(들)을 받는 콜백.
+   * @param {{ isolation?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable' }} [opts] - 트랜잭션 옵션(ADR-190).
    * @returns {Promise<T>}
    */
-  static async withTransaction(fn) {
-    return this._resolveAdapter().withTransaction(fn)
+  static async withTransaction(fn, opts) {
+    return this._resolveAdapter().withTransaction(fn, opts)
   }
 
   /**
@@ -109,6 +114,81 @@ export class MegaModel {
     return this._resolveAdapter().query(sql, params)
   }
 
+  // ── 공통 CRUD (ADR-212) ────────────────────────────────────────────────
+  //
+  // `static schema`(ADR-204)를 선언한 모델에 한해, 컬럼·PK 메타에서 도출된 **bounded** CRUD 를
+  // 제공한다. 모든 식별자는 schema 화이트리스트 + `quoteIdent`, 값은 100% 파라미터 바인딩이라
+  // SQL 인젝션 표면이 없다(crud-sql-builder). raw 트랙(`this.query`/`this.db`)은 그대로 살아있다 —
+  // CRUD 는 추가 표면일 뿐 ADR-009 native 형태를 바꾸지 않는다. driver→dialect(DML facet) 디스패치는
+  // 단일 base(MegaModel)에서 런타임에 결정한다(A안). mongo 는 미지원(P3) — 호출 시 명시 throw.
+  //
+  // 본문·정규화·에러는 model-crud 에 위임하고 여기서는 `this`(Model 클래스)만 넘긴다.
+
+  /** 단건 조회(없으면 null). filter 는 등호 AND + 배열 IN + null IS NULL. @param {Record<string, any>} filter @param {{ select?: string[] }} [opts] @returns {Promise<any|null>} */
+  static async findOne(filter, opts) {
+    return crud.findOne(this, filter, opts)
+  }
+
+  /** PK 단건 조회(단일 PK 필요, 없으면 model.no_primary_key). @param {any} id @param {{ select?: string[] }} [opts] @returns {Promise<any|null>} */
+  static async findById(id, opts) {
+    return crud.findById(this, id, opts)
+  }
+
+  /** 다건 조회(기본 limit 없음 — 명시할 때만, ADR-212 #2). @param {Record<string, any>} [filter] @param {{ select?: string[], orderBy?: string | Array<{ column: string, dir?: 'asc'|'desc' }>, limit?: number, offset?: number }} [opts] @returns {Promise<any[]>} */
+  static async findMany(filter, opts) {
+    return crud.findMany(this, filter ?? {}, opts)
+  }
+
+  /** 조건 매칭 행 수. @param {Record<string, any>} [filter] @returns {Promise<number>} */
+  static async count(filter) {
+    return crud.count(this, filter)
+  }
+
+  /** 조건 매칭 행 존재 여부. @param {Record<string, any>} filter @returns {Promise<boolean>} */
+  static async exists(filter) {
+    return crud.exists(this, filter)
+  }
+
+  /** 페이지 조회. total 은 `{ withTotal: true }` 일 때만 추가 count(ADR-212 #4). @param {Record<string, any>} filter @param {{ select?: string[], orderBy?: any, limit: number, offset?: number, withTotal?: boolean }} opts @returns {Promise<{ rows: any[], limit: number, offset: number, total?: number }>} */
+  static async paginate(filter, opts) {
+    return crud.paginate(this, filter ?? {}, opts)
+  }
+
+  /** 단건 삽입. 기본 새 id 반환, `{ returning: true }` 면 레코드(ADR-212 #1). @param {Record<string, any>} data @param {{ returning?: boolean }} [opts] @returns {Promise<any>} */
+  static async insertOne(data, opts) {
+    return crud.insertOne(this, data, opts)
+  }
+
+  /** 다건 삽입. 기본 `{ count }`, `{ returning: true }` 면 레코드 배열(maria 미지원→throw). @param {Record<string, any>[]} rows @param {{ returning?: boolean }} [opts] @returns {Promise<{ count: number } | any[]>} */
+  static async insertMany(rows, opts) {
+    return crud.insertMany(this, rows, opts)
+  }
+
+  /** 정확히 한 행 갱신(>1 매칭→롤백 후 model.multiple_matches, ADR-212 #3). 변경 행 수 반환. @param {Record<string, any>} filter @param {Record<string, any>} patch @returns {Promise<number>} */
+  static async updateOne(filter, patch) {
+    return crud.updateOne(this, filter, patch)
+  }
+
+  /** 다건 갱신. 빈 filter 는 차단 — 전체 갱신은 `{ all: true }`. @param {Record<string, any>} filter @param {Record<string, any>} patch @param {{ all?: boolean }} [opts] @returns {Promise<number>} */
+  static async updateMany(filter, patch, opts) {
+    return crud.updateMany(this, filter, patch, opts)
+  }
+
+  /** 정확히 한 행 삭제(>1 매칭→롤백 후 model.multiple_matches). 삭제 행 수 반환. @param {Record<string, any>} filter @returns {Promise<number>} */
+  static async deleteOne(filter) {
+    return crud.deleteOne(this, filter)
+  }
+
+  /** 다건 삭제. 빈 filter 는 차단 — 전체 삭제는 `{ all: true }`. @param {Record<string, any>} filter @param {{ all?: boolean }} [opts] @returns {Promise<number>} */
+  static async deleteMany(filter, opts) {
+    return crud.deleteMany(this, filter, opts)
+  }
+
+  /** upsert(INSERT … ON CONFLICT/DUPLICATE KEY UPDATE). `opts.conflict` 는 PK/unique 컬럼 필수. @param {Record<string, any>} data @param {{ conflict: string[], update?: string[], returning?: boolean }} opts @returns {Promise<any>} */
+  static async upsert(data, opts) {
+    return crud.upsert(this, data, opts)
+  }
+
   /**
    * `adapter`/`table` 정합성을 검증하고 글로벌 매니저에서 어댑터(MegaDbAdapter)를 잡아 반환한다.
    *