mega-framework 0.1.0

package/src/core/ws-controller.js

@@ -0,0 +1,109 @@
+// @ts-check
+/**
+ * MegaWebSocketController — WS 채널 **필수 베이스** (ADR-074, 03-api-spec §2).
+ *
+ * HTTP 컨트롤러 베이스는 폐기됐지만(ADR-074), WS 는 N 개 메시지 타입을 한 객체로 묶고
+ * instance 가 namespace 별 상태를 가지는 게 본질이라 클래스를 강제한다. 라이프사이클 3 훅
+ * (`onConnect` / `onMessage` / `onDisconnect`) + 메시지 `type` 기반 **자동 디스패치** (ADR-015):
+ * `{ type: 'chat.send' }` → `this['chat.send'](sock, msg, ctx)`, 해당 메서드 없으면 onMessage 폴백.
+ *
+ * # 이 Step 의 범위
+ *   베이스 계약 + 디스패치 로직만 제공한다. 실 소켓 upgrade 연결과 ctx/services 주입 wiring 은
+ *   후속 Step(`router.ws`/`app.ws` upgrade, hub 통합) 에서 {@link MegaWebSocketController#_bind}
+ *   을 통해 붙는다. 본 Step 에서는 디스패치 라우팅을 실 소켓 없이 단위 테스트로 검증한다.
+ *
+ * @module core/ws-controller
+ */
+import { WS_TYPE_PATTERN } from './ws-message.js'
+
+export class MegaWebSocketController {
+  constructor() {
+    /** @type {any} */ this._ctxRef = null
+    /** @type {any} */ this._appRef = null
+    /** @type {any} */ this._logRef = null
+    /** @type {any} */ this._servicesRef = null
+  }
+
+  /**
+   * 프레임워크가 채널 인스턴스에 컨텍스트를 바인딩한다 (후속 Step 의 upgrade 처리에서 호출).
+   * **사용자 코드는 호출하지 않는다** (framework-internal).
+   *
+   * @param {{ ctx?: any, app?: any, log?: any, services?: any }} [binding]
+   * @returns {void}
+   */
+  _bind(binding = {}) {
+    this._ctxRef = binding.ctx ?? null
+    this._appRef = binding.app ?? null
+    this._logRef = binding.log ?? null
+    this._servicesRef = binding.services ?? null
+  }
+
+  /** 현재 채널 컨텍스트 (미바인딩 시 null). */
+  get ctx() {
+    return this._ctxRef
+  }
+
+  /** 소속 MegaApp (미바인딩 시 null). */
+  get app() {
+    return this._appRef
+  }
+
+  /** request_id 자동 주입 로거 (미바인딩 시 null). */
+  get log() {
+    return this._logRef
+  }
+
+  /** 자동 DI 핸들 — `ctx.services` 와 동일 (미바인딩 시 null). */
+  get services() {
+    return this._servicesRef
+  }
+
+  /**
+   * 연결 수립 시 1회 호출. 기본 no-op — 서브클래스가 override.
+   * @param {any} _sock - WS 소켓.
+   * @param {any} _ctx - 채널 컨텍스트.
+   * @returns {Promise<void>}
+   */
+  async onConnect(_sock, _ctx) {}
+
+  /**
+   * 디스패치되지 않은 메시지의 폴백 핸들러. 기본 no-op — 서브클래스가 override.
+   * @param {any} _sock - WS 소켓.
+   * @param {Object} _msg - 검증된 WS envelope.
+   * @param {any} _ctx - 채널 컨텍스트.
+   * @returns {Promise<any>}
+   */
+  async onMessage(_sock, _msg, _ctx) {}
+
+  /**
+   * 연결 종료 시 호출. 기본 no-op — 서브클래스가 override.
+   * @param {any} _sock - WS 소켓.
+   * @param {any} _ctx - 채널 컨텍스트.
+   * @returns {Promise<void>}
+   */
+  async onDisconnect(_sock, _ctx) {}
+
+  /**
+   * 수신 메시지 자동 디스패치 (ADR-015). 프레임워크(후속 Step)가 소켓 message 마다 호출한다.
+   *
+   * `msg.type` 이 `domain.action` 패턴({@link WS_TYPE_PATTERN}) 이고 동명 메서드가 있으면 그
+   * 메서드를, 아니면 {@link MegaWebSocketController#onMessage} 폴백을 호출한다. 패턴이 점(`.`)을
+   * 강제하므로 `constructor` / `onMessage` 같은 베이스 멤버명은 type 으로 매칭될 수 없다 —
+   * prototype 오염 / 의도치 않은 베이스 호출을 구조적으로 차단.
+   *
+   * @param {any} sock - WS 소켓.
+   * @param {{ type?: string }} msg - 검증된 WS envelope (ws-message.js).
+   * @param {any} ctx - 채널 컨텍스트.
+   * @returns {Promise<any>} 핸들러 반환값.
+   */
+  async dispatch(sock, msg, ctx) {
+    const type = msg?.type
+    if (typeof type === 'string' && WS_TYPE_PATTERN.test(type)) {
+      const handler = /** @type {any} */ (this)[type]
+      if (typeof handler === 'function') {
+        return handler.call(this, sock, msg, ctx)
+      }
+    }
+    return this.onMessage(sock, msg, ctx)
+  }
+}

