mega-framework 0.1.6 → 0.1.7

package/types/core/template.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 앱 `views` config 를 정규화한다. `dir` 이 없으면 null(옵트인 미활성 — i18n normalizeI18n 패턴 정합).
+ *
+ * @param {unknown} views - 앱 config 의 `views` 키.
+ * @returns {{ dir: string, layoutDir: string, partialsDir: string, defaultLayout: string|null, cache: boolean }|null}
+ */
+export function normalizeViews(views: unknown): {
+    dir: string;
+    layoutDir: string;
+    partialsDir: string;
+    defaultLayout: string | null;
+    cache: boolean;
+} | null;
+/**
+ * view/layout 이름을 뷰 루트 기준 절대 경로로 풀고, 그 경로가 **뷰 루트 내부**인지 검증한다(경로 탐색 차단).
+ * 확장자가 없으면 `.ejs` 를 붙인다. 루트를 벗어나면 400 throw(LFI 방어 — multipart sanitize 이중 방어 정합).
+ *
+ * @param {string} dir - 뷰 루트(절대경로).
+ * @param {string} name - view 또는 layout 상대 이름(예 'posts/show', 'layouts/main').
+ * @param {'view'|'layout'} kind - 에러 메시지 구분용.
+ * @returns {string} 검증된 절대 경로.
+ * @throws {MegaValidationError} 뷰 루트를 벗어나면 `template.invalid_view`.
+ */
+export function resolveViewPath(dir: string, name: string, kind?: "view" | "layout"): string;
+/**
+ * 순수 렌더 — 뷰를 HTML 문자열로 만든다(send 없이). `MegaTemplate#render` 본체이자 reply.render 의 코어.
+ * 트레이싱 span + 메트릭을 여기서 1회 기록한다(reply.render·ctx.render 가 공유).
+ *
+ * @param {{ dir: string, layoutDir: string, partialsDir: string, defaultLayout: string|null, cache: boolean }} cfg
+ * @param {string} view - 뷰 루트 기준 상대 이름(예 'posts/show').
+ * @param {object} [data] - 템플릿 로컬(데이터). 예약 키 `t`/`lang`/`settings`/`cache` 는 프레임워크가 채운다.
+ * @param {{ layout?: string|false }} [opts] - `layout` 으로 레이아웃 override(false 면 레이아웃 강제 해제).
+ * @param {{ app?: string }} [meta] - 메트릭 app 라벨.
+ * @returns {Promise<string>} 렌더된 HTML.
+ * @throws {MegaValidationError} 경로 탐색 거부(400). @throws {MegaInternalError} 렌더 실패(500).
+ */
+export function renderView(cfg: {
+    dir: string;
+    layoutDir: string;
+    partialsDir: string;
+    defaultLayout: string | null;
+    cache: boolean;
+}, view: string, data?: object, opts?: {
+    layout?: string | false;
+}, meta?: {
+    app?: string;
+}): Promise<string>;
+/**
+ * MegaApp 에 템플릿을 옵트인 등록한다. `views.dir` 이 있을 때만 `reply.render` 데코레이터를 단다(없으면
+ * 미등록 — render 호출 시 Fastify 가 'reply.render is not a function' 으로 fail-fast, 옵트인 명시).
+ *
+ * `reply.render` 는 정본 `res.render(view, data, { layout })`(docs/03 §618):
+ *   - 요청별 i18n `t`/`lang`(`req.t`/`req.lang`, i18n 미등록이면 passthrough)을 data 에 자동 병합.
+ *   - 렌더 후 `Content-Type: text/html; charset=utf-8` 로 send. 체이닝용으로 reply 반환.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {object} args
+ * @param {unknown} [args.views] - 앱 `views` config(`{ dir, layoutDir, partialsDir, defaultLayout, cache }`).
+ * @param {string} [args.appName] - 메트릭·로그 라벨.
+ * @param {{ debug?: Function }} [args.logger]
+ * @returns {{ enabled: boolean, template: MegaTemplate|null }}
+ */
+export function registerTemplate(fastify: import("fastify").FastifyInstance, { views, appName, logger }?: {
+    views?: unknown;
+    appName?: string;
+    logger?: {
+        debug?: Function;
+    };
+}): {
+    enabled: boolean;
+    template: MegaTemplate | null;
+};
+/** 고정 뷰 엔진·확장자 (ADR-011 — EJS). ejs-mate `settings['view engine']` 과 일치시킨다. */
+export const VIEW_ENGINE: "ejs";
+/** 레이아웃 디렉터리 기본 관례 (02-architecture §11 — `views/layouts/`). */
+export const DEFAULT_LAYOUT_DIR: "layouts";
+/** 파셜 디렉터리 기본 관례 (02-architecture §11 — `views/partials/`). */
+export const DEFAULT_PARTIALS_DIR: "partials";
+/**
+ * 정본 `MegaTemplate`(docs/03 §892 / 06-class-diagrams) — 옵트인 뷰 config 를 감싼 thin wrapper.
+ * registerTemplate 가 앱당 1개 만들어 reply.render 가 위임한다. i18n/MegaTracing 처럼 본체는 모듈 함수형.
+ */
+export class MegaTemplate {
+    /** @param {unknown} views - 앱 `views` config. @param {string} [appName] - 메트릭 app 라벨. */
+    constructor(views: unknown, appName?: string);
+    /** @type {{ dir: string, layoutDir: string, partialsDir: string, defaultLayout: string|null, cache: boolean }} */
+    _cfg: {
+        dir: string;
+        layoutDir: string;
+        partialsDir: string;
+        defaultLayout: string | null;
+        cache: boolean;
+    };
+    /** @type {string|undefined} */
+    _app: string | undefined;
+    /**
+     * 뷰를 HTML 문자열로 렌더(send 없이) — docs/03 §892.
+     * @param {string} viewPath - 뷰 루트 기준 상대 이름(예 'posts/show').
+     * @param {object} [data]
+     * @param {{ layout?: string|false }} [opts]
+     * @returns {Promise<string>}
+     */
+    render(viewPath: string, data?: object, opts?: {
+        layout?: string | false;
+    }): Promise<string>;
+}

