mega-framework 0.1.0

package/sample/crud/test/apps/main/tracing-demo-service.test.js

@@ -0,0 +1,90 @@
+// @ts-check
+/**
+ * TracingDemoService 단위 테스트 — zipkinBase 파생, 현재 trace 기록(있을 때만), snapshot 을 검증한다.
+ * MegaTracing(currentTraceIds/isEnabled)을 가짜로 갈음하고 redis native(lpush/ltrim/lrange)를 가짜로 둔다.
+ */
+import { describe, test, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('mega-framework', async (importOriginal) => {
+  const actual = /** @type {any} */ (await importOriginal())
+  return {
+    ...actual,
+    MegaTracing: { ...actual.MegaTracing, currentTraceIds: vi.fn(), isEnabled: vi.fn() },
+  }
+})
+
+import { MegaTracing } from 'mega-framework'
+import { TracingDemoService } from '../../../apps/main/services/tracing-demo-service.js'
+
+function makeCtx() {
+  /** @type {Map<string, string[]>} */
+  const lists = new Map()
+  const native = {
+    async lpush(/** @type {string} */ k, /** @type {string} */ v) {
+      const arr = lists.get(k) ?? []
+      arr.unshift(v)
+      lists.set(k, arr)
+      return arr.length
+    },
+    ltrim: vi.fn(async (/** @type {string} */ k, /** @type {number} */ _s, /** @type {number} */ stop) => {
+      lists.set(k, (lists.get(k) ?? []).slice(0, stop + 1))
+      return 'OK'
+    }),
+    async lrange(/** @type {string} */ k, /** @type {number} */ s, /** @type {number} */ e) {
+      return (lists.get(k) ?? []).slice(s, e + 1)
+    },
+  }
+  const ctx = { log: { debug() {} }, cache: (/** @type {string} */ a) => (a === 'demo' ? { native } : null) }
+  return { ctx, lists }
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('TracingDemoService — zipkinBase', () => {
+  test('MEGA_OTEL_ZIPKIN_API 에서 /api/v2 를 떼 UI 루트를 만든다', () => {
+    const prev = process.env.MEGA_OTEL_ZIPKIN_API
+    process.env.MEGA_OTEL_ZIPKIN_API = 'http://zip.example:9411/api/v2'
+    expect(TracingDemoService.zipkinBase()).toBe('http://zip.example:9411')
+    delete process.env.MEGA_OTEL_ZIPKIN_API
+    expect(TracingDemoService.zipkinBase()).toBe('http://localhost:9411')
+    if (prev !== undefined) process.env.MEGA_OTEL_ZIPKIN_API = prev
+  })
+})
+
+describe('TracingDemoService — record', () => {
+  test('trace_id 가 있으면 이력 머리에 기록하고 traceId 를 돌려준다', async () => {
+    vi.mocked(MegaTracing.currentTraceIds).mockReturnValue({ traceId: 'abc', spanId: 'def' })
+    const { ctx, lists } = makeCtx()
+    const svc = new TracingDemoService(/** @type {any} */ (ctx))
+    const id = await svc.record('GET /demo/tracing')
+    expect(id).toBe('abc')
+    const stored = (lists.get(TracingDemoService.RECENT_KEY) ?? []).map((s) => JSON.parse(s))
+    expect(stored[0]).toMatchObject({ traceId: 'abc', spanId: 'def', route: 'GET /demo/tracing' })
+  })
+
+  test('trace_id 가 없으면(트레이싱 OFF) no-op + null', async () => {
+    vi.mocked(MegaTracing.currentTraceIds).mockReturnValue(null)
+    const { ctx, lists } = makeCtx()
+    const svc = new TracingDemoService(/** @type {any} */ (ctx))
+    const id = await svc.record('x')
+    expect(id).toBeNull()
+    expect(lists.get(TracingDemoService.RECENT_KEY)).toBeUndefined()
+  })
+})
+
+describe('TracingDemoService — snapshot', () => {
+  test('enabled/current/recent/zipkinBase 를 돌려준다', async () => {
+    vi.mocked(MegaTracing.isEnabled).mockReturnValue(true)
+    vi.mocked(MegaTracing.currentTraceIds).mockReturnValue({ traceId: 't1', spanId: 's1' })
+    const { ctx } = makeCtx()
+    const svc = new TracingDemoService(/** @type {any} */ (ctx))
+    await svc.record('GET /demo/tracing')
+    const snap = await svc.snapshot()
+    expect(snap.enabled).toBe(true)
+    expect(snap.current).toEqual({ traceId: 't1', spanId: 's1' })
+    expect(snap.recent).toHaveLength(1)
+    expect(snap.zipkinBase).toMatch(/^https?:\/\//)
+  })
+})

package/sample/crud/test/apps/main/upload-demo-service.test.js

@@ -0,0 +1,61 @@
+// @ts-check
+/**
+ * UploadDemoService 단위 테스트 — saveUploads 결과 메타(파일명/크기/MIME)를 redis 이력에 기록하고 snapshot
+ * 으로 최신순 반환하는지 검증한다. redis native(lpush/ltrim/lrange)를 가짜로 둔다.
+ */
+import { describe, test, expect, vi } from 'vitest'
+import { UploadDemoService } from '../../../apps/main/services/upload-demo-service.js'
+
+function makeCtx() {
+  /** @type {Map<string, string[]>} */
+  const lists = new Map()
+  const native = {
+    async lpush(/** @type {string} */ k, /** @type {string} */ v) {
+      const arr = lists.get(k) ?? []
+      arr.unshift(v)
+      lists.set(k, arr)
+      return arr.length
+    },
+    ltrim: vi.fn(async (/** @type {string} */ k, /** @type {number} */ _s, /** @type {number} */ stop) => {
+      lists.set(k, (lists.get(k) ?? []).slice(0, stop + 1))
+      return 'OK'
+    }),
+    async lrange(/** @type {string} */ k, /** @type {number} */ s, /** @type {number} */ e) {
+      return (lists.get(k) ?? []).slice(s, e + 1)
+    },
+  }
+  const ctx = { log: { debug() {} }, cache: (/** @type {string} */ a) => (a === 'demo' ? { native } : null) }
+  return { ctx, lists }
+}
+
+describe('UploadDemoService — record', () => {
+  test('파일별로 메타를 이력 머리에 쌓는다(최신이 앞)', async () => {
+    const { ctx, lists } = makeCtx()
+    const svc = new UploadDemoService(/** @type {any} */ (ctx))
+    await svc.record([
+      { filename: 'a.png', bytes: 100, mimetype: 'image/png' },
+      { filename: 'b.pdf', bytes: 200, mimetype: 'application/pdf' },
+    ])
+    const stored = (lists.get(UploadDemoService.RECENT_KEY) ?? []).map((s) => JSON.parse(s))
+    expect(stored[0]).toMatchObject({ filename: 'b.pdf', bytes: 200, mimetype: 'application/pdf' })
+    expect(stored[1]).toMatchObject({ filename: 'a.png' })
+  })
+
+  test('빈 배열은 no-op', async () => {
+    const { ctx, lists } = makeCtx()
+    const svc = new UploadDemoService(/** @type {any} */ (ctx))
+    await svc.record([])
+    expect(lists.get(UploadDemoService.RECENT_KEY)).toBeUndefined()
+  })
+})
+
+describe('UploadDemoService — snapshot', () => {
+  test('최근 업로드 목록을 최신순으로 돌려준다', async () => {
+    const { ctx } = makeCtx()
+    const svc = new UploadDemoService(/** @type {any} */ (ctx))
+    await svc.record([{ filename: 'a.txt', bytes: 10, mimetype: 'text/plain' }])
+    const snap = await svc.snapshot()
+    expect(snap.recent).toHaveLength(1)
+    expect(snap.recent[0]).toMatchObject({ filename: 'a.txt', bytes: 10, mimetype: 'text/plain' })
+  })
+})

package/sample/crud/test/apps/main/user-service.test.js

@@ -0,0 +1,65 @@
+// @ts-check
+/**
+ * UserService 단위 테스트 — 모델(static)을 스파이로 갈음해 DB 없이 비즈니스 로직(검증·404·409 매핑)을 검증.
+ * 실 postgres CRUD 는 레포 E2E(scaffold/sample 검증)에서 확인.
+ */
+import { describe, test, expect, vi, afterEach } from 'vitest'
+import { UserService } from '../../../apps/main/services/user-service.js'
+import { User } from '../../../apps/main/models/user.js'
+
+/** @returns {UserService} */
+function makeService() {
+  return new UserService(/** @type {any} */ ({ log: { debug() {} } }))
+}
+
+afterEach(() => vi.restoreAllMocks())
+
+describe('UserService', () => {
+  test('list → User.list 위임', async () => {
+    vi.spyOn(User, 'list').mockResolvedValue([/** @type {any} */ ({ id: 1, name: 'a', email: 'a@b.c' })])
+    expect(await makeService().list()).toEqual([{ id: 1, name: 'a', email: 'a@b.c' }])
+  })
+
+  test('get — 존재하면 반환', async () => {
+    vi.spyOn(User, 'findById').mockResolvedValue(/** @type {any} */ ({ id: 7 }))
+    expect(await makeService().get(7)).toEqual({ id: 7 })
+  })
+
+  test('get — 없으면 MegaNotFoundError(404)', async () => {
+    vi.spyOn(User, 'findById').mockResolvedValue(null)
+    await expect(makeService().get(99)).rejects.toMatchObject({ status: 404, code: 'user.not_found' })
+  })
+
+  test('create — name/email 누락 시 MegaValidationError(400)', async () => {
+    await expect(makeService().create({ name: '', email: '' })).rejects.toMatchObject({ status: 400, code: 'user.invalid' })
+  })
+
+  test('create — 정상 생성', async () => {
+    const spy = vi.spyOn(User, 'create').mockResolvedValue(/** @type {any} */ ({ id: 1, name: 'a', email: 'a@b.c' }))
+    const r = await makeService().create({ name: ' a ', email: ' a@b.c ' })
+    expect(r).toEqual({ id: 1, name: 'a', email: 'a@b.c' })
+    expect(spy).toHaveBeenCalledWith({ name: 'a', email: 'a@b.c' }) // trim 적용
+  })
+
+  test('create — postgres 23505 → MegaConflictError(409)', async () => {
+    vi.spyOn(User, 'create').mockRejectedValue(Object.assign(new Error('dup'), { code: '23505' }))
+    await expect(makeService().create({ name: 'a', email: 'a@b.c' })).rejects.toMatchObject({ status: 409, code: 'user.email_taken' })
+  })
+
+  test('update — 없으면 404', async () => {
+    vi.spyOn(User, 'update').mockResolvedValue(null)
+    await expect(makeService().update(99, { name: 'x' })).rejects.toMatchObject({ status: 404 })
+  })
+
+  test('update — postgres 23505 → MegaConflictError(409)', async () => {
+    vi.spyOn(User, 'update').mockRejectedValue(Object.assign(new Error('dup'), { code: '23505' }))
+    await expect(makeService().update(1, { email: 'taken@b.c' })).rejects.toMatchObject({ status: 409, code: 'user.email_taken' })
+  })
+
+  test('remove — 없으면 404, 있으면 deleted', async () => {
+    const spy = vi.spyOn(User, 'remove').mockResolvedValue(false)
+    await expect(makeService().remove(99)).rejects.toMatchObject({ status: 404 })
+    spy.mockResolvedValue(true)
+    expect(await makeService().remove(1)).toEqual({ deleted: true })
+  })
+})

package/sample/crud/test/apps/main/ws-chat.integration.test.js

@@ -0,0 +1,232 @@
+// @ts-check
+/**
+ * WS 채팅 + ASP 통합 테스트(ADR-158) — 실 sample/crud 부팅(listen) + ASP `ws` 클라이언트.
+ *
+ * 검증:
+ *   - WS upgrade 세션 인증(makeWsRequireAuth/readSession) — 비로그인 401, 로그인 통과.
+ *   - ASP E: 프레임 round-trip — 클라가 envelope `{v,id,type,ts,payload}` 를 wsEncrypt(E:) 로 보내고
+ *     서버가 복호→dispatch→E: 로 broadcast. (이 ws 클라의 wire 는 WASM MegaSocket `protocol:'envelope'`
+ *     모드와 byte 동일 — frame_encrypt==wsEncrypt, envelope 동일, ADR-160.)
+ *   - broadcast — 두 로그인 클라가 같은 채널에서 서로의 메시지를 받는다.
+ *
+ * 인프라(pg·redis·mongo) + ASP_MASTER_SECRET env 가 없으면 통째로 skip.
+ */
+import { describe, test, expect, beforeAll, afterAll } from 'vitest'
+import { WebSocket } from 'ws'
+import { bootApp, MegaShutdown, createWsMessage } from 'mega-framework'
+import { MegaAspCrypto } from 'mega-framework/lib'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { User } from '../../../apps/main/models/user.js'
+import { closeChatBus, ROSTER_KEY } from '../../../apps/main/channels/chat-bus.js'
+
+const { wsEncrypt, wsDecrypt } = MegaAspCrypto
+const PROJECT = resolve(dirname(fileURLToPath(import.meta.url)), '../../..')
+
+const WS_PATH = '/ws/chat'
+const HOSTNAME = 'localhost' // Host → 호스트 라우팅 + ASP domain 유도값(둘 다 'localhost').
+const UA = 'MegaChatTest/1.0' // ASP 키 유도용 — 연결 헤더와 wsEncrypt 가 동일해야 복호 성공.
+const SECRET = process.env.ASP_MASTER_SECRET ?? ''
+
+const hasInfra = Boolean(
+  process.env.DATABASE_URL &&
+    process.env.REDIS_SESSION_URL &&
+    process.env.REDIS_RATE_URL &&
+    process.env.REDIS_DEMO_URL &&
+    process.env.MONGO_URL &&
+    process.env.SESSION_SECRET &&
+    SECRET,
+)
+const d = hasInfra ? describe : describe.skip
+
+/** set-cookie → 쿠키 jar. @param {any} res @param {Record<string,string>} jar */
+function applyCookies(res, jar) {
+  const raw = res.headers['set-cookie']
+  const arr = Array.isArray(raw) ? raw : raw ? [raw] : []
+  for (const c of arr) {
+    const pair = String(c).split(';')[0]
+    const eq = pair.indexOf('=')
+    if (eq === -1) continue
+    const name = pair.slice(0, eq).trim()
+    const val = pair.slice(eq + 1).trim()
+    if (val === '') delete jar[name]
+    else jar[name] = val
+  }
+}
+
+/** @param {Record<string,string>} jar @returns {string} */
+const cookieHeader = (jar) => Object.entries(jar).map(([k, v]) => `${k}=${v}`).join('; ')
+
+/** @param {string} html @returns {string} */
+function csrfFrom(html) {
+  const m = /name="_csrf" value="([^"]+)"/.exec(html)
+  if (!m) throw new Error('csrf token not found')
+  return m[1]
+}
+
+/** @param {Record<string,string>} fields @returns {string} */
+const form = (fields) =>
+  Object.entries(fields).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&')
+
+/** 회원가입(→자동 로그인)으로 세션 쿠키 jar 확보. @param {any} fastify @param {string} email @returns {Promise<Record<string,string>>} */
+async function registerUser(fastify, email) {
+  const jar = {}
+  const reg = await fastify.inject({ method: 'GET', url: '/register' })
+  applyCookies(reg, jar)
+  const done = await fastify.inject({
+    method: 'POST',
+    url: '/register',
+    headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
+    payload: form({ _csrf: csrfFrom(reg.body), name: `User ${email}`, email, password: 'secret-pass-123' }),
+  })
+  applyCookies(done, jar)
+  return jar
+}
+
+/**
+ * ASP envelope ws 클라이언트(WASM `protocol:'envelope'` 모드 byte-equivalent).
+ * @param {number} port @param {Record<string,string>} jar
+ * @returns {Promise<any>}
+ */
+function openClient(port, jar) {
+  const url = `ws://${HOSTNAME}:${port}${WS_PATH}`
+  const socket = /** @type {any} */ (
+    new WebSocket(url, /** @type {any} */ ({ headers: { 'user-agent': UA, cookie: cookieHeader(jar) } }))
+  )
+  /** @type {object[]} */ const queue = []
+  /** @type {Array<(m: object) => void>} */ const waiters = []
+  socket.lastEncrypted = false
+  socket.on('message', (/** @type {Buffer} */ data) => {
+    const frame = data.toString('utf8')
+    socket.lastEncrypted = frame.startsWith('E:')
+    const plain = frame.startsWith('E:')
+      ? wsDecrypt(SECRET, HOSTNAME, WS_PATH, UA, frame.slice(2))
+      : frame.startsWith('P:')
+        ? frame.slice(2)
+        : frame
+    const msg = JSON.parse(plain)
+    const w = waiters.shift()
+    if (w) w(msg)
+    else queue.push(msg)
+  })
+  /** 다음 메시지 1건(평문 envelope). */
+  socket.next = () =>
+    new Promise((res) => {
+      const m = queue.shift()
+      if (m !== undefined) res(m)
+      else waiters.push(res)
+    })
+  /** type 이 t 인 다음 메시지까지 소비. @param {string} t */
+  socket.nextOf = async (t) => {
+    for (let i = 0; i < 20; i++) {
+      const m = await socket.next()
+      if (m.type === t) return m
+    }
+    throw new Error(`message type '${t}' not received`)
+  }
+  /** E: 암호 envelope 송신. @param {string} type @param {object} payload */
+  socket.sendChat = (type, payload) => {
+    const env = createWsMessage({ type, payload })
+    socket.send(`E:${wsEncrypt(SECRET, HOSTNAME, WS_PATH, UA, JSON.stringify(env))}`)
+  }
+  return new Promise((res, rej) => {
+    socket.once('open', () => res(socket))
+    socket.once('error', rej)
+  })
+}
+
+d('WS 채팅 + ASP E2E — sample/crud 실 인프라 (ADR-158)', () => {
+  /** @type {Awaited<ReturnType<typeof bootApp>>} */ let boot
+  /** @type {any} */ let fastify
+  /** @type {number} */ let port
+  /** @type {Record<string,string>} */ let jarA
+  /** @type {Record<string,string>} */ let jarB
+  const emailA = `ws-a-${Date.now()}@example.com`
+  const emailB = `ws-b-${Date.now()}@example.com`
+
+  beforeAll(async () => {
+    MegaShutdown._reset()
+    boot = await bootApp(PROJECT, { listen: true, port: 0, host: '127.0.0.1' })
+    const app = boot.megaApps.find((a) => a.name === 'main')
+    fastify = app?.fastify
+    port = /** @type {any} */ (boot.server)._httpServer.address().port
+    await User.query(
+      'CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE, created_at TIMESTAMPTZ NOT NULL DEFAULT now())',
+    )
+    await User.query('ALTER TABLE users ADD COLUMN IF NOT EXISTS password_hash TEXT')
+    await User.query('ALTER TABLE users ADD COLUMN IF NOT EXISTS last_login_at TIMESTAMPTZ')
+    await boot.ctx.cache('demo').del(ROSTER_KEY) // 결정적 접속자 명단.
+    jarA = await registerUser(fastify, emailA)
+    jarB = await registerUser(fastify, emailB)
+  })
+
+  afterAll(async () => {
+    if (!boot) return
+    await closeChatBus() // redis pub/sub 구독 연결 정리(이벤트루프 누수 방지).
+    await User.query('DELETE FROM users WHERE email = ANY($1)', [[emailA, emailB]]).catch(() => {})
+    await boot.ctx.cache('demo').del(ROSTER_KEY).catch(() => {})
+    await boot.server.close().catch(() => {})
+    const app = boot.megaApps.find((a) => a.name === 'main')
+    await app?.sessionStore?.disconnect().catch(() => {})
+    await boot.ctx.cache('rate').disconnect().catch(() => {})
+    await boot.ctx.cache('demo').disconnect().catch(() => {})
+    await boot.ctx.db('mongo').disconnect().catch(() => {})
+    await boot.ctx.db('primary').disconnect().catch(() => {})
+    MegaShutdown._reset()
+  })
+
+  test('비로그인 WS upgrade 는 401 로 거부된다', async () => {
+    const url = `ws://${HOSTNAME}:${port}${WS_PATH}`
+    const status = await new Promise((res, rej) => {
+      const s = new WebSocket(url, /** @type {any} */ ({ headers: { 'user-agent': UA } }))
+      s.on('unexpected-response', (_req, response) => {
+        res(response.statusCode)
+        s.terminate()
+      })
+      s.on('open', () => {
+        s.close()
+        rej(new Error('로그인 없이 연결되면 안 됨'))
+      })
+      s.on('error', () => {}) // unexpected-response 뒤 따라오는 소켓 에러는 무시.
+    })
+    expect(status).toBe(401)
+  })
+
+  test('로그인 클라는 연결 직후 ASP E: 로 chat.history 를 받는다', async () => {
+    const a = await openClient(port, jarA)
+    try {
+      const history = await a.nextOf('chat.history')
+      expect(a.lastEncrypted).toBe(true) // 수신 프레임이 E:(암호화) 였음.
+      expect(history.payload.me.userId).toBeTruthy()
+      expect(Array.isArray(history.payload.items)).toBe(true)
+      expect(history.payload.online).toBeGreaterThanOrEqual(1)
+      // roster(cluster-wide redis HASH) 에 내 이름이 있고, 워커 PID 가 실린다.
+      expect(history.payload.members).toContain(history.payload.me.userName)
+      expect(typeof history.payload.workerPid).toBe('number')
+    } finally {
+      a.close()
+    }
+  })
+
+  test('broadcast — A 가 보낸 메시지를 A(echo)와 B 가 모두 ASP E: 로 받는다', async () => {
+    const b = await openClient(port, jarB)
+    await b.nextOf('chat.history')
+    const a = await openClient(port, jarA)
+    await a.nextOf('chat.history')
+    // A 입장 → B 는 presence(join) 수신.
+    const join = await b.nextOf('chat.presence')
+    expect(join.payload.event).toBe('join')
+
+    const text = `hello-${Date.now()}`
+    a.sendChat('chat.send', { text })
+
+    const onA = await a.nextOf('chat.msg')
+    const onB = await b.nextOf('chat.msg')
+    expect(onA.payload.text).toBe(text)
+    expect(onB.payload.text).toBe(text)
+    expect(a.lastEncrypted && b.lastEncrypted).toBe(true) // 양쪽 모두 E: 암호 수신.
+
+    a.close()
+    b.close()
+  })
+})

package/sample/crud/vitest.config.js

@@ -0,0 +1,8 @@
+// @ts-check
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.js', 'apps/**/*.test.js', 'shared/**/*.test.js'],
+  },
+})