mega-framework 0.1.0

package/src/adapters/nats-adapter.js

@@ -0,0 +1,370 @@
+// @ts-check
+/**
+ * MegaNatsAdapter — NATS 메시지 버스 어댑터 (`nats` 공식 driver 래퍼, ADR-112).
+ *
+ * **첫 bus 도메인 어댑터**(`MegaBusAdapter` 첫 구체). DB/cache 와 달리 pub/sub·req/reply·
+ * queue group 메시징 인터페이스를 구현한다.
+ *
+ * # 표준 표면 (MegaBusAdapter 상속)
+ *   - `_connect()`   — `connect({ servers, ...auth, ...options })` (driver 는 connect 시점 lazy import).
+ *                      connect() 자체가 서버 응답까지 기다리므로 별도 ping 불필요(실패 시 throw=검증).
+ *   - `_disconnect()`— `nc.drain()` — 진행 중 메시지/구독을 모두 비운 뒤 **연결까지 닫는다**(공식 문서:
+ *                      "Finally, the connection is closed"). 그래서 별도 `close()` 는 호출하지 않는다.
+ *   - `_native()`    — `NatsConnection`(raw handle, ADR-009). 사용자가 직접 NATS API(jetstream 등) 접근.
+ *   - `healthCheck()`— `nc.rtt()` (서버 왕복 ping)으로 실제 응답성 확인.
+ *   - `getStats()`   — 베이스 stats + nats 특화(server/연결 stats: inMsgs/outMsgs/inBytes/outBytes).
+ *   - `publish/subscribe/request` + `enqueue/process` — 아래 인터페이스.
+ *
+ * # 직렬화 = JSONCodec
+ *   payload 는 NATS wire 에서 `Uint8Array` 다. 본 어댑터는 `JSONCodec` 로 인코드/디코드를 표준화해
+ *   사용자는 JS 값을 그대로 publish/subscribe 한다(수신 측에서 같은 값으로 복원). `undefined` payload
+ *   는 `null` 로 정규화(JSONCodec 가 undefined 를 인코드하지 못함).
+ *
+ * # queue (job) 인터페이스 — 단순 publish + queue group (jetstream 미사용, ADR-112)
+ *   `enqueue(job, msg)` = 해당 subject 로 **단순 publish**. `process(job, handler)` = **queue group**
+ *   구독(같은 queue 의 구독자끼리 메시지를 load-balance 분배). jetstream(영속 큐·재시도·DLQ)은
+ *   `MegaJob` 백엔드에서 다룬다(ADR-028) — 코어 fan-out 까지.
+ *
+ * # 콜백 에러 표면화 (silent 금지)
+ *   subscribe/process 콜백은 비동기 메시지 전달이라 호출자에게 직접 throw 할 수 없다. 구독 에러
+ *   (NatsError) 또는 handler throw 는 **`console.error` 로 표면화**한다(로거 미주입 베이스).
+ *   트레이싱이 정식 logger 로 대체 가능.
+ *
+ * # pool 미지원
+ *   NATS 클라이언트는 단일 멀티플렉스 연결이라 풀 개념이 없다. `config.pool` 지정 시 throw.
+ *
+ * # 설정 (services.buses.<key>) — 통합 옵션 구조 (ADR-109/112)
+ *   ```js
+ *   services: {
+ *     buses: {
+ *       main: {
+ *         driver: 'nats',
+ *         // (a) 연결 — url 또는 discrete (host/port) (+ token 또는 user/password 인증)
+ *         url: 'nats://host:4222',                          // 또는 ↓
+ *         host: 'localhost', port: 4222,
+ *         token: '...',                                     // 또는 user/password
+ *         // (b) options — connect() passthrough (pool 은 미지원)
+ *         options: { name: 'mega', reconnect: true, maxReconnectAttempts: -1, pingInterval: 30000,
+ *                    tls: {}, jwt: '...', nkey: '...' },
+ *       },
+ *     },
+ *   }
+ *   ```
+ *   `url`(또는 deprecated 별칭 `connectionString`) **XOR** discrete(host/port/user/password). `token` 은
+ *   별도 인증 축(discrete 모드 권장 — url 에 auth 포함 시 생략). 토큰/jwt/url 은 healthCheck/getStats/
+ *   에러 details 에 절대 노출하지 않는다.
+ *
+ * @module adapters/nats-adapter
+ */
+import { MegaValidationError, MegaInternalError } from '../errors/http-errors.js'
+import { MegaBusAdapter } from './mega-bus-adapter.js'
+import { resolveConnection, assertPlainObject } from './adapter-options.js'
+import * as Registry from './registry.js'
+
+/** NATS 기본 클라이언트 포트(discrete 모드에서 port 미지정 시). */
+const DEFAULT_NATS_PORT = 4222
+/** request() 기본 타임아웃(ms). */
+const DEFAULT_REQUEST_TIMEOUT_MS = 30000
+
+/**
+ * @typedef {object} NatsConfig
+ * @property {string} [driver] - 'nats' (매니저가 사용 — 어댑터는 무시).
+ * @property {string} [url] - `nats://host:port` 연결 문자열 (discrete 와 배타).
+ * @property {string} [connectionString] - `url` 의 deprecated 별칭 (하위 호환).
+ * @property {string} [host] @property {number} [port] @property {string} [user] @property {string} [password]
+ * @property {string} [token] - 토큰 인증 (별도 축 — url/discrete 어느 쪽과도 조합 가능).
+ * @property {any} [pool] - 미지원 — 지정 시 `adapter.invalid_option` throw (NATS 는 단일 연결, ADR-112).
+ * @property {Record<string, any>} [options] - connect() passthrough (name, reconnect, maxReconnectAttempts, pingInterval, tls, jwt, nkey, …).
+ */
+
+export class MegaNatsAdapter extends MegaBusAdapter {
+  /** @type {import('nats').NatsConnection | null} 연결된 NatsConnection (connect 후에만). */
+  #nc = null
+  /** @type {import('nats').Codec<any> | null} JSONCodec (connect 시 생성). */
+  #codec = null
+  /** @type {import('nats').ConnectionOptions} _connect 에서 `connect()` 에 넘길 옵션(생성자에서 고정). */
+  #connectOptions
+
+  /**
+   * @param {NatsConfig} [config] - services.buses.<key> 설정.
+   * @throws {MegaValidationError} `adapter.connection_required` - url·discrete 둘 다 없음.
+   * @throws {MegaValidationError} `adapter.connection_conflict` - url + discrete 동시 지정.
+   * @throws {MegaValidationError} `adapter.invalid_option` - pool 지정/옵션 타입 오류.
+   */
+  constructor(config = /** @type {any} */ ({})) {
+    super(config)
+
+    // NATS 는 단일 멀티플렉스 연결이라 풀 개념이 없다 — pool 지정 명시 거부.
+    if (config.pool !== undefined) {
+      throw new MegaValidationError(
+        'adapter.invalid_option',
+        'nats: connection pooling is not supported (NATS uses a single multiplexed connection). Remove "pool".',
+        { details: { driver: 'nats', option: 'pool' } },
+      )
+    }
+
+    // 연결 모드(url XOR discrete) 결정. token 은 별도 인증 축이라 connection 충돌 검사에 넣지 않는다.
+    const conn = resolveConnection(config, { driver: 'nats', dbConflictsWithUrl: false })
+    assertPlainObject('options', config.options, { driver: 'nats' })
+
+    /** @type {import('nats').ConnectionOptions} */
+    const connectOptions = {}
+    // options(passthrough) 먼저 — 아래 servers/auth 가 항상 이긴다(연결 필수값 보호).
+    if (config.options !== undefined) Object.assign(connectOptions, config.options)
+
+    // servers: url 모드면 url 그대로, discrete 모드면 host[:port].
+    if (conn.url !== undefined) {
+      connectOptions.servers = conn.url
+    } else {
+      const host = conn.host ?? 'localhost'
+      connectOptions.servers = conn.port !== undefined ? `${host}:${conn.port}` : `${host}:${DEFAULT_NATS_PORT}`
+    }
+    // 인증 — discrete user/password 또는 token(별도 축). 지정된 것만 설정.
+    if (conn.user !== undefined) connectOptions.user = conn.user
+    if (conn.password !== undefined) connectOptions.pass = conn.password
+    if (config.token !== undefined) connectOptions.token = config.token
+
+    this.#connectOptions = connectOptions
+  }
+
+  /**
+   * `connect()` 로 NATS 연결 수립. connect() 가 서버 핸드셰이크까지 await 하므로 성공=연결 검증 완료
+   * (실패 시 throw → 베이스가 상태 failed). driver 는 **connect 시점에 lazy import**(DB 어댑터 정합).
+   *
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _connect() {
+    const { connect, JSONCodec } = await import('nats')
+    const nc = await connect(this.#connectOptions)
+    this.#nc = nc
+    this.#codec = JSONCodec()
+  }
+
+  /**
+   * NATS 연결 drain — 진행 중 메시지/구독을 모두 비운 뒤 연결을 닫는다(공식 문서). 별도 close 불필요.
+   * 베이스 상태 머신이 connected 상태에서만 호출을 보장한다.
+   * @protected
+   * @returns {Promise<void>}
+   */
+  async _disconnect() {
+    if (this.#nc !== null) {
+      const nc = this.#nc
+      this.#nc = null
+      this.#codec = null
+      // 이미 닫혀 있으면(서버측 절단 등) drain 이 throw 할 수 있어 가드.
+      if (!nc.isClosed()) await nc.drain()
+    }
+  }
+
+  /**
+   * raw NatsConnection handle (ADR-009). `connect()` 후에만 베이스 `native` getter 가 호출한다.
+   * @protected
+   * @returns {import('nats').NatsConnection}
+   */
+  _native() {
+    if (this.#nc === null) {
+      // 베이스 native getter 가 state 검증을 먼저 하므로 정상 경로에선 도달 안 함 — 방어.
+      return this._notImplemented('native')
+    }
+    return this.#nc
+  }
+
+  /**
+   * 헬스 체크 — 실제 `rtt`(서버 왕복 ping)로 응답성 확인. 실패는 throw 없이 `ok:false` + 사유.
+   * @returns {Promise<{ ok: boolean, driver: 'nats', state: string, server?: string, rttMs?: number, error?: string }>}
+   */
+  async healthCheck() {
+    if (this.state !== 'connected' || this.#nc === null || this.#nc.isClosed()) {
+      return { ok: false, driver: 'nats', state: this.state }
+    }
+    try {
+      const rttMs = await this.#nc.rtt()
+      return { ok: true, driver: 'nats', state: this.state, server: this.#nc.getServer(), rttMs }
+    } catch (err) {
+      return {
+        ok: false,
+        driver: 'nats',
+        state: this.state,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+
+  /**
+   * 누적 통계 + nats 특화(server + 연결 stats). 연결 전이면 server/stats 는 undefined.
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, server: string | undefined, nats: import('nats').Stats | undefined }}
+   */
+  getStats() {
+    const nc = this.#nc
+    return {
+      ...super.getStats(),
+      driver: 'nats',
+      server: nc?.getServer(),
+      nats: nc ? nc.stats() : undefined,
+    }
+  }
+
+  // ──────────────────────────────────────────────────────────────────────
+  // MegaBusAdapter 인터페이스 — publish / subscribe / request + enqueue / process
+  // hook + 상태검증 + stats 는 `_instrument` 가 처리(ADR-077).
+  // ──────────────────────────────────────────────────────────────────────
+
+  /**
+   * fire-and-forget 발행 (ack X). payload 는 JSONCodec 로 인코드.
+   * @param {string} subject
+   * @param {any} payload
+   * @returns {Promise<void>}
+   */
+  async publish(subject, payload) {
+    return this._instrument('publish', { subject }, async () => {
+      const nc = /** @type {import('nats').NatsConnection} */ (this.#nc)
+      nc.publish(subject, this.#encode(payload))
+    })
+  }
+
+  /**
+   * 구독. `handler` 는 `(msg, replyFn?) => any` — msg 는 디코드된 값, replyFn 은 reply subject 가
+   * 있을 때만 제공(`request` 응답용). 반환된 핸들의 `unsubscribe()` 로 정리.
+   *
+   * @param {string} subject
+   * @param {(msg: any, replyFn?: (payload: any) => void) => any} handler
+   * @returns {Promise<{ unsubscribe: () => Promise<void> }>}
+   */
+  async subscribe(subject, handler) {
+    return this._instrument('subscribe', { subject }, async () => {
+      const nc = /** @type {import('nats').NatsConnection} */ (this.#nc)
+      const sub = nc.subscribe(subject, {
+        callback: (err, msg) => this.#dispatch('subscribe', subject, handler, err, msg),
+      })
+      return {
+        unsubscribe: async () => {
+          sub.unsubscribe()
+        },
+      }
+    })
+  }
+
+  /**
+   * req/reply 패턴. `timeout`(ms) 초과 시 `bus.request_timeout`, 응답자 없으면 `bus.no_responders`.
+   * @param {string} subject
+   * @param {any} payload
+   * @param {{ timeout?: number }} [opts]
+   * @returns {Promise<any>} 디코드된 reply.
+   */
+  async request(subject, payload, { timeout = DEFAULT_REQUEST_TIMEOUT_MS } = {}) {
+    return this._instrument('request', { subject, timeout }, async () => {
+      const nc = /** @type {import('nats').NatsConnection} */ (this.#nc)
+      try {
+        const reply = await nc.request(subject, this.#encode(payload), { timeout })
+        return /** @type {import('nats').Codec<any>} */ (this.#codec).decode(reply.data)
+      } catch (err) {
+        // NATS 타임아웃/무응답을 명시 에러 코드로 변환(silent 무시 X). 그 외 에러는 원본 전파.
+        const code = /** @type {any} */ (err)?.code
+        if (code === 'TIMEOUT') {
+          throw new MegaInternalError('bus.request_timeout', `nats request("${subject}") timed out after ${timeout}ms.`, {
+            details: { subject, timeout },
+            cause: err,
+          })
+        }
+        if (code === '503') {
+          throw new MegaInternalError('bus.no_responders', `nats request("${subject}"): no responders subscribed to the subject.`, {
+            details: { subject },
+            cause: err,
+          })
+        }
+        throw err
+      }
+    })
+  }
+
+  /**
+   * 잡 enqueue — 단순 publish (queue group 분배는 `process` 측 책임, ADR-112).
+   * @param {string} jobName
+   * @param {any} payload
+   * @returns {Promise<void>}
+   */
+  async enqueue(jobName, payload) {
+    return this._instrument('enqueue', { jobName }, async () => {
+      const nc = /** @type {import('nats').NatsConnection} */ (this.#nc)
+      nc.publish(jobName, this.#encode(payload))
+    })
+  }
+
+  /**
+   * 잡 처리 등록 — **queue group** 구독(같은 queue 구독자끼리 load-balance). 기본 queue 이름은 jobName
+   * (같은 잡의 모든 워커가 한 그룹).
+   *
+   * **subscription 핸들을 반환하지 않는 건 의도적**(L-2): worker 는 앱 수명 동안 상주하는 것이
+   * 정상이고(개별 잡 처리 등록을 런타임에 떼었다 붙였다 하는 패턴은 비표준), 정리는 disconnect 시
+   * `_disconnect()` 의 `nc.drain()` 이 **모든 구독을 일괄 비우며** 처리한다. 개별 unsubscribe 가
+   * 필요한 일시 구독은 `subscribe()`(핸들 반환)를 쓴다 — `process` 는 fire-and-forget `enqueue` 와
+   * 대칭인 상주 worker 용이다. 영속 큐/재시도/DLQ 가 필요하면 `MegaJob`(jetstream, ADR-028).
+   *
+   * @param {string} jobName
+   * @param {(payload: any) => any} handler
+   * @param {{ queue?: string }} [opts]
+   * @returns {Promise<void>}
+   */
+  async process(jobName, handler, { queue = jobName } = {}) {
+    return this._instrument('process', { jobName, queue }, async () => {
+      const nc = /** @type {import('nats').NatsConnection} */ (this.#nc)
+      nc.subscribe(jobName, {
+        queue,
+        callback: (err, msg) => this.#dispatch('process', jobName, (m) => handler(m), err, msg),
+      })
+    })
+  }
+
+  /**
+   * payload → Uint8Array (JSONCodec). undefined 는 null 로 정규화(JSONCodec 가 undefined 미지원).
+   * @param {any} payload @returns {Uint8Array}
+   */
+  #encode(payload) {
+    return /** @type {import('nats').Codec<any>} */ (this.#codec).encode(payload === undefined ? null : payload)
+  }
+
+  /**
+   * 구독/잡 콜백 공통 디스패처 — 에러·디코드·handler 호출을 표면화한다(silent 금지).
+   * 구독 에러(NatsError)·디코드 실패·handler throw 를 모두 `console.error` 로 드러낸다.
+   *
+   * @param {'subscribe' | 'process'} kind
+   * @param {string} subject
+   * @param {(msg: any, replyFn?: (payload: any) => void) => any} handler
+   * @param {import('nats').NatsError | null} err
+   * @param {import('nats').Msg} msg
+   * @returns {void}
+   */
+  #dispatch(kind, subject, handler, err, msg) {
+    if (err) {
+      // 구독 레벨 에러 — 콜백은 호출자에게 throw 못하므로 표면화.
+      console.error(`[MegaNatsAdapter] ${kind}("${subject}") subscription error:`, err)
+      return
+    }
+    let decoded
+    try {
+      decoded = /** @type {import('nats').Codec<any>} */ (this.#codec).decode(msg.data)
+    } catch (decodeErr) {
+      console.error(`[MegaNatsAdapter] ${kind}("${subject}") payload decode failed:`, decodeErr)
+      return
+    }
+    // reply subject 가 있으면 replyFn 제공(request 응답용). subscribe 만 해당 — process 는 단방향.
+    const replyFn =
+      kind === 'subscribe' && msg.reply ? /** @param {any} p */ (p) => msg.respond(this.#encode(p)) : undefined
+    try {
+      const out = handler(decoded, replyFn)
+      // handler 가 async 면 reject 도 표면화(떠다니는 promise 가 silent 실패되지 않게).
+      if (out && typeof (/** @type {any} */ (out).then) === 'function') {
+        /** @type {Promise<any>} */ (out).catch((hErr) =>
+          console.error(`[MegaNatsAdapter] ${kind}("${subject}") async handler rejected:`, hErr),
+        )
+      }
+    } catch (hErr) {
+      console.error(`[MegaNatsAdapter] ${kind}("${subject}") handler threw:`, hErr)
+    }
+  }
+}
+
+// 빌트인 driver 자기등록 (ADR-044) — 배럴(`adapters/index.js`)이 본 모듈을 import 하면 트리거된다.
+// nats 는 _connect() 의 lazy import 까지 로드되지 않으므로 등록은 안전(미사용 환경 비강제).
+Registry.register('nats', MegaNatsAdapter)