mega-framework 0.1.0 → 0.1.2

package/sample/crud/apps/main/channels/chat-bus.js

@@ -1,115 +0,0 @@
-// @ts-check
-/**
- * chat-bus.js — redis pub/sub 기반 cluster-wide 채팅 broadcast (ADR-158).
- *
- * `app.broadcast`(로컬 ns fan-out)는 단일 프로세스 안에서만 전달된다 — 클러스터(워커 N개)에선 다른
- * 워커에 붙은 클라에게 닿지 않는다. hub 프로세스 없이 cluster-wide 전파를 하기 위해 redis pub/sub 를 쓴다:
- *   - 송신: 메시지를 redis 채널(`ws:chat:bcast`)에 **PUBLISH** 만 한다(로컬 직접 전달 안 함).
- *   - 수신: **워커마다** 전용 구독 연결(ioredis `duplicate()`)이 그 채널을 **SUBSCRIBE** 하고, 도착한
- *     메시지를 자기 워커의 로컬 연결들에 전달한다.
- * 결과: PUBLISH 1건 → 모든 워커의 구독자가 받아 각자 로컬 전달 → 전 클러스터 클라가 정확히 1회씩 수신
- * (송신자 본인 워커도 구독자 경로로 전달받아 echo). 구독 연결은 명령 전용 연결과 분리해야 하므로
- * (subscribe 모드 연결은 일반 명령 불가) `demo` 캐시의 raw ioredis 를 `duplicate()` 한다.
- *
- * 접속자 명단(roster)도 cluster-wide 다 — redis HASH(`ws:chat:roster`, field=sessionId→userName)에 두어
- * 어느 워커에서든 같은 명단·인원수를 본다(INCR/DECR 카운터의 비정상종료 드리프트 회피, 명단까지 공유).
- *
- * @module channels/chat-bus
- */
-import { MegaShutdown } from 'mega-framework'
-
-/** cluster-wide 전파 채널(redis pub/sub 은 db 와 무관한 글로벌 네임스페이스). */
-export const BCAST_CHANNEL = 'ws:chat:bcast'
-/** 접속자 명단 HASH 키 — field=sessionId, value=userName. */
-export const ROSTER_KEY = 'ws:chat:roster'
-
-/** 이 워커의 로컬 연결 레지스트리. sock → { sessionId, userName }. */
-const localConns = new Map()
-/** 이 워커의 전용 구독 연결(1개, lazy). */
-let subscriber = null
-
-/**
- * 이 워커의 구독자를 1회 보장한다(첫 연결 시). 채널 SUBSCRIBE + 메시지 → 로컬 전달 + graceful 종료 hook.
- *
- * @param {any} app - MegaApp(로깅용).
- * @param {import('ioredis').Redis} redisNative - `demo` 캐시의 raw ioredis(여기서 duplicate).
- * @returns {void}
- */
-export function ensureSubscriber(app, redisNative) {
-  if (subscriber) return
-  const log = app?.fastify?.log
-  subscriber = redisNative.duplicate()
-  subscriber.on('message', (/** @type {string} */ _channel, /** @type {string} */ raw) => {
-    let env
-    try {
-      env = JSON.parse(raw)
-    } catch (err) {
-      // 손상 페이로드는 전달하지 않는다(사유 명시 + 로그, silent 금지).
-      log?.warn?.({ err }, 'chat-bus subscribe payload parse failed')
-      return
-    }
-    deliverLocal(env)
-  })
-  subscriber.on('error', (/** @type {Error} */ err) => {
-    // 구독 연결 오류는 비치명적(ioredis 가 재연결) — 로그만.
-    log?.warn?.({ err }, 'chat-bus subscriber connection error')
-  })
-  // subscribe 실패는 전파 자체가 죽는 심각한 신호 — 로그 + throw(fail-closed, silent 금지).
-  subscriber.subscribe(BCAST_CHANNEL).catch((err) => {
-    log?.error?.({ err, channel: BCAST_CHANNEL }, 'chat-bus subscribe failed')
-    throw err
-  })
-  // 워커 graceful 종료 시 구독 연결 정리(이벤트루프 누수 방지).
-  MegaShutdown.register('sample-chat-bus', async () => {
-    const s = subscriber
-    subscriber = null
-    localConns.clear()
-    if (s) await s.quit().catch(() => {})
-  })
-}
-
-/**
- * 구독으로 받은 메시지를 이 워커의 로컬 연결에 전달한다. exceptSessionIds 에 든 세션은 건너뛴다.
- * @param {{ message: { type: string, payload?: object }, exceptSessionIds?: string[] }} env
- * @returns {void}
- */
-function deliverLocal({ message, exceptSessionIds }) {
-  if (!message || typeof message.type !== 'string') return
-  const except = Array.isArray(exceptSessionIds) && exceptSessionIds.length > 0 ? new Set(exceptSessionIds) : null
-  for (const [sock, meta] of localConns) {
-    if (!sock.isOpen) continue
-    if (except && except.has(meta.sessionId)) continue
-    sock.send({ type: message.type, payload: message.payload })
-  }
-}
-
-/**
- * 로컬 연결 등록(onConnect). @param {any} sock @param {{ sessionId: string, userName: string }} meta
- * @returns {void}
- */
-export function registerConn(sock, meta) {
-  localConns.set(sock, meta)
-}
-
-/** 로컬 연결 해제(onDisconnect). @param {any} sock @returns {void} */
-export function unregisterConn(sock) {
-  localConns.delete(sock)
-}
-
-/**
- * cluster-wide 전파 — redis 채널에 PUBLISH(모든 워커 구독자가 받아 로컬 전달).
- * @param {import('ioredis').Redis} redisNative
- * @param {{ message: { type: string, payload?: object }, exceptSessionIds?: string[] }} env
- * @returns {Promise<void>}
- */
-export async function publish(redisNative, env) {
-  await redisNative.publish(BCAST_CHANNEL, JSON.stringify(env))
-}
-
-/** 테스트 정리용 — 구독 연결 종료 + 레지스트리 초기화. @returns {Promise<void>} */
-export async function closeChatBus() {
-  const s = subscriber
-  subscriber = null
-  localConns.clear()
-  if (s) await s.quit().catch(() => {})
-}