package/types/core/workers-manager.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `config.workers`(MegaWorker 서브클래스 배열)로부터 워커 풀 인스턴스를 만든다(아직 start 안 함).
+ * config-validator 가 배열·클래스 shape 를 먼저 검증하지만, 여기서도 MegaWorker 서브클래스·이름 중복을
+ * 부팅 시점에 fail-fast(형제 register 패턴).
+ *
+ * @param {{ workers?: Array<typeof MegaWorker> }} [globalConfig] - mega.config.js default export.
+ * @param {{ projectRoot?: string, registerShutdownHook?: boolean }} [opts]
+ * @returns {void}
+ * @throws {MegaConfigError} MegaWorker 서브클래스가 아니거나 `static name` 중복일 때.
+ */
+export function buildWorkers(globalConfig?: {
+    workers?: Array<typeof MegaWorker>;
+}, { projectRoot, registerShutdownHook }?: {
+    projectRoot?: string;
+    registerShutdownHook?: boolean;
+}): void;
+/**
+ * 모든 워커 풀을 start 한다(스레드/프로세스 spawn). 하나라도 실패하면 이미 start 된 풀을 등록 역순(LIFO)으로
+ * stop 한 뒤 원래 에러를 throw(fail-fast + leak 방지 — adapter-manager connectAll 패턴).
+ *
+ * @param {{ logger?: { debug?: Function, info?: Function, warn?: Function } }} [opts]
+ * @returns {Promise<void>}
+ */
+export function startAll({ logger }?: {
+    logger?: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+    };
+}): Promise<void>;
+/**
+ * `static name` 으로 워커 풀 조회. 미등록이면 fail-fast(silent X — adapter-manager.get 정합).
+ * @param {string} name @returns {MegaWorker} @throws {MegaConfigError}
+ */
+export function get(name: string): MegaWorker;
+/**
+ * 등록 여부(Boolean — has*, 컨벤션). @param {string} name @returns {boolean}
+ */
+export function has(name: string): boolean;
+/**
+ * 등록된 워커 메타 스냅샷(디버그/CLI). @returns {Array<{ name: string, mode: string, poolSize: number, started: boolean }>}
+ */
+export function list(): Array<{
+    name: string;
+    mode: string;
+    poolSize: number;
+    started: boolean;
+}>;
+/**
+ * `ctx.workers` 로 줄 객체 — `ctx.workers.<name>.run(task)`. 미등록 이름 접근은 fail-fast.
+ * 동일 Proxy 를 boot ctx·요청 ctx 가 공유한다(워커는 글로벌 자원이라 요청·앱 무관).
+ * @returns {Record<string, MegaWorker>}
+ */
+export function contextProxy(): Record<string, MegaWorker>;
+/**
+ * 모든 워커 풀을 graceful stop 한다 — 등록 **역순(LIFO)**. 개별 실패는 비치명적(warn 후 계속).
+ * @param {{ logger?: { debug?: Function, warn?: Function } }} [opts]
+ * @returns {Promise<void>}
+ */
+export function stopAll({ logger }?: {
+    logger?: {
+        debug?: Function;
+        warn?: Function;
+    };
+}): Promise<void>;
+/**
+ * 테스트용 reset — 인스턴스 비우고 shutdown hook 해제(워커는 stop 안 함 — 호출자가 먼저 stopAll).
+ * @returns {void}
+ */
+export function _reset(): void;
+/**
+ * Proxy get 트랩이 throw 하면 안 되는 "암묵 조회" string 키 모음. `await`(then)·`JSON.stringify`(toJSON)·
+ * 문자열/원시값 변환(toString/valueOf)·inspect 류(constructor/inspect)가 일반 객체에 으레 조회하는 키라,
+ * 미등록 fail-fast 대상(오타)과 구분해 undefined 를 돌려준다. 같은 이름이 실제로 등록돼 있으면 그대로
+ * 해석한다. `then` 은 Symbol 이 아니라 **string 키**다 — Promise resolution 이 string 'then' 을 조회하므로
+ * 이 가드가 없으면 `await ctx.workers`/`await ctx.services` 가 not_registered 로 죽는다.
+ */
+export const PROXY_PROTOCOL_KEYS: Set<string>;
+import { MegaWorker } from '../lib/mega-worker.js';

