mega-framework 0.1.6 → 0.1.8

package/types/core/mega-app.d.ts

@@ -0,0 +1,529 @@
+/**
+ * 브라우저↔Bridge WS 프레임 최대 크기 디폴트 (bytes, L-3 / ADR-099).
+ * 1 MiB — Hub(`DEFAULT_MAX_PAYLOAD_BYTES`, src/lib/ws-hub.js)와 대칭. 초과 프레임은 ws 가 1009 close.
+ * core→cli 역방향 import 를 피하려 값을 여기 별도 정의(두 곳 모두 1 MiB 로 동일).
+ */
+export const DEFAULT_WS_MAX_PAYLOAD_BYTES: 1048576;
+/**
+ * MegaApp — 한 도메인 집합(hosts)에 대응하는 Fastify 인스턴스 래퍼.
+ *
+ * baseline — Fastify 인스턴스 보유, listen/close 라이프사이클.
+ * 라우터 등록·미들웨어 통합.
+ * 자동 envelope (ADR-018) + 글로벌 에러 핸들러 (ADR-025/090).
+ *
+ * ADR-002 (Fastify), ADR-063 (앱당 Fastify 인스턴스 격리), ADR-004 (dev *.localhost).
+ */
+export class MegaApp {
+    /**
+     * WS ASP 옵트인 정규화. masterSecret 없으면 null (평문 WS).
+     * @param {{ masterSecret?: string, websocket?: { namespaces?: string[] } }} [asp]
+     * @returns {{ masterSecret: string, namespaces: string[] } | null}
+     * @private
+     */
+    private static _normalizeWsAsp;
+    /**
+     * @param {Object} opts
+     * @param {string} opts.name - 앱 이름 (apps/<name> 폴더와 일치, ADR-067 검증됨)
+     * @param {string[]} [opts.hosts] - 도메인 매핑 (scaffold 모드 필수, single 모드 옵셔널)
+     * @param {'scaffold'|'single'} [opts.mode='scaffold'] - 부팅 모드 (ADR-013)
+     * @param {Object} [opts.fastifyOptions] - Fastify 생성 옵션 (logger 등)
+     * @param {import('pino').Logger|false} [opts.logger] - pino 로거 인스턴스 (ADR-023/141). bootApp 이
+     *   `global.logger`(MegaLoggerConfig)로 만들어 모든 앱에 주입한다. 미주입이면 `false`(무로그). Fastify 가
+     *   요청별 child(`req.log`, reqId 바인딩)를 만들고, `ctx.log` 가 이를 노출한다(trace_id 는 mixin 자동 주입).
+     * @param {boolean} [opts.exposeInternalDetails=false] - true 면 일반 Error 메시지를
+     *   envelope 에 노출 (디버그용). 기본 false — 보안 (ADR-025).
+     * @param {Object|false} [opts.helmet] - fastify-helmet 옵션 (보안 헤더). false=미등록, undefined=디폴트 ON
+     *   (ADR-047/127). 라우트 옵션 오버라이드는 완전 교체(ADR-073).
+     * @param {Object|false} [opts.cors] - fastify-cors 옵션. false=미등록, undefined=origin:false(교차출처 거부, 안전 디폴트).
+     * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(IP당 1000/min, ADR-048/197).
+     *   멀티 인스턴스 분산 카운팅은 `caches.rate` 별명(Redis), 미선언 시 in-memory 폴백.
+     * @param {Object|false} [opts.csrf] - fastify-csrf-protection 옵션. false=미등록, undefined=디폴트 ON.
+     *   ADR-051: JSON 요청은 토큰 면제+Origin 검증, 폼 요청만 토큰 검증.
+     * @param {{ masterSecret?: string, http?: { enabledPaths?: string[], driftMs?: number, headerSignal?: string, timestampHeader?: string, nonceCache?: any }, websocket?: { namespaces?: string[] } }} [opts.asp] -
+     *   ASP 옵트인. `masterSecret` 있으면 모든 WS 프레임이 `E:`/`P:` prefix 코덱 경유;
+     *   `websocket.namespaces` 에 포함된 경로만 기본 암호화(`E:`), 나머지는 평문(`P:`, ADR-083). `http.enabledPaths`
+     *   가 있으면 그 glob 경로에 HTTP ASP terminator 자동 등록(ADR-127). 미지정 시 raw JSON WS.
+     * @param {{ compression?: import('./ws-compression.js').WsCompressionConfig, maxPayloadBytes?: number }} [opts.websocket] -
+     *   브라우저↔Bridge WS 옵션 (ADR-078 / MegaWebsocketAppConfig). `compression`
+     *   블록으로 per-message deflate 옵트인. 디폴트 OFF. 부팅 시 threshold 음수 / serverMaxWindowBits
+     *   범위(9~15) 위반 throw. `maxPayloadBytes` 는 WS 프레임 최대 크기(L-3, 디폴트 1 MiB — Hub 와 대칭);
+     *   초과 프레임은 ws 가 1009 close. 양의 정수 아니면 디폴트로 폴백(부팅 검증은 config-validator 가 throw).
+     * @param {Record<string, string>} [opts.databases] - 어댑터 별명 맵 `{ alias: globalKey }` (ADR-102
+     *   글로벌 공유). `ctx.db(alias)` 가 globalKey 로 바꿔 전역 공유 인스턴스(MegaAdapterManager)를 반환.
+     *   실 인스턴스는 `mega.config.js` 의 `services.databases.<globalKey>` 에 정의되고 매니저가 소유·connect.
+     * @param {Record<string, string>} [opts.caches] - 캐시 별명 맵 `{ alias: globalKey }` (`ctx.cache(alias)`).
+     * @param {Record<string, string>} [opts.buses] - 버스 별명 맵 `{ alias: globalKey }` (`ctx.bus(alias)`).
+     * @param {Record<string, string>} [opts.locks] - 락 별명 맵 `{ alias: globalKey }` (`ctx.lock(alias)`, ADR-113).
+     * @param {{ maxFileSize?: number, maxFiles?: number, allowedMimeTypes?: string[] }} [opts.upload] -
+     *   파일 업로드 옵트인 (MegaUploadConfig, per ADR-133). 있으면 `@fastify/multipart` 를 자동 등록해
+     *   `req.file()`/`req.files()`/`req.saveUploads(dir)` 를 제공한다(없으면 multipart 요청 415).
+     *   `maxFileSize`(디폴트 10 MB)·`maxFiles`(미지정=무제한)·`allowedMimeTypes`(빈 배열=전부 허용, `image/*`
+     *   와일드카드 지원). MIME 화이트리스트 위반은 415, 크기·개수 초과는 413. CSRF(폼 토큰)는 보안 플러그인이,
+     *   ASP(body 평문 통과)는 ASP terminator 가 자동 통합. 트레이싱 `mega.upload.*` + 메트릭 `mega_upload_*`.
+     * @param {false | { store: { driver: 'file'|'redis', [k: string]: any }, secret?: string, ttlMs?: number, rolling?: boolean, cookie?: object, csrf?: boolean }} [opts.session] -
+     *   세션 옵트인 (ADR-129/046). `store` = 백엔드(file/redis) inline config. `secret` =
+     *   쿠키 HMAC 시크릿(미지정 시 `opts.sessionSecret` — bootApp 이 global `server.sessionSecret` 주입).
+     *   `ttlMs`(기본 24h)·`rolling`(기본 true)·`cookie`(httpOnly/secure/sameSite). `csrf:true` 면 CSRF 를
+     *   세션 모드로(시크릿을 세션 `_csrf` 키에 바인딩). `false`/미지정 → 세션 비활성.
+     * @param {string} [opts.sessionSecret] - 세션 쿠키 HMAC 시크릿(global `server.sessionSecret`). `session.secret` 미지정 시 사용.
+     * @param {{ default?: string, available?: string[], fallback?: string, cookieName?: string, autoComplete?: { enabled?: boolean, dir?: string, debounceMs?: number }, localesDir?: string, resources?: object, exposeTranslations?: boolean, translationsPath?: string }} [opts.i18n] -
+     *   i18n 옵트인 (ADR-037/038/039/135). 있으면 앱 전용 `i18next` 인스턴스를 등록해
+     *   `req.lang`/`req.t`/`req.setLocale`/`req.translations` + `ctx.lang`/`ctx.t` 를 제공한다(없으면 ctx.t 는
+     *   passthrough). 언어 결정은 **쿠키만**(ADR-038, `cookieName` 디폴트 `mega.lang`). scope 분리(server/client,
+     *   ADR-039) — `ctx.t()` 는 server scope, `GET /i18n/translations` 는 client scope 만 노출. dev 면 누락 키
+     *   자동 생성(saveMissing axion 패턴, `autoComplete`). 트레이싱 `mega.i18n.*` + 메트릭 `mega_i18n_*`.
+     * @param {{ dir?: string, layoutDir?: string, partialsDir?: string, defaultLayout?: string, cache?: boolean }} [opts.views] -
+     *   서버사이드 템플릿 옵트인 (ADR-011/136 — EJS + ejs-mate). `dir`(뷰 루트, 예
+     *   `apps/<name>/views`)이 있을 때만 `reply.render(view, data, { layout })`(정본 res.render) + `ctx.render`
+     *   를 제공한다(없으면 미정의 → 호출 시 fail-fast). 렌더 data 에 요청별 i18n `t`/`lang` 자동 병합(다국어 뷰).
+     *   XSS auto-escape(`<%=`) 기본 + 경로 탐색 차단. 트레이싱 `mega.template.*` + 메트릭 `mega_template_*`.
+     * @param {{ enabled?: boolean, path?: string, info?: { title?: string, version?: string, description?: string }, auth?: Function[], theme?: Object }} [opts.openapi] -
+     *   OpenAPI/Swagger 옵트인 (MegaOpenApiAppConfig, ADR-070/140 — `@fastify/swagger` + `@fastify/swagger-ui`).
+     *   `enabled:true` 일 때만 라우트 schema 를 OpenAPI 3.x 명세로 수집하고 `path`(디폴트 `/docs`)에 swagger-ui 를
+     *   등록한다(디폴트 OFF — 프로덕션 노출 방지). `info`={title,version,description}. `auth` 미들웨어 배열로 docs
+     *   접근 보호(빈 배열=공개, `(req, reply, ctx)` 시그니처). `theme`=swagger-ui uiConfig. 라우트 옵션
+     *   `openapi:{tags,summary,description,deprecated}` 가 명세에 반영(router.js).
+     * @param {{ enabled?: boolean, dir?: string, prefix?: string, cacheControl?: string, dotfiles?: boolean }} [opts.staticAssets] -
+     *   정적 자산 옵트인 (MegaStaticAssetsAppConfig, ADR-071/139 — `@fastify/static`). `enabled:true` + 실존 `dir`
+     *   (서빙 루트, 예 `apps/<name>/public`)일 때만 `${prefix}/<파일>`(prefix 디폴트 `/static`)로 디스크 파일을 서빙
+     *   (디폴트 OFF). `cacheControl` = raw `Cache-Control` 헤더 문자열(예 `'public, max-age=3600'`). `dotfiles`
+     *   디폴트 false(`.git`/`.env` 차단). `enabled:true` 인데 `dir` 누락/미존재 시 프로덕션 부팅 throw / dev warn+skip.
+     *   prefix 가 `health.metricsPath` 와 같으면 부팅 throw(ADR-072).
+     * @param {{ enabled?: boolean, paths?: { live?: string, ready?: string }, exposeCheckDetails?: boolean, exposeMetrics?: boolean, metricsPath?: string, metricsAllowList?: string[] }} [opts.health] -
+     *   운영 관측성 config(Global-only, ADR-072/131). bootApp 이 global `health` 블록을 주입한다.
+     *   `exposeCheckDetails:true` 면 readiness 응답에 체크별 전체 필드(error 메시지 등)를 노출 — 기본 false
+     *   (체크별 `{ ok }` 만, ADR-186).
+     *   `exposeMetrics:true` 면 `metricsPath`(디폴트 `/metrics`)에 Prometheus `/metrics` 라우트를 등록(보안 면제).
+     *   `metricsAllowList` = 접근 허용 IP/CIDR(빈 배열이면 메인 포트 전체 노출, ADR-131). metricsPath 가 health
+     *   경로와 충돌하면 부팅 throw. SDK 초기화(MegaMetrics.init)는 bootApp/prepareRuntime 이 담당.
+     * @param {Array<{ plugin: Function, opts?: object }>} [opts.plugins] - 플러그인이 `mega.app.use(...)`
+     *   로 등록한 Fastify 플러그인 묶음(정본 §14 hook표 — "모든 앱 인스턴스에 등록"). 부팅 orchestrator
+     *   (`bootApp`)가 `MegaPluginHost.fastifyPlugins` 를 모든 앱에 주입한다(ADR-123). 각 원소는
+     *   `this.fastify.register(plugin, opts)` 로 등록.
+     * @param {Function[]} [opts.globalMiddlewares] - 플러그인이 `mega.middlewares.global(...)` 로 등록한
+     *   글로벌 미들웨어(모든 라우트 적용). orchestrator 가 주입한다. 계약: `async (req, reply, ctx) => void`
+     *   — 라우트 핸들러와 동일한 canonical 시그니처(ADR-074/134). `ctx` 는 요청당 1회 만들어 핸들러와
+     *   공유하므로, 미들웨어가 `ctx` 에 심은 값을 핸들러가 본다. 기존 `(req, reply)` 미들웨어는 3번째
+     *   인자를 무시하므로 하위 호환.
+     * @param {Function[]} [opts.globalTransforms] - 앱/전역 레벨 응답 변환(ADR-021 체인의 "앱 → 전역"
+     *   구간, ADR-194). 계약: `async (req, reply, payload) => payload`. 라우트(+파일) transform 뒤·
+     *   자동 envelope wrap 직전에 배열 순서대로 실행(주입자가 앱 항목 먼저·전역 항목 뒤로 배열).
+     *   health/metrics 등 `config.skipGlobalLifecycle` 라우트는 제외.
+     * @param {Function[]} [opts.globalAfters] - 앱/전역 레벨 응답 후 side-effect(ADR-194). 계약:
+     *   `async (req, reply) => void` — 응답 전송 후(onResponse), throw 는 warn 로그 후 무시(ADR-091).
+     *   라우트(+파일) after 뒤에 실행. `config.skipGlobalLifecycle` 라우트는 제외.
+     */
+    constructor(opts: {
+        name: string;
+        hosts?: string[];
+        mode?: "scaffold" | "single";
+        fastifyOptions?: Object;
+        logger?: import("pino").Logger | false;
+        exposeInternalDetails?: boolean;
+        helmet?: Object | false;
+        cors?: Object | false;
+        rateLimit?: Object | false;
+        csrf?: Object | false;
+        asp?: {
+            masterSecret?: string;
+            http?: {
+                enabledPaths?: string[];
+                driftMs?: number;
+                headerSignal?: string;
+                timestampHeader?: string;
+                nonceCache?: any;
+            };
+            websocket?: {
+                namespaces?: string[];
+            };
+        };
+        websocket?: {
+            compression?: import("./ws-compression.js").WsCompressionConfig;
+            maxPayloadBytes?: number;
+        };
+        databases?: Record<string, string>;
+        caches?: Record<string, string>;
+        buses?: Record<string, string>;
+        locks?: Record<string, string>;
+        upload?: {
+            maxFileSize?: number;
+            maxFiles?: number;
+            allowedMimeTypes?: string[];
+        };
+        session?: false | {
+            store: {
+                driver: "file" | "redis";
+                [k: string]: any;
+            };
+            secret?: string;
+            ttlMs?: number;
+            rolling?: boolean;
+            cookie?: object;
+            csrf?: boolean;
+        };
+        sessionSecret?: string;
+        i18n?: {
+            default?: string;
+            available?: string[];
+            fallback?: string;
+            cookieName?: string;
+            autoComplete?: {
+                enabled?: boolean;
+                dir?: string;
+                debounceMs?: number;
+            };
+            localesDir?: string;
+            resources?: object;
+            exposeTranslations?: boolean;
+            translationsPath?: string;
+        };
+        views?: {
+            dir?: string;
+            layoutDir?: string;
+            partialsDir?: string;
+            defaultLayout?: string;
+            cache?: boolean;
+        };
+        openapi?: {
+            enabled?: boolean;
+            path?: string;
+            info?: {
+                title?: string;
+                version?: string;
+                description?: string;
+            };
+            auth?: Function[];
+            theme?: Object;
+        };
+        staticAssets?: {
+            enabled?: boolean;
+            dir?: string;
+            prefix?: string;
+            cacheControl?: string;
+            dotfiles?: boolean;
+        };
+        health?: {
+            enabled?: boolean;
+            paths?: {
+                live?: string;
+                ready?: string;
+            };
+            exposeCheckDetails?: boolean;
+            exposeMetrics?: boolean;
+            metricsPath?: string;
+            metricsAllowList?: string[];
+        };
+        plugins?: Array<{
+            plugin: Function;
+            opts?: object;
+        }>;
+        globalMiddlewares?: Function[];
+        globalTransforms?: Function[];
+        globalAfters?: Function[];
+    });
+    name: string;
+    hosts: string[];
+    mode: string;
+    /** @type {import('./ctx-builder.js').AdapterAccessors} */
+    _adapterAccessors: import("./ctx-builder.js").AdapterAccessors;
+    /** @type {MegaBruteForce|null} ctx.bruteForce 단축의 lazy 인스턴스(앱당 1개 재사용). */
+    _bruteForce: MegaBruteForce | null;
+    /**
+     * name → 서비스 클래스. 부팅 시 services-loader 가 `apps/<name>/services/*.js` 를 스캔해 채운다
+     * (ADR-148). 요청별 `ctx.services.<name>` lazy DI 가 이 맵을 보고 인스턴스화한다. 기본은 빈 Map
+     * (서비스 없는 앱·standalone 테스트).
+     * @type {Map<string, Function>}
+     */
+    _serviceRegistry: Map<string, Function>;
+    /** @type {string|null} OpenAPI 옵트인 시 swagger-ui 경로(ADR-140). envelope onRoute 가 이 경로를 제외. */
+    _openapiPath: string | null;
+    /** @type {Function[]} */
+    _globalTransforms: Function[];
+    /** @type {Function[]} */
+    _globalAfters: Function[];
+    _wsAsp: {
+        masterSecret: string;
+        namespaces: string[];
+    };
+    /** @type {false | Object} _ensureWss 의 WebSocketServer perMessageDeflate 로 전달. */
+    _wsPerMessageDeflate: false | Object;
+    /** @type {number} _ensureWss 의 WebSocketServer maxPayload 로 전달. */
+    _wsMaxPayloadBytes: number;
+    /** @type {Router|null} single 모드 직접 등록(app.ws)용 lazy 라우터. */
+    _router: Router | null;
+    /** @type {WebSocketServer|null} noServer 모드 WS 핸드셰이커 (lazy). */
+    _wss: WebSocketServer | null;
+    fastify: Fastify.FastifyInstance<import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>, import("node:http").IncomingMessage, import("node:http").ServerResponse<import("node:http").IncomingMessage>, import("pino").Logger<never, boolean>, Fastify.FastifyTypeProviderDefault> & PromiseLike<Fastify.FastifyInstance<import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>, import("node:http").IncomingMessage, import("node:http").ServerResponse<import("node:http").IncomingMessage>, import("pino").Logger<never, boolean>, Fastify.FastifyTypeProviderDefault>> & {
+        __linterBrands: "SafePromiseLike";
+    };
+    _presence: MegaWsPresence;
+    /** @type {import('../adapters/mega-session-adapter.js').MegaSessionAdapter | null} */
+    _sessionStore: import("../adapters/mega-session-adapter.js").MegaSessionAdapter | null;
+    /**
+     * rate-limit Redis 백엔드 해석기를 만든다 (ADR-048). 앱이 `caches.rate` 별명을 선언했고 그 어댑터가
+     * Redis(`MegaRedisAdapter`)면 ioredis raw handle 을 반환하는 함수를, 아니면 `undefined` 를 돌려준다
+     * (= in-memory 폴백, 단일 인스턴스 dev). 해석은 보안 등록 시점(생성자)에 1회 호출되며, 어댑터는
+     * 그 전에 `MegaAdapterManager` 가 connect 해 둔 상태여야 한다(부팅 orchestrator 가 보장).
+     *
+     * Redis 가 아닌 캐시를 `rate` 로 매핑한 misconfiguration 은 silent 무시하지 않고 warn 후 in-memory
+     * 폴백한다(ADR-048 — rate-limit 은 ioredis 전용, 폴백은 비치명적·문서화된 디폴트).
+     *
+     * @param {Record<string, string>} [caches] - 앱 캐시 별명 맵 `{ alias: globalKey }`.
+     * @returns {(() => import('ioredis').Redis | null) | undefined}
+     * @private
+     */
+    private _buildRateStoreResolver;
+    /**
+     * Single 모드 WS 채널 등록. `router.ws` 와 동일 검증 위임.
+     *
+     * 단일 파일 모드에서 `routes/` 스캔 없이 직접 채널을 등록한다 (02-architecture §3). 등록은
+     * `fastify._megaWsRoutes` 에 보관되며 {@link MegaApp#listen} 시 upgrade 핸들오프가 배선된다.
+     *
+     * @param {string} path - WS 경로 (= namespace).
+     * @param {Function} ChannelClass - MegaWebSocketController 상속.
+     * @param {{ before?: Function[], schemas?: Object }} [opts]
+     * @returns {this} 체이닝용.
+     * @throws {import('./router.js').MegaRouteError} 형식/상속 위반.
+     */
+    ws(path: string, ChannelClass: Function, opts?: {
+        before?: Function[];
+        schemas?: Object;
+    }): this;
+    /**
+     * 등록된 WS 라우트 목록 (router.ws + app.ws 통합). 비어 있으면 빈 배열.
+     * @returns {Array<{ path: string, ns: string, ChannelClass: Function, opts: { before?: Function[], schemas?: Object }, schemaValidators?: Record<string, import('ajv').ValidateFunction> | null }>}
+     */
+    get wsRoutes(): Array<{
+        path: string;
+        ns: string;
+        ChannelClass: Function;
+        opts: {
+            before?: Function[];
+            schemas?: Object;
+        };
+        schemaValidators?: Record<string, import("ajv").ValidateFunction> | null;
+    }>;
+    /**
+     * 이 앱의 `ctx.db/cache/bus` 접근자 3종 (ADR-102). 요청 ctx 빌더(HTTP·WS)가 spread 해서 노출한다.
+     * 별명→globalKey→전역 공유 어댑터로 해석하며, 미선언 별명·미등록 키는 호출 시 throw.
+     * @returns {import('./ctx-builder.js').AdapterAccessors}
+     */
+    get adapterAccessors(): import("./ctx-builder.js").AdapterAccessors;
+    /**
+     * 이 앱의 서비스 레지스트리(name → 클래스, ADR-148). 요청 ctx 빌더가 `ctx.services.<name>` lazy DI 의
+     * 클래스 lookup 출처로 읽는다. 부팅 orchestrator 가 `setServiceRegistry` 로 채운다.
+     * @returns {Map<string, Function>}
+     */
+    get serviceRegistry(): Map<string, Function>;
+    /**
+     * 서비스 레지스트리 주입 (부팅 시 1회, ADR-148). services-loader 가 만든 name→Class 맵으로 교체한다.
+     * @param {Map<string, Function>} registry - name → 서비스 클래스.
+     * @returns {void}
+     * @throws {TypeError} Map 이 아니면.
+     */
+    setServiceRegistry(registry: Map<string, Function>): void;
+    /**
+     * `ctx.bruteForce` 단축이 반환하는 MegaBruteForce 인스턴스(03-api-spec §10/§786, ADR-049/130).
+     * **lazy** — 처음 접근할 때만 만들고 앱당 재사용한다. 백엔드는 `caches.rate` 별명(ADR-049 디폴트)을
+     * 해석한 redis 어댑터. rate 캐시를 선언 안 한 앱이 이 getter 를 건드리면 cache 접근자가 fail-fast
+     * (`adapter.not_registered`) — brute-force 를 안 쓰는 앱은 이 getter 를 호출하지 않으므로 무해하다.
+     * 세분 정책(도메인별 maxAttempts 등)은 `new MegaBruteForce({ cache: ctx.cache('alias'), key, ... })`
+     * 로 직접 구성한다(별도 config 키는 향후 Step, ADR-130).
+     * @returns {MegaBruteForce}
+     */
+    get bruteForce(): MegaBruteForce;
+    /** 현재 연결된 hub link (미연결 시 null). */
+    get hubLink(): import("./hub-link.js").MegaHubLink;
+    /**
+     * 이 bridge 를 hub 에 연결한다 (ADR-033/059) — 계약·옵션은 {@link MegaWsPresence#connectHub} 정본.
+     * @param {any} [config] - MegaBridgeHubConfig(§2.1) + 구독 채널.
+     * @returns {Promise<import('./hub-link.js').MegaHubLink>} 등록 완료된 link.
+     */
+    connectHub(config?: any): Promise<import("./hub-link.js").MegaHubLink>;
+    /**
+     * 실 사용자 세션을 hub presence 에 등록하고 로컬 매핑을 만든다 — {@link MegaWsPresence#joinSession} 위임.
+     * @param {import('./ws-upgrade.js').MegaWsConnection} conn
+     * @param {{ userId: string, sessionId: string, channels?: string[], metadata?: Object }} [entry]
+     * @returns {this}
+     */
+    joinSession(conn: import("./ws-upgrade.js").MegaWsConnection, entry?: {
+        userId: string;
+        sessionId: string;
+        channels?: string[];
+        metadata?: Object;
+    }): this;
+    /**
+     * 채널 broadcast — 로컬 즉시 전달 + (hub/NATS 연결 시) 클러스터 fan-out. {@link MegaWsPresence#broadcast} 위임.
+     * @param {{ ns: string, channel: string, message: { type: string, payload?: Object }, exceptSessionIds?: string[] }} args
+     * @returns {void}
+     */
+    broadcast(args: {
+        ns: string;
+        channel: string;
+        message: {
+            type: string;
+            payload?: Object;
+        };
+        exceptSessionIds?: string[];
+    }): void;
+    /**
+     * 특정 사용자에게 직접 전송 (ADR-035) — {@link MegaWsPresence#directToUser} 위임.
+     * @param {string} userId
+     * @param {{ type: string, payload?: Object }} message
+     * @returns {void}
+     */
+    directToUser(userId: string, message: {
+        type: string;
+        payload?: Object;
+    }): void;
+    /**
+     * 세션 presence 메타데이터 갱신 (ADR-059) — {@link MegaWsPresence#updateMetadata} 위임.
+     * @param {string} sessionId
+     * @param {Object} metadata
+     * @returns {this}
+     */
+    updateMetadata(sessionId: string, metadata: Object): this;
+    /**
+     * NATS 클러스터 fan-out/roster 배선 (ADR-176, boot 자동 호출) — {@link MegaWsPresence#setWsCluster} 위임.
+     * @param {import('./ws-cluster.js').MegaWsCluster|null} cluster
+     * @returns {this}
+     */
+    setWsCluster(cluster: import("./ws-cluster.js").MegaWsCluster | null): this;
+    /**
+     * ns(WS 채널 경로) 기준 접속자 목록 (ADR-176) — {@link MegaWsPresence#roster} 위임.
+     * @param {string} ns
+     * @returns {Array<{ sessionId: string, userId: string, metadata?: Object }>}
+     */
+    roster(ns: string): Array<{
+        sessionId: string;
+        userId: string;
+        metadata?: Object;
+    }>;
+    /**
+     * 채널별 redis roster 배선 (ADR-177, boot 자동 호출) — {@link MegaWsPresence#setWsRoster} 위임.
+     * @param {import('./ws-roster.js').MegaWsRedisRoster|null} roster
+     * @returns {this}
+     */
+    setWsRoster(roster: import("./ws-roster.js").MegaWsRedisRoster | null): this;
+    /**
+     * 채널들의 cluster-wide 접속자 목록 (ADR-177) — {@link MegaWsPresence#presenceList} 위임.
+     * @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) — {@link MegaWsPresence#localRosterMembers} 위임.
+     * @returns {Array<{ channel: string, sessionId: string, member: { userId: string, metadata?: Object } }>}
+     */
+    localRosterMembers(): Array<{
+        channel: string;
+        sessionId: string;
+        member: {
+            userId: string;
+            metadata?: Object;
+        };
+    }>;
+    /**
+     * broadcast payload 로컬 전달 (framework-internal — boot 의 MegaWsCluster 배선이 사용).
+     * @param {{ ns: string, channel?: string, message: { type: string, payload?: Object }, exceptSessionIds?: string[] }} payload
+     * @returns {void}
+     * @private
+     */
+    private _deliverBroadcast;
+    /**
+     * direct payload 로컬 전달 (framework-internal — boot 의 MegaWsCluster 배선이 사용).
+     * @param {{ userId: string, message: { type: string, payload?: Object } }} payload
+     * @returns {void}
+     * @private
+     */
+    private _deliverDirect;
+    /**
+     * hub 의 DISCONNECT(admin-kick, ADR-097) 라우팅 처리 (framework-internal).
+     * @param {{ sessionId: string, reason?: string, requeue?: boolean }} payload
+     * @returns {void}
+     * @private
+     */
+    private _handleHubDisconnect;
+    /**
+     * 로컬 WS 연결 등록 (driveWsConnection 이 호출 — framework-internal).
+     * @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;
+    set _hubLink(v: import("./hub-link.js").MegaHubLink | null);
+    /** @returns {import('./hub-link.js').MegaHubLink|null} */
+    get _hubLink(): import("./hub-link.js").MegaHubLink | null;
+    set _wsCluster(v: import("./ws-cluster.js").MegaWsCluster | null);
+    /** @returns {import('./ws-cluster.js').MegaWsCluster|null} */
+    get _wsCluster(): import("./ws-cluster.js").MegaWsCluster | null;
+    set _wsRoster(v: import("./ws-roster.js").MegaWsRedisRoster | null);
+    /** @returns {import('./ws-roster.js').MegaWsRedisRoster|null} */
+    get _wsRoster(): import("./ws-roster.js").MegaWsRedisRoster | null;
+    /** @returns {Map<string, import('./ws-upgrade.js').MegaWsConnection>} */
+    get _sessionConns(): Map<string, import("./ws-upgrade.js").MegaWsConnection>;
+    /** @returns {Map<string, Set<import('./ws-upgrade.js').MegaWsConnection>>} */
+    get _userConns(): Map<string, Set<import("./ws-upgrade.js").MegaWsConnection>>;
+    /** @returns {Map<string, Set<import('./ws-upgrade.js').MegaWsConnection>>} */
+    get _wsConns(): Map<string, Set<import("./ws-upgrade.js").MegaWsConnection>>;
+    /**
+     * HTTP `'upgrade'` 이벤트 처리 — 경로 매칭 → 인증(before) → 핸드셰이크 → 채널 라이프사이클.
+     *
+     * single 모드는 {@link MegaApp#listen} 이, scaffold 모드는 MegaServer 가 호스트 분기 후 호출한다.
+     * 매칭 WS 라우트가 없으면 404 로 거부 (HTTP 핸드셰이크 단계라 WS close 아님).
+     *
+     * @param {import('node:http').IncomingMessage} req
+     * @param {import('node:stream').Duplex} socket
+     * @param {Buffer} head
+     * @returns {void}
+     */
+    handleUpgrade(req: import("node:http").IncomingMessage, socket: import("node:stream").Duplex, head: Buffer): void;
+    /**
+     * 연결별 프레임 코덱 선택 (ADR-083). ASP 설정 시 namespace 활성 여부로 E:/P: 기본 결정.
+     * @param {{ path: string }} route
+     * @param {import('node:http').IncomingMessage} req
+     * @returns {import('./ws-upgrade.js').WsFrameCodec}
+     * @private
+     */
+    private _buildWsCodec;
+    /**
+     * noServer 모드 WebSocketServer lazy 생성 (WS 라우트가 있을 때만).
+     * @returns {WebSocketServer}
+     * @private
+     */
+    private _ensureWss;
+    /**
+     * 등록된 WS 라우트가 있으면 httpServer 의 'upgrade' 이벤트를 자기 handleUpgrade 에 배선.
+     * single 모드 listen 에서 호출. WS 라우트가 없으면 no-op (불필요한 리스너 회피).
+     * @param {import('node:http').Server} httpServer
+     * @returns {void}
+     */
+    _attachWsUpgrade(httpServer: import("node:http").Server): void;
+    /**
+     * Single 모드 전용 listen — MegaServer 거치지 않고 직접 listen.
+     * Scaffold 모드는 MegaServer.mount() + MegaServer.listen() 사용.
+     * @param {{ port?: number, host?: string }} [opts]
+     */
+    listen(opts?: {
+        port?: number;
+        host?: string;
+    }): Promise<string>;
+    /** 인스턴스 close — hub link · WS 연결 정리 후 진행 중 요청 grace 후 종료. */
+    close(): Promise<void>;
+    /** 이 앱의 세션 스토어 어댑터 (세션 미활성 시 null). 테스트·헬스용. */
+    get sessionStore(): import("../adapters/mega-session-adapter.js").MegaSessionAdapter;
+}
+import { MegaBruteForce } from '../lib/mega-brute-force.js';
+import { Router } from './router.js';
+import { WebSocketServer } from 'ws';
+import Fastify from 'fastify';
+import { MegaWsPresence } from './ws-presence.js';

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