package/sample/crud/test/apps/main/chat-bus.test.js

@@ -1,101 +0,0 @@
-// @ts-check
-/**
- * chat-bus 단위 테스트(ADR-158) — redis pub/sub cluster broadcast 의 송수신 계약.
- *
- * 인프라 불필요: ioredis 를 fake(duplicate→fake subscriber, publish spy)로 대체해
- * PUBLISH 직렬화·SUBSCRIBE→로컬 전달·exceptSessionIds 제외·손상 페이로드 무시를 검증한다.
- */
-import { describe, test, expect, vi, afterEach } from 'vitest'
-import {
-  ensureSubscriber,
-  registerConn,
-  unregisterConn,
-  publish,
-  closeChatBus,
-  BCAST_CHANNEL,
-} from '../../../apps/main/channels/chat-bus.js'
-
-/** fake ioredis — duplicate 는 메시지 핸들러를 캡처하는 fake 구독자를 돌려준다. */
-function fakeRedis() {
-  const handlers = {}
-  const sub = {
-    on: vi.fn((/** @type {string} */ ev, /** @type {Function} */ cb) => {
-      handlers[ev] = cb
-    }),
-    subscribe: vi.fn(async () => 1),
-    quit: vi.fn(async () => 'OK'),
-  }
-  return {
-    duplicate: vi.fn(() => sub),
-    publish: vi.fn(async () => 1),
-    _sub: sub,
-    /** 구독 채널로 메시지 1건 주입. */
-    emit: (raw) => handlers.message?.(BCAST_CHANNEL, raw),
-  }
-}
-
-const app = { fastify: { log: { warn: vi.fn(), error: vi.fn() } } }
-const mkSock = () => ({ isOpen: true, send: vi.fn() })
-
-afterEach(async () => {
-  await closeChatBus()
-  vi.clearAllMocks()
-})
-
-test('publish 는 채널에 envelope 을 직렬화해 PUBLISH 한다', async () => {
-  const redis = fakeRedis()
-  const env = { message: { type: 'chat.msg', payload: { text: 'hi' } } }
-  await publish(/** @type {any} */ (redis), env)
-  expect(redis.publish).toHaveBeenCalledWith(BCAST_CHANNEL, JSON.stringify(env))
-})
-
-test('ensureSubscriber 는 워커당 1회만 구독자를 만든다', () => {
-  const redis = fakeRedis()
-  ensureSubscriber(app, /** @type {any} */ (redis))
-  ensureSubscriber(app, /** @type {any} */ (redis))
-  expect(redis.duplicate).toHaveBeenCalledTimes(1)
-  expect(redis._sub.subscribe).toHaveBeenCalledWith(BCAST_CHANNEL)
-})
-
-test('구독 메시지를 로컬 연결에 전달하고 exceptSessionIds 는 건너뛴다', () => {
-  const redis = fakeRedis()
-  ensureSubscriber(app, /** @type {any} */ (redis))
-  const a = mkSock()
-  const b = mkSock()
-  registerConn(a, { sessionId: 'sA', userName: 'a' })
-  registerConn(b, { sessionId: 'sB', userName: 'b' })
-
-  redis.emit(JSON.stringify({ message: { type: 'chat.msg', payload: { text: 'yo' } }, exceptSessionIds: ['sA'] }))
-
-  expect(a.send).not.toHaveBeenCalled() // 제외됨.
-  expect(b.send).toHaveBeenCalledWith({ type: 'chat.msg', payload: { text: 'yo' } })
-})
-
-test('except 없으면 모든 로컬 연결에 전달(본인 echo 포함)', () => {
-  const redis = fakeRedis()
-  ensureSubscriber(app, /** @type {any} */ (redis))
-  const a = mkSock()
-  registerConn(a, { sessionId: 'sA', userName: 'a' })
-  redis.emit(JSON.stringify({ message: { type: 'chat.msg', payload: { text: 'echo' } } }))
-  expect(a.send).toHaveBeenCalledWith({ type: 'chat.msg', payload: { text: 'echo' } })
-})
-
-test('unregister 된 연결에는 전달하지 않는다', () => {
-  const redis = fakeRedis()
-  ensureSubscriber(app, /** @type {any} */ (redis))
-  const a = mkSock()
-  registerConn(a, { sessionId: 'sA', userName: 'a' })
-  unregisterConn(a)
-  redis.emit(JSON.stringify({ message: { type: 'chat.msg', payload: {} } }))
-  expect(a.send).not.toHaveBeenCalled()
-})
-
-test('손상 페이로드는 전달하지 않고 warn 로그', () => {
-  const redis = fakeRedis()
-  ensureSubscriber(app, /** @type {any} */ (redis))
-  const a = mkSock()
-  registerConn(a, { sessionId: 'sA', userName: 'a' })
-  redis.emit('{not json')
-  expect(a.send).not.toHaveBeenCalled()
-  expect(app.fastify.log.warn).toHaveBeenCalled()
-})