mega-framework 0.1.0

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

@@ -0,0 +1,85 @@
+// @ts-check
+/**
+ * LogsDemoService 단위 테스트 — 실제 logger emit(레벨 화이트리스트) + 안전 메타데이터만 redis 이력에 저장
+ * (시크릿 제외)하는지 검증한다. MegaTracing.currentTraceIds 를 가짜로, redis native 를 가짜로 둔다.
+ */
+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() } }
+})
+
+import { MegaTracing } from 'mega-framework'
+import { LogsDemoService } from '../../../apps/main/services/logs-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 log = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() }
+  const ctx = { log, requestId: 'req-1', cache: (/** @type {string} */ a) => (a === 'demo' ? { native } : null) }
+  return { ctx, lists, log }
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.mocked(MegaTracing.currentTraceIds).mockReturnValue({ traceId: 'tr', spanId: 'sp' })
+})
+
+describe('LogsDemoService — emit', () => {
+  test('선택 레벨로 실제 logger 를 호출하고 안전 메타만 이력에 저장한다(시크릿 제외)', async () => {
+    const { ctx, lists, log } = makeCtx()
+    const svc = new LogsDemoService(/** @type {any} */ (ctx))
+    const r = await svc.emit('warn', '  hello  ')
+    expect(r).toMatchObject({ level: 'warn', message: 'hello', traceId: 'tr' })
+    expect(log.warn).toHaveBeenCalledTimes(1)
+    // logger payload 엔 시연용 시크릿이 들어가지만(콘솔 redact 시연), redis 이력엔 시크릿이 없어야 한다.
+    const stored = (lists.get(LogsDemoService.RECENT_KEY) ?? []).map((s) => JSON.parse(s))
+    expect(stored[0]).toMatchObject({ level: 'warn', message: 'hello', traceId: 'tr', reqId: 'req-1' })
+    expect(JSON.stringify(stored[0])).not.toContain('password')
+    expect(JSON.stringify(stored[0])).not.toContain('demo-token')
+  })
+
+  test('허용되지 않은 레벨은 info 로 폴백', async () => {
+    const { ctx, log } = makeCtx()
+    const svc = new LogsDemoService(/** @type {any} */ (ctx))
+    const r = await svc.emit('fatal', 'x')
+    expect(r.level).toBe('info')
+    expect(log.info).toHaveBeenCalledTimes(1)
+  })
+
+  test('빈 메시지는 기본 문구로 대체', async () => {
+    const { ctx } = makeCtx()
+    const svc = new LogsDemoService(/** @type {any} */ (ctx))
+    const r = await svc.emit('info', '   ')
+    expect(r.message.length).toBeGreaterThan(0)
+  })
+})
+
+describe('LogsDemoService — snapshot', () => {
+  test('최근 emit 메타 목록 + 레벨 화이트리스트를 돌려준다', async () => {
+    const { ctx } = makeCtx()
+    const svc = new LogsDemoService(/** @type {any} */ (ctx))
+    await svc.emit('info', 'a')
+    await svc.emit('error', 'b')
+    const snap = await svc.snapshot()
+    expect(snap.recent).toHaveLength(2)
+    expect(snap.recent[0]).toMatchObject({ message: 'b', level: 'error' })
+    expect(snap.levels).toEqual(['debug', 'info', 'warn', 'error'])
+  })
+})

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