package/types/core/ws-cluster.d.ts

@@ -0,0 +1,208 @@
+/**
+ * NATS 기반 WS 클러스터 fan-out + roster.
+ *
+ * 앱 1개당 1 인스턴스. boot 가 생성·start·shutdown 을 관리한다(자동 배선). subject 는 앱 이름으로
+ * 격리되어(`<prefix>.<appName>.*`) 다중 앱이 한 NATS 를 공유해도 섞이지 않는다.
+ */
+export class MegaWsCluster {
+    /**
+     * @param {Object} opts
+     * @param {import('../adapters/mega-bus-adapter.js').MegaBusAdapter} opts.bus - 연결된 NATS 버스 어댑터.
+     * @param {string} opts.appName - 앱 이름(subject 격리 + 로그).
+     * @param {(payload: { ns: string, channel?: string, message: { type: string, payload?: Object }, exceptSessionIds?: string[] }) => void} opts.deliverBroadcast -
+     *   수신한 broadcast 를 로컬 연결에 전달하는 콜백(보통 `app._deliverBroadcast`).
+     * @param {(payload: { userId: string, message: { type: string, payload?: Object } }) => void} opts.deliverDirect -
+     *   수신한 direct 를 로컬 연결에 전달하는 콜백(보통 `app._deliverDirect`).
+     * @param {{ debug?: Function, info?: Function, warn?: Function, error?: Function }} [opts.logger]
+     * @param {string} [opts.subjectPrefix] - subject 접두(기본 'mega.ws').
+     * @param {{ driver?: 'nats'|'none', ttlMs?: number }} [opts.roster] - roster 동기화 설정.
+     */
+    constructor({ bus, appName, deliverBroadcast, deliverDirect, logger, subjectPrefix, roster }?: {
+        bus: import("../adapters/mega-bus-adapter.js").MegaBusAdapter;
+        appName: string;
+        deliverBroadcast: (payload: {
+            ns: string;
+            channel?: string;
+            message: {
+                type: string;
+                payload?: Object;
+            };
+            exceptSessionIds?: string[];
+        }) => void;
+        deliverDirect: (payload: {
+            userId: string;
+            message: {
+                type: string;
+                payload?: Object;
+            };
+        }) => void;
+        logger?: {
+            debug?: Function;
+            info?: Function;
+            warn?: Function;
+            error?: Function;
+        };
+        subjectPrefix?: string;
+        roster?: {
+            driver?: "nats" | "none";
+            ttlMs?: number;
+        };
+    });
+    /** @type {import('../adapters/mega-bus-adapter.js').MegaBusAdapter} */
+    _bus: import("../adapters/mega-bus-adapter.js").MegaBusAdapter;
+    _appName: string;
+    _deliverBroadcast: (payload: {
+        ns: string;
+        channel?: string;
+        message: {
+            type: string;
+            payload?: Object;
+        };
+        exceptSessionIds?: string[];
+    }) => void;
+    _deliverDirect: (payload: {
+        userId: string;
+        message: {
+            type: string;
+            payload?: Object;
+        };
+    }) => void;
+    _log: {
+        debug?: Function;
+        info?: Function;
+        warn?: Function;
+        error?: Function;
+    };
+    /** 이 프로세스의 고유 식별자 — echo 구분. */
+    instanceId: string;
+    _subjBroadcast: string;
+    _subjDirect: string;
+    _subjRoster: string;
+    _rosterDriver: string;
+    _rosterTtlMs: number;
+    /** 이 인스턴스가 보유한 로컬 멤버. sessionId → RosterMember. */
+    _localMembers: Map<any, any>;
+    /** 클러스터 전역 view. sessionId → RosterMember & { instanceId, expiresAt }. */
+    _view: Map<any, any>;
+    /** @type {Array<{ unsubscribe: () => Promise<void> }>} 활성 구독 핸들. */
+    _subs: Array<{
+        unsubscribe: () => Promise<void>;
+    }>;
+    /** @type {ReturnType<typeof setInterval>|null} */
+    _heartbeatTimer: ReturnType<typeof setInterval> | null;
+    /** @type {ReturnType<typeof setInterval>|null} */
+    _sweepTimer: ReturnType<typeof setInterval> | null;
+    _isStarted: boolean;
+    /** 시작됐는지. @returns {boolean} */
+    get isStarted(): boolean;
+    /**
+     * 구독 시작 — broadcast/direct subject + (roster:'nats' 면) roster subject 를 subscribe 하고, roster
+     * 동기화 타이머(heartbeat/sweep)를 켜고, 신규 인스턴스 sync_request 를 보낸다. 멱등(중복 호출 무시).
+     * @returns {Promise<void>}
+     */
+    start(): Promise<void>;
+    /**
+     * broadcast 를 클러스터로 publish. 송신측은 이미 로컬 전달했으므로 `o`(origin)로 자기 echo 를 표시한다.
+     * @param {{ ns: string, channel?: string, message: { type: string, payload?: Object }, exceptSessionIds?: string[] }} payload
+     * @returns {Promise<void>}
+     */
+    publishBroadcast(payload: {
+        ns: string;
+        channel?: string;
+        message: {
+            type: string;
+            payload?: Object;
+        };
+        exceptSessionIds?: string[];
+    }): Promise<void>;
+    /**
+     * direct(특정 userId)를 클러스터로 publish — 다른 인스턴스의 같은 userId 세션까지 닿게 한다.
+     * @param {string} userId
+     * @param {{ type: string, payload?: Object }} message
+     * @returns {Promise<void>}
+     */
+    publishDirect(userId: string, message: {
+        type: string;
+        payload?: Object;
+    }): Promise<void>;
+    /**
+     * roster 에 멤버 추가(joinSession 훅). 로컬 보유 + 전역 view 반영 + 델타 publish. roster:'none' 이면
+     * 로컬만 갱신한다.
+     * @param {RosterMember} member
+     * @returns {void}
+     */
+    rosterAdd(member: RosterMember): void;
+    /**
+     * roster 에서 멤버 제거(disconnect 훅). 로컬 제거 + 전역 view 제거 + 델타 publish.
+     * @param {string} sessionId
+     * @returns {void}
+     */
+    rosterRemove(sessionId: string): void;
+    /**
+     * 해당 ns 의 클러스터 전역 접속자 목록. roster:'none' 이면 로컬 멤버만.
+     * @param {string} ns
+     * @returns {Array<{ sessionId: string, userId: string, metadata?: Object }>}
+     */
+    roster(ns: string): Array<{
+        sessionId: string;
+        userId: string;
+        metadata?: Object;
+    }>;
+    /**
+     * 정리 — 타이머 해제 + 구독 해제 + 자기 멤버 LEAVE 공지(graceful 종료 시 다른 인스턴스 roster 즉시 정리).
+     * @returns {Promise<void>}
+     */
+    stop(): Promise<void>;
+    /**
+     * roster subject 수신 처리. 자기 echo 는 건너뛰되, sync_request 만은 자기 요청이어도 무관(상대가 응답).
+     * @param {any} msg
+     * @returns {void}
+     * @private
+     */
+    private _onRosterMessage;
+    /**
+     * view 에 멤버 upsert + 만료시각 갱신. 멤버 출처 instanceId 를 함께 저장(sweep 판단·자기멤버 구분).
+     * @param {RosterMember} member @param {string} instanceId @returns {void}
+     * @private
+     */
+    private _upsertView;
+    /**
+     * 만료(heartbeat 끊긴 crash 인스턴스) 멤버를 view 에서 제거. 자기 멤버는 항상 fresh 하므로 영향 없음.
+     * @returns {void}
+     * @private
+     */
+    private _sweepExpired;
+    /**
+     * 자기 로컬 멤버 전체를 heartbeat 로 공지(다른 인스턴스의 TTL 갱신) + 자기 view 도 fresh 유지.
+     * @returns {Promise<void>}
+     * @private
+     */
+    private _publishHeartbeat;
+    /**
+     * roster subject 로 메시지 publish(자기 instanceId 를 origin 으로).
+     * @param {Object} body @returns {Promise<void>}
+     * @private
+     */
+    private _publishRoster;
+}
+/**
+ * roster 멤버(클러스터 공유). sessionId 는 joinSession 전역 유일 계약(ADR-098)으로 키가 된다.
+ */
+export type RosterMember = {
+    /**
+     * - WS namespace(채널 경로, 예: '/ws/chat').
+     */
+    ns: string;
+    /**
+     * - 세션 식별자(전역 유일).
+     */
+    sessionId: string;
+    /**
+     * - 사용자 식별자.
+     */
+    userId: string;
+    /**
+     * - presence 메타(명시 필드만).
+     */
+    metadata?: Object;
+};