package/src/core/ws-message.js

@@ -0,0 +1,176 @@
+// @ts-check
+/**
+ * WS 메시지 envelope (ADR-015, 04-data-models §6.2 정본).
+ *
+ * 모든 WebSocket 메시지는 단일 envelope `{ v, id, type, ts, ns?, payload?, error?, ref? }`
+ * 로 통일된다. 이 envelope 은 두 곳의 공통 바탕이다:
+ *   (1) 클라이언트 ↔ bridge 비즈니스 메시지
+ *   (2) bridge ↔ hub 12-타입 프로토콜 (03-api-spec §7) — `type` 값만 12종 중 하나로 얹음
+ *
+ * HTTP 응답 envelope (`{ ok, data, meta }`, core/envelope.js) 와는 **별개** — transport 가 다르다.
+ *
+ * # 설계 메모
+ *   - 검증은 AJV 의존 없이 고정 shape 를 직접 검사한다 (신규 의존성 회피). bridge↔hub 단계에서
+ *     스키마 컴파일이 필요해지면 {@link WS_MESSAGE_SCHEMA} 를 재사용 (별도 결정).
+ *   - `id` 는 ULID (정렬 가능 + 충돌 거의 없음). 정식 `MegaIdGen` 라이브러리화는 OQ-014 로 남김 —
+ *     본 모듈은 zero-dep private 생성기만 둔다.
+ *
+ * @module core/ws-message
+ */
+import { randomBytes } from 'node:crypto'
+
+/** 현 프로토콜 버전 (04-data-models §6.2 `v: { const: 1 }`). */
+export const WS_PROTOCOL_VERSION = 1
+
+/**
+ * 메시지 `type` / `error.code` 패턴 — `domain.action[.result]` (ADR-016, §6.2/§6.3).
+ * 점(`.`)이 최소 1개 강제 → 베이스 메서드명(`onMessage` 등, 점 없음) 과 절대 충돌하지 않음.
+ */
+export const WS_TYPE_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/
+
+/** envelope 허용 키 집합 (additionalProperties: false 검증용). */
+const WS_ALLOWED_KEYS = new Set(['v', 'id', 'type', 'ts', 'ns', 'payload', 'error', 'ref'])
+
+/**
+ * WS 메시지 JSON Schema (04-data-models §6.2 정본 그대로).
+ * 후속 단계(bridge↔hub, AJV 컴파일)에서 재사용할 수 있도록 export.
+ * @type {Object}
+ */
+export const WS_MESSAGE_SCHEMA = {
+  type: 'object',
+  required: ['v', 'id', 'type', 'ts'],
+  properties: {
+    v: { const: WS_PROTOCOL_VERSION },
+    id: { type: 'string' },
+    type: { type: 'string', pattern: WS_TYPE_PATTERN.source },
+    ts: { type: 'integer' },
+    ns: { type: 'string' },
+    payload: { type: 'object', additionalProperties: true },
+    error: { type: 'object', additionalProperties: true },
+    ref: { type: 'string' },
+  },
+  additionalProperties: false,
+}
+
+/**
+ * Crockford base32 알파벳 (ULID 표준). 혼동 문자(I, L, O, U) 제외.
+ * 256 = 8 × 32 이므로 `byte % 32` 는 편향 없이 균일 분포.
+ */
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+
+/**
+ * 메시지 id 생성 — ULID (48-bit timestamp + 80-bit randomness = 26자 Crockford base32).
+ *
+ * 정식 `MegaIdGen` 라이브러리화는 OQ-014 로 예약 — 본 helper 는 envelope 전용 zero-dep 구현.
+ *
+ * @param {number} [timestamp] - epoch ms (테스트 주입용; 미지정 시 `Date.now()`).
+ * @returns {string} 26자 ULID (앞 10자 = 시간, 뒤 16자 = 랜덤).
+ */
+export function generateMessageId(timestamp = Date.now()) {
+  // 48-bit 타임스탬프 → 10자 (5bit × 10 = 50bit 여유, 실사용 48bit). 2^48 < 2^53 이라 정수 안전.
+  let time = timestamp
+  let timeChars = ''
+  for (let i = 0; i < 10; i++) {
+    timeChars = CROCKFORD[time % 32] + timeChars
+    time = Math.floor(time / 32)
+  }
+  // 80-bit 랜덤 → 16자 (char 당 5bit 균일). byte % 32 무편향 (256 = 8×32).
+  const rand = randomBytes(16)
+  let randChars = ''
+  for (let i = 0; i < 16; i++) randChars += CROCKFORD[rand[i] % 32]
+  return timeChars + randChars
+}
+
+/**
+ * WS 메시지 envelope 생성. `v` / `id` / `ts` 자동 채움 (§6.2).
+ *
+ * @param {Object} [fields]
+ * @param {string} [fields.type] - `domain.action` 패턴 (검증됨, 위반 시 throw). 누락 시 throw.
+ * @param {string} [fields.ns] - 채널 namespace (예: `'chat'`).
+ * @param {Object} [fields.payload] - 페이로드.
+ * @param {Object} [fields.error] - 에러 객체 (§6.3 모양 권장).
+ * @param {string} [fields.ref] - 요청-응답 매칭용. 서버 푸시는 생략.
+ * @param {{ id?: string, ts?: number }} [opts] - 테스트/재현용 주입 (미지정 시 자동).
+ * @returns {{ v: number, id: string, type: string, ts: number }} 완성된 envelope.
+ * @throws {Error} `type` 이 {@link WS_TYPE_PATTERN} 위반.
+ * @example
+ *   createWsMessage({ type: 'chat.send', ns: 'chat', payload: { text: 'hi' } })
+ *   // → { v: 1, id: '01HV...', type: 'chat.send', ts: 1735..., ns: 'chat', payload: { text: 'hi' } }
+ */
+export function createWsMessage({ type, ns, payload, error, ref } = {}, opts = {}) {
+  if (typeof type !== 'string' || !WS_TYPE_PATTERN.test(type)) {
+    throw new Error(
+      `createWsMessage: 'type' must match ${WS_TYPE_PATTERN.source} (ADR-016). Got: ${JSON.stringify(type)}`,
+    )
+  }
+  const ts = opts.ts ?? Date.now()
+  /** @type {Record<string, any>} */
+  const msg = { v: WS_PROTOCOL_VERSION, id: opts.id ?? generateMessageId(ts), type, ts }
+  if (ns !== undefined) msg.ns = ns
+  if (payload !== undefined) msg.payload = payload
+  if (error !== undefined) msg.error = error
+  if (ref !== undefined) msg.ref = ref
+  return /** @type {{ v: number, id: string, type: string, ts: number }} */ (msg)
+}
+
+/**
+ * 평탄 객체 판별 (배열·null 제외). payload/error 타입 검증용.
+ * @param {any} v
+ * @returns {boolean}
+ */
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v)
+}
+
+/**
+ * WS 메시지 envelope 검증 (§6.2 schema). 위반 사유 배열을 반환한다 (빈 배열 = 유효).
+ *
+ * 던지지 않고 사유 목록을 돌려주는 이유: 호출부(디스패처/hub)가 사유를 ERROR envelope 의
+ * `details` 로 그대로 실어 보낼 수 있도록 (ADR-075 배열 표준).
+ *
+ * @param {any} msg
+ * @returns {string[]} 위반 메시지 목록 (없으면 빈 배열).
+ */
+export function validateWsMessage(msg) {
+  if (!isPlainObject(msg)) return ['message must be a non-null object']
+  const errors = []
+  if (msg.v !== WS_PROTOCOL_VERSION) errors.push(`v must be ${WS_PROTOCOL_VERSION}`)
+  if (typeof msg.id !== 'string') errors.push('id must be a string')
+  if (typeof msg.type !== 'string' || !WS_TYPE_PATTERN.test(msg.type)) {
+    errors.push(`type must match ${WS_TYPE_PATTERN.source}`)
+  }
+  if (!Number.isInteger(msg.ts)) errors.push('ts must be an integer')
+  if (msg.ns !== undefined && typeof msg.ns !== 'string') errors.push('ns must be a string')
+  if (msg.payload !== undefined && !isPlainObject(msg.payload)) errors.push('payload must be an object')
+  if (msg.error !== undefined && !isPlainObject(msg.error)) errors.push('error must be an object')
+  if (msg.ref !== undefined && typeof msg.ref !== 'string') errors.push('ref must be a string')
+  for (const key of Object.keys(msg)) {
+    if (!WS_ALLOWED_KEYS.has(key)) errors.push(`unknown key: ${key}`)
+  }
+  return errors
+}
+
+/**
+ * JSON 문자열 → 검증된 WS 메시지 envelope. 파싱/검증 실패 시 throw (silent 금지).
+ *
+ * @param {string} json - wire 평문 JSON (ASP 복호화 후 또는 `P:` 평문).
+ * @returns {Object} 검증 통과한 envelope.
+ * @throws {Error} JSON 파싱 실패 또는 schema 위반 (메시지에 사유 포함).
+ */
+export function parseWsMessage(json) {
+  let obj
+  try {
+    obj = JSON.parse(json)
+  } catch (err) {
+    // 파싱 실패를 묻지 않고 wrap 후 throw. 호출부가 ERROR envelope 로 변환.
+    throw new Error(
+      `parseWsMessage: invalid JSON — ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
+    )
+  }
+  const errors = validateWsMessage(obj)
+  if (errors.length > 0) {
+    throw new Error(`parseWsMessage: invalid WS message — ${errors.join('; ')}`)
+  }
+  return obj
+}