mega-framework 0.1.0

package/src/lib/hub-protocol.js

@@ -0,0 +1,322 @@
+// @ts-check
+/**
+ * Bridge ↔ Hub 12-타입 프로토콜 카탈로그 (04-data-models §7 정본).
+ *
+ * Bridge(=mega server) 와 Hub(=`mega ws-hub`) 사이는 WebSocket 위에 §6.2 envelope 을 얹어
+ * 통신한다 (ADR-033). 메시지 `type` 은 아래 **12 종** 중 하나다. 이 모듈은 그 12 타입의
+ * 상수·payload JSON Schema·검증 함수를 한곳에 모은다.
+ *
+ * # type 네이밍 — ADR-097
+ *   04-data-models §7 의 카탈로그는 논리명을 UPPERCASE(`REGISTER` 등)로 적지만, 모든 WS envelope
+ *   의 `type` 은 §6.2(ADR-015)의 `domain.action` 패턴({@link WS_TYPE_PATTERN}, 소문자+점)을 따라야
+ *   한다. 둘이 충돌하므로 **오너 결정(ADR-097)** 으로 wire `type` 은 `hub.<lower>` 로 못박는다
+ *   (`REGISTER` → `hub.register`). 논리명↔wire 매핑은 {@link HUB_MESSAGE_TYPES}. 이로써 hub 메시지도
+ *   §6.2 검증(`validateWsMessage`)을 그대로 통과한다.
+ *
+ * # ASP 무관 (ADR-059)
+ *   12 타입은 모두 **평문**으로 hub link 를 흐른다. hub link 는 Bearer 토큰 + timing-safe 비교 +
+ *   내부망 TLS 로 보호하며 ASP 암복호화는 bridge 가 종단(클라↔bridge 구간)한다. 따라서 본 모듈은
+ *   암호화에 관여하지 않는다.
+ *
+ * # ERROR 의 ErrorObject 위치
+ *   §7 은 `ERROR` payload 를 §6.3 `ErrorObject` 라 적지만, §6.2 envelope 엔 이미 전용 `error` 필드가
+ *   있고 그 스키마가 §6.3 그대로다. 프레임워크 기존 관례(ws-upgrade `sendError`, error-mapper)와
+ *   정합을 위해 `hub.error` 의 ErrorObject 는 envelope 의 **`error` 필드**에 싣는다(payload 아님,
+ *   ADR-097 에 명시).
+ *
+ * @module lib/hub-protocol
+ */
+
+/**
+ * hub 메시지 envelope (§6.2 + hub 타입). payload/error 는 타입별로 다르므로 any 로 둔다.
+ * @typedef {{ v: number, id: string, type: string, ts: number, ns?: string, payload?: any, error?: any, ref?: string }} HubEnvelope
+ */
+import { Ajv } from 'ajv'
+import {
+  createWsMessage,
+  validateWsMessage,
+  WS_TYPE_PATTERN,
+} from '../core/ws-message.js'
+
+/**
+ * 논리명(04 §7 UPPERCASE) → wire `type`(`hub.<lower>`, ADR-097) 매핑.
+ * 키는 04-data-models §7 표의 타입명과 1:1. 값은 §6.2 패턴을 통과하는 소문자-점 형식.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const HUB_MESSAGE_TYPES = Object.freeze({
+  REGISTER: 'hub.register',
+  REGISTER_OK: 'hub.register_ok',
+  JOIN: 'hub.join',
+  LEAVE: 'hub.leave',
+  BULK_LEAVE: 'hub.bulk_leave',
+  BROADCAST: 'hub.broadcast',
+  DIRECT: 'hub.direct',
+  METADATA: 'hub.metadata',
+  DISCONNECT: 'hub.disconnect',
+  BINARY: 'hub.binary',
+  HEARTBEAT: 'hub.heartbeat',
+  ERROR: 'hub.error',
+})
+
+/** 12 개 wire `type` 문자열 집합 (빠른 소속 판별용). @type {ReadonlySet<string>} */
+export const HUB_TYPE_SET = new Set(Object.values(HUB_MESSAGE_TYPES))
+
+/**
+ * bridge↔hub WebSocket close code 카탈로그 (ADR-098).
+ *
+ * 클라↔bridge 의 close code(4500 decrypt / 1011 internal, {@link import('../core/ws-upgrade.js')})
+ * 와 **다른 평면**이다 — 이쪽은 bridge↔hub 전송계층(plaintext+Bearer, ADR-059) 전용.
+ *
+ * - `1001` GOING_AWAY — 일반 graceful shutdown(테스트/명시 stop). 재연결 의무 없음.
+ * - `1008` UNAUTHORIZED — REGISTER Bearer 불일치(RFC 6455 policy violation, ADR-097).
+ * - `4503` DRAIN — hub 가 의도적으로 비우는 중. bridge 는 **다른 hub 인스턴스로 재연결**해야 한다
+ *   (LB/mesh 회전). ADR-097 카탈로그가 예약했던 코드를 활성화.
+ * @type {Readonly<Record<string, number>>}
+ */
+export const HUB_CLOSE_CODES = Object.freeze({
+  GOING_AWAY: 1001,
+  UNAUTHORIZED: 1008,
+  DRAIN: 4503,
+})
+
+/** hub drain close code(4503). bridge 가 이 코드를 받으면 재연결 대상으로 간주(ADR-098). */
+export const CLOSE_CODE_DRAIN = HUB_CLOSE_CODES.DRAIN
+
+/** hub.error 의 `error` 필드 = §6.3 ErrorObject. 재사용을 위해 단독 정의. */
+const ERROR_OBJECT_SCHEMA = {
+  type: 'object',
+  required: ['code', 'message'],
+  properties: {
+    code: { type: 'string', pattern: WS_TYPE_PATTERN.source },
+    message: { type: 'string' },
+    details: {},
+  },
+  additionalProperties: false,
+}
+
+/**
+ * 타입별 payload JSON Schema (04-data-models §7 그대로). AJV 컴파일 대상.
+ * `hub.error` 는 payload 가 아니라 envelope `error` 로 검증하므로 여기엔 없다(아래 별도 처리).
+ * @type {Readonly<Record<string, Object>>}
+ */
+export const HUB_PAYLOAD_SCHEMAS = Object.freeze({
+  [HUB_MESSAGE_TYPES.REGISTER]: {
+    type: 'object',
+    required: ['instanceId', 'token', 'capabilities'],
+    properties: {
+      instanceId: { type: 'string', minLength: 1 },
+      token: { type: 'string', minLength: 1 },
+      capabilities: { type: 'array', items: { type: 'string' } },
+    },
+    additionalProperties: false,
+  },
+  [HUB_MESSAGE_TYPES.REGISTER_OK]: {
+    type: 'object',
+    required: ['hubId', 'acceptedAt', 'heartbeatMs'],
+    properties: {
+      hubId: { type: 'string', minLength: 1 },
+      acceptedAt: { type: 'integer' },
+      heartbeatMs: { type: 'integer', minimum: 1 },
+    },
+    additionalProperties: false,
+  },
+  [HUB_MESSAGE_TYPES.JOIN]: {
+    type: 'object',
+    required: ['userId', 'sessionId', 'channels'],
+    properties: {
+      userId: { type: 'string', minLength: 1 },
+      sessionId: { type: 'string', minLength: 1 },
+      channels: { type: 'array', items: { type: 'string' } },
+      metadata: { type: 'object' },
+    },
+    additionalProperties: false,
+  },
+  [HUB_MESSAGE_TYPES.LEAVE]: {
+    type: 'object',
+    required: ['sessionId'],
+    properties: { sessionId: { type: 'string', minLength: 1 } },
+    additionalProperties: false,
+  },
+  [HUB_MESSAGE_TYPES.BULK_LEAVE]: {
+    type: 'object',
+    required: ['sessionIds'],
+    properties: { sessionIds: { type: 'array', items: { type: 'string' } } },
+    additionalProperties: false,
+  },
+  [HUB_MESSAGE_TYPES.BROADCAST]: {
+    type: 'object',
+    required: ['ns', 'channel', 'message'],
+    properties: {
+      ns: { type: 'string', minLength: 1 },
+      channel: { type: 'string', minLength: 1 },
+      message: { type: 'object' },
+      // exceptSessionIds: wire 호환을 위해 schema 는 유지하나, 세션단위 fan-out 전까지
+      // hub fan-out 어디서도 읽지 않는 **no-op** 이다(ADR-097). bridge 는 채널 단위로만 구독하므로
+      // hub 가 개별 세션을 제외하려면 세션↔소켓 매핑(인증·세션 DI 연동)이 선행돼야 한다.
+      exceptSessionIds: { type: 'array', items: { type: 'string' } },
+    },
+    additionalProperties: false,
+  },
+  [HUB_MESSAGE_TYPES.DIRECT]: {
+    type: 'object',
+    required: ['userId', 'message'],
+    properties: {
+      userId: { type: 'string', minLength: 1 },
+      message: { type: 'object' },
+    },
+    additionalProperties: false,
+  },
+  [HUB_MESSAGE_TYPES.METADATA]: {
+    type: 'object',
+    required: ['sessionId', 'metadata'],
+    properties: {
+      sessionId: { type: 'string', minLength: 1 },
+      metadata: { type: 'object' },
+    },
+    additionalProperties: false,
+  },
+  [HUB_MESSAGE_TYPES.DISCONNECT]: {
+    type: 'object',
+    required: ['sessionId', 'reason'],
+    properties: {
+      sessionId: { type: 'string', minLength: 1 },
+      reason: { type: 'string' },
+      requeue: { type: 'boolean' },
+    },
+    additionalProperties: false,
+  },
+  [HUB_MESSAGE_TYPES.BINARY]: {
+    type: 'object',
+    required: ['ref', 'mimeType', 'bytes'],
+    properties: {
+      ref: { type: 'string', minLength: 1 },
+      mimeType: { type: 'string', minLength: 1 },
+      bytes: { type: 'integer', minimum: 0 },
+    },
+    additionalProperties: false,
+  },
+  [HUB_MESSAGE_TYPES.HEARTBEAT]: {
+    type: 'object',
+    required: ['at'],
+    properties: {
+      at: { type: 'integer' },
+      pendingDeliveries: { type: 'integer', minimum: 0 },
+    },
+    additionalProperties: false,
+  },
+})
+
+// 부팅 시 1회 컴파일 (요청 경로에서 컴파일 비용 회피). allErrors=true 로 모든 위반 수집.
+const hubAjv = new Ajv({ allErrors: true })
+
+/** type(wire) → 컴파일된 payload 검증 함수. @type {Record<string, import('ajv').ValidateFunction>} */
+const PAYLOAD_VALIDATORS = {}
+for (const [type, schema] of Object.entries(HUB_PAYLOAD_SCHEMAS)) {
+  PAYLOAD_VALIDATORS[type] = hubAjv.compile(schema)
+}
+const ERROR_OBJECT_VALIDATOR = hubAjv.compile(ERROR_OBJECT_SCHEMA)
+
+/**
+ * AJV 에러 배열 → 사람이 읽는 사유 문자열 배열. validateHubMessage 의 결과 누적용.
+ * @param {import('ajv').ErrorObject[] | null | undefined} errors
+ * @param {string} prefix - 'payload' | 'error' 등 위치 라벨.
+ * @returns {string[]}
+ */
+function ajvErrorsToStrings(errors, prefix) {
+  if (!Array.isArray(errors)) return []
+  return errors.map((e) => {
+    const where = e.instancePath ? `${prefix}${e.instancePath}` : prefix
+    return `${where} ${e.message || 'invalid'}`
+  })
+}
+
+/**
+ * hub 메시지 전체 검증 — envelope(§6.2) + type 소속(12 종) + payload/error 스키마.
+ *
+ * 던지지 않고 위반 사유 배열을 돌려준다(빈 배열 = 유효). 호출부(hub/link)가 사유를 그대로
+ * `hub.error` envelope 의 `details` 로 실어 보낼 수 있도록 한다(ADR-075 배열 표준).
+ *
+ * @param {any} msg - 파싱된 envelope 객체.
+ * @returns {string[]} 위반 사유 목록(없으면 빈 배열).
+ */
+export function validateHubMessage(msg) {
+  // 1) envelope(§6.2) 검증을 먼저 위임 — v/id/ts/type 패턴/허용키 등.
+  const errors = validateWsMessage(msg)
+  // type 자체가 깨졌으면(객체 아님 등) 여기서 종료 — payload 검증 의미 없음.
+  if (!msg || typeof msg !== 'object') return errors
+
+  // 2) type 이 12 종 hub 타입인지.
+  const type = msg.type
+  if (typeof type === 'string' && !HUB_TYPE_SET.has(type)) {
+    errors.push(`type must be one of the 12 hub protocol types (got '${type}')`)
+    return errors
+  }
+
+  // 3) hub.error 는 envelope.error(=§6.3 ErrorObject) 를 검증. payload 는 사용 안 함.
+  if (type === HUB_MESSAGE_TYPES.ERROR) {
+    if (msg.error === undefined) {
+      errors.push('error is required for hub.error (§6.3 ErrorObject)')
+    } else if (!ERROR_OBJECT_VALIDATOR(msg.error)) {
+      errors.push(...ajvErrorsToStrings(ERROR_OBJECT_VALIDATOR.errors, 'error'))
+    }
+    return errors
+  }
+
+  // 4) 나머지 11 종은 payload 를 타입별 스키마로 검증.
+  const validate = typeof type === 'string' ? PAYLOAD_VALIDATORS[type] : undefined
+  if (validate) {
+    if (msg.payload === undefined) {
+      errors.push(`payload is required for ${type}`)
+    } else if (!validate(msg.payload)) {
+      errors.push(...ajvErrorsToStrings(validate.errors, 'payload'))
+    }
+  }
+  return errors
+}
+
+/**
+ * hub 메시지 envelope 생성. {@link createWsMessage} 위임 — v/id/ts 자동.
+ * wire `type` 은 반드시 {@link HUB_MESSAGE_TYPES} 의 값(`hub.*`) 이어야 한다.
+ *
+ * @param {Object} fields
+ * @param {string} fields.type - wire type(`hub.*`). 12 종 아님 → throw.
+ * @param {string} [fields.ns]
+ * @param {Object} [fields.payload]
+ * @param {Object} [fields.error] - hub.error 의 §6.3 ErrorObject.
+ * @param {string} [fields.ref]
+ * @param {{ id?: string, ts?: number }} [opts] - 테스트 주입용.
+ * @returns {{ v: number, id: string, type: string, ts: number }}
+ * @throws {Error} type 이 12 종 hub 타입이 아님.
+ */
+export function createHubMessage(fields, opts = {}) {
+  if (!fields || !HUB_TYPE_SET.has(fields.type)) {
+    throw new Error(
+      `createHubMessage: 'type' must be one of the 12 hub types (ADR-097). Got: ${JSON.stringify(fields?.type)}`,
+    )
+  }
+  return createWsMessage(fields, opts)
+}
+
+/**
+ * JSON 문자열 → 검증된 hub 메시지 envelope. 파싱/검증 실패 시 throw(silent 금지).
+ *
+ * @param {string} json - hub link 평문 JSON.
+ * @returns {HubEnvelope} 검증 통과한 envelope.
+ * @throws {Error} JSON 파싱 실패 또는 hub 프로토콜 위반(메시지에 사유 포함).
+ */
+export function parseHubMessage(json) {
+  let obj
+  try {
+    obj = JSON.parse(json)
+  } catch (err) {
+    throw new Error(
+      `parseHubMessage: invalid JSON — ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
+    )
+  }
+  const errors = validateHubMessage(obj)
+  if (errors.length > 0) {
+    throw new Error(`parseHubMessage: invalid hub message — ${errors.join('; ')}`)
+  }
+  return obj
+}

package/src/lib/index.js

@@ -0,0 +1,42 @@
+// @ts-check
+export * as MegaHealth from './mega-health.js'
+export { MegaShutdown } from './mega-shutdown.js'
+// 재시도 백오프 유틸 (p-retry 래퍼, ADR-029/098)
+export { MegaRetry, withRetry, RetryAbortError } from './mega-retry.js'
+// 서킷 브레이커 — 외부 호출 보호 (opossum 래퍼, ADR-029/117)
+export {
+  MegaCircuitBreaker,
+  wrap as wrapCircuitBreaker,
+  OPEN_CIRCUIT_ERROR_CODE,
+  TIMEOUT_ERROR_CODE,
+  CAPACITY_ERROR_CODE,
+} from './mega-circuit-breaker.js'
+// cron 파서 + cron 기반 스케줄러(분산 중복방지) (croner 래퍼, ADR-029/118)
+export { MegaCron } from './mega-cron.js'
+export { MegaSchedule, MegaScheduler } from './mega-schedule.js'
+// NATS JetStream 잡 큐 — 영속 큐 + 재시도 + DLQ (JetStream 래퍼, ADR-029/119)
+export { MegaJob, resolveJobRetryConfig, JOB_RETRY_DEFAULTS } from './mega-job.js'
+export { MegaJobQueue } from './mega-job-queue.js'
+// 잡 소비 워커 런타임 — 잡 등록 + bus 배선 + consume 라이프사이클 (ADR-120)
+export { MegaJobWorker } from './mega-job-worker.js'
+// CPU 워커 풀(정본) — worker_threads/child_process 격리 + ctx.workers.<name>.run(task) (ADR-121/124)
+export { MegaWorker } from './mega-worker.js'
+// 인증 보안 묶음 — 비밀번호 해싱(scrypt) + brute-force 차단 (ADR-049/050/130)
+export { MegaHash } from './mega-hash.js'
+export { MegaBruteForce } from './mega-brute-force.js'
+// 플러그인 시스템 — install(mega) 패턴 + apiVersion 호환 (ADR-079/122)
+export { MegaPluginHost, loadPlugins, CORE_API_VERSION } from './mega-plugin.js'
+// .env → 어댑터 옵션 자동 매핑 (12-factor, ADR-109)
+export { buildAdapterEnvConfig } from './env-mapper.js'
+// OpenTelemetry 분산 트레이싱 옵트인 (ADR-077 hook 위 자동 span, ADR-114)
+export * as MegaTracing from './mega-tracing.js'
+// OpenTelemetry 메트릭 + Prometheus /metrics 옵트인 (ADR-072/131)
+export * as MegaMetrics from './mega-metrics.js'
+
+// ASP (Application Secure Protocol) (ADR-053 ~ ADR-060).
+export * as MegaAspCrypto from './asp/crypto.js'
+export { registerAspPlugin } from './asp/plugin.js'
+export { MegaAspTerminator } from './asp/ws-terminator.js'
+export { MegaAspNonceCache, MegaMemoryNonceStore } from './asp/nonce-cache.js'
+export { MegaAspDecryptError, ASP_RULES } from './asp/errors.js'
+export { normalizeAspConfig } from './asp/config.js'

package/src/lib/logger/telegram-core.js

@@ -0,0 +1,150 @@
+// @ts-check
+/**
+ * 텔레그램 sink 순수 로직 — throttle + 메시지 포맷 + disk-backed retry queue (ADR-023/141).
+ *
+ * worker thread transport(`telegram-transport.js`)가 이 순수 함수들을 조합한다. 순수/주입 가능 설계라
+ * worker thread 없이 단위 테스트한다(throttle 윈도우·포맷·retry queue append/drain·send 주입).
+ *
+ * @module lib/logger/telegram-core
+ */
+import { appendFile, readFile, rename, mkdir, rm } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+/**
+ * 슬라이딩 윈도우 throttle — 최근 `windowMs` 안에 `max` 건까지만 허용(폭주 시 텔레그램 rate limit 직격 방지).
+ *
+ * @param {number} max - 윈도우당 최대 전송 건수(디폴트 5).
+ * @param {number} windowMs - 윈도우 길이 ms(디폴트 60_000 = 1분).
+ * @returns {{ tryAcquire(now: number): boolean, size(): number }}
+ */
+export function createThrottle(max = 5, windowMs = 60_000) {
+  /** @type {number[]} 최근 전송 타임스탬프(ms). */
+  let stamps = []
+  return {
+    /**
+     * 지금(now) 전송이 허용되면 true(슬롯 점유), 초과면 false.
+     * @param {number} now
+     * @returns {boolean}
+     */
+    tryAcquire(now) {
+      stamps = stamps.filter((t) => now - t < windowMs) // 윈도우 밖 만료 제거.
+      if (stamps.length >= max) return false
+      stamps.push(now)
+      return true
+    },
+    size() {
+      return stamps.length
+    },
+  }
+}
+
+/**
+ * pino 레코드를 텔레그램 메시지 텍스트로 포맷한다. redact 는 메인 스레드 pino 가 이미 적용했으므로
+ * 레코드에는 시크릿이 없다(transport 는 마스킹된 NDJSON 만 받음). 핵심 필드만 추린다(전체 payload X, P5).
+ *
+ * @param {Record<string, any>} record - pino 표준 레코드(JSON 파싱됨).
+ * @param {string} [serviceName]
+ * @returns {string} 텔레그램 sendMessage 용 텍스트.
+ */
+export function formatMessage(record, serviceName = 'mega') {
+  const levelName = LEVEL_NAMES[record.level] ?? String(record.level ?? '')
+  const parts = [`🚨 [${serviceName}] ${levelName.toUpperCase()}: ${record.msg ?? ''}`.trim()]
+  if (record.err?.message) parts.push(`err: ${record.err.message}`)
+  if (record.req?.method && record.req?.url) parts.push(`req: ${record.req.method} ${record.req.url}`)
+  if (record.reqId ?? record.req_id ?? record.request_id) parts.push(`reqId: ${record.reqId ?? record.req_id ?? record.request_id}`)
+  if (record.trace_id) parts.push(`trace: ${record.trace_id}`)
+  return parts.join('\n')
+}
+
+/** pino 숫자 level → 이름. */
+const LEVEL_NAMES = /** @type {Record<number, string>} */ ({
+  10: 'trace',
+  20: 'debug',
+  30: 'info',
+  40: 'warn',
+  50: 'error',
+  60: 'fatal',
+})
+
+/**
+ * disk-backed retry queue — 전송 실패한 텍스트를 파일(JSONL)에 쌓고, 다음 기회에 재시도한다(전송 실패해도
+ * 메시지를 잃지 않음, ADR-023). worker thread 내에서만 접근하므로 락 불필요(단일 소비자).
+ */
+export class RetryQueue {
+  /**
+   * @param {string} filePath - JSONL 큐 파일 경로(없으면 비어 있음).
+   */
+  constructor(filePath) {
+    /** @type {string} */
+    this._file = filePath
+  }
+
+  /**
+   * 실패 메시지를 큐에 append.
+   * @param {string} text
+   * @returns {Promise<void>}
+   */
+  async append(text) {
+    await mkdir(dirname(this._file), { recursive: true })
+    await appendFile(this._file, JSON.stringify({ text, ts: Date.now() }) + '\n', 'utf8')
+  }
+
+  /**
+   * 큐 전체를 가로채(claim) 비우고, 각 항목 텍스트 배열을 반환한다. 호출자가 재전송 시도 후, 다시
+   * 실패한 것만 `append` 로 되돌린다.
+   *
+   * read-then-`writeFile('')` 는 두 await 사이에 끼어든 `append` 를 통째로 지운다(producer=write 경로의
+   * 재시도 append, consumer=drain). 그래서 `rename` 으로 **단일 syscall** 가로채기를 쓴다: 가로챈 뒤 들어오는
+   * append 는 새 파일(`this._file`)에 쌓이므로 유실되지 않는다(유실 0, ADR-023/141). 동시 drain 이 한 번 더
+   * 들어오면 파일이 이미 옮겨져 `ENOENT` → 빈 배열(중복 처리 없음).
+   * @returns {Promise<string[]>}
+   */
+  async drain() {
+    const claim = `${this._file}.draining`
+    try {
+      await rename(this._file, claim)
+    } catch (e) {
+      // 큐 파일 없음(아직 실패 없음) 또는 다른 drain 이 이미 가로챔 → 처리할 것 없음.
+      if (/** @type {NodeJS.ErrnoException} */ (e)?.code === 'ENOENT') return []
+      throw e
+    }
+    const raw = await readFile(claim, 'utf8')
+    await rm(claim, { force: true })
+    /** @type {string[]} */
+    const texts = []
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue
+      try {
+        const obj = JSON.parse(line)
+        if (typeof obj.text === 'string') texts.push(obj.text)
+      } catch {
+        // 손상된 라인은 건너뛴다 — 큐 전체를 막지 않기 위함(비치명적, 다음 항목 계속).
+        continue
+      }
+    }
+    return texts
+  }
+
+  /** 큐 파일 제거(테스트·정리용). @returns {Promise<void>} */
+  async clear() {
+    await rm(this._file, { force: true })
+  }
+}
+
+/**
+ * 텔레그램 Bot API `sendMessage` 호출. https 호출은 주입 가능(`httpsRequest`)이라 단위 테스트에서 모킹한다.
+ *
+ * @param {object} args
+ * @param {string} args.botToken
+ * @param {string} args.chatId
+ * @param {string} args.text
+ * @param {(url: string, body: string) => Promise<{ statusCode: number }>} args.httpsRequest - 주입 HTTP.
+ * @returns {Promise<boolean>} 전송 성공(2xx) 여부.
+ * @throws 호출 자체가 throw 하면 호출자(transport)가 retry queue 로 보낸다.
+ */
+export async function sendTelegram({ botToken, chatId, text, httpsRequest }) {
+  const url = `https://api.telegram.org/bot${botToken}/sendMessage`
+  const body = JSON.stringify({ chat_id: chatId, text })
+  const res = await httpsRequest(url, body)
+  return res.statusCode >= 200 && res.statusCode < 300
+}

package/src/lib/logger/telegram-transport.js

@@ -0,0 +1,126 @@
+// @ts-check
+/**
+ * 텔레그램 pino transport — **worker thread** 에서 실행(pino transport 가 자동 격리, ADR-023).
+ *
+ * pino 가 NDJSON 청크를 이 stream 에 흘려보내면: (1) throttle 통과분만 (2) 텔레그램으로 POST,
+ * (3) 실패는 disk-backed retry queue 로 적재 후 타이머가 주기 재시도. 메인 이벤트루프와 격리돼 전송 지연·
+ * 실패가 앱을 막지 않는다. 순수 로직은 `telegram-core.js`(단위 테스트), 본 모듈은 https + stream glue.
+ *
+ * @module lib/logger/telegram-transport
+ * @see ADR-023
+ * @see ADR-141
+ */
+import { Writable } from 'node:stream'
+import { request as httpsRequestRaw } from 'node:https'
+import { join } from 'node:path'
+import { createThrottle, formatMessage, RetryQueue, sendTelegram } from './telegram-core.js'
+
+/**
+ * 실제 https POST — telegram-core 의 주입 시그니처에 맞춘 thin 래퍼.
+ *
+ * @param {string} url
+ * @param {string} body
+ * @param {{ request?: typeof httpsRequestRaw, timeoutMs?: number }} [deps] - request 는 테스트 주입용(기본=node:https).
+ * @returns {Promise<{ statusCode: number }>}
+ */
+export function httpsPost(url, body, { request = httpsRequestRaw, timeoutMs = 10_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    /** @type {ReturnType<typeof setTimeout> | null} */
+    let timer = null
+    /** 한 번만 settle — timer 정리 후 결정(중복 settle 은 Promise 가 무시). */
+    const settle = (/** @type {(v:any)=>void} */ fn, /** @type {any} */ arg) => {
+      if (timer) {
+        clearTimeout(timer)
+        timer = null
+      }
+      fn(arg)
+    }
+    const req = request(url, { method: 'POST', headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) } }, (res) => {
+      // 헤더 수신 후 응답 스트림이 끊기면 unhandled 'error' 로 워커가 죽는다 — reject 로 흡수(호출자가 retry queue 로).
+      res.on('error', (e) => settle(reject, e))
+      res.resume() // 응답 본문 드레인(메모리 누수 방지) — statusCode 만 본다.
+      res.on('end', () => settle(resolve, { statusCode: res.statusCode ?? 0 }))
+    })
+    // 무응답(연결만 열리고 응답 없음)이면 trySend·drain 루프가 영구 정지 → 타임아웃으로 끊어 retry queue 로 넘긴다.
+    timer = setTimeout(() => req.destroy(new Error(`telegram request timeout after ${timeoutMs}ms`)), timeoutMs)
+    if (typeof timer.unref === 'function') timer.unref() // 종료 막지 않음.
+    req.on('error', (e) => settle(reject, e))
+    req.write(body)
+    req.end()
+  })
+}
+
+/**
+ * pino transport 진입점 — `{ target: <this>, options }` 로 등록되면 worker 가 이 default export 를 호출한다.
+ *
+ * @param {object} opts
+ * @param {string} opts.botToken
+ * @param {string} opts.chatId
+ * @param {number} [opts.throttleMax] - 윈도우당 최대 전송(디폴트 5).
+ * @param {number} [opts.throttleWindowMs] - 윈도우 ms(디폴트 60_000).
+ * @param {string} [opts.retryDir] - retry queue 디렉터리(디폴트 './logs/telegram-retry').
+ * @param {string} [opts.serviceName]
+ * @param {number} [opts.retryDrainMs] - retry 드레인 주기(디폴트 30_000).
+ * @param {(url: string, body: string) => Promise<{ statusCode: number }>} [opts.httpsRequest] - HTTP 주입(기본=httpsPost). 단위 테스트용 seam(ADR-165 동일 패턴) — pino worker 는 미전달.
+ * @returns {import('node:stream').Writable}
+ */
+export default function telegramTransport(opts) {
+  const {
+    botToken,
+    chatId,
+    throttleMax = 5,
+    throttleWindowMs = 60_000,
+    retryDir = './logs/telegram-retry',
+    serviceName = 'mega',
+    retryDrainMs = 30_000,
+    httpsRequest = httpsPost,
+  } = opts
+  const throttle = createThrottle(throttleMax, throttleWindowMs)
+  const queue = new RetryQueue(join(retryDir, 'telegram-retry.jsonl'))
+
+  /** 한 건 전송 시도 — 실패/throw 시 retry queue 로. */
+  async function trySend(/** @type {string} */ text) {
+    try {
+      const ok = await sendTelegram({ botToken, chatId, text, httpsRequest })
+      if (!ok) await queue.append(text)
+    } catch {
+      // 네트워크 throw 도 유실 금지 — 큐로 보관 후 다음 드레인에서 재시도(silent 아님: 큐가 증거).
+      await queue.append(text)
+    }
+  }
+
+  // 주기 드레인 — 쌓인 실패분을 재전송(여전히 실패하면 다시 큐로). unref 로 프로세스 종료 막지 않음.
+  /** @returns {Promise<void>} 쌓인 실패분 재전송(여전히 실패하면 trySend 가 다시 큐로). */
+  const drainTick = async () => {
+    const pending = await queue.drain().catch(() => /** @type {string[]} */ ([]))
+    for (const text of pending) await trySend(text)
+  }
+  const timer = setInterval(drainTick, retryDrainMs)
+  if (typeof timer.unref === 'function') timer.unref()
+
+  let buffer = '' // NDJSON 프레이밍 — 청크 경계에 걸친 미완 라인 보관.
+  return new Writable({
+    write(chunk, _enc, cb) {
+      buffer += chunk.toString()
+      const lines = buffer.split('\n')
+      buffer = lines.pop() ?? '' // 마지막(미완) 라인은 다음 write 까지 보류.
+      for (const line of lines) {
+        if (!line.trim()) continue
+        /** @type {Record<string, any>} */
+        let record
+        try {
+          record = JSON.parse(line)
+        } catch {
+          continue // 손상 라인 skip — 다음 라인 계속.
+        }
+        if (!throttle.tryAcquire(Date.now())) continue // 폭주 억제(초과분 드롭).
+        void trySend(formatMessage(record, serviceName))
+      }
+      cb()
+    },
+    final(cb) {
+      clearInterval(timer)
+      cb()
+    },
+  })
+}