package/types/core/ws-compression.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 압축 설정 검증 — 위반 시 사람이 읽을 에러 메시지, 통과 시 null 반환(throw 안 함).
+ *
+ * 호출부가 컨텍스트(MegaConfigError vs 일반 Error)에 맞게 wrap 한다 — config-validator 는
+ * MegaConfigError 로, MegaApp/MegaWsHub 직접 생성 경로는 일반 Error 로.
+ *
+ * @param {Partial<WsCompressionConfig>} [config] - MegaWebsocketCompressionConfig | MegaWsHubCompressionConfig.
+ * @param {string} [label='websocket.compression'] - 에러 메시지 prefix (예: 'wsHub.compression').
+ * @returns {string | null} 위반 메시지 또는 null.
+ */
+export function checkCompressionConfig(config?: Partial<WsCompressionConfig>, label?: string): string | null;
+/**
+ * 압축 설정 → `ws` WebSocket(Server) 의 `perMessageDeflate` 값으로 변환.
+ *
+ * - `enabled !== true` → `false` (압축 비활성, ws 기본값과 동일).
+ * - `enabled === true` → 5 필드를 디폴트로 채운 perMessageDeflate 옵션 객체.
+ *
+ * 부팅(config-validator)에서 이미 검증되지만, 직접 생성 경로(single 모드·테스트)를 위해 여기서도
+ * 방어적으로 검증한다 — 위반 시 throw(silent 금지).
+ *
+ * @param {Partial<WsCompressionConfig>} [config] - MegaWebsocketCompressionConfig | MegaWsHubCompressionConfig.
+ * @param {string} [label='websocket.compression'] - throw 메시지 prefix.
+ * @returns {false | { threshold: number, serverNoContextTakeover: boolean, clientNoContextTakeover: boolean, serverMaxWindowBits: number, concurrencyLimit: number }}
+ * @throws {Error} threshold 음수 / serverMaxWindowBits 범위 위반.
+ */
+export function buildPerMessageDeflate(config?: Partial<WsCompressionConfig>, label?: string): false | {
+    threshold: number;
+    serverNoContextTakeover: boolean;
+    clientNoContextTakeover: boolean;
+    serverMaxWindowBits: number;
+    concurrencyLimit: number;
+};
+/**
+ * WebSocket per-message deflate 압축 옵션 정규화 (ADR-078).
+ *
+ * 두 곳이 같은 스키마를 쓴다(04-data-models §1.1/§2.1):
+ *   - App-only `websocket.compression`  — 브라우저↔Bridge(embedded WS, MegaApp `_ensureWss`)
+ *   - Global   `wsHub.compression`       — Bridge↔Hub link (MegaWsHub 서버 + MegaHubLink 클라)
+ *
+ * 두 typedef(`MegaWebsocketCompressionConfig` / `MegaWsHubCompressionConfig`)의 6 필드는
+ * 그대로 `ws` 패키지의 `perMessageDeflate` 옵션명과 1:1 매핑된다(검증: node_modules/ws/lib/
+ * permessage-deflate.js — threshold/serverNoContextTakeover/clientNoContextTakeover/
+ * serverMaxWindowBits/concurrencyLimit). `enabled` 만 우리 게이트 — false 면 압축 비활성
+ * (`perMessageDeflate: false`, ws 기본값).
+ *
+ * # threshold 의미 (ws 소스 확인)
+ *   threshold 는 **context takeover 가 비활성일 때만** 적용된다(sender.js: no_context_takeover
+ *   negotiate 시 `rsv1 = byteLength >= threshold`). ADR-078 이 두 NoContextTakeover 디폴트를 true 로
+ *   둔 이유 — threshold 가 실제로 동작하고 연결당 메모리도 절감.
+ *
+ * # negotiate 실패 = 자동 raw fallback
+ *   `permessage-deflate` 확장은 양쪽이 모두 협상해야 활성(RFC 7692). 한쪽이 OFF(`false`)면 협상되지
+ *   않아 자동으로 raw 통신으로 떨어진다 — 별도 fallback 코드 불필요(ws 내장 동작).
+ *
+ * @module core/ws-compression
+ */
+/**
+ * 압축 설정 — App `websocket.compression` 과 Global `wsHub.compression` 공통 스키마 (ADR-078).
+ * 04-data-models 의 `MegaWebsocketCompressionConfig` / `MegaWsHubCompressionConfig` 와 동일.
+ * @typedef {Object} WsCompressionConfig
+ * @property {boolean} enabled                     - 디폴트 false. 옵트인 게이트.
+ * @property {number}  [threshold]                 - byte. 디폴트 1024. 미만은 압축 우회(NoContextTakeover 시).
+ * @property {boolean} [serverNoContextTakeover]   - 디폴트 true (연결당 메모리 절감).
+ * @property {boolean} [clientNoContextTakeover]   - 디폴트 true.
+ * @property {number}  [serverMaxWindowBits]       - 디폴트 10. 범위 9~15 (벗어나면 부팅 throw).
+ * @property {number}  [concurrencyLimit]          - 디폴트 10.
+ */
+/**
+ * ADR-078 디폴트값. `enabled` 외 5 필드는 `ws` perMessageDeflate 에 그대로 전달된다.
+ * @type {Readonly<{ enabled: boolean, threshold: number, serverNoContextTakeover: boolean, clientNoContextTakeover: boolean, serverMaxWindowBits: number, concurrencyLimit: number }>}
+ */
+export const COMPRESSION_DEFAULTS: Readonly<{
+    enabled: boolean;
+    threshold: number;
+    serverNoContextTakeover: boolean;
+    clientNoContextTakeover: boolean;
+    serverMaxWindowBits: number;
+    concurrencyLimit: number;
+}>;
+/** serverMaxWindowBits 허용 범위 (zlib windowBits 최소 9 ~ RFC 7692 최대 15, ADR-078). */
+export const SERVER_MAX_WINDOW_BITS_MIN: 9;
+export const SERVER_MAX_WINDOW_BITS_MAX: 15;
+/**
+ * 압축 설정 — App `websocket.compression` 과 Global `wsHub.compression` 공통 스키마 (ADR-078).
+ * 04-data-models 의 `MegaWebsocketCompressionConfig` / `MegaWsHubCompressionConfig` 와 동일.
+ */
+export type WsCompressionConfig = {
+    /**
+     * - 디폴트 false. 옵트인 게이트.
+     */
+    enabled: boolean;
+    /**
+     * - byte. 디폴트 1024. 미만은 압축 우회(NoContextTakeover 시).
+     */
+    threshold?: number;
+    /**
+     * - 디폴트 true (연결당 메모리 절감).
+     */
+    serverNoContextTakeover?: boolean;
+    /**
+     * - 디폴트 true.
+     */
+    clientNoContextTakeover?: boolean;
+    /**
+     * - 디폴트 10. 범위 9~15 (벗어나면 부팅 throw).
+     */
+    serverMaxWindowBits?: number;
+    /**
+     * - 디폴트 10.
+     */
+    concurrencyLimit?: number;
+};

