mega-framework 0.1.6 → 0.1.7

package/src/core/ws-upgrade.js

@@ -25,7 +25,7 @@
  *
  * @module core/ws-upgrade
  */
-import { createWsMessage, parseWsMessage, generateMessageId, WS_TYPE_PATTERN } from './ws-message.js'
+import { createWsMessage, parseWsMessage, generateMessageId, WS_TYPE_PATTERN, WS_PROTOCOL_VERSION } 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'
@@ -49,9 +49,50 @@ 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 = 16 * 1024 * 1024
 
+/**
+ * 클라↔bridge ping/pong liveness 기본 주기(ms) — 30초. 주기마다 ping 을 보내고 직전 주기의 pong 이
+ * 없으면 half-open(상대 사망·네트워크 단절) 으로 보고 terminate 한다 — 좀비 연결이 OS TCP 타임아웃까지
+ * `_wsConns`/roster 에 잔존하는 것을 막는다. 라우트 `opts.heartbeatMs` 로 조정, `0` = 끔.
+ */
+export const DEFAULT_WS_HEARTBEAT_MS = 30_000
+
+/**
+ * onConnect 완료 전 도착한 프레임의 대기 큐 상한 — 초과 시 연결 종료(1013). onConnect 가 느릴 때
+ * 악의적/과속 클라이언트가 큐로 메모리를 채우는 것을 막는다.
+ */
+export const MAX_PENDING_FRAMES_BEFORE_CONNECT = 256
+
+/**
+ * 라우트 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, log) {
+  const v = opts?.heartbeatMs
+  if (v === undefined || v === null) return DEFAULT_WS_HEARTBEAT_MS
+  if (typeof v !== 'number' || !Number.isInteger(v) || v < 0) {
+    log?.warn?.({ heartbeatMs: v }, `ws route opts.heartbeatMs is invalid (integer >= 0 expected) — using default ${DEFAULT_WS_HEARTBEAT_MS}ms`)
+    return DEFAULT_WS_HEARTBEAT_MS
+  }
+  return v
+}
+
 /**
  * WS 프레임 코덱 — 평문/암호 와이어 변환을 추상화한다.
  * @typedef {Object} WsFrameCodec
@@ -122,6 +163,8 @@ export class MegaWsConnection {
     this.channels = null
     /** @type {Object|undefined} joinSession/updateMetadata 로 저장한 presence 메타(재연결 재동기화에 보존, M-1). */
     this.metadata = undefined
+    /** @type {number} 협상된 envelope 프로토콜 버전(기본 v1) — driveWsConnection 이 핸드셰이크 결과로 설정. */
+    this.protocolVersion = 1
   }
 
   /** 하위 raw `ws` WebSocket (escape hatch — 바이너리/직접 제어용). */