@@ -0,0 +1,90 @@
+// @ts-check
+/**
+ * MetricsDemoService 단위 테스트 — Prometheus exposition 텍스트 파서(parseLine/parse/sum)와 snapshot 요약을
+ * 검증한다. snapshot 은 collectCluster() 를 가짜로 갈음해 redis·실 메트릭 없이 집계 로직만 본다.
+ */
+import { describe, test, expect, vi } from 'vitest'
+
+vi.mock('mega-framework', async (importOriginal) => {
+  const actual = /** @type {any} */ (await importOriginal())
+  return { ...actual, collectCluster: vi.fn() }
+})
+
+import { collectCluster } from 'mega-framework'
+import { MetricsDemoService } from '../../../apps/main/services/metrics-demo-service.js'
+
+const SAMPLE = [
+  '# HELP mega_http_requests_total total',
+  '# TYPE mega_http_requests_total counter',
+  'mega_http_requests_total{method="GET",route="/",status_code="200",app="main"} 3',
+  'mega_http_requests_total{method="GET",route="/users",status_code="200",app="main"} 5',
+  'mega_http_requests_total{method="POST",route="/users",status_code="400",app="main"} 1',
+  'mega_http_requests_total{method="GET",route="/x",status_code="500",app="main"} 2',
+  'mega_jobs_total{queue="email",event="enqueued"} 4',
+  'mega_jobs_total{queue="email",event="processed"} 3',
+  'mega_jobs_total{queue="email",event="dlq"} 1',
+  'mega_ws_messages_total{type="message.send",ns="/ws/chat",app="main"} 7',
+  'mega_process_memory_bytes{kind="heapUsed"} 10485760',
+  'mega_process_memory_bytes{kind="rss"} 52428800',
+  'mega_process_uptime_seconds 123.5',
+  'mega_process_cpu_seconds_total{type="user"} 1.5',
+  'mega_process_cpu_seconds_total{type="system"} 0.5',
+].join('\n')
+
+function makeCtx() {
+  return { log: { debug() {} } }
+}
+
+describe('MetricsDemoService — parseLine', () => {
+  test('주석/빈 줄은 null, 라벨 있는/없는 샘플은 파싱된다', () => {
+    expect(MetricsDemoService.parseLine('# HELP x')).toBeNull()
+    expect(MetricsDemoService.parseLine('   ')).toBeNull()
+    expect(MetricsDemoService.parseLine('mega_x 0')).toEqual({ name: 'mega_x', labels: {}, value: 0 })
+    expect(MetricsDemoService.parseLine('mega_x{a="1",b="y"} 4.5')).toEqual({
+      name: 'mega_x',
+      labels: { a: '1', b: 'y' },
+      value: 4.5,
+    })
+  })
+
+  test('값이 숫자가 아니면 null', () => {
+    expect(MetricsDemoService.parseLine('mega_x abc')).toBeNull()
+  })
+})
+
+describe('MetricsDemoService — sum', () => {
+  test('패밀리 합산 + 라벨 필터', () => {
+    const samples = MetricsDemoService.parse(SAMPLE)
+    expect(MetricsDemoService.sum(samples, 'mega_http_requests_total')).toBe(11)
+    expect(MetricsDemoService.sum(samples, 'mega_jobs_total', (l) => l.event === 'enqueued')).toBe(4)
+    expect(MetricsDemoService.sum(samples, 'mega_process_cpu_seconds_total')).toBe(2)
+  })
+})
+
+describe('MetricsDemoService — snapshot', () => {
+  test('collect() 결과를 HTTP/잡/WS/process 요약으로 정리한다', async () => {
+    vi.mocked(collectCluster).mockResolvedValue(SAMPLE)
+    const svc = new MetricsDemoService(/** @type {any} */ (makeCtx()))
+    const snap = await svc.snapshot()
+
+    expect(snap.enabled).toBe(true)
+    expect(snap.http.total).toBe(11)
+    expect(snap.http.byClass).toEqual({ '2xx': 8, '3xx': 0, '4xx': 1, '5xx': 2 })
+    expect(snap.http.topRoutes[0]).toEqual({ route: '/users', count: 6 })
+    expect(snap.jobs).toEqual({ enqueued: 4, processed: 3, retried: 0, dlq: 1 })
+    expect(snap.ws.total).toBe(7)
+    expect(snap.ws.byType).toEqual([{ type: 'message.send', count: 7 }])
+    expect(snap.process.heapUsedMb).toBeCloseTo(10, 5)
+    expect(snap.process.rssMb).toBeCloseTo(50, 5)
+    expect(snap.process.uptimeSec).toBe(123.5)
+    expect(snap.process.cpuSec).toBe(2)
+  })
+
+  test('메트릭 OFF(collect 빈 문자열)면 enabled=false', async () => {
+    vi.mocked(collectCluster).mockResolvedValue('')
+    const svc = new MetricsDemoService(/** @type {any} */ (makeCtx()))
+    const snap = await svc.snapshot()
+    expect(snap.enabled).toBe(false)
+    expect(snap.http.total).toBe(0)
+  })
+})

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