package/types/core/ws-controller.d.ts

@@ -0,0 +1,65 @@
+export class MegaWebSocketController {
+    /** @type {any} */ _ctxRef: any;
+    /** @type {any} */ _appRef: any;
+    /** @type {any} */ _logRef: any;
+    /** @type {any} */ _servicesRef: any;
+    /**
+     * 프레임워크가 채널 인스턴스에 컨텍스트를 바인딩한다 (후속 Step 의 upgrade 처리에서 호출).
+     * **사용자 코드는 호출하지 않는다** (framework-internal).
+     *
+     * @param {{ ctx?: any, app?: any, log?: any, services?: any }} [binding]
+     * @returns {void}
+     */
+    _bind(binding?: {
+        ctx?: any;
+        app?: any;
+        log?: any;
+        services?: any;
+    }): void;
+    /** 현재 채널 컨텍스트 (미바인딩 시 null). */
+    get ctx(): any;
+    /** 소속 MegaApp (미바인딩 시 null). */
+    get app(): any;
+    /** request_id 자동 주입 로거 (미바인딩 시 null). */
+    get log(): any;
+    /** 자동 DI 핸들 — `ctx.services` 와 동일 (미바인딩 시 null). */
+    get services(): any;
+    /**
+     * 연결 수립 시 1회 호출. 기본 no-op — 서브클래스가 override.
+     * @param {any} _sock - WS 소켓.
+     * @param {any} _ctx - 채널 컨텍스트.
+     * @returns {Promise<void>}
+     */
+    onConnect(_sock: any, _ctx: any): Promise<void>;
+    /**
+     * 디스패치되지 않은 메시지의 폴백 핸들러. 기본 no-op — 서브클래스가 override.
+     * @param {any} _sock - WS 소켓.
+     * @param {Object} _msg - 검증된 WS envelope.
+     * @param {any} _ctx - 채널 컨텍스트.
+     * @returns {Promise<any>}
+     */
+    onMessage(_sock: any, _msg: Object, _ctx: any): Promise<any>;
+    /**
+     * 연결 종료 시 호출. 기본 no-op — 서브클래스가 override.
+     * @param {any} _sock - WS 소켓.
+     * @param {any} _ctx - 채널 컨텍스트.
+     * @returns {Promise<void>}
+     */
+    onDisconnect(_sock: any, _ctx: any): Promise<void>;
+    /**
+     * 수신 메시지 자동 디스패치 (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>} 핸들러 반환값.
+     */
+    dispatch(sock: any, msg: {
+        type?: string;
+    }, ctx: any): Promise<any>;
+}

