mega-framework 0.1.0

package/src/core/ws-upgrade.js

@@ -0,0 +1,445 @@
+// @ts-check
+/**
+ * WS HTTP Upgrade 핸들오프 — embedded 모드.
+ *
+ * `router.ws`/`app.ws` 로 등록된 WS 라우트를 실 HTTP `'upgrade'` 이벤트에 연결한다.
+ * 토폴로지상 production 은 별도 hub 프로세스(02-architecture §5-3)지만, **single 모드**
+ * (`app.ws` + `app.listen`) 와 dev/통합 테스트는 서버 프로세스가 직접 WS 를 종단한다.
+ * 본 모듈은 그 embedded 종단 로직(코덱 선택 → 핸드셰이크 → 라이프사이클 구동)을 담는다.
+ *
+ * # 프레임 코덱 (ADR-083)
+ *   - ASP 활성 namespace: {@link MegaAspTerminator} 경유 `E:`(암호)/`P:`(평문) prefix.
+ *   - ASP 미설정 앱: prefix 없는 raw JSON (zero-config WS). WASM `MegaSocket` 정합은 후속 과제.
+ *
+ * # fail-closed (ADR-084)
+ *   decrypt/포맷 실패 → silent fallback 금지. 평문 `asp.error` 통지 후 close 4500.
+ *   잘못된 envelope → 명시적 error envelope 응답(연결은 유지 — 비치명적).
+ *
+ * # close code 카탈로그 (ADR-096)
+ *   - `1000` Normal closure (정상 종료)
+ *   - `1001` Going away (graceful shutdown — MegaApp.close)
+ *   - `1011` Internal error (onConnect 등 서버 내부 실패) — {@link CLOSE_CODE_INTERNAL_ERROR}
+ *   - `4500` Decrypt failed (ASP 키 mismatch / 프레임 손상) — {@link CLOSE_CODE_DECRYPT_FAILED}
+ *   4500 은 복호화 실패 **전용**이다. 일반 핸들러 실패를 4500 으로 닫으면 클라이언트가 키
+ *   mismatch 로 오해하므로, onConnect 등 서버 내부 오류는 RFC 6455 표준 `1011` 로 분리한다(M3).
+ *
+ * @module core/ws-upgrade
+ */
+import { createWsMessage, parseWsMessage, generateMessageId, WS_TYPE_PATTERN } from './ws-message.js'
+import { MegaAspDecryptError } from '../lib/asp/errors.js'
+import * as MegaTracing from '../lib/mega-tracing.js'
+import * as MegaMetrics from '../lib/mega-metrics.js'
+
+/**
+ * 라우팅 핸들러가 없는(=onMessage 폴백으로 가는) WS 메시지 type 을 접는 고정 라벨. HTTP 의
+ * `__unmatched__`(ADR-131 M-A)와 동일 정책 — 악의적 클라가 임의 type 을 무한히 보내 메트릭 라벨
+ * 카디널리티를 폭증시키는 풋건을 차단한다.
+ */
+export const UNHANDLED_WS_TYPE = '__unhandled__'
+
+/** ASP decrypt 실패 close code (ADR-084, transport_ws.rs CLOSE_CODE_DECRYPT_FAILED 와 일치). */
+export const CLOSE_CODE_DECRYPT_FAILED = 4500
+
+/**
+ * 서버 내부 오류 close code (RFC 6455 §7.4.1 표준 1011, M3).
+ * onConnect 실패 등 **복호화와 무관한** 서버측 오류에 사용한다 — 4500(decrypt) 과 의미 분리.
+ */
+export const CLOSE_CODE_INTERNAL_ERROR = 1011
+
+/**
+ * WS 프레임 코덱 — 평문/암호 와이어 변환을 추상화한다.
+ * @typedef {Object} WsFrameCodec
+ * @property {(frame: string) => string} decode - 수신 프레임 → 평문 JSON 문자열 (실패 시 throw).
+ * @property {(json: string) => string} encode - 평문 JSON → 송신 프레임 (기본: ASP 활성 시 암호).
+ * @property {(json: string) => string} encodePlain - 평문 JSON → 평문 송신 프레임 (asp.error 통지용).
+ * @property {boolean} isEncrypted - 기본 송신이 암호화인지.
+ */
+
+/**
+ * ASP 미설정 앱용 평문 코덱 — prefix 없는 raw JSON 그대로.
+ * @returns {WsFrameCodec}
+ */
+export function createPlainCodec() {
+  return {
+    decode: (frame) => frame,
+    encode: (json) => json,
+    encodePlain: (json) => json,
+    isEncrypted: false,
+  }
+}
+
+/**
+ * ASP 활성/비활성 namespace 용 코덱 — {@link MegaAspTerminator} 위임 (`E:`/`P:` prefix).
+ * @param {import('../lib/asp/ws-terminator.js').MegaAspTerminator} terminator
+ * @returns {WsFrameCodec}
+ */
+export function createAspCodec(terminator) {
+  return {
+    decode: (frame) => terminator.decodeFrame(frame).plain,
+    encode: (json) => terminator.encodeFrame(json),
+    encodePlain: (json) => terminator.encodeFrame(json, { plain: true }),
+    isEncrypted: terminator.isEncrypted,
+  }
+}
+
+/**
+ * 채널 핸들러에 전달되는 소켓 래퍼 — envelope 송신을 강제한다.
+ *
+ * 사용자 채널은 `sock.send({ type, payload, ref })` 형태로 호출한다. 내부에서
+ * {@link createWsMessage} 로 v/id/ts 를 자동 채운 valid envelope 을 만든 뒤 코덱으로
+ * 인코딩해 와이어에 쓴다. raw `ws` 소켓은 {@link MegaWsConnection#raw} 로 노출 (escape hatch).
+ */
+export class MegaWsConnection {
+  /**
+   * @param {import('ws').WebSocket} rawSocket
+   * @param {WsFrameCodec} codec
+   * @param {{ id?: string, ns?: string, path: string }} meta
+   */
+  constructor(rawSocket, codec, meta) {
+    /** @type {import('ws').WebSocket} */
+    this._raw = rawSocket
+    /** @type {WsFrameCodec} */
+    this._codec = codec
+    /** @type {string} 연결 식별자 (ULID). */
+    this.id = meta.id ?? generateMessageId()
+    /** @type {string|undefined} 채널 namespace. */
+    this.ns = meta.ns
+    /** @type {string} 연결 경로. */
+    this.path = meta.path
+    /** @type {string|undefined} joinSession 으로 매핑된 사용자 식별자 (DIRECT 타겟). */
+    this.userId = undefined
+    /** @type {string|undefined} joinSession 으로 매핑된 세션 식별자. */
+    this.sessionId = undefined
+    /** @type {Set<string>|null} joinSession 으로 가입한 채널 집합. */
+    this.channels = null
+    /** @type {Object|undefined} joinSession/updateMetadata 로 저장한 presence 메타(재연결 재동기화에 보존, M-1). */
+    this.metadata = undefined
+  }
+
+  /** 하위 raw `ws` WebSocket (escape hatch — 바이너리/직접 제어용). */
+  get raw() {
+    return this._raw
+  }
+
+  /** 연결이 OPEN 상태인지 (`ws.OPEN` === 1). */
+  get isOpen() {
+    return this._raw.readyState === 1
+  }
+
+  /**
+   * envelope 송신. v/id/ts 자동 채움 (§6.2). ASP 활성 시 자동 암호화.
+   *
+   * `ns` 가 생략되면 연결의 namespace(`this.ns`)를 자동 주입한다(L1). 호출부가 명시한 `ns` 는
+   * 그대로 존중한다(다른 namespace 로 보내는 경우 등).
+   *
+   * @param {{ type: string, ns?: string, payload?: Object, error?: Object, ref?: string }} fields
+   * @returns {void}
+   */
+  send(fields) {
+    // ns 자동 주입 (L1): 명시 안 됐고 연결 ns 가 있으면 채운다. 명시값은 덮어쓰지 않음.
+    const withNs = fields.ns === undefined && this.ns !== undefined ? { ...fields, ns: this.ns } : fields
+    const env = createWsMessage(withNs)
+    this._raw.send(this._codec.encode(JSON.stringify(env)))
+  }
+
+  /**
+   * error envelope 송신 (§6.3). 핸들러 throw / 검증 실패 통지용.
+   * @param {{ code: string, message?: string, details?: unknown, ref?: string, type?: string }} opts
+   * @returns {void}
+   */
+  sendError({ code, message, details, ref, type = 'mega.error' }) {
+    /** @type {Record<string, any>} */
+    const error = { code }
+    if (message !== undefined) error.message = message
+    if (details !== undefined) error.details = details
+    this.send({ type, error, ...(ref !== undefined ? { ref } : {}) })
+  }
+
+  /**
+   * 연결 종료.
+   * @param {number} [code]
+   * @param {string} [reason]
+   * @returns {void}
+   */
+  close(code, reason) {
+    this._raw.close(code, reason)
+  }
+}
+
+/**
+ * 핸드셰이크 완료된 raw 소켓에 채널 라이프사이클을 구동한다.
+ *
+ * `onConnect` 1회 → 매 message `dispatch` (코덱 decode → envelope 검증 → type 디스패치) →
+ * close 시 `onDisconnect`. 모든 단계는 fail-closed (ADR-084) + 명시적 로그.
+ *
+ * @param {Object} args
+ * @param {import('ws').WebSocket} args.raw - 핸드셰이크된 ws 소켓.
+ * @param {import('node:http').IncomingMessage} args.req - upgrade 요청 (ctx 용).
+ * @param {{ path: string, ns?: string, ChannelClass: Function, opts: Object, schemaValidators?: Record<string, import('ajv').ValidateFunction> | null }} args.route
+ * @param {import('./mega-app.js').MegaApp} args.app
+ * @param {WsFrameCodec} args.codec
+ * @param {any} args.log - request 로거 (debug/warn/error).
+ * @param {any} [args.auth] - `before` 미들웨어가 인증 후 돌려준 신원(`{ userId, sessionId, ... }`).
+ *   `ctx.auth` 로 노출 — onConnect 에서 `app.joinSession(sock, { userId: ctx.auth.userId, ... })` 에 쓴다.
+ * @returns {MegaWsConnection}
+ */
+export function driveWsConnection({ raw, req, route, app, codec, log, auth = null }) {
+  const conn = new MegaWsConnection(raw, codec, { ns: route.ns, path: route.path })
+  // ChannelClass 는 부팅 시 MegaWebSocketController 상속 검증됨 (router.ws). 여기선 인스턴스화만.
+  const channel = /** @type {import('./ws-controller.js').MegaWebSocketController} */ (
+    new (/** @type {any} */ (route.ChannelClass))()
+  )
+  // services DI(request-scoped, OQ-010) 는 후속. 현재는 app/log/auth 만 바인딩.
+  // auth = before 미들웨어가 채운 인증 신원(없으면 null). onConnect 가 joinSession 에 사용.
+  // db/cache/bus 접근자(ADR-102)를 HTTP ctx 와 동일 표면으로 WS ctx 에도 노출. mock app(단위 테스트)은
+  // 접근자가 없을 수 있어 옵셔널 spread.
+  /** @type {Record<string, any>} */
+  const ctx = {
+    app,
+    log,
+    services: null,
+    auth,
+    ns: route.ns,
+    path: route.path,
+    req,
+    connId: conn.id,
+    tracer: MegaTracing.tracer, // ctx.tracer.span(name, fn) — WS 핸들러에서도 사용자 직접 span(ADR-126).
+    ...(app?.adapterAccessors ?? {}),
+  }
+  channel._bind({ ctx, app, log, services: null })
+
+  // 로컬 연결 레지스트리 등록 (hub broadcast fan-out 의 local 전달 대상). close 시 해제.
+  // 옵셔널 호출 — 단위 테스트의 mock app 은 추적 메서드가 없을 수 있다.
+  app._trackWsConn?.(conn)
+
+  log.debug?.({ connId: conn.id, path: route.path, ns: route.ns }, 'ws.connect enter')
+
+  // onConnect — 실패 시 fail-closed. 복호화와 무관한 서버 내부 오류이므로 1011 (M3). silent 금지.
+  Promise.resolve()
+    .then(() => channel.onConnect(conn, ctx))
+    .catch((err) => {
+      log.error?.({ err, connId: conn.id }, 'ws.onConnect threw — closing (1011)')
+      if (conn.isOpen) conn.close(CLOSE_CODE_INTERNAL_ERROR, 'onConnect failed')
+    })
+
+  // type 별 payload 스키마 검증 함수 맵 (M2, router.ws 에서 사전 컴파일). 없으면 검증 없음.
+  const schemaValidators = route.schemaValidators ?? null
+
+  raw.on('message', (data) => {
+    // ws 는 Buffer | ArrayBuffer | Buffer[] 를 줄 수 있음. 텍스트 프레임만 처리 (바이너리는 후속 BINARY 타입).
+    const frame = Array.isArray(data)
+      ? Buffer.concat(data).toString('utf8')
+      : data.toString('utf8')
+    // 최외곽 가드 (L2): handleIncoming 은 내부에서 단계별 try/catch 하지만, 예기치 못한
+    // 동기 throw / reject 가 unhandledRejection 으로 새지 않도록 .catch 로 마무리한다.
+    handleIncoming({ conn, channel, codec, ctx, raw, frame, schemaValidators, log }).catch((err) => {
+      log.warn?.({ err, connId: conn.id }, 'ws handleIncoming unexpected error')
+    })
+  })
+
+  raw.on('close', (code, reasonBuf) => {
+    app._untrackWsConn?.(conn)
+    const reason = Buffer.isBuffer(reasonBuf) ? reasonBuf.toString('utf8') : String(reasonBuf ?? '')
+    log.debug?.({ connId: conn.id, code, reason }, 'ws.disconnect')
+    Promise.resolve()
+      .then(() => channel.onDisconnect(conn, ctx))
+      .catch((err) => {
+        // onDisconnect 는 정리 단계 — throw 해도 연결은 이미 닫힘. warn 후 무시 (이유+로그).
+        log.warn?.({ err, connId: conn.id }, 'ws.onDisconnect threw — ignored (already closed)')
+      })
+  })
+
+  raw.on('error', (err) => {
+    // 소켓 레벨 에러(전송 실패 등) — 비치명적, 로그만. close 이벤트가 뒤따른다.
+    log.warn?.({ err, connId: conn.id }, 'ws socket error')
+  })
+
+  return conn
+}
+
+/**
+ * AJV payload 검증 에러 → envelope details 배열 (M2, ADR-075 형식).
+ *
+ * HTTP 의 {@link import('./ajv-mapper.js')} 와 동일한 `{ field, rule, message }` shape 를 쓰되,
+ * WS payload 는 단순 값이라 PII 마스킹/value 노출은 하지 않는다(필드 경로·규칙·메시지만).
+ *
+ * @param {import('ajv').ErrorObject[] | null | undefined} errors - `validate.errors`.
+ * @returns {Array<{ field: string, rule: string, message: string }>}
+ * @private
+ */
+function wsPayloadErrorsToDetails(errors) {
+  if (!Array.isArray(errors)) return []
+  return errors.map((e) => ({
+    // instancePath 예: '/n' → 'n', '' → '(root)'. payload 루트 기준 경로.
+    field: e.instancePath ? e.instancePath.replace(/^\//, '').replace(/\//g, '.') : '(root)',
+    rule: e.keyword || 'unknown',
+    message: e.message || 'invalid',
+  }))
+}
+
+/**
+ * WS 메시지 메트릭 라벨용 type 을 카디널리티-안전하게 접는다(ADR-132). 채널에 **전용
+ * 핸들러 메서드가 등록된 type** 만 그대로 라벨에 노출하고, 그 외(= {@link MegaWebSocketController#dispatch}
+ * 가 `onMessage` 폴백으로 보내는 임의 type)는 {@link UNHANDLED_WS_TYPE} 로 접는다. dispatch 의 핸들러 판정
+ * (`WS_TYPE_PATTERN` + 동명 메서드 존재)을 그대로 미러하므로 "라벨로 노출되는 type = 실제 라우팅된 type" 이
+ * 보장된다. HTTP 가 매칭된 라우트 패턴만 라벨에 쓰는 것(ADR-131)과 동일한 카디널리티 정책이다.
+ *
+ * **트레이싱 span(`ws.<type>`)은 raw type 을 그대로 쓴다** — span 은 요청마다 독립이라 무한 type 도 집계
+ * 폭증을 일으키지 않지만, 메트릭 라벨은 누적 집계라 반드시 bounded 해야 하기 때문이다(둘의 의도된 차이).
+ *
+ * @param {import('./ws-controller.js').MegaWebSocketController} channel - dispatch 대상 채널 인스턴스.
+ * @param {string} type - 검증된 envelope 의 메시지 type.
+ * @returns {string} 라벨에 안전한 type(등록 핸들러 있으면 원본, 없으면 `__unhandled__`).
+ */
+export function wsMetricType(channel, type) {
+  if (
+    typeof type === 'string' &&
+    WS_TYPE_PATTERN.test(type) &&
+    typeof (/** @type {any} */ (channel)[type]) === 'function'
+  ) {
+    return type
+  }
+  return UNHANDLED_WS_TYPE
+}
+
+/**
+ * 수신 프레임 1건 처리 — decode → 검증 → dispatch. 단계별 fail-closed.
+ *
+ * @param {Object} args
+ * @param {MegaWsConnection} args.conn
+ * @param {import('./ws-controller.js').MegaWebSocketController} args.channel
+ * @param {WsFrameCodec} args.codec
+ * @param {any} args.ctx
+ * @param {import('ws').WebSocket} args.raw
+ * @param {string} args.frame
+ * @param {Record<string, import('ajv').ValidateFunction> | null} args.schemaValidators
+ *   type 별 payload 검증 함수 맵 (M2). null 이면 검증 생략.
+ * @param {any} args.log
+ * @returns {Promise<void>}
+ * @private
+ */
+async function handleIncoming({ conn, channel, codec, ctx, raw, frame, schemaValidators, log }) {
+  // 1) 코덱 decode (ASP 복호화 포함). 실패 → fail-closed (ADR-084).
+  let plain
+  try {
+    plain = codec.decode(frame)
+  } catch (err) {
+    const rule = err instanceof MegaAspDecryptError ? err.rule : 'unknown'
+    log.warn?.({ err, rule, connId: conn.id }, 'ws frame decode failed (ADR-084)')
+    // 클라가 키를 못 만드는 상황 → 평문 asp.error 통지 후 close 4500.
+    try {
+      const notice = JSON.stringify(
+        createWsMessage({ type: 'asp.error', error: { code: 'asp.decrypt_failed', rule } }),
+      )
+      raw.send(codec.encodePlain(notice))
+    } catch (sendErr) {
+      // 송신 실패 = 소켓이 이미 닫히는 중. 비치명적 — close 로 마무리 (이유+로그).
+      log.debug?.({ err: sendErr, connId: conn.id }, 'ws asp.error notify failed (socket closing)')
+    }
+    if (conn.isOpen) raw.close(CLOSE_CODE_DECRYPT_FAILED, 'asp.decrypt_failed')
+    return
+  }
+
+  // 2) envelope 파싱 + 검증. 실패 → error envelope 응답(연결 유지 — 비치명적).
+  /** @type {{ type: string, id: string }} */
+  let msg
+  try {
+    msg = /** @type {{ type: string, id: string }} */ (parseWsMessage(plain))
+  } catch (err) {
+    log.warn?.({ err, connId: conn.id }, 'ws invalid envelope')
+    if (conn.isOpen) {
+      conn.sendError({
+        code: 'ws.invalid_message',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+    return
+  }
+
+  // 2.5) payload 스키마 검증 (M2). type 에 등록된 스키마가 있으면 payload 검증.
+  //      실패 → ws.invalid_payload error envelope 응답(연결 유지 — HTTP AJV 매핑과 동일 fail-closed,
+  //      ADR-090). 스키마 없는 type 은 그대로 통과. fail-closed 표방인데 통과시키지 않기 위함.
+  const validate = schemaValidators ? schemaValidators[msg.type] : undefined
+  if (validate) {
+    /** @type {any} */
+    const payload = /** @type {any} */ (msg).payload
+    if (!validate(payload)) {
+      const details = wsPayloadErrorsToDetails(validate.errors)
+      log.warn?.({ connId: conn.id, type: msg.type, details }, 'ws payload schema validation failed')
+      if (conn.isOpen) {
+        conn.sendError({
+          code: 'ws.invalid_payload',
+          message: `payload failed schema validation for type '${msg.type}'`,
+          details,
+          ref: msg.id,
+        })
+      }
+      return
+    }
+  }
+
+  // 3) type 자동 디스패치 (ADR-015). 핸들러 throw → error envelope (ref 매칭).
+  log.debug?.({ connId: conn.id, type: msg.type, ref: msg.id }, 'ws.message dispatch')
+  // WS 메시지 메트릭 (ADR-132) — 옵트인 OFF 면 isEnabled() false 라 0 비용. 트레이싱 span 과
+  //   **동일 seam**(dispatch 1건 = 메트릭 1건): decode/검증 실패(위 early-return)는 애플리케이션 메시지가
+  //   아니라 프로토콜 오류라 집계 대상이 아니다. 성공·핸들러 throw 둘 다 1건으로 센다(HTTP onResponse 가
+  //   상태코드 무관하게 1건 세는 것과 정합 — wsMessages 인스트루먼트엔 성공/실패 라벨이 없음).
+  const metricsOn = MegaMetrics.isEnabled()
+  const startedAt = metricsOn ? performance.now() : 0
+  try {
+    // WS 메시지 span (ADR-126) — 메시지 1건당 루트 span `ws.<type>`. 각 message 콜백은
+    //   독립 async 흐름이라 run() 격리가 정확하고, 핸들러 안 ctx.tracer.span·어댑터 호출이 자식으로 중첩.
+    //   옵트인 OFF 면 span() 이 0 비용으로 dispatch 만 그대로 호출한다.
+    await MegaTracing.span(
+      `ws.${msg.type}`,
+      () => channel.dispatch(conn, msg, ctx),
+      {
+        kind: MegaTracing.SpanKind.SERVER,
+        attributes: { 'ws.type': msg.type, 'ws.ns': ctx.ns, 'ws.path': ctx.path, 'mega.conn_id': conn.id },
+      },
+    )
+  } catch (err) {
+    log.warn?.({ err, type: msg.type, connId: conn.id }, 'ws handler threw')
+    if (conn.isOpen) {
+      conn.sendError({
+        code: 'ws.handler_error',
+        message: err instanceof Error ? err.message : String(err),
+        ref: msg.id,
+      })
+    }
+  } finally {
+    // 성공·실패 무관하게 1건 기록(finally). type 은 wsMetricType 으로 카디널리티-안전하게 접는다(라우팅
+    //   핸들러 없는 임의 type → __unhandled__). app 이름은 ctx.app.name(mock app 대비 옵셔널).
+    if (metricsOn) {
+      MegaMetrics.recordWs({
+        type: wsMetricType(channel, msg.type),
+        ns: ctx.ns,
+        durationMs: performance.now() - startedAt,
+        app: ctx.app?.name,
+      })
+    }
+  }
+}
+
+/**
+ * upgrade 핸드셰이크 거부 — 401/404 등 HTTP 응답 후 소켓 파괴.
+ * (ws 핸드셰이크 전이므로 WS close frame 이 아니라 HTTP 응답으로 거부한다.)
+ *
+ * @param {import('node:stream').Duplex} socket
+ * @param {number} status - HTTP status code.
+ * @param {string} reason - status text.
+ * @param {any} [log] - 선택 로거 (write 실패 통지용).
+ * @returns {void}
+ */
+export function rejectUpgrade(socket, status, reason, log) {
+  // 이미 파괴된 소켓엔 write 하지 않는다(불필요한 'error' emit 회피).
+  if (!socket.destroyed) {
+    try {
+      socket.write(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`)
+    } catch (err) {
+      // 닫히는 중인 소켓에 write 실패는 비치명적 — destroy 로 마무리 (이유+로그).
+      log?.debug?.({ err }, 'ws upgrade reject write failed (socket closing)')
+    }
+    socket.destroy()
+  }
+}

package/src/errors/config-error.js

@@ -0,0 +1,16 @@
+// @ts-check
+/**
+ * config 검증 전용 에러.
+ *
+ * @module errors/config-error
+ */
+import { MegaError } from './mega-error.js'
+
+/**
+ * 부팅 시 config 검증 실패 (3-스코프, 키 오타, 호스트 충돌, Shared-Reference 등).
+ * code = 'config.<reason>'.
+ *
+ * 부팅 시 throw 되어 프로세스를 중단시킨다 (fail-fast). silent catch 금지 —
+ * 이 에러를 잡아서 무시하면 잘못된 config 로 서버가 뜨므로 절대 삼키지 말 것.
+ */
+export class MegaConfigError extends MegaError {}

package/src/errors/http-errors.js

@@ -0,0 +1,130 @@
+// @ts-check
+/**
+ * HTTP 에러 클래스 계층 (ADR-025).
+ *
+ * 모든 HTTP 에러는 {@link MegaHttpError} 를 상속하고, status + envelope code 를 가진다.
+ * 글로벌 에러 핸들러(error-mapper.js)가 이 status/code/message/details 를
+ * envelope error (ADR-014) 로 변환한다.
+ *
+ * @module errors/http-errors
+ */
+import { MegaError } from './mega-error.js'
+
+/**
+ * HTTP 표준 status 와 envelope code 를 가진 베이스. 모든 HTTP 에러는 이걸 상속.
+ *
+ * envelope 변환 시 status → response status, code → error.code, message → error.message,
+ * details → error.details (object | array, ADR-075).
+ *
+ * 코드 컨벤션: `domain.error` (ADR-016). 예: 'user.not_found', 'auth.required'.
+ */
+export class MegaHttpError extends MegaError {
+  /**
+   * @param {number} status - HTTP status code (4xx/5xx).
+   * @param {string} code - 'domain.error' 형식 envelope 코드 (ADR-016).
+   * @param {string} message - 사람이 읽는 에러 메시지.
+   * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+   *   - details: 구조화된 부가 정보 (object | array — ADR-075).
+   *   - cause: 원인 에러 (전파용).
+   */
+  constructor(status, code, message, opts = {}) {
+    super(code, message, opts)
+    this.status = status
+  }
+}
+
+/** 400 — 클라이언트 검증 실패. AJV 자동 매핑 대상 (ADR-090). */
+export class MegaValidationError extends MegaHttpError {
+  /**
+   * @param {string} [code]
+   * @param {string} [message]
+   * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+   */
+  constructor(code = 'validation.failed', message = 'Validation failed', opts = {}) {
+    super(400, code, message, opts)
+  }
+}
+
+/** 401 — 인증 누락 / 무효. */
+export class MegaAuthError extends MegaHttpError {
+  /**
+   * @param {string} [code]
+   * @param {string} [message]
+   * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+   */
+  constructor(code = 'auth.required', message = 'Authentication required', opts = {}) {
+    super(401, code, message, opts)
+  }
+}
+
+/** 403 — 인증은 했으나 권한 없음. */
+export class MegaForbiddenError extends MegaHttpError {
+  /**
+   * @param {string} [code]
+   * @param {string} [message]
+   * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+   */
+  constructor(code = 'auth.forbidden', message = 'Forbidden', opts = {}) {
+    super(403, code, message, opts)
+  }
+}
+
+/** 404 — 리소스 없음. */
+export class MegaNotFoundError extends MegaHttpError {
+  /**
+   * @param {string} [code]
+   * @param {string} [message]
+   * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+   */
+  constructor(code = 'resource.not_found', message = 'Not found', opts = {}) {
+    super(404, code, message, opts)
+  }
+}
+
+/** 409 — 충돌 (예: email 중복). */
+export class MegaConflictError extends MegaHttpError {
+  /**
+   * @param {string} [code]
+   * @param {string} [message]
+   * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+   */
+  constructor(code = 'resource.conflict', message = 'Conflict', opts = {}) {
+    super(409, code, message, opts)
+  }
+}
+
+/** 413 — 페이로드 과대 (업로드 크기·개수 초과). @fastify/multipart 네이티브 413 과 정합. */
+export class MegaPayloadTooLargeError extends MegaHttpError {
+  /**
+   * @param {string} [code]
+   * @param {string} [message]
+   * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+   */
+  constructor(code = 'upload.too_large', message = 'Payload too large', opts = {}) {
+    super(413, code, message, opts)
+  }
+}
+
+/** 415 — 지원하지 않는 미디어 타입 (업로드 MIME 화이트리스트 위반). */
+export class MegaUnsupportedMediaTypeError extends MegaHttpError {
+  /**
+   * @param {string} [code]
+   * @param {string} [message]
+   * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+   */
+  constructor(code = 'upload.unsupported_media_type', message = 'Unsupported media type', opts = {}) {
+    super(415, code, message, opts)
+  }
+}
+
+/** 500 — 내부 오류. 기본 code `server.internal` (H-6). */
+export class MegaInternalError extends MegaHttpError {
+  /**
+   * @param {string} [code]
+   * @param {string} [message]
+   * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+   */
+  constructor(code = 'server.internal', message = 'Internal server error', opts = {}) {
+    super(500, code, message, opts)
+  }
+}

package/src/errors/index.js

@@ -0,0 +1,19 @@
+// @ts-check
+/**
+ * errors 배럴 — 모든 에러 클래스 re-export.
+ *
+ * @module errors
+ */
+export { MegaError } from './mega-error.js'
+export { MegaConfigError } from './config-error.js'
+export {
+  MegaHttpError,
+  MegaValidationError,
+  MegaAuthError,
+  MegaForbiddenError,
+  MegaNotFoundError,
+  MegaConflictError,
+  MegaPayloadTooLargeError,
+  MegaUnsupportedMediaTypeError,
+  MegaInternalError,
+} from './http-errors.js'

package/src/errors/mega-error.js

@@ -0,0 +1,34 @@
+// @ts-check
+/**
+ * MEGA-FRAMEWORK 모든 에러의 베이스.
+ * - code: 'domain.error' 컨벤션 (ADR-016)
+ * - details: object | array (ADR-075)
+ * - cause: Error 전파
+ *
+ * @module errors/mega-error
+ */
+
+/**
+ * 프레임워크 공통 에러 베이스 클래스.
+ *
+ * @example
+ * throw new MegaError('user.not_found', 'User 42 not found', {
+ *   details: { userId: 42 },
+ * })
+ */
+export class MegaError extends Error {
+  /**
+   * @param {string} code - 'domain.error' 형식 에러 코드 (ADR-016).
+   * @param {string} message - 사람이 읽는 에러 메시지.
+   * @param {{ details?: object | unknown[], cause?: unknown }} [options]
+   *   - details: 구조화된 부가 정보 (object | array — ADR-075).
+   *   - cause: 원인 에러 (전파용).
+   */
+  constructor(code, message, { details, cause } = {}) {
+    super(message)
+    this.name = this.constructor.name
+    this.code = code
+    if (details !== undefined) this.details = details
+    if (cause !== undefined) this.cause = cause
+  }
+}

package/src/eslint-plugin/index.js

@@ -0,0 +1,15 @@
+// @ts-check
+import noDirectModelImport from './no-direct-model-import.js'
+
+/** @type {import('eslint').ESLint.Plugin} */
+const megaPlugin = {
+  meta: {
+    name: 'eslint-plugin-mega',
+    version: '0.0.1',
+  },
+  rules: {
+    'no-direct-model-import': noDirectModelImport,
+  },
+}
+
+export default megaPlugin