@@ -0,0 +1,68 @@
+// @ts-check
+/**
+ * NoteService 단위 테스트(ADR-157) — 모델(static)을 스파이로 갈음해 mongo 없이 비즈니스 로직(검증·404)을
+ * 검증한다. 실 mongo CRUD 는 demo-flow.integration.test.js 가 커버한다.
+ */
+import { describe, test, expect, vi, afterEach } from 'vitest'
+import { NoteService } from '../../../apps/main/services/note-service.js'
+import { Note } from '../../../apps/main/models/note.js'
+
+/** @returns {NoteService} */
+function makeService() {
+  return new NoteService(/** @type {any} */ ({ log: { debug() {} } }))
+}
+
+afterEach(() => vi.restoreAllMocks())
+
+describe('NoteService', () => {
+  test('list → Note.list 위임', async () => {
+    vi.spyOn(Note, 'list').mockResolvedValue([/** @type {any} */ ({ id: 'a', title: 't', body: 'b' })])
+    expect(await makeService().list()).toEqual([{ id: 'a', title: 't', body: 'b' }])
+  })
+
+  test('get — 존재하면 반환', async () => {
+    vi.spyOn(Note, 'findById').mockResolvedValue(/** @type {any} */ ({ id: 'x', title: 't' }))
+    expect(await makeService().get('x')).toEqual({ id: 'x', title: 't' })
+  })
+
+  test('get — 없으면 MegaNotFoundError(404)', async () => {
+    vi.spyOn(Note, 'findById').mockResolvedValue(null)
+    await expect(makeService().get('nope')).rejects.toMatchObject({ status: 404, code: 'note.not_found' })
+  })
+
+  test('create — 제목 누락 시 MegaValidationError(400)', async () => {
+    await expect(makeService().create({ title: '   ', body: 'b' })).rejects.toMatchObject({ status: 400, code: 'note.invalid' })
+  })
+
+  test('create — 제목 길이 초과 시 MegaValidationError(400)', async () => {
+    const long = 'x'.repeat(NoteService.MAX_TITLE + 1)
+    await expect(makeService().create({ title: long })).rejects.toMatchObject({ status: 400, code: 'note.invalid' })
+  })
+
+  test('create — 정상 생성(trim 후 위임)', async () => {
+    const spy = vi.spyOn(Note, 'create').mockResolvedValue(/** @type {any} */ ({ id: 'n1', title: 'memo', body: 'hi' }))
+    const r = await makeService().create({ title: ' memo ', body: ' hi ' })
+    expect(r).toMatchObject({ id: 'n1', title: 'memo' })
+    expect(spy).toHaveBeenCalledWith({ title: 'memo', body: 'hi' })
+  })
+
+  test('update — 없으면 MegaNotFoundError(404)', async () => {
+    vi.spyOn(Note, 'update').mockResolvedValue(null)
+    await expect(makeService().update('gone', { title: 't' })).rejects.toMatchObject({ status: 404, code: 'note.not_found' })
+  })
+
+  test('update — 정상 수정', async () => {
+    vi.spyOn(Note, 'update').mockResolvedValue(/** @type {any} */ ({ id: 'n1', title: 'new' }))
+    expect(await makeService().update('n1', { title: ' new ', body: '' })).toMatchObject({ id: 'n1', title: 'new' })
+  })
+
+  test('remove — 없으면 MegaNotFoundError(404)', async () => {
+    vi.spyOn(Note, 'remove').mockResolvedValue(false)
+    await expect(makeService().remove('gone')).rejects.toMatchObject({ status: 404, code: 'note.not_found' })
+  })
+
+  test('remove — 성공 시 { deleted: true }', async () => {
+    vi.spyOn(Note, 'remove').mockResolvedValue(true)
+    expect(await makeService().remove('n1')).toEqual({ deleted: true })
+  })
+})

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