@@ -234,10 +277,15 @@ function buildWsPresence(app, conn, ns) {
  * @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 = null }) {
+export function driveWsConnection({ raw, req, route, app, codec, log, auth = null, protocolVersion = WS_PROTOCOL_VERSION }) {
   const conn = new MegaWsConnection(raw, codec, { ns: route.ns, path: route.path })
+  // 협상된 envelope 버전 — 이 연결의 검증 기준이자 v2 도입 시 코덱/검증 분기의 기준점.
+  conn.protocolVersion = protocolVersion
   // ChannelClass 는 부팅 시 MegaWebSocketController 상속 검증됨 (router.ws). 여기선 인스턴스화만.
   const channel = /** @type {import('./ws-controller.js').MegaWebSocketController} */ (
     new (/** @type {any} */ (route.ChannelClass))()
@@ -256,6 +304,7 @@ export function driveWsConnection({ raw, req, route, app, codec, log, auth = nul
     path: route.path,
     req,
     connId: conn.id,
+    protocolVersion, // 협상된 envelope 버전(v1 기본) — 채널이 버전별 동작을 분기할 때 사용.
     tracer: MegaTracing.tracer, // ctx.tracer.span(name, fn) — WS 핸들러에서도 사용자 직접 span(ADR-126).
     // presence 단축 API (ADR-176) — list(클러스터 roster)/join/directToUser/broadcast 를 ns·conn 바인딩으로
     // 노출. 클러스터 동기화는 wsCluster 가 처리하므로 채널은 비즈니스 로직만 쓴다. mock app 이면 null.
@@ -270,29 +319,86 @@ export function driveWsConnection({ raw, req, route, app, codec, log, auth = nul
 
   log.debug?.({ connId: conn.id, path: route.path, ns: route.ns }, 'ws.connect enter')
 
+  // type 별 payload 스키마 검증 함수 맵 (M2, router.ws 에서 사전 컴파일). 없으면 검증 없음.
+  const schemaValidators = route.schemaValidators ?? null
+
+  /** 프레임 1건 처리 시작 — fire-and-forget(각 메시지 독립 async 흐름). @param {string} frame */
+  const processFrame = (frame) => {
+    // 최외곽 가드 (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')
+    })
+  }
+
+  // onConnect 완료 전 도착한 프레임은 큐에 보관했다가 완료 후 도착 순서대로 처리한다 — 'message' 리스너는
+  // 동기 부착되고 onConnect 는 비동기라, 빠른 클라이언트의 첫 메시지가 채널 초기화(joinSession 등) 전에
+  // 디스패치되는 race 를 막는다. onConnect 실패 시 연결이 닫히므로 큐는 버린다.
+  let isConnectSettled = false
+  /** @type {string[]} */
+  let pendingFrames = []
+
   // onConnect — 실패 시 fail-closed. 복호화와 무관한 서버 내부 오류이므로 1011 (M3). silent 금지.
   Promise.resolve()
     .then(() => channel.onConnect(conn, ctx))
+    .then(() => {
+      isConnectSettled = true
+      const queued = pendingFrames
+      pendingFrames = []
+      for (const frame of queued) processFrame(frame)
+    })
     .catch((err) => {
       log.error?.({ err, connId: conn.id }, 'ws.onConnect threw — closing (1011)')
+      pendingFrames = [] // 연결이 닫히므로 대기 프레임은 처리하지 않는다.
       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')
-    })
+    if (!isConnectSettled) {
+      if (pendingFrames.length >= MAX_PENDING_FRAMES_BEFORE_CONNECT) {
+        // onConnect 가 끝나기 전에 큐 상한 도달 — 더 쌓으면 메모리 abuse 라 연결을 닫는다(1013).
+        log.warn?.({ connId: conn.id, queued: pendingFrames.length }, 'ws pre-connect frame queue overflow — closing (1013)')
+        pendingFrames = []
+        if (conn.isOpen) conn.close(CLOSE_CODE_SLOW_CONSUMER, 'pre-connect queue overflow')
+        return
+      }
+      pendingFrames.push(frame)
+      return
+    }
+    processFrame(frame)
   })
 
+  // liveness(ping/pong): 주기마다 ping 을 보내고 직전 주기의 pong 이 없으면 half-open 으로 보고
+  // terminate 한다 — 'close' 이벤트가 onDisconnect/untrack 정리를 그대로 트리거한다. opts.heartbeatMs=0 으로 끔.
+  const heartbeatMs = resolveWsHeartbeatMs(/** @type {any} */ (route.opts), log)
+  if (heartbeatMs > 0) {
+    let isAlive = true
+    raw.on('pong', () => {
+      isAlive = true
+    })
+    const pingTimer = setInterval(() => {
+      if (raw.readyState !== 1) return // 닫히는 중 — 'close' 가 곧 타이머를 정리한다.
+      if (!isAlive) {
+        log.warn?.({ connId: conn.id, heartbeatMs }, 'ws heartbeat timeout — terminating half-open connection')
+        raw.terminate()
+        return
+      }
+      isAlive = false
+      try {
+        raw.ping()
+      } catch (err) {
+        // 소켓이 닫히는 중이면 ping 실패 — 비치명적, close 가 뒤따른다 (이유+로그).
+        log.debug?.({ err, connId: conn.id }, 'ws ping send failed (socket closing)')
+      }
+    }, heartbeatMs)
+    if (typeof pingTimer.unref === 'function') pingTimer.unref()
+    raw.on('close', () => clearInterval(pingTimer))
+  }
+
   raw.on('close', (code, reasonBuf) => {
     app._untrackWsConn?.(conn)
     const reason = Buffer.isBuffer(reasonBuf) ? reasonBuf.toString('utf8') : String(reasonBuf ?? '')
@@ -396,11 +502,11 @@ async function handleIncoming({ conn, channel, codec, ctx, raw, frame, schemaVal
     return
   }
 
-  // 2) envelope 파싱 + 검증. 실패 → error envelope 응답(연결 유지 — 비치명적).
+  // 2) envelope 파싱 + 검증 — 이 연결에서 협상된 버전 기준. 실패 → error envelope 응답(연결 유지 — 비치명적).
   /** @type {{ type: string, id: string }} */
   let msg
   try {
-    msg = /** @type {{ type: string, id: string }} */ (parseWsMessage(plain))
+    msg = /** @type {{ type: string, id: string }} */ (parseWsMessage(plain, { version: conn.protocolVersion }))
   } catch (err) {
     log.warn?.({ err, connId: conn.id }, 'ws invalid envelope')
     if (conn.isOpen) {

package/src/index.js

@@ -115,7 +115,7 @@ export { MegaAspDecryptError, ASP_RULES } from './lib/asp/errors.js'
 export { normalizeAspConfig } from './lib/asp/config.js'
 
 // Bridge ↔ Hub 12-타입 프로토콜 (ADR-033/059/097)
-export { MegaWsHub, DEFAULT_HEARTBEAT_MS, runWsHubCli } from './cli/ws-hub.js'
+export { MegaWsHub, DEFAULT_HEARTBEAT_MS, runWsHubCli } from './lib/ws-hub.js'
 export { MegaHubLink } from './core/hub-link.js'
 // WS per-message deflate 압축 (ADR-078)
 export { buildPerMessageDeflate, checkCompressionConfig, COMPRESSION_DEFAULTS } from './core/ws-compression.js'

package/src/lib/hub-protocol.js

@@ -61,6 +61,30 @@ export const HUB_MESSAGE_TYPES = Object.freeze({
 /** 12 개 wire `type` 문자열 집합 (빠른 소속 판별용). @type {ReadonlySet<string>} */
 export const HUB_TYPE_SET = new Set(Object.values(HUB_MESSAGE_TYPES))
 
+/** bridge↔hub 프로토콜 현 버전. REGISTER/REGISTER_OK 의 `protocolVersion` 협상 기준(부재 = v1). */
+export const HUB_PROTOCOL_VERSION = 1
+
+/**
+ * 이 측이 지원하는 bridge↔hub 프로토콜 버전 목록. 버전은 선형 누적 계약 — vN 지원 = v1..vN 전부 지원.
+ * @type {ReadonlyArray<number>}
+ */
+export const SUPPORTED_HUB_PROTOCOL_VERSIONS = Object.freeze([HUB_PROTOCOL_VERSION])
+
+/**
+ * bridge 가 REGISTER 로 보낸 최대 지원 버전과 hub 지원 버전의 상호 최고 버전을 고른다.
+ * 선형 누적 계약(vN 지원 = v1..vN 지원)이라 `min(bridgeMax, hubMax)` 가 항상 유효한 상호 버전이다
+ * (v1 이 바닥이라 협상이 실패할 수 없다 — 부재/무효 입력은 v1).
+ *
+ * @param {unknown} requestedMax - bridge 의 `protocolVersion`(최대 지원 버전).
+ * @param {ReadonlyArray<number>} [supported] - 이 측 지원 버전 목록.
+ * @returns {number} 협상된 버전(>= 1).
+ */
+export function negotiateHubProtocolVersion(requestedMax, supported = SUPPORTED_HUB_PROTOCOL_VERSIONS) {
+  const ourMax = Math.max(...supported)
+  if (!Number.isInteger(requestedMax) || /** @type {number} */ (requestedMax) < 1) return HUB_PROTOCOL_VERSION
+  return Math.min(/** @type {number} */ (requestedMax), ourMax)
+}
+
 /**
  * bridge↔hub WebSocket close code 카탈로그 (ADR-098).
  *
@@ -107,6 +131,8 @@ export const HUB_PAYLOAD_SCHEMAS = Object.freeze({
       instanceId: { type: 'string', minLength: 1 },
       token: { type: 'string', minLength: 1 },
       capabilities: { type: 'array', items: { type: 'string' } },
+      // 버전 협상(옵션): bridge 의 최대 지원 버전. 부재 = v1(레거시 bridge — 협상 없이 v1 고정).
+      protocolVersion: { type: 'integer', minimum: 1 },
     },
     additionalProperties: false,
   },
@@ -117,6 +143,9 @@ export const HUB_PAYLOAD_SCHEMAS = Object.freeze({
       hubId: { type: 'string', minLength: 1 },
       acceptedAt: { type: 'integer' },
       heartbeatMs: { type: 'integer', minimum: 1 },
+      // 버전 협상 결과(옵션): hub 가 채택한 버전. bridge 가 REGISTER 에 protocolVersion 을 실었을
+      // 때만 회신(echo-on-request) — 레거시 bridge(strict 스키마)가 모르는 필드를 받지 않게 한다.
+      protocolVersion: { type: 'integer', minimum: 1 },
     },
     additionalProperties: false,
   },

package/src/lib/mega-health.js

@@ -19,21 +19,30 @@
 
 import { MegaShutdown } from './mega-shutdown.js'
 
+/** 체크 1개의 기본 타임아웃(ms) — hung 체크가 readiness 응답을 무기한 막지 않게 한다. */
+export const DEFAULT_CHECK_TIMEOUT_MS = 5_000
+
+/** @type {Map<string, { fn: Function, timeoutMs: number }>} */
 const checks = new Map()
 
 /**
  * 헬스 체크 등록.
  * @param {string} name
  * @param {() => Promise<{ ok: boolean, [key: string]: any }> | { ok: boolean }} fn
+ * @param {{ timeoutMs?: number }} [opts] - 체크별 타임아웃(양의 정수 ms, 기본 {@link DEFAULT_CHECK_TIMEOUT_MS}).
  */
-export function register(name, fn) {
+export function register(name, fn, opts = {}) {
   if (typeof name !== 'string' || name.length === 0) {
     throw new Error('MegaHealth.register: name is required (string)')
   }
   if (typeof fn !== 'function') {
     throw new Error('MegaHealth.register: fn must be a function')
   }
-  checks.set(name, fn)
+  const timeoutMs =
+    Number.isInteger(opts.timeoutMs) && /** @type {number} */ (opts.timeoutMs) > 0
+      ? /** @type {number} */ (opts.timeoutMs)
+      : DEFAULT_CHECK_TIMEOUT_MS
+  checks.set(name, { fn, timeoutMs })
 }
 
 /**
@@ -48,12 +57,24 @@ export async function checkAll() {
 
   const entries = [...checks.entries()]
   const results = await Promise.all(
-    entries.map(async ([name, fn]) => {
+    entries.map(async ([name, { fn, timeoutMs }]) => {
+      /** @type {NodeJS.Timeout | undefined} */
+      let timer
       try {
-        const result = await fn()
+        // 체크별 race — hung 체크 1개가 readiness 전체를 무기한 막지 않게 timeoutMs 에서 끊는다
+        // (probe timeout 으로 인한 연쇄 재시작 방지). 타임아웃은 해당 체크만 ok:false 처리.
+        const result = await Promise.race([
+          Promise.resolve(fn()),
+          new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`health check timed out after ${timeoutMs}ms`)), timeoutMs)
+            timer.unref?.()
+          }),
+        ])
         return [name, result?.ok === true ? result : { ok: false, ...result }]
       } catch (err) {
         return [name, { ok: false, error: err?.message ?? String(err) }]
+      } finally {
+        clearTimeout(timer)
       }
     }),
   )

package/src/lib/mega-job-queue.js

@@ -43,7 +43,7 @@
  */
 import { EventEmitter } from 'node:events'
 import { MegaConfigError } from '../errors/config-error.js'
-import { MegaJob, resolveJobRetryConfig } from './mega-job.js'
+import { MegaJob, resolveJobRetryConfig, resolveJobRunTimeoutMs } from './mega-job.js'
 import { withRetry } from './mega-retry.js'
 
 /** 잡 큐가 노출하는 이벤트 화이트리스트(오타 차단 + 문서화 — 형제 클래스와 동일 정책). */
@@ -52,7 +52,7 @@ const KNOWN_EVENTS = Object.freeze([
   'start', // 메시지 처리 시작
   'done', // 처리 성공 + ack — event.result
   'retry', // 재시도 1회 실패(다음 시도 전) — event.attempt/retriesLeft/error
-  'fail', // 최종 실패 — event.phase('run'|'decode'|'dlq-publish'|'max-deliver'|'consume-loop')/error
+  'fail', // 최종 실패 — event.phase('run'|'decode'|'dlq-publish'|'dlq-orphan'|'max-deliver'|'consume-loop'|'abandoned-run')/error
   'dlq', // DLQ 라우팅 완료 — event.dlqSubject
 ])
 
@@ -62,6 +62,15 @@ const NOT_FOUND_CODE = '404'
 /** DLQ 스트림 `max_age` 디폴트(ms) — 7일. 무한 적재 방지(ADR-134). `dlqMaxAgeMs: 0` 으로 끌 수 있다. */
 export const DEFAULT_DLQ_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
 
+/**
+ * run 전체(재시도 포함) 실행 상한 디폴트(ms) — 30분. 행(hang)된 run 이 `working()` lease 를 영원히
+ * 갱신하며 메시지를 영구 점유하는 것을 막는 backstop. 잡별 `static timeoutMs` 로 override, `0` = 무제한.
+ */
+export const DEFAULT_RUN_TIMEOUT_MS = 30 * 60 * 1000
+
+/** DLQ publish 실패 nak 재전달 지연 상한(ms) — 즉시 재전달 핫 루프 방지(점증 지연의 cap). */
+const NAK_DELAY_MAX_MS = 30_000
+
 /** DLQ 봉투에 싣는 error.stack 최대 길이(자) — poison 잡 폭주 시 DLQ 비대 방지(Med). */
 const DLQ_MAX_STACK_LEN = 4000
 
@@ -88,6 +97,10 @@ function truncateStack(stack) {
  *   스트림 생성 시에만** 적용(멱등 — 기존 스트림은 운영자가 NATS CLI 로 갱신).
  * @property {number} [dlqMaxBytes] - DLQ 스트림 최대 크기(bytes). 미지정이면 byte 상한 없음(`max_age` 가
  *   주 가드). 디스크 상한이 필요한 운영 환경에서만 지정.
+ * @property {number} [runTimeoutMs=1800000] - run 전체(재시도 포함) 실행 상한 디폴트(ms, 기본 30분).
+ *   초과 시 잡을 실패로 판정해 DLQ 라우팅 — 행 잡이 `working()` lease 를 영구 갱신하며 메시지를 점유하는
+ *   것을 막는다. 잡별 `static timeoutMs` 가 우선, `0` = 무제한. ⚠️ 타임아웃돼도 진행 중 run 은 중단되지
+ *   않는다(백그라운드 계속 — run 멱등 설계 필요). 나중 실패는 fail(abandoned-run) 으로 표면화.
  */
 
 /**
@@ -116,6 +129,7 @@ export class MegaJobQueue extends EventEmitter {
   /** @type {string} */ #streamPrefix
   /** @type {number} DLQ max_age(ms). 0 = 무제한. */ #dlqMaxAgeMs
   /** @type {number|undefined} DLQ max_bytes. undefined = 무제한. */ #dlqMaxBytes
+  /** @type {number} run 전체 실행 상한 디폴트(ms). 0 = 무제한. 잡별 static timeoutMs 가 우선. */ #runTimeoutMs
   /** @type {typeof import('nats')|null} 지연 로드된 nats 모듈(enum/codec/nanos). */ #nats = null
   /** @type {import('nats').Codec<any>|null} */ #codec = null
   /** @type {import('nats').JetStreamClient|null} */ #js = null
@@ -126,7 +140,7 @@ export class MegaJobQueue extends EventEmitter {
    * @param {MegaJobQueueOptions} options
    * @throws {TypeError} nc 가 JetStream 가능한 NatsConnection 이 아니면(fail-fast).
    */
-  constructor({ nc, ackWaitMs = 30_000, maxDeliver = 5, heartbeatMs, streamPrefix = 'MEGA_JOBS', dlqMaxAgeMs = DEFAULT_DLQ_MAX_AGE_MS, dlqMaxBytes } = /** @type {any} */ ({})) {
+  constructor({ nc, ackWaitMs = 30_000, maxDeliver = 5, heartbeatMs, streamPrefix = 'MEGA_JOBS', dlqMaxAgeMs = DEFAULT_DLQ_MAX_AGE_MS, dlqMaxBytes, runTimeoutMs = DEFAULT_RUN_TIMEOUT_MS } = /** @type {any} */ ({})) {
     super()
     if (!nc || typeof nc.jetstream !== 'function' || typeof nc.jetstreamManager !== 'function') {
       throw new TypeError(
@@ -146,6 +160,10 @@ export class MegaJobQueue extends EventEmitter {
     if (dlqMaxBytes !== undefined && (typeof dlqMaxBytes !== 'number' || !Number.isInteger(dlqMaxBytes) || dlqMaxBytes < 1)) {
       throw new TypeError(`MegaJobQueue: dlqMaxBytes must be an integer >= 1 when set. Got: ${dlqMaxBytes}.`)
     }
+    // runTimeoutMs: 0 = 무제한(끔). 음수/비정수는 운영 실수라 fail-fast(silent 보정 X).
+    if (typeof runTimeoutMs !== 'number' || !Number.isInteger(runTimeoutMs) || runTimeoutMs < 0) {
+      throw new TypeError(`MegaJobQueue: runTimeoutMs must be an integer >= 0 (0 = unlimited). Got: ${runTimeoutMs}.`)
+    }
     this.#nc = nc
     this.#ackWaitMs = ackWaitMs
     this.#maxDeliver = maxDeliver
@@ -153,6 +171,7 @@ export class MegaJobQueue extends EventEmitter {
     this.#streamPrefix = streamPrefix
     this.#dlqMaxAgeMs = dlqMaxAgeMs
     this.#dlqMaxBytes = dlqMaxBytes
+    this.#runTimeoutMs = runTimeoutMs
   }
 
   // ── 이벤트 화이트리스트(L-1 정책 — 형제 클래스와 동일) ────────────────────
@@ -416,6 +435,7 @@ export class MegaJobQueue extends EventEmitter {
     const durable = this.#durableName(subject)
     const concurrency = this.#resolveConcurrency(JobClass) // L-1: 양의 정수 fail-fast(max_ack_pending=0 풋건 차단).
     const retryConfig = resolveJobRetryConfig(JobClass)
+    const runTimeoutMs = resolveJobRunTimeoutMs(JobClass, this.#runTimeoutMs) // 행 잡 영구 점유 backstop.
     await this.#ensureConsumer(stream, durable, subject, concurrency)
 
     const js = /** @type {import('nats').JetStreamClient} */ (this.#js)
@@ -426,7 +446,7 @@ export class MegaJobQueue extends EventEmitter {
     const inFlight = new Set()
     const loop = (async () => {
       for await (const msg of messages) {
-        const p = this._handleMessage(instance, ctx, msg, retryConfig, subject).finally(() =>
+        const p = this._handleMessage(instance, ctx, msg, retryConfig, subject, runTimeoutMs).finally(() =>
           inFlight.delete(p),
         )
         inFlight.add(p)
@@ -464,9 +484,10 @@ export class MegaJobQueue extends EventEmitter {
    *
    * @param {MegaJob} instance @param {Record<string, any>} ctx @param {import('nats').JsMsg} msg
    * @param {ReturnType<typeof resolveJobRetryConfig>} retryConfig @param {string} subject
+   * @param {number} [runTimeoutMs] - run 전체(재시도 포함) 상한(ms). 미지정 시 큐 디폴트, 0 = 무제한.
    * @returns {Promise<MegaJobHandleResult>}
    */
-  async _handleMessage(instance, ctx, msg, retryConfig, subject) {
+  async _handleMessage(instance, ctx, msg, retryConfig, subject, runTimeoutMs = this.#runTimeoutMs) {
     const seq = msg.seq
 
     // M-1(ADR-119 hardening): 이번 전달이 max_deliver 에 도달했고(deliveryCount >= maxDeliver)
@@ -520,8 +541,14 @@ export class MegaJobQueue extends EventEmitter {
     let runResult
     /** @type {Error|null} run 최종 실패 사유(성공이면 null). */
     let runError = null
+    /** @type {NodeJS.Timeout|undefined} run 타임아웃 타이머(있으면 finally 에서 정리). */
+    let timeoutHandle
+    /** @type {boolean} 타임아웃이 race 를 이겼는지(버려진 run 의 잔여 실패 표면화 분기용). */
+    let timedOut = false
+    /** @type {Promise<any>|undefined} run(재시도) Promise — 타임아웃 시 잔여 실패 관찰에 필요. */
+    let runPromise
     try {
-      runResult = await withRetry(() => instance.run(payload, ctx), {
+      runPromise = withRetry(() => instance.run(payload, ctx), {
         ...retryConfig,
         onFailedAttempt: (info) => {
           this.#safeEmit('retry', {
@@ -533,11 +560,44 @@ export class MegaJobQueue extends EventEmitter {
           })
         },
       })
+      if (runTimeoutMs > 0) {
+        // 행(hang) 잡 backstop: run 전체(재시도 포함)에 상한을 건다. 상한 초과 = 실패 판정 → DLQ.
+        // 없으면 working() 하트비트가 lease 를 영원히 갱신해 메시지가 재전달도 DLQ 도 못 가는
+        // 영구 점유가 된다(프로세스 사망 시에만 해소).
+        runResult = await Promise.race([
+          runPromise,
+          new Promise((_resolve, reject) => {
+            timeoutHandle = setTimeout(() => {
+              timedOut = true
+              reject(new Error(
+                `MegaJobQueue: job on '${subject}' exceeded run timeout (${runTimeoutMs}ms) — treating as ` +
+                  `failed (run continues in background; design run to be idempotent).`,
+              ))
+            }, runTimeoutMs)
+            if (typeof timeoutHandle.unref === 'function') timeoutHandle.unref()
+          }),
+        ])
+      } else {
+        runResult = await runPromise
+      }
     } catch (err) {
       runError = err instanceof Error ? err : new Error(String(err))
+      if (timedOut && runPromise) {
+        // 버려진(타임아웃 패배) run 의 나중 실패를 묵히지 않고 표면화한다 — 잡은 이미 실패 판정·DLQ
+        // 라우팅됐으므로 처리 흐름엔 영향 없다(reject 자체는 race 가 구독해 unhandledRejection 아님).
+        runPromise.catch((lateErr) => {
+          this.#safeEmit('fail', {
+            subject,
+            seq,
+            error: lateErr instanceof Error ? lateErr : new Error(String(lateErr)),
+            phase: 'abandoned-run',
+          })
+        })
+      }
     } finally {
       settled = true
       clearInterval(heartbeat)
+      if (timeoutHandle !== undefined) clearTimeout(timeoutHandle)
     }
 
     if (runError === null) {
@@ -552,30 +612,47 @@ export class MegaJobQueue extends EventEmitter {
   }
 
   /**
-   * DLQ 라우팅 — 실패 페이로드+에러 메타를 `<subject>.dlq` 로 발행하고 원본을 ack. 발행 실패 시 ack 하지
-   * 않고 nak 해 잡을 보존한다(at-least-once). 본 메서드도 throw 하지 않는다.
+   * DLQ 라우팅 — 실패 페이로드+에러 메타를 `<subject>.dlq` 로 발행하고 원본을 ack. 발행은 인프로세스로
+   * 짧게 재시도(일시 장애 흡수)하고, 그래도 실패하면 ack 하지 않고 **점증 지연 nak** 해 잡을 보존한다
+   * (at-least-once — 즉시 재전달 핫 루프 방지). 단 이번 전달이 `max_deliver` 의 **마지막 전달**이면 nak 해도
+   * 재전달이 없어 메시지가 워크 스트림에 orphan 으로 남는다 — 이때는 un-ack 보존 + `fail(dlq-orphan)` 으로
+   * 운영자 개입을 명시 표면화한다(ack/term 으로 잡을 지우면 유실이라 하지 않는다). 본 메서드도 throw 하지 않는다.
    * @param {string} subject @param {any} payload @param {Error} error @param {import('nats').JsMsg} msg @param {number} seq @returns {Promise<void>}
    */
   async #routeToDlq(subject, payload, error, msg, seq) {
     const dlqSubject = `${subject}.dlq`
     const js = /** @type {import('nats').JetStreamClient} */ (this.#js)
     try {
-      await js.publish(
-        dlqSubject,
-        this.#encode({
-          originalSubject: subject,
-          failedAt: new Date().toISOString(),
-          deliveryCount: msg.info.deliveryCount,
-          // stack 전체를 봉투에 담으면 poison 잡 폭주 시 DLQ 직렬화 비용·디스크가 급증한다 → 상한으로 truncate(Med).
-          error: { name: error.name, message: error.message, stack: truncateStack(error.stack) },
-          payload,
-        }),
+      // DLQ publish 자체를 짧게 재시도(추가 2회, 250ms→1s) — 일시적 NATS 응답 지연/재연결 틈을 흡수해
+      // nak 재전달(전체 인프로세스 재시도 사이클 반복)보다 훨씬 싸게 orphan 확률을 줄인다.
+      await withRetry(
+        () =>
+          js.publish(
+            dlqSubject,
+            this.#encode({
+              originalSubject: subject,
+              failedAt: new Date().toISOString(),
+              deliveryCount: msg.info.deliveryCount,
+              // stack 전체를 봉투에 담으면 poison 잡 폭주 시 DLQ 직렬화 비용·디스크가 급증한다 → 상한으로 truncate(Med).
+              error: { name: error.name, message: error.message, stack: truncateStack(error.stack) },
+              payload,
+            }),
+          ),
+        { retries: 2, minTimeout: 250, maxTimeout: 1000, factor: 2, jitter: true },
       )
     } catch (pubErr) {
-      // DLQ 발행 실패 → ack 안 함(보존). nak 으로 재전달 요청 → DLQ 백엔드 회복 후 재시도(안 묻음).
       const e = pubErr instanceof Error ? pubErr : new Error(String(pubErr))
-      msg.nak() // 부작용(nak) 먼저 확정 — emit 보다 앞선다(M-3: 리스너 throw 가 보존 결정을 막지 않게).
-      this.#safeEmit('fail', { subject, seq, error: e, phase: 'dlq-publish' })
+      if (msg.info.deliveryCount >= this.#maxDeliver) {
+        // 마지막 전달 — nak 해도 JetStream 이 더는 재전달하지 않는다. ack/term 하면 잡이 사라지므로
+        // un-ack 로 워크 스트림에 보존하고(운영자가 NATS CLI 로 수습 가능), orphan 을 크게 표면화한다.
+        this.#safeEmit('fail', { subject, seq, error: e, phase: 'dlq-orphan' })
+        return
+      }
+      // DLQ 발행 실패 → ack 안 함(보존). 점증 지연 nak — 즉시 재전달이면 DLQ 백엔드 장애 동안
+      // 재전달→재시도 사이클 전체가 타이트하게 도는 핫 루프가 된다(deliveryCount 기반 지수 지연).
+      const nakDelayMs = Math.min(NAK_DELAY_MAX_MS, 1000 * 2 ** (msg.info.deliveryCount - 1))
+      msg.nak(nakDelayMs) // 부작용(nak) 먼저 확정 — emit 보다 앞선다(M-3: 리스너 throw 가 보존 결정을 막지 않게).
+      this.#safeEmit('fail', { subject, seq, error: e, phase: 'dlq-publish', nakDelayMs })
       return
     }
     msg.ack() // DLQ 에 안전히 보관됨 → 워크 메시지 제거(emit 보다 먼저 확정).

package/src/lib/mega-job.js

@@ -23,6 +23,7 @@
  *   - `static concurrency` : 동시에 처리할 메시지 수(consumer `max_ack_pending`). 기본 1(순차·안전).
  *   - `static retries`     : run 실패 시 **추가** 재시도 횟수(첫 시도 제외). 기본 3.
  *   - `static backoff`     : `{ type:'exponential', initial, max }`. p-retry 로 매핑(factor=2, jitter=on).
+ *   - `static timeoutMs`   : run 전체(재시도 포함) 상한(ms). 미지정 시 큐 디폴트, `0` = 무제한.
  *
  * @module lib/mega-job
  * @see ADR-119, ADR-028 (잡·스케줄러·워커 3종 분리), ADR-029 (라이브러리 래핑)
@@ -81,6 +82,15 @@ export class MegaJob {
   /** @type {MegaJobBackoff} 지수 백오프 설정. 기본 { exponential, 1s, 30s }(OQ-012). */
   static backoff = JOB_RETRY_DEFAULTS.backoff
 
+  /**
+   * @type {number|undefined} run 전체(재시도 포함) 실행 상한(ms). 초과 시 큐가 잡을 실패로 판정해 DLQ 로
+   *   보낸다 — 행(hang)된 run 이 `working()` lease 를 영원히 갱신하며 메시지를 영구 점유하는 것을 막는다.
+   *   미지정 시 {@link import('./mega-job-queue.js').MegaJobQueue} 의 `runTimeoutMs`(기본 30분), `0` = 무제한.
+   *   ⚠️ 타임아웃돼도 진행 중이던 run 은 JS 특성상 중단되지 않는다(백그라운드 계속) — run 은 멱등하게
+   *   설계해야 한다(at-least-once, 모듈 docstring).
+   */
+  static timeoutMs = undefined
+
   /**
    * 메시지 1건마다 실행되는 본문. 서브클래스가 **반드시** 구현한다. throw 하면 {@link MegaJobQueue}
    * 가 재시도하고, 재시도 소진 시 DLQ 로 보낸다 — 그러므로 비치명/일시 오류는 그냥 throw 하면 된다.
@@ -138,3 +148,22 @@ export function resolveJobRetryConfig(JobClass) {
   // factor=2(exponential), jitter=on — OQ-012 정합. MegaRetry 가 첫 시도 즉시 + 이후 지수 백오프.
   return { retries, minTimeout: initial, maxTimeout: max, factor: 2, jitter: true }
 }
+
+/**
+ * 잡 클래스의 `static timeoutMs` 를 검증해 반환한다. 미지정(undefined/null)이면 `defaultMs`(큐 디폴트),
+ * `0` = 무제한. 음수/비정수는 운영 실수라 fail-fast(silent 보정 금지).
+ *
+ * @param {typeof MegaJob} JobClass - 잡 클래스.
+ * @param {number} defaultMs - 큐 레벨 디폴트(ms, 0 = 무제한).
+ * @returns {number} 적용할 타임아웃(ms). 0 = 무제한.
+ * @throws {TypeError} timeoutMs 가 0 이상 정수가 아닐 때.
+ */
+export function resolveJobRunTimeoutMs(JobClass, defaultMs) {
+  const timeoutMs = JobClass.timeoutMs ?? defaultMs
+  if (typeof timeoutMs !== 'number' || !Number.isInteger(timeoutMs) || timeoutMs < 0) {
+    throw new TypeError(
+      `MegaJob '${JobClass.name}': static timeoutMs must be an integer >= 0 (0 = unlimited). Got: ${timeoutMs}.`,
+    )
+  }
+  return timeoutMs
+}

package/src/lib/mega-metrics.js

@@ -38,12 +38,7 @@
  */
 import { MeterProvider } from '@opentelemetry/sdk-metrics'
 import { PrometheusExporter, PrometheusSerializer } from '@opentelemetry/exporter-prometheus'
-import { resourceFromAttributes } from '@opentelemetry/resources'
-import {
-  ATTR_SERVICE_NAME,
-  ATTR_SERVICE_VERSION,
-  ATTR_DEPLOYMENT_ENVIRONMENT_NAME,
-} from '@opentelemetry/semantic-conventions'
+import { buildOtelResource } from './otel-resource.js'
 import { MegaConfigError } from '../errors/config-error.js'
 
 /** meter 이름 (instrumentation scope) — OTel 컨벤션상 패키지명. */
@@ -147,12 +142,8 @@ export function init(opts = /** @type {any} */ ({})) {
     )
   }
 
-  const resource = resourceFromAttributes({
-    [ATTR_SERVICE_NAME]: serviceName,
-    ...(typeof opts.version === 'string' ? { [ATTR_SERVICE_VERSION]: opts.version } : {}),
-    ...(typeof opts.environment === 'string' ? { [ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: opts.environment } : {}),
-    ...(opts.attributes && typeof opts.attributes === 'object' ? opts.attributes : {}),
-  })
+  // resource 조립은 트레이싱과 공유하는 단일 출처(otel-resource.js, ADR-193) — 두 SDK 간 드리프트 방지.
+  const resource = buildOtelResource({ serviceName, version: opts.version, environment: opts.environment, attributes: opts.attributes })
 
   // preventServerStart — 자체 :9464 서버를 띄우지 않고 우리가 collect() 로 직접 긁는다(메인 포트 서빙).
   const reader = new PrometheusExporter({ preventServerStart: true })