package/types/core/ws-message.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Sec-WebSocket-Protocol 제안 목록에서 envelope 프로토콜 버전을 협상한다.
+ *
+ * 규칙 (구버전 클라/서버 혼합 롤링 배포 안전):
+ *   - `mega.v<N>` 토큰이 하나도 없으면 → **레거시 폴백 v1** (`{ version: 1, subprotocol: undefined }`)
+ *     — subprotocol 미사용 클라(현 WASM MegaSocket·브라우저 기본)는 전부 v1 로 취급한다.
+ *   - 상호 지원 버전이 있으면 최고 버전 채택 → `{ version: N, subprotocol: 'mega.v<N>' }`
+ *     (서버가 핸드셰이크 응답 `Sec-WebSocket-Protocol` 로 확정 통지 — 클라는 `WebSocket.protocol` 로 읽는다).
+ *   - `mega.v*` 를 제안했지만 상호 버전이 없으면(클라가 미래 버전만 지원) → `null`
+ *     — 호출부는 subprotocol 없이 수락한다(클라 입장에선 "서버가 내 버전을 못 함" = v1 폴백 신호.
+ *     v1 을 못 하는 클라이언트는 스스로 닫는다). 핸드셰이크를 거부하지 않아 하위호환이 절대 깨지지 않는다.
+ *
+ * @param {Iterable<string>} offered - 클라이언트가 제안한 subprotocol 토큰들(ws 는 Set 을 전달).
+ * @param {ReadonlyArray<number>} [supported] - 서버 지원 버전 목록.
+ * @returns {{ version: number, subprotocol: string | undefined } | null} 협상 결과, 상호 버전 없으면 null.
+ */
+export function negotiateWsProtocol(offered: Iterable<string>, supported?: ReadonlyArray<number>): {
+    version: number;
+    subprotocol: string | undefined;
+} | null;
+/**
+ * 메시지 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?: number): string;
+/**
+ * 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 }?: {
+    type?: string;
+    ns?: string;
+    payload?: Object;
+    error?: Object;
+    ref?: string;
+}, opts?: {
+    id?: string;
+    ts?: number;
+}): {
+    v: number;
+    id: string;
+    type: string;
+    ts: number;
+};
+/**
+ * WS 메시지 envelope 검증 (§6.2 schema). 위반 사유 배열을 반환한다 (빈 배열 = 유효).
+ *
+ * 던지지 않고 사유 목록을 돌려주는 이유: 호출부(디스패처/hub)가 사유를 ERROR envelope 의
+ * `details` 로 그대로 실어 보낼 수 있도록 (ADR-075 배열 표준).
+ *
+ * @param {any} msg
+ * @param {{ version?: number }} [opts] - `version` = 이 연결에서 협상된 envelope 버전
+ *   ({@link negotiateWsProtocol}). 미지정 시 v1 — 협상 없는 기존 호출부와 하위호환.
+ * @returns {string[]} 위반 메시지 목록 (없으면 빈 배열).
+ */
+export function validateWsMessage(msg: any, { version }?: {
+    version?: number;
+}): string[];
+/**
+ * JSON 문자열 → 검증된 WS 메시지 envelope. 파싱/검증 실패 시 throw (silent 금지).
+ *
+ * @param {string} json - wire 평문 JSON (ASP 복호화 후 또는 `P:` 평문).
+ * @param {{ version?: number }} [opts] - 협상된 envelope 버전(미지정 시 v1, {@link validateWsMessage}).
+ * @returns {Object} 검증 통과한 envelope.
+ * @throws {Error} JSON 파싱 실패 또는 schema 위반 (메시지에 사유 포함).
+ */
+export function parseWsMessage(json: string, opts?: {
+    version?: number;
+}): Object;
+/** 현 프로토콜 버전 (04-data-models §6.2 `v: { const: 1 }`). */
+export const WS_PROTOCOL_VERSION: 1;
+/**
+ * 이 서버가 지원하는 WS envelope 프로토콜 버전 목록. 버전은 선형 누적 계약 — vN 지원 = v1..vN 전부
+ * 지원. 협상은 클라이언트 제안과의 **최고 상호 버전**을 채택한다(v2 도입 시 [1, 2] 로 확장).
+ * @type {ReadonlyArray<number>}
+ */
+export const SUPPORTED_WS_PROTOCOL_VERSIONS: ReadonlyArray<number>;
+/** WS 버전 협상 subprotocol 토큰 형식 — `mega.v<양의 정수>` (예: 'mega.v1'). */
+export const WS_SUBPROTOCOL_PATTERN: RegExp;
+/**
+ * 메시지 `type` / `error.code` 패턴 — `domain.action[.result]` (ADR-016, §6.2/§6.3).
+ * 점(`.`)이 최소 1개 강제 → 베이스 메서드명(`onMessage` 등, 점 없음) 과 절대 충돌하지 않음.
+ */
+export const WS_TYPE_PATTERN: RegExp;
+/**
+ * WS 메시지 JSON Schema (04-data-models §6.2 정본 그대로).
+ * 후속 단계(bridge↔hub, AJV 컴파일)에서 재사용할 수 있도록 export.
+ * @type {Object}
+ */
+export const WS_MESSAGE_SCHEMA: Object;