@@ -0,0 +1,104 @@
+/**
+ * 코어가 워커에 부착하는 비표준 프로퍼티(`_megaBirthAt`, 수명 측정용)를 포함한 Worker.
+ * @typedef {import('node:cluster').Worker & { _megaBirthAt?: number }} MegaWorker
+ */
+export class MegaCluster {
+    /**
+     * @param {Object} [opts]
+     * @param {number | 'max'} [opts.instances] - 워커 수. 'max' 면 CPU 코어 수.
+     * @param {boolean} [opts.respawn=true] - 워커 crash 시 자동 재시작
+     * @param {number} [opts.gracePeriodMs=30000] - SIGTERM 후 강제 kill 까지 대기. ⚠️ 워커가
+     *   `MegaShutdown.setupSignals()` 를 쓰면 워커 종료 예산 상한은 hardKill(기본 60s)이다 — 마스터 grace 가
+     *   그보다 작으면 워커 drain 도중 SIGKILL 되는 예산 역전이 생긴다. `mega start` CLI 는
+     *   `DEFAULT_HARD_KILL_MS + 5s` 로 위계화해 전달한다(직접 생성 시에도 동일 권장).
+     * @param {import('node:cluster').Cluster} [opts._cluster] - 테스트용 cluster 주입(기본 node:cluster). per ADR-165
+     * @param {NodeJS.Process} [opts._proc] - 테스트용 process 주입(기본 전역 process). per ADR-165
+     * @param {{ info?: Function, warn?: Function, error?: Function } | null} [opts.logger] - 조율 로그용 pino 로거.
+     *   미설정이면 console 폴백(마스터는 bootApp 을 안 해 pino 인스턴스가 없을 수 있다, ADR-180).
+     */
+    constructor(opts?: {
+        instances?: number | "max";
+        respawn?: boolean;
+        gracePeriodMs?: number;
+        _cluster?: import("node:cluster").Cluster;
+        _proc?: NodeJS.Process;
+        logger?: {
+            info?: Function;
+            warn?: Function;
+            error?: Function;
+        } | null;
+    });
+    _instances: number;
+    _respawn: boolean;
+    _gracePeriodMs: number;
+    _shuttingDown: boolean;
+    _cluster: cluster.Cluster;
+    _proc: NodeJS.Process;
+    /** @type {{ info?: Function, warn?: Function, error?: Function } | null} 조율 로그용 로거(없으면 console). */
+    _logger: {
+        info?: Function;
+        warn?: Function;
+        error?: Function;
+    } | null;
+    /** @type {Set<MegaWorker>} */
+    _workers: Set<MegaWorker>;
+    /** @type {(() => Promise<void>) | null} */
+    _workerFn: (() => Promise<void>) | null;
+    _maxRapidRespawn: number;
+    _minRespawnIntervalMs: number;
+    /** @type {number[]} 윈도우 내 빠른-crash 타임스탬프(ms). */
+    _rapidCrashTimes: number[];
+    /** @type {ReturnType<typeof setTimeout>|null} SIGTERM grace 강제-kill 타이머(전원 정상종료 시 취소). */
+    _graceTimer: ReturnType<typeof setTimeout> | null;
+    /**
+     * 마스터 / 워커 둘 다 호출. 마스터면 fork, 워커면 사용자 함수 실행.
+     * @param {() => Promise<void>} workerFn - 워커 프로세스에서 실행할 부팅 함수.
+     * @returns {Promise<void>}
+     */
+    start(workerFn: () => Promise<void>): Promise<void>;
+    /** boolean 네이밍 (ADR-036). */
+    isShuttingDown(): boolean;
+    /** boolean — primary 프로세스인지. */
+    isPrimary(): boolean;
+    /** boolean — worker 프로세스인지. */
+    isWorker(): boolean;
+    /**
+     * 조율 로그용 로거 주입(생성 후, start 전에 호출). 마스터는 bootApp 을 안 해 pino 가 없으므로 CLI 가
+     * config 로 만든 인스턴스를 넘긴다(ADR-180). 미주입이면 console 폴백.
+     * @param {{ info?: Function, warn?: Function, error?: Function } | null | undefined} logger
+     * @returns {void}
+     */
+    setLogger(logger: {
+        info?: Function;
+        warn?: Function;
+        error?: Function;
+    } | null | undefined): void;
+    /**
+     * @private 조율 로그 — 주입 로거가 있으면 그 레벨로, 없으면 console 폴백(`[mega-cluster]` 접두).
+     * @param {'info'|'warn'|'error'} level @param {string} msg
+     */
+    private _log;
+    /**
+     * @private 마스터 프로세스 부팅 시퀀스.
+     * @param {() => Promise<void>} workerFn
+     */
+    private _startPrimary;
+    /** @private 워커 fork + 라이프사이클 wiring. */
+    private _forkWorker;
+    /** @private 모든 워커에 shutdown 메시지 송신. */
+    private _broadcastShutdown;
+    /**
+     * @private 워커 프로세스 시작 — 사용자 함수 실행 + 마스터 메시지 수신.
+     * @param {() => Promise<void>} workerFn
+     */
+    private _startWorker;
+    /** 외부에서 강제 종료 트리거 (테스트용). */
+    shutdown(): Promise<void>;
+}
+/**
+ * 코어가 워커에 부착하는 비표준 프로퍼티(`_megaBirthAt`, 수명 측정용)를 포함한 Worker.
+ */
+export type MegaWorker = import("node:cluster").Worker & {
+    _megaBirthAt?: number;
+};
+import cluster from 'node:cluster';