@@ -0,0 +1,121 @@
+// @ts-check
+/**
+ * PerfService 단위 테스트(ADR-174) — 통계 함수(percentile/summarize)의 정확성과, 인프라가 필요 없는
+ * in-process 시나리오(http/json/crypto)의 실행·clamp·검증을 다룬다. 어댑터 왕복 시나리오(db/cache/session)는
+ * 실 백엔드 의존이라 통합/수동 검증 몫이다(perf-service 는 ctx.db/cache/app 접근만 위임).
+ */
+import { describe, test, expect } from 'vitest'
+import { PerfService, percentile, summarize, SCENARIO_LIMITS } from '../../../apps/main/services/perf-service.js'
+
+/** 로그만 있는 최소 ctx — in-process 시나리오는 db/cache/app 을 안 건드린다. */
+function makeCtx() {
+  return { log: { debug() {}, warn() {} } }
+}
+
+describe('percentile', () => {
+  test('nearest-rank — 정렬된 1..10 에서 표준 백분위', () => {
+    const sorted = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+    expect(percentile(sorted, 50)).toBe(5)
+    expect(percentile(sorted, 90)).toBe(9)
+    expect(percentile(sorted, 95)).toBe(10)
+    expect(percentile(sorted, 99)).toBe(10)
+    expect(percentile(sorted, 100)).toBe(10)
+  })
+
+  test('단일 표본은 모든 백분위가 그 값', () => {
+    expect(percentile([42], 50)).toBe(42)
+    expect(percentile([42], 99)).toBe(42)
+  })
+
+  test('빈 표본은 0', () => {
+    expect(percentile([], 50)).toBe(0)
+  })
+})
+
+describe('summarize', () => {
+  test('avg/min/max/ok/fail 과 백분위를 정확히 계산', () => {
+    const samples = [10, 20, 30, 40, 50] // 미정렬 입력도 정렬해 처리
+    const s = summarize(samples, 100, 5)
+    expect(s.ok).toBe(5)
+    expect(s.fail).toBe(0)
+    expect(s.min).toBe(10)
+    expect(s.max).toBe(50)
+    expect(s.avg).toBe(30)
+    expect(s.p50).toBe(30)
+    expect(s.durationMs).toBe(100)
+    // rps = total(5) / wallSec(0.1) = 50
+    expect(s.rps).toBe(50)
+  })
+
+  test('성공 표본 < total 이면 fail 로 채워진다', () => {
+    const s = summarize([5, 5], 50, 4)
+    expect(s.ok).toBe(2)
+    expect(s.fail).toBe(2)
+  })
+
+  test('표본 0 이면 통계는 0, fail=total', () => {
+    const s = summarize([], 10, 3)
+    expect(s.ok).toBe(0)
+    expect(s.fail).toBe(3)
+    expect(s.avg).toBe(0)
+    expect(s.p99).toBe(0)
+  })
+})
+
+describe('PerfService.run — in-process 시나리오', () => {
+  test('http.echo — 전부 성공, 통계 필드 존재', async () => {
+    const svc = new PerfService(makeCtx())
+    const r = await svc.run({ scenario: 'http.echo', iterations: 50 })
+    expect(r.scenario).toBe('http.echo')
+    expect(r.iterations).toBe(50)
+    expect(r.ok).toBe(50)
+    expect(r.fail).toBe(0)
+    expect(r.rps).toBeGreaterThan(0)
+    expect(typeof r.p95).toBe('number')
+    expect(r.clamped).toBeUndefined()
+  })
+
+  test('http.jsonLarge — payloadSize 반영, 전부 성공', async () => {
+    const svc = new PerfService(makeCtx())
+    const r = await svc.run({ scenario: 'http.jsonLarge', iterations: 20, payloadSize: 2048 })
+    expect(r.payloadSize).toBe(2048)
+    expect(r.ok).toBe(20)
+    expect(r.fail).toBe(0)
+  })
+
+  test('crypto.aspRoundtrip — encrypt→decrypt 왕복 전부 성공', async () => {
+    const svc = new PerfService(makeCtx())
+    const r = await svc.run({ scenario: 'crypto.aspRoundtrip', iterations: 30, payloadSize: 128 })
+    expect(r.ok).toBe(30)
+    expect(r.fail).toBe(0)
+  })
+})
+
+describe('PerfService.run — clamp + 검증', () => {
+  test('crypto.hash — 동시성이 시나리오 상한(4)으로 clamp 되고 결과에 표시', async () => {
+    const svc = new PerfService(makeCtx())
+    // iterations 3 은 상한(500) 이내라 그대로, concurrency 8 은 상한(4)으로 줄어든다.
+    const r = await svc.run({ scenario: 'crypto.hash', iterations: 3, concurrency: 8 })
+    expect(r.iterations).toBe(3)
+    expect(r.concurrency).toBe(4)
+    expect(r.ok).toBe(3)
+    expect(r.clamped).toBeDefined()
+    expect(r.clamped.concurrency).toEqual({ requested: 8, applied: 4 })
+    expect(r.clamped.iterations).toBeUndefined()
+  })
+
+  test('crypto.hash — concurrency 미지정 시 시나리오 디폴트(1) 적용, clamp 없음', async () => {
+    const svc = new PerfService(makeCtx())
+    const r = await svc.run({ scenario: 'crypto.hash', iterations: 2 })
+    expect(r.concurrency).toBe(SCENARIO_LIMITS['crypto.hash'].defConc)
+    expect(r.concurrency).toBe(1)
+    expect(r.clamped).toBeUndefined()
+  })
+
+  test('미지원 시나리오는 MegaValidationError', async () => {
+    const svc = new PerfService(makeCtx())
+    await expect(svc.run({ scenario: 'bogus.scenario', iterations: 1 })).rejects.toMatchObject({
+      code: 'perf.unknown_scenario',
+    })
+  })
+})

package/sample/crud/test/apps/main/perf.integration.test.js

@@ -0,0 +1,202 @@
+// @ts-check
+/**
+ * /perf 벤치마크 통합 테스트(ADR-174) — 실 postgres+mongo+redis(캐시·세션)로 sample/crud 를 부팅하고
+ * 인증된 HTTP 경로로 각 어댑터 시나리오를 실행한다. in-process 시나리오(http/json/crypto)는 단위 테스트가
+ * 커버하므로, 여기서는 어댑터 왕복(db.pg/db.mongo/cache.redis/session)과 스키마 검증·가드·teardown 을 본다.
+ *
+ * 인프라(pg·redis·mongo) env 가 없으면 통째로 skip 한다. 필요한 env(.env): DATABASE_URL·REDIS_SESSION_URL·
+ * REDIS_RATE_URL·REDIS_DEMO_URL·MONGO_URL·SESSION_SECRET.
+ */
+import { describe, test, expect, beforeAll, afterAll } from 'vitest'
+import { bootApp, MegaShutdown } from 'mega-framework'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { User } from '../../../apps/main/models/user.js'
+
+// 프로젝트 루트(mega.config.js 가 있는 sample/crud) — 이 파일 기준 상위 4단계.
+const PROJECT = resolve(dirname(fileURLToPath(import.meta.url)), '../../..')
+
+// .env 가 DATABASE_URL 대신 PG_URL 만 줄 수 있으므로(로컬 관례) 매핑한다.
+if (!process.env.DATABASE_URL && process.env.PG_URL) process.env.DATABASE_URL = process.env.PG_URL
+
+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,
+)
+const d = hasInfra ? describe : describe.skip
+
+/** set-cookie 를 누적 쿠키 jar 에 반영(maxAge=0 → 삭제). @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} Cookie 헤더. */
+function cookieHeader(jar) {
+  return Object.entries(jar).map(([k, v]) => `${k}=${v}`).join('; ')
+}
+
+/** 렌더된 폼 HTML 에서 hidden `_csrf` 토큰을 뽑는다. @param {string} html @returns {string} */
+function csrfFrom(html) {
+  const m = /name="_csrf" value="([^"]+)"/.exec(html)
+  if (!m) throw new Error('csrf token not found in form HTML')
+  return m[1]
+}
+
+/** urlencoded 폼 바디 직렬화. @param {Record<string,string>} fields @returns {string} */
+function form(fields) {
+  return Object.entries(fields).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&')
+}
+
+d('/perf 벤치마크 E2E — sample/crud 실 pg+mongo+redis (ADR-174)', () => {
+  /** @type {Awaited<ReturnType<typeof bootApp>>} */
+  let boot
+  /** @type {any} */
+  let fastify
+  /** @type {Record<string,string>} 로그인 세션 쿠키 jar. */
+  const jar = {}
+  const EMAIL = `itest-perf-${Date.now()}@example.com`
+  const PASSWORD = 'secret-pass-123'
+  const NAME = 'Perf Tester'
+
+  /**
+   * 인증 쿠키로 /perf/run 을 호출한다(JSON — CSRF 토큰 면제, Origin 헤더 없으면 비브라우저로 통과, ADR-051).
+   * @param {object} body @returns {Promise<any>} inject 응답.
+   */
+  function runPerf(body) {
+    return fastify.inject({
+      method: 'POST',
+      url: '/perf/run',
+      headers: { cookie: cookieHeader(jar), 'content-type': 'application/json', accept: 'application/json' },
+      payload: JSON.stringify(body),
+    })
+  }
+
+  beforeAll(async () => {
+    MegaShutdown._reset()
+    boot = await bootApp(PROJECT, { listen: false })
+    const app = boot.megaApps.find((a) => a.name === 'main')
+    fastify = app?.fastify
+    await fastify.ready()
+    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 User.query('DELETE FROM users WHERE email = $1', [EMAIL])
+
+    // 회원가입 → 자동 로그인 → 세션 쿠키 확보(가드된 /perf 접근에 필요).
+    const regForm = await fastify.inject({ method: 'GET', url: '/register' })
+    applyCookies(regForm, jar)
+    const reg = await fastify.inject({
+      method: 'POST',
+      url: '/register',
+      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
+      payload: form({ _csrf: csrfFrom(regForm.body), name: NAME, email: EMAIL, password: PASSWORD }),
+    })
+    applyCookies(reg, jar)
+  })
+
+  afterAll(async () => {
+    if (!boot) return
+    await User.query('DELETE FROM users WHERE email = $1', [EMAIL]).catch(() => {})
+    await boot.ctx.db('primary').query('DROP TABLE IF EXISTS perf_bench').catch(() => {})
+    await fastify?.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('비로그인: /perf 는 로그인으로 302', async () => {
+    const res = await fastify.inject({ method: 'GET', url: '/perf' })
+    expect(res.statusCode).toBe(302)
+    expect(res.headers.location).toBe('/auth/login')
+  })
+
+  test('로그인 후 /perf UI 200', async () => {
+    const res = await fastify.inject({ method: 'GET', url: '/perf', headers: { cookie: cookieHeader(jar) } })
+    expect(res.statusCode).toBe(200)
+    expect(res.body).toContain('perf.js')
+  })
+
+  test('스키마: 미지원 scenario → 400', async () => {
+    const res = await runPerf({ scenario: 'bogus', iterations: 10 })
+    expect(res.statusCode).toBe(400)
+  })
+
+  test('스키마: iterations 상한 초과 → 400', async () => {
+    const res = await runPerf({ scenario: 'http.echo', iterations: 100001 })
+    expect(res.statusCode).toBe(400)
+  })
+
+  test('http.echo — 200, 전부 성공', async () => {
+    const res = await runPerf({ scenario: 'http.echo', iterations: 100 })
+    expect(res.statusCode).toBe(200)
+    const env = JSON.parse(res.body)
+    expect(env.ok).toBe(true)
+    expect(env.data.ok).toBe(100)
+    expect(env.data.fail).toBe(0)
+    expect(env.data.rps).toBeGreaterThan(0)
+  })
+
+  test('cache.redis.setGet — 실 redis 왕복 전부 성공', async () => {
+    const res = await runPerf({ scenario: 'cache.redis.setGet', iterations: 50, payloadSize: 128 })
+    expect(res.statusCode).toBe(200)
+    const env = JSON.parse(res.body)
+    expect(env.data.ok).toBe(50)
+    expect(env.data.fail).toBe(0)
+  })
+
+  test('session.createRead — 실 세션 스토어 왕복 전부 성공', async () => {
+    const res = await runPerf({ scenario: 'session.createRead', iterations: 50 })
+    expect(res.statusCode).toBe(200)
+    const env = JSON.parse(res.body)
+    expect(env.data.ok).toBe(50)
+    expect(env.data.fail).toBe(0)
+  })
+
+  test('db.pg.insertSelect — 실 postgres 왕복 전부 성공 + teardown 으로 잔여 0', async () => {
+    const res = await runPerf({ scenario: 'db.pg.insertSelect', iterations: 50 })
+    expect(res.statusCode).toBe(200)
+    const env = JSON.parse(res.body)
+    expect(env.data.ok).toBe(50)
+    expect(env.data.fail).toBe(0)
+    // teardown(DELETE WHERE run_id) 후 이 실행이 남긴 행은 없어야 한다(다른 run 부재 시 총 0).
+    const left = await boot.ctx.db('primary').query('SELECT count(*)::int AS c FROM perf_bench')
+    expect(left.rows[0].c).toBe(0)
+  })
+
+  test('db.mongo.insertFind — 실 mongo 왕복 전부 성공 + teardown 으로 잔여 0', async () => {
+    const res = await runPerf({ scenario: 'db.mongo.insertFind', iterations: 50 })
+    expect(res.statusCode).toBe(200)
+    const env = JSON.parse(res.body)
+    expect(env.data.ok).toBe(50)
+    expect(env.data.fail).toBe(0)
+    const left = await boot.ctx.db('mongo').native.collection('perf_bench').countDocuments({})
+    expect(left).toBe(0)
+  })
+
+  test('crypto.hash — 동시성 clamp(>4 → 4) 가 결과에 표시', async () => {
+    const res = await runPerf({ scenario: 'crypto.hash', iterations: 3, concurrency: 16 })
+    expect(res.statusCode).toBe(200)
+    const env = JSON.parse(res.body)
+    expect(env.data.ok).toBe(3)
+    expect(env.data.concurrency).toBe(4)
+    expect(env.data.clamped.concurrency).toEqual({ requested: 16, applied: 4 })
+  })
+})

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

@@ -0,0 +1,98 @@
+// @ts-check
+/**
+ * RedisDemoService 단위 테스트(ADR-157) — 'demo' 캐시 어댑터(get/set/del + native incr/expire/ttl)와
+ * User.count 를 가짜로 갈음해 redis 없이 카운터·캐시 로직을 검증한다. 실 redis 흐름은 통합 테스트가 커버한다.
+ */
+import { describe, test, expect, vi, afterEach } from 'vitest'
+import { RedisDemoService } from '../../../apps/main/services/redis-demo-service.js'
+import { User } from '../../../apps/main/models/user.js'
+
+/**
+ * incr/expire/ttl/get/set/del 을 추적하는 가짜 'demo' 캐시 어댑터 + 이를 돌려주는 ctx 를 만든다.
+ * @param {{ store?: Map<string, any> }} [opts]
+ */
+function makeCtx({ store = new Map() } = {}) {
+  /** @type {Map<string, number>} INCR 카운터(native). */
+  const counters = new Map()
+  const native = {
+    /** @param {string} k */
+    async incr(k) {
+      const n = (counters.get(k) ?? 0) + 1
+      counters.set(k, n)
+      return n
+    },
+    expire: vi.fn(async () => 1),
+    /** @param {string} k */
+    async ttl(k) {
+      return store.has(k) ? 30 : -2
+    },
+  }
+  const cache = {
+    native,
+    /** @param {string} k */
+    async get(k) {
+      return store.has(k) ? store.get(k) : null
+    },
+    /** @param {string} k @param {any} v */
+    async set(k, v) {
+      store.set(k, v)
+    },
+    /** @param {string} k */
+    async del(k) {
+      store.delete(k)
+    },
+  }
+  const ctx = { log: { debug() {} }, cache: (/** @type {string} */ alias) => (alias === 'demo' ? cache : null) }
+  return { ctx, native, store, counters }
+}
+
+afterEach(() => vi.restoreAllMocks())
+
+describe('RedisDemoService — 방문 카운터', () => {
+  test('recordVisit — total/today 가 매 호출마다 1씩 증가하고 당일 키에 EXPIRE 를 건다', async () => {
+    const { ctx, native } = makeCtx()
+    const svc = new RedisDemoService(/** @type {any} */ (ctx))
+    const first = await svc.recordVisit()
+    expect(first).toMatchObject({ total: 1, today: 1 })
+    expect(typeof first.date).toBe('string')
+    const second = await svc.recordVisit()
+    expect(second).toMatchObject({ total: 2, today: 2 })
+    // 당일 키 TTL 재설정이 매 방문마다 호출된다(rolling).
+    expect(native.expire).toHaveBeenCalledWith(RedisDemoService.VISITS_DAY_PREFIX + second.date, RedisDemoService.VISITS_DAY_TTL)
+    expect(native.expire).toHaveBeenCalledTimes(2)
+  })
+})
+
+describe('RedisDemoService — 쿼리 결과 캐시', () => {
+  test('miss → SQL 재계산 후 SET, isHit=false', async () => {
+    const { ctx, store } = makeCtx()
+    vi.spyOn(User, 'count').mockResolvedValue(7)
+    const svc = new RedisDemoService(/** @type {any} */ (ctx))
+    const r = await svc.getUserCountCached()
+    expect(r).toEqual({ value: 7, isHit: false, ttlSeconds: RedisDemoService.USER_COUNT_TTL })
+    // SET 으로 캐시에 채워졌다.
+    expect(store.get(RedisDemoService.USER_COUNT_KEY)).toBe(7)
+  })
+
+  test('hit → 캐시 값 반환, SQL 미실행, isHit=true + 남은 TTL', async () => {
+    const store = new Map([[RedisDemoService.USER_COUNT_KEY, 42]])
+    const { ctx } = makeCtx({ store })
+    const countSpy = vi.spyOn(User, 'count')
+    const svc = new RedisDemoService(/** @type {any} */ (ctx))
+    const r = await svc.getUserCountCached()
+    expect(r).toEqual({ value: 42, isHit: true, ttlSeconds: 30 })
+    expect(countSpy).not.toHaveBeenCalled()
+  })
+
+  test('clearUserCountCache — DEL 후 다음 조회는 miss', async () => {
+    const store = new Map([[RedisDemoService.USER_COUNT_KEY, 99]])
+    const { ctx } = makeCtx({ store })
+    vi.spyOn(User, 'count').mockResolvedValue(3)
+    const svc = new RedisDemoService(/** @type {any} */ (ctx))
+    await svc.clearUserCountCache()
+    expect(store.has(RedisDemoService.USER_COUNT_KEY)).toBe(false)
+    const r = await svc.getUserCountCached()
+    expect(r.isHit).toBe(false)
+    expect(r.value).toBe(3)
+  })
+})