mega-framework 0.1.7 → 0.1.8

package/types/lib/mega-job-queue.d.ts

@@ -12,6 +12,8 @@ export const DEFAULT_RUN_TIMEOUT_MS: number;
  *   하트비트가 이 값의 절반마다 lease 를 갱신한다.
  * @property {number} [maxDeliver=5] - JetStream 최대 전달 횟수(워커 크래시 재전달 backstop).
  * @property {number} [heartbeatMs] - `working()` 전송 주기(ms). 기본 `max(1000, ackWaitMs/2)`.
+ *   양의 정수 + `< ackWaitMs` 필수(생성자 fail-fast) — 이상이면 lease 갱신이 늦어 정상 처리 중
+ *   중복 재전달, 0 이하면 working() 플러딩.
  * @property {string} [streamPrefix='MEGA_JOBS'] - 스트림 이름 접두사.
  * @property {number} [dlqMaxAgeMs=604800000] - DLQ 스트림 메시지 보존 기한(ms, 디폴트 7일). 초과한 실패
  *   잡은 NATS 가 자동 만료시킨다(무한 적재 방지, ADR-134). `0` 이면 무제한(끔 — 영구 보존). **신규 DLQ
@@ -73,10 +75,18 @@ export class MegaJobQueue extends EventEmitter<any> {
      */
     ensureStream(JobClass: typeof MegaJob): Promise<void>;
     /**
-     * 잡을 큐에 넣는다(JetStream publish — 서버에 영속 저장). 스트림이 없으면 만든다.
-     * @param {typeof MegaJob} JobClass @param {any} payload @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
-     */
-    enqueue(JobClass: typeof MegaJob, payload: any): Promise<{
+     * 잡을 큐에 넣는다(JetStream publish — 서버에 영속 저장). 스트림이 없으면 만든다(subject 별 1회 확인 후 캐시).
+     *
+     * @param {typeof MegaJob} JobClass @param {any} payload
+     * @param {{ msgID?: string }} [opts] - `msgID` = JetStream `Nats-Msg-Id` dedup 키(옵트인). 스트림
+     *   duplicate window(NATS 기본 2분 — 운영자가 NATS CLI 로 스트림별 조정) 안의 같은 msgID 재발행은
+     *   적재되지 않고 `duplicate: true` 로 반환된다. 비즈니스 멱등키(주문 ID 등)를 권장. 미지정 시
+     *   dedup 없음 — `duplicate` 는 항상 false.
+     * @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
+     */
+    enqueue(JobClass: typeof MegaJob, payload: any, { msgID }?: {
+        msgID?: string;
+    }): Promise<{
         seq: number;
         stream: string;
         duplicate: boolean;
@@ -129,6 +139,8 @@ export type MegaJobQueueOptions = {
     maxDeliver?: number;
     /**
      * - `working()` 전송 주기(ms). 기본 `max(1000, ackWaitMs/2)`.
+     * 양의 정수 + `< ackWaitMs` 필수(생성자 fail-fast) — 이상이면 lease 갱신이 늦어 정상 처리 중
+     * 중복 재전달, 0 이하면 working() 플러딩.
      */
     heartbeatMs?: number;
     /**

package/types/lib/mega-job.d.ts

@@ -92,7 +92,14 @@ export class MegaJob {
     static subject: string | undefined;
     /** @type {string|undefined} bus 별명(`ctx.bus(alias)`). 워커 배선이 nc 해석에 사용. */
     static bus: string | undefined;
-    /** @type {number} 동시 처리 메시지 수(consumer max_ack_pending). 기본 1(순차·안전). */
+    /**
+     * @type {number} 동시 처리 메시지 수. 기본 1(순차·안전).
+     *
+     * ⚠️ 이 값은 durable consumer 의 `max_ack_pending` 으로 들어가므로 **워커 그룹(같은 subject 를
+     * 소비하는 모든 인스턴스) 전체의 합산 in-flight 상한**이다 — `mega worker` 인스턴스를 늘려도
+     * 합산 동시 처리는 이 값을 넘지 못한다. 처리량을 늘리려면 인스턴스 증설과 **함께** concurrency 를
+     * 키워야 한다(실측: c=1→c=32 에서 처리량 ~10배).
+     */
     static concurrency: number;
     /** @type {number} run 실패 시 **추가** 재시도 횟수(첫 시도 제외). 기본 3(OQ-012). */
     static retries: number;

package/types/lib/mega-plugin.d.ts

@@ -53,7 +53,7 @@ export const CORE_API_VERSION: string;
  * @property {Array<{ path: string, template: string }>} files
  * @property {string} [description] - `mega help` 가 병기하는 한 줄 설명(선택).
  */
-/** 빌트인 generator 13종 이름 — 플러그인 scaffold 가 점유 금지(빌트인이 우선이라 silent shadow 가 됨).
+/** 빌트인 generator 이름 — 플러그인 scaffold 가 점유 금지(빌트인이 우선이라 silent shadow 가 됨).
  * cli/generators 의 `GENERATOR_KINDS` 와 동일해야 한다(레이어 역전 회피를 위해 미러 — 동기화는
  * mega-plugin 단위 테스트가 GENERATOR_KINDS 와 집합 비교로 강제한다). */
 export const RESERVED_GENERATOR_NAMES: Set<string>;

package/types/lib/mega-worker.d.ts

@@ -37,8 +37,10 @@ export class MegaWorker extends EventEmitter<any> {
     get mode(): "thread" | "process";
     /** @returns {number} 풀 크기. */
     get poolSize(): number;
-    /** @returns {number} crash 교체 허용 총량. */
+    /** @returns {number} 윈도우({@link MegaWorker#restartWindowMs}) 내 crash 교체 허용 횟수. */
     get maxRestarts(): number;
+    /** @returns {number} crash 교체 판정 슬라이딩 윈도우(ms). `static restartWindowMs` 로 조정. */
+    get restartWindowMs(): number;
     /** @returns {boolean} start() 후 stop() 전이면 true. */
     get isStarted(): boolean;
     /** @param {'dispatch'|'done'|'fail'|'crash'|'stopped'} event @param {(payload: any) => void} listener @returns {this} */

package/types/lib/ws-hub.d.ts

@@ -69,11 +69,12 @@ export class MegaWsHub {
     _wss: WebSocketServer | null;
     /** heartbeat liveness 체크 interval (M3). @type {ReturnType<typeof setInterval> | null} */
     _livenessTimer: ReturnType<typeof setInterval> | null;
-    /** 등록된 bridge 연결. connId → { socket, lastSeen, protocolVersion }. @type {Map<string, { socket: import('ws').WebSocket, lastSeen: number, protocolVersion?: number }>} */
+    /** 등록된 bridge 연결. connId → { socket, lastSeen, protocolVersion, presenceFanout }. @type {Map<string, { socket: import('ws').WebSocket, lastSeen: number, protocolVersion?: number, presenceFanout?: boolean }>} */
     _bridges: Map<string, {
         socket: import("ws").WebSocket;
         lastSeen: number;
         protocolVersion?: number;
+        presenceFanout?: boolean;
     }>;
     /** presence. sessionId → { bridgeConnId, userId, channels:Set, metadata }. @type {Map<string, { bridgeConnId: string, userId: string, channels: Set<string>, metadata: Object }>} */
     _sessions: Map<string, {
@@ -86,6 +87,13 @@ export class MegaWsHub {
     _channelSessions: Map<string, Set<string>>;
     /** userId → sessionId 집합 (DIRECT fan-out, ADR-035). @type {Map<string, Set<string>>} */
     _userSessions: Map<string, Set<string>>;
+    /**
+     * 역인덱스: channel → (bridgeConnId → 그 bridge 의 채널 내 세션 수). BROADCAST 의 bridge 선정을
+     * 세션 수 무관 O(bridge 수)로 만든다 — 멤버 10k 채널에서 메시지당 수백 µs 가 µs 대로 떨어진다.
+     * `_addSession`/`_removeSession` 이 증분 유지(카운트 0 → 키 제거), 메모리는 채널×bridge 수준.
+     * @type {Map<string, Map<string, number>>}
+     */
+    _channelBridges: Map<string, Map<string, number>>;
     /** hub 식별자. */
     get hubId(): string;
     /** 등록된 bridge 수 (테스트/관측용). */
@@ -148,6 +156,12 @@ export class MegaWsHub {
      * @private
      */
     private _addSession;
+    /**
+     * channel→bridge 역인덱스 증분 갱신. 카운트가 0 이 되면 키를 지워 인덱스가 stale 하지 않게 한다.
+     * @param {string} channel @param {string} connId @param {1|-1} delta
+     * @private
+     */
+    private _bumpChannelBridge;
     /**
      * presence 에서 세션 제거. 빈 인덱스는 정리.
      * @param {string} sessionId
@@ -162,12 +176,23 @@ export class MegaWsHub {
      */
     private _handleBridgeGone;
     /**
-     * origin 을 제외한 모든 등록 bridge 로 송신 (presence 공유용). envelope 는 1회만 직렬화(L5).
+     * origin 을 제외한 모든 등록 bridge 로 송신. envelope 는 1회만 직렬화(L5).
+     * BULK_LEAVE(bridge-gone 정리 통지)처럼 전 bridge 가 받아야 하는 통지에 쓴다.
      * @param {string} exceptConnId
      * @param {Object} envelope
      * @private
      */
     private _fanOutToOthers;
+    /**
+     * presence(JOIN/LEAVE/METADATA) fan-out — `presence-fanout` capability 를 선언한 bridge 에만 송신.
+     * roster 가 redis 로 분리(ADR-177)된 뒤 표준 bridge 는 이 타입들을 no-op 으로 버리므로, 옵트인하지
+     * 않은 bridge 에는 보내지 않는다 — 세션 churn × bridge 수 만큼의 죽은 프레임을 제거한다.
+     * 구버전 bridge 호환: hub presence 를 실제로 쓰려는 bridge 는 capability 로 명시 선언한다.
+     * @param {string} exceptConnId
+     * @param {Object} envelope
+     * @private
+     */
+    private _fanOutPresence;
     /**
      * 한 채널의 세션을 가진 bridge 들로 fan-out (origin 제외, 중복 bridge 1회). 직렬화 1회(L5).
      *