mega-framework 0.1.6 → 0.1.8

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

@@ -0,0 +1,273 @@
+export class MegaWsPresence {
+    /**
+     * @param {Object} opts
+     * @param {string} opts.appName - 소유 앱 이름(hook 이름·로그 식별자).
+     * @param {import('pino').Logger | { debug?: Function, warn?: Function } | null} [opts.log] -
+     *   앱 공유 로거(보통 `app.fastify.log`). 미주입이면 무로그.
+     */
+    constructor({ appName, log }?: {
+        appName: string;
+        log?: import("pino").Logger | {
+            debug?: Function;
+            warn?: Function;
+        } | null;
+    });
+    /** @type {string} */
+    _appName: string;
+    /** @type {any} */
+    _log: any;
+    /** @type {MegaHubLink|null} hub 연결 (scaffold 권장). */
+    _hubLink: MegaHubLink | null;
+    /** @type {import('./ws-cluster.js').MegaWsCluster|null} NATS 기반 클러스터 fan-out/roster (ADR-176, boot 자동배선). */
+    _wsCluster: import("./ws-cluster.js").MegaWsCluster | null;
+    /** @type {import('./ws-roster.js').MegaWsRedisRoster|null} 채널별 redis roster(ADR-177, boot 자동배선).
+     * 접속자 목록(상태)을 redis HASH 로 cluster-wide 관리한다(broadcast 와 별개 — 멀티 허브 정합·즉시 스냅샷). */
+    _wsRoster: import("./ws-roster.js").MegaWsRedisRoster | null;
+    /** ns(=ws path) → 활성 로컬 연결 집합 (hub broadcast 의 local fan-out 용). @type {Map<string, Set<import('./ws-upgrade.js').MegaWsConnection>>} */
+    _wsConns: Map<string, Set<import("./ws-upgrade.js").MegaWsConnection>>;
+    /** userId → 활성 로컬 연결 집합 (DIRECT 타겟팅, H-latent guard). @type {Map<string, Set<import('./ws-upgrade.js').MegaWsConnection>>} */
+    _userConns: Map<string, Set<import("./ws-upgrade.js").MegaWsConnection>>;
+    /** sessionId → 활성 로컬 연결 1개 (세션단위 JOIN/LEAVE). @type {Map<string, import('./ws-upgrade.js').MegaWsConnection>} */
+    _sessionConns: Map<string, import("./ws-upgrade.js").MegaWsConnection>;
+    /** @type {string[]} connectHub 으로 구독한 채널. */
+    _hubChannels: string[];
+    /** connectHub 의 bridgeId (재연결 재구독·세션 JOIN 에 재사용). @type {string|null} */
+    _hubBridgeId: string | null;
+    /** 현재 연결된 hub link (미연결 시 null). */
+    get hubLink(): MegaHubLink;
+    /**
+     * 이 bridge 를 hub 에 연결한다 (ADR-033/059). REGISTER 핸드셰이크 완료 후
+     * 선언 채널을 구독(bridge-subscriber JOIN)하고, hub 의 BROADCAST/DIRECT 를 로컬 소켓에 전달한다.
+     *
+     * single 모드는 embedded 종단이라 hub 가 필수는 아니지만(02-architecture §3), 멀티 인스턴스
+     * fan-out 이 필요하면 single 에서도 사용 가능하다. scaffold(멀티앱/클러스터)에서 권장.
+     *
+     * @param {Object} config - MegaBridgeHubConfig (§2.1) + 구독 채널.
+     * @param {string} config.url - hub URL.
+     * @param {string} config.token - Bearer 토큰.
+     * @param {string} config.bridgeId - 운영 식별자.
+     * @param {string} [config.instanceId]
+     * @param {string[]} [config.capabilities]
+     * @param {string[]} [config.channels] - 자동 구독할 채널 목록.
+     * @param {import('../lib/mega-retry.js').MegaRetryOptions} [config.retry] - 지정 시 재연결 활성(ADR-098).
+     *   hub 재시작·drain(4503)·네트워크 단절 시 지수 백오프로 재연결하고, 성공하면 presence(채널·세션
+     *   JOIN)를 자동 재동기화한다(hub 는 절단 시점 presence 를 잃으므로).
+     * @param {import('./ws-compression.js').WsCompressionConfig} [config.compression] - Bridge↔Hub
+     *   link 압축(ADR-078 / MegaWsHubCompressionConfig). Global `wsHub.compression`
+     *   블록을 그대로 전달한다 — hub 서버와 같은 스키마. 디폴트 OFF. 잘못된 threshold/windowBits 면
+     *   즉시 throw(부팅 fail-fast).
+     * @returns {Promise<MegaHubLink>} 등록 완료된 link.
+     */
+    connectHub(config?: {
+        url: string;
+        token: string;
+        bridgeId: string;
+        instanceId?: string;
+        capabilities?: string[];
+        channels?: string[];
+        retry?: import("../lib/mega-retry.js").MegaRetryOptions;
+        compression?: import("./ws-compression.js").WsCompressionConfig;
+    }): Promise<MegaHubLink>;
+    /**
+     * hub presence 재동기화 — bridge-subscriber 채널 JOIN + 활성 사용자 세션 JOIN 을 모두 다시 보낸다.
+     * 최초 등록 직후와 재연결(RECONNECTED) 직후에 호출된다. hub 의 JOIN 처리는 멱등(같은 sessionId 덮어씀).
+     * @returns {void}
+     * @private
+     */
+    private _resyncPresence;
+    /**
+     * 실 사용자 세션을 hub presence 에 등록하고 로컬 매핑을 만든다 (OQ-010/ADR-098).
+     *
+     * 표준 패턴: WS upgrade 의 `before` 미들웨어가 인증 후 신원을 `ctx.auth` 로 싣고(ADR-091 DI),
+     * 채널의 `onConnect(sock, ctx)` 에서 `ctx.app.joinSession(sock, { userId: ctx.auth.userId, ... })`
+     * 를 호출한다. 이 매핑이 있어야 DIRECT 가 **해당 userId 세션에만** 전달된다(cross-user flood 방지,
+     * H-latent guard). 매핑 없는 연결은 DIRECT 대상에서 제외된다.
+     *
+     * @param {import('./ws-upgrade.js').MegaWsConnection} conn - onConnect 가 받은 소켓 래퍼.
+     * @param {Object} entry
+     * @param {string} entry.userId - 인증된 사용자 식별자(비어 있으면 throw).
+     * @param {string} entry.sessionId - 세션 식별자(비어 있으면 throw). 전역 유일 권장.
+     * @param {string[]} [entry.channels] - 가입 채널 목록.
+     * @param {Object} [entry.metadata] - presence 메타데이터(명시 필드만, ADR-059).
+     * @returns {this}
+     * @throws {Error} conn/userId/sessionId 누락 시 — 잘못된 매핑을 silent 통과시키지 않는다.
+     */
+    joinSession(conn: import("./ws-upgrade.js").MegaWsConnection, { userId, sessionId, channels, metadata }?: {
+        userId: string;
+        sessionId: string;
+        channels?: string[];
+        metadata?: Object;
+    }): this;
+    /**
+     * 채널 broadcast — 로컬 ns 소켓에 즉시 전달 + (hub 연결 시) 클러스터 fan-out.
+     *
+     * @param {{ ns: string, channel: string, message: { type: string, payload?: Object }, exceptSessionIds?: string[] }} args
+     * @returns {void}
+     * @throws {Error} message.type(string) 누락 시 — 호출부 입력 오류를 silent drop 하지 않고 즉시 알린다(L6).
+     */
+    broadcast({ ns, channel, message, exceptSessionIds }: {
+        ns: string;
+        channel: string;
+        message: {
+            type: string;
+            payload?: Object;
+        };
+        exceptSessionIds?: string[];
+    }): void;
+    /**
+     * 특정 사용자에게 직접 전송 (directToUser, ADR-035) — 로컬에서 그 userId 로 매핑된 연결에만 전달
+     * (H-latent guard) + (hub 연결 시) 클러스터 fan-out(다른 bridge 의 같은 userId 세션까지).
+     *
+     * {@link MegaWsPresence#joinSession} 으로 매핑된 연결만 대상이다 — 매핑 없는 userId 면 로컬 no-op.
+     *
+     * @param {string} userId - 대상 사용자.
+     * @param {{ type: string, payload?: Object }} message - 내부 envelope `{ type, payload }`.
+     * @returns {void}
+     * @throws {Error} userId/message.type 누락 시(broadcast 와 동일한 입력 보호, L6).
+     */
+    directToUser(userId: string, message: {
+        type: string;
+        payload?: Object;
+    }): void;
+    /**
+     * 세션 presence 메타데이터 갱신 (METADATA, ADR-059) — 로컬 conn 에 저장 + (hub 연결 시) 전파.
+     *
+     * 로컬 conn 의 `metadata` 를 갱신해 두면 이후 재연결 시 {@link MegaWsPresence#_resyncPresence} 가 최신
+     * 메타까지 복구한다(M-1). 매핑 없는 sessionId 면 no-op(로컬 저장 없이 hub 전파만은 하지 않음 —
+     * 재연결 보존 대상이 없으므로). broadcast/directToUser 와 같은 best-effort fan-out.
+     *
+     * @param {string} sessionId - 대상 세션(joinSession 으로 매핑된 것).
+     * @param {Object} metadata - 갱신할 메타데이터(명시 필드만).
+     * @returns {this}
+     * @throws {Error} sessionId/metadata 누락 시(입력 보호, L6 와 동일 원칙).
+     */
+    updateMetadata(sessionId: string, metadata: Object): this;
+    /**
+     * NATS 클러스터 fan-out/roster 를 이 앱에 배선한다 (ADR-176). boot 가 `wsCluster` config 를 보고
+     * 자동 호출하므로 개발자가 직접 부를 일은 없다(테스트·고급 용도로만 공개).
+     * @param {import('./ws-cluster.js').MegaWsCluster|null} cluster
+     * @returns {this}
+     */
+    setWsCluster(cluster: import("./ws-cluster.js").MegaWsCluster | null): this;
+    /**
+     * 해당 ns(WS 채널 경로)의 **클러스터 전역 접속자 목록**을 반환한다 (ADR-176). `wsCluster` 자동배선 +
+     * `joinSession`/disconnect 훅으로 프레임워크가 동기화하므로 개발자는 roster 코드를 짜지 않고 읽기만 한다.
+     * wsCluster 미배선(또는 roster:'none')이면 로컬 멤버만 반환한다.
+     *
+     * @param {string} ns - WS namespace(채널 경로, 예: '/ws/chat').
+     * @returns {Array<{ sessionId: string, userId: string, metadata?: Object }>}
+     */
+    roster(ns: string): Array<{
+        sessionId: string;
+        userId: string;
+        metadata?: Object;
+    }>;
+    /**
+     * 채널별 redis roster(ADR-177)를 이 앱에 배선한다. boot 가 `bridgeHub.roster.driver==='redis'` 일 때
+     * 자동 호출하므로 개발자가 직접 부를 일은 없다(테스트·고급 용도로만 공개).
+     * @param {import('./ws-roster.js').MegaWsRedisRoster|null} roster
+     * @returns {this}
+     */
+    setWsRoster(roster: import("./ws-roster.js").MegaWsRedisRoster | null): this;
+    /**
+     * 주어진 **채널들**의 cluster-wide 접속자 목록 — redis roster(원격 포함) + 로컬 세션을 병합한다(ADR-177).
+     * 로컬을 항상 포함해 join 직후 redis HSET 반영 전에도 본인이 빠지지 않게 한다. `ctx.presence.list()` 의
+     * redis 경로가 호출(async). roster 미배선이면 로컬 채널 멤버만.
+     * @param {string[]} channels
+     * @returns {Promise<Array<{ sessionId: string, userId: string, metadata?: Object }>>}
+     */
+    presenceList(channels: string[]): Promise<Array<{
+        sessionId: string;
+        userId: string;
+        metadata?: Object;
+    }>>;
+    /**
+     * 이 워커의 로컬 멤버 목록 — redis roster heartbeat 갱신 대상(ADR-177). joinSession 으로 매핑된
+     * (채널 × 세션)마다 1개. MegaWsRedisRoster 가 주기적으로 이 목록의 expiresAt 을 갱신한다.
+     * @returns {Array<{ channel: string, sessionId: string, member: { userId: string, metadata?: Object } }>}
+     */
+    localRosterMembers(): Array<{
+        channel: string;
+        sessionId: string;
+        member: {
+            userId: string;
+            metadata?: Object;
+        };
+    }>;
+    /**
+     * broadcast payload 를 로컬 ns 소켓에 전달한다. message 는 `{ type, payload }` 내부 envelope.
+     *
+     * `exceptSessionIds` 에 든 sessionId 로 매핑된 연결은 제외한다(ADR-098). 세션 매핑이 없는
+     * 연결(zero-config·미JOIN)은 sessionId 가 없어 제외 대상에 걸리지 않으므로 그대로 받는다.
+     *
+     * @param {{ ns: string, channel?: string, message: { type: string, payload?: Object }, exceptSessionIds?: string[] }} payload
+     * @returns {void}
+     */
+    _deliverBroadcast({ ns, message, exceptSessionIds }: {
+        ns: string;
+        channel?: string;
+        message: {
+            type: string;
+            payload?: Object;
+        };
+        exceptSessionIds?: string[];
+    }): void;
+    /**
+     * direct payload 를 **해당 userId 로 매핑된 로컬 연결에만** 전달한다 (H-latent guard).
+     *
+     * 초기에는 매핑이 없어 모든 연결에 flood 됐다(cross-user 누출). {@link MegaWsPresence#joinSession}
+     * 으로 만든 `userId → 연결` 매핑을 통해 대상 사용자에게만 보낸다. 매핑이 없는 userId 면 no-op
+     * (다른 사용자에게 새지 않음).
+     *
+     * @param {{ userId: string, message: { type: string, payload?: Object } }} payload
+     * @returns {void}
+     */
+    _deliverDirect({ userId, message }: {
+        userId: string;
+        message: {
+            type: string;
+            payload?: Object;
+        };
+    }): void;
+    /**
+     * hub 가 라우팅한 DISCONNECT(admin-kick/재배치, ADR-097)를 처리한다 — sessionId 로 매핑된 로컬
+     * 소켓을 닫는다. `requeue` 로 두 시맨틱이 갈린다:
+     *
+     *   - `requeue: false`(기본) = **kick** — RFC 6455 `1008`(policy violation, hub Bearer 거부와 동일
+     *     코드). "돌아오지 마라" — 클라이언트는 재연결하지 않아야 한다.
+     *   - `requeue: true` = **우아한 재배치** — `4503`({@link import('./ws-upgrade.js').CLOSE_CODE_REQUEUE},
+     *     bridge↔hub drain 과 동일 규약). "세션 유지한 채 즉시 재연결하라" — HTTP 세션은 그대로이므로
+     *     재연결이 LB 를 거쳐 다른 워커에 닿아도 `before` 인증이 세션 쿠키로 자연 통과한다
+     *     (transparent re-route — 워커 drain·리밸런싱용).
+     *
+     * reason 은 WS close frame 한도(123 bytes)에 맞춰 자른다.
+     *
+     * @param {{ sessionId: string, reason?: string, requeue?: boolean }} payload
+     * @returns {void}
+     */
+    _handleHubDisconnect({ sessionId, reason, requeue }?: {
+        sessionId: string;
+        reason?: string;
+        requeue?: boolean;
+    }): void;
+    /**
+     * 로컬 WS 연결 등록 (driveWsConnection 이 호출 — framework-internal). hub broadcast 의 local 전달 대상.
+     * @param {import('./ws-upgrade.js').MegaWsConnection} conn
+     * @returns {void}
+     */
+    _trackWsConn(conn: import("./ws-upgrade.js").MegaWsConnection): void;
+    /**
+     * 로컬 WS 연결 해제 (close 시 driveWsConnection 이 호출 — framework-internal).
+     * @param {import('./ws-upgrade.js').MegaWsConnection} conn
+     * @returns {void}
+     */
+    _untrackWsConn(conn: import("./ws-upgrade.js").MegaWsConnection): void;
+    /**
+     * presence 전체 정리 — hub link → NATS cluster → redis roster → 연결 인덱스 순.
+     * 각 자원의 shutdown hook 도 짝맞춰 해제한다(닫힌 앱의 hook 잔존·중복 정리 방지).
+     * MegaApp.close 가 WS 클라이언트 종료(1001) **전에** 호출한다.
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+}
+import { MegaHubLink } from './hub-link.js';

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

@@ -0,0 +1,108 @@
+/**
+ * 채널 roster 멤버(redis 에 저장되는 형태 — sessionId 는 HASH field 라 값엔 안 넣음).
+ * @typedef {Object} RosterMember
+ * @property {string} userId
+ * @property {Object} [metadata]
+ */
+/**
+ * redis 기반 채널별 roster.
+ *
+ * 앱(MegaApp) 1개당 1 인스턴스. boot 가 `bridgeHub.roster.driver==='redis'` 일 때 생성·start·shutdown 한다.
+ * redis 핸들은 캐시 어댑터의 `.native`(ioredis) 를 받는다 — pub/sub 가 아니라 HASH 명령(HSET/HGETALL/HDEL)만 쓴다.
+ */
+export class MegaWsRedisRoster {
+    /**
+     * @param {Object} opts
+     * @param {import('ioredis').Redis} opts.redis - 캐시 어댑터의 raw ioredis 핸들.
+     * @param {() => Array<{ channel: string, sessionId: string, member: RosterMember }>} opts.getLocalMembers -
+     *   이 워커의 현재 로컬 멤버 목록(heartbeat 갱신 대상). 보통 mega-app 의 세션 매핑에서 도출.
+     * @param {string} [opts.keyPrefix] - 키 접두(기본 'ws:roster').
+     * @param {number} [opts.ttlMs] - 멤버 TTL(ms, 기본 30000).
+     * @param {{ debug?: Function, warn?: Function, error?: Function }} [opts.logger]
+     */
+    constructor({ redis, getLocalMembers, keyPrefix, ttlMs, logger }?: {
+        redis: import("ioredis").Redis;
+        getLocalMembers: () => Array<{
+            channel: string;
+            sessionId: string;
+            member: RosterMember;
+        }>;
+        keyPrefix?: string;
+        ttlMs?: number;
+        logger?: {
+            debug?: Function;
+            warn?: Function;
+            error?: Function;
+        };
+    });
+    _redis: import("ioredis").default;
+    _getLocalMembers: () => Array<{
+        channel: string;
+        sessionId: string;
+        member: RosterMember;
+    }>;
+    _prefix: string;
+    _ttlMs: number;
+    _log: {
+        debug?: Function;
+        warn?: Function;
+        error?: Function;
+    };
+    /** @type {ReturnType<typeof setInterval>|null} */
+    _hbTimer: ReturnType<typeof setInterval> | null;
+    /** 채널 → redis 키. @param {string} channel @returns {string} @private */
+    private _key;
+    /**
+     * 채널 roster 에 멤버 추가/갱신(joinSession). 키 자체에도 EXPIRE 를 걸어 버려진 채널이 새지 않게 한다.
+     * @param {string} channel @param {string} sessionId @param {RosterMember} member @returns {Promise<void>}
+     */
+    add(channel: string, sessionId: string, member: RosterMember): Promise<void>;
+    /**
+     * ioredis pipeline.exec() 결과(`[err, res][]`)에서 첫 명령 오류를 throw 한다 — pipeline 은 명령별
+     * 오류를 reject 가 아니라 결과 배열에 싣기 때문에, 묵히면 호출부의 기존 실패 처리(catch+warn)가
+     * 더는 동작하지 않는다(직렬 await 시절의 throw 계약 유지).
+     * @param {Array<[Error | null, any]> | null} results
+     * @returns {void}
+     * @private
+     */
+    private _throwFirstPipelineError;
+    /**
+     * 채널 roster 에서 멤버 제거(disconnect).
+     * @param {string} channel @param {string} sessionId @returns {Promise<void>}
+     */
+    remove(channel: string, sessionId: string): Promise<void>;
+    /**
+     * 채널의 **현재 접속자 목록**(만료 제외). 만료 엔트리는 best-effort 로 정리한다.
+     * @param {string} channel @returns {Promise<Array<{ sessionId: string, userId: string, metadata?: Object }>>}
+     */
+    list(channel: string): Promise<Array<{
+        sessionId: string;
+        userId: string;
+        metadata?: Object;
+    }>>;
+    /**
+     * heartbeat 시작 — 주기적으로 로컬 멤버의 `expiresAt` 을 갱신해 살아있음을 알린다(crash 워커는 갱신이
+     * 끊겨 만료). 프로세스 종료를 막지 않게 unref. 멱등(중복 호출 무시).
+     * @returns {void}
+     */
+    startHeartbeat(): void;
+    /**
+     * 로컬 멤버 전체의 `expiresAt` 을 한 pipeline 으로 일괄 갱신. 직렬 add 루프(멤버당 2 RT)는 멤버
+     * 1,000 에 주기당 수백 ms — 갱신 지연이 TTL 윈도를 침식해 살아있는 세션이 lazy 만료될 수 있었다.
+     * pipeline 이면 단일 왕복 수준(실측 ~200×). 채널 키 PEXPIRE 는 채널당 1회만 싣는다.
+     * @returns {Promise<void>} @private
+     */
+    private _refreshLocal;
+    /**
+     * 정리 — heartbeat 중지 + 로컬 멤버를 redis 에서 제거(graceful 종료 시 다른 워커가 즉시 정합).
+     * @returns {Promise<void>}
+     */
+    stop(): Promise<void>;
+}
+/**
+ * 채널 roster 멤버(redis 에 저장되는 형태 — sessionId 는 HASH field 라 값엔 안 넣음).
+ */
+export type RosterMember = {
+    userId: string;
+    metadata?: Object;
+};

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

@@ -0,0 +1,260 @@
+/**
+ * 프로세스 합산 send budget 을 조정한다(ADR-215). 부팅/운영 튜닝 진입점.
+ * @param {{ maxTotalBufferedBytes?: number }} [opts] - 바이트 budget. `0` = 무제한(옵트아웃).
+ * @returns {{ maxTotalBufferedBytes: number }} 적용된 현재 값.
+ * @throws {TypeError} 음수/비숫자 — 설정 실수 fail-fast.
+ */
+export function configureWsSendBudget({ maxTotalBufferedBytes: max }?: {
+    maxTotalBufferedBytes?: number;
+}): {
+    maxTotalBufferedBytes: number;
+};
+/**
+ * 테스트 격리용 — budget 상태 초기화(추적 Set·스로틀·budget 디폴트 복원).
+ * @returns {void}
+ */
+export function _resetWsSendBudget(): void;
+/** 테스트용 — 연결을 budget 추적에 등록. @param {MegaWsConnection} conn @returns {void} */
+export function _trackWsSendBudget(conn: MegaWsConnection): void;
+/** 테스트용 — 스로틀 우회 가능한 스윕 직접 호출. @param {number} [now] @returns {void} */
+export function _sweepWsSendBudget(now?: number): void;
+/**
+ * 라우트 opts 의 `heartbeatMs` 를 검증해 반환한다. 미지정 → 기본 30초, `0` = liveness 끔.
+ * 무효값(음수/비정수/비숫자)은 운영 실수 — 조용히 보정하지 않고 warn 로그 후 기본값을 쓴다
+ * (연결 구동 시점이라 throw 하면 핸드셰이크 콜백 밖으로 새므로 로그+기본값이 안전한 fail-safe).
+ *
+ * @param {{ heartbeatMs?: number } | undefined} opts - WS 라우트 opts.
+ * @param {any} [log] - 로거(warn).
+ * @returns {number} 적용할 주기(ms). 0 = 끔.
+ */
+export function resolveWsHeartbeatMs(opts: {
+    heartbeatMs?: number;
+} | undefined, log?: any): number;
+/**
+ * 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(): WsFrameCodec;
+/**
+ * ASP 활성/비활성 namespace 용 코덱 — {@link MegaAspTerminator} 위임 (`E:`/`P:` prefix).
+ * @param {import('../lib/asp/ws-terminator.js').MegaAspTerminator} terminator
+ * @returns {WsFrameCodec}
+ */
+export function createAspCodec(terminator: import("../lib/asp/ws-terminator.js").MegaAspTerminator): WsFrameCodec;
+/**
+ * 핸드셰이크 완료된 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, ... })` 에 쓴다.
+ * @param {number} [args.protocolVersion] - 핸드셰이크에서 협상된 envelope 버전(`mega.v<N>` subprotocol,
+ *   {@link import('./ws-message.js').negotiateWsProtocol}). 미지정 = v1(레거시). 이 연결의 envelope
+ *   검증 기준이 되고 `conn.protocolVersion`/`ctx.protocolVersion` 으로 노출된다.
+ * @returns {MegaWsConnection}
+ */
+export function driveWsConnection({ raw, req, route, app, codec, log, auth, protocolVersion }: {
+    raw: import("ws").WebSocket;
+    req: import("node:http").IncomingMessage;
+    route: {
+        path: string;
+        ns?: string;
+        ChannelClass: Function;
+        opts: Object;
+        schemaValidators?: Record<string, import("ajv").ValidateFunction> | null;
+    };
+    app: import("./mega-app.js").MegaApp;
+    codec: WsFrameCodec;
+    log: any;
+    auth?: any;
+    protocolVersion?: number;
+}): MegaWsConnection;
+/**
+ * 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: import("./ws-controller.js").MegaWebSocketController, type: string): string;
+/**
+ * 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: import("node:stream").Duplex, status: number, reason: string, log?: any): void;
+/**
+ * 라우팅 핸들러가 없는(=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;
+/** 느린 소비자 백프레셔 close code (RFC 6455 §7.4.1 표준 1013 "Try Again Later", Med). */
+export const CLOSE_CODE_SLOW_CONSUMER: 1013;
+/**
+ * 재배치(requeue) close code — 4503. "이 워커 말고 다른 곳으로 즉시 재연결하라"는 신호로,
+ * bridge↔hub 의 drain(4503, `hub-protocol.js` CLOSE_CODE_DRAIN)과 같은 코드를 써서 클라이언트가
+ * 한 가지 규약("4503 = 세션 유지한 채 재연결")으로 두 링크를 모두 처리한다. admin-kick 의
+ * `requeue: true`(hub.disconnect) 가 사용 — kick(1008, 돌아오지 마라)과 의미가 반대다.
+ * HTTP 세션은 보존되므로 재연결 시 `before` 인증이 세션 쿠키로 자연 통과한다(transparent re-route).
+ */
+export const CLOSE_CODE_REQUEUE: 4503;
+/** send 버퍼(bufferedAmount) 기본 상한(바이트). 초과 = 소비자가 ack 를 못 따라옴 → 연결 종료(서버 OOM 방지). */
+export const DEFAULT_MAX_BUFFERED_BYTES: number;
+/**
+ * 프로세스 **합산** send 버퍼 기본 budget(바이트, ADR-215 — G5 audit M-6).
+ *
+ * per-conn 상한(위 16MiB)은 연결 1개의 OOM 방어일 뿐이라, 느린 소비자 N 개가 각자 cap 직전까지
+ * 쌓으면 합산은 무제한이었다(이론상 1,000개 × 16MiB = 16GB). 합산이 본 budget 을 넘으면 **가장 큰
+ * 송신 큐를 보유한 연결부터** 1013(slow consumer)으로 종료해 budget 아래로 회수한다.
+ * `configureWsSendBudget({ maxTotalBufferedBytes: 0 })` 으로 무제한 옵트아웃.
+ */
+export const DEFAULT_MAX_TOTAL_BUFFERED_BYTES: number;
+/**
+ * 클라↔bridge ping/pong liveness 기본 주기(ms) — 30초. 주기마다 ping 을 보내고 직전 주기의 pong 이
+ * 없으면 half-open(상대 사망·네트워크 단절) 으로 보고 terminate 한다 — 좀비 연결이 OS TCP 타임아웃까지
+ * `_wsConns`/roster 에 잔존하는 것을 막는다. 라우트 `opts.heartbeatMs` 로 조정, `0` = 끔.
+ */
+export const DEFAULT_WS_HEARTBEAT_MS: 30000;
+/**
+ * onConnect 완료 전 도착한 프레임의 대기 큐 상한 — 초과 시 연결 종료(1013). onConnect 가 느릴 때
+ * 악의적/과속 클라이언트가 큐로 메모리를 채우는 것을 막는다.
+ */
+export const MAX_PENDING_FRAMES_BEFORE_CONNECT: 256;
+/**
+ * 채널 핸들러에 전달되는 소켓 래퍼 — 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, maxBufferedBytes?: number }} meta
+     */
+    constructor(rawSocket: import("ws").WebSocket, codec: WsFrameCodec, meta: {
+        id?: string;
+        ns?: string;
+        path: string;
+        maxBufferedBytes?: number;
+    });
+    /** @type {import('ws').WebSocket} */
+    _raw: import("ws").WebSocket;
+    /** @type {number} send 버퍼 상한(바이트) — 초과 시 느린 소비자로 보고 연결 종료(백프레셔). */
+    _maxBufferedBytes: number;
+    /** @type {WsFrameCodec} */
+    _codec: WsFrameCodec;
+    /** @type {string} 연결 식별자 (ULID). */
+    id: string;
+    /** @type {string|undefined} 채널 namespace. */
+    ns: string | undefined;
+    /** @type {string} 연결 경로. */
+    path: string;
+    /** @type {string|undefined} joinSession 으로 매핑된 사용자 식별자 (DIRECT 타겟). */
+    userId: string | undefined;
+    /** @type {string|undefined} joinSession 으로 매핑된 세션 식별자. */
+    sessionId: string | undefined;
+    /** @type {Set<string>|null} joinSession 으로 가입한 채널 집합. */
+    channels: Set<string> | null;
+    /** @type {Object|undefined} joinSession/updateMetadata 로 저장한 presence 메타(재연결 재동기화에 보존, M-1). */
+    metadata: Object | undefined;
+    /** @type {number} 협상된 envelope 프로토콜 버전(기본 v1) — driveWsConnection 이 핸드셰이크 결과로 설정. */
+    protocolVersion: number;
+    /** 하위 raw `ws` WebSocket (escape hatch — 바이너리/직접 제어용). */
+    get raw(): import("ws").WebSocket;
+    /** 연결이 OPEN 상태인지 (`ws.OPEN` === 1). */
+    get isOpen(): boolean;
+    /**
+     * 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: {
+        type: string;
+        ns?: string;
+        payload?: Object;
+        error?: Object;
+        ref?: string;
+    }): void;
+    /**
+     * 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 }: {
+        code: string;
+        message?: string;
+        details?: unknown;
+        ref?: string;
+        type?: string;
+    }): void;
+    /**
+     * 연결 종료.
+     * @param {number} [code]
+     * @param {string} [reason]
+     * @returns {void}
+     */
+    close(code?: number, reason?: string): void;
+}
+/**
+ * WS 프레임 코덱 — 평문/암호 와이어 변환을 추상화한다.
+ */
+export type WsFrameCodec = {
+    /**
+     * - 수신 프레임 → 평문 JSON 문자열 (실패 시 throw).
+     */
+    decode: (frame: string) => string;
+    /**
+     * - 평문 JSON → 송신 프레임 (기본: ASP 활성 시 암호).
+     */
+    encode: (json: string) => string;
+    /**
+     * - 평문 JSON → 평문 송신 프레임 (asp.error 통지용).
+     */
+    encodePlain: (json: string) => string;
+    /**
+     * - 기본 송신이 암호화인지.
+     */
+    isEncrypted: boolean;
+};

package/types/errors/config-error.d.ts

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