mega-framework 0.1.0

package/sample/crud/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "sample-crud",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "NODE_ENV=development mega start",
+    "start": "NODE_ENV=production mega start",
+    "migrate": "mega migrate",
+    "migrate:down": "mega migrate:down",
+    "migrate:status": "mega migrate:status",
+    "scheduler": "mega scheduler",
+    "worker": "mega worker",
+    "test": "mega test"
+  },
+  "dependencies": {
+    "highlight.js": "^11.11.1",
+    "marked": "^18.0.5",
+    "mega-framework": "file:../.."
+  },
+  "devDependencies": {
+    "concurrently": "^9.0.0",
+    "vitest": "^4.0.0"
+  }
+}

package/sample/crud/test/apps/main/auth-flow.integration.test.js

@@ -0,0 +1,177 @@
+// @ts-check
+/**
+ * 인증 흐름 통합 테스트(ADR-155) — 실 redis(세션·brute-force) + postgres 로 sample/crud 를 부팅하고
+ * HTTP 전 경로(회원가입→자동로그인→보호자원→로그아웃→차단, 잘못된 비밀번호→brute-force 잠금)를 검증한다.
+ *
+ * 인프라(redis·pg) env 가 없으면 통째로 skip 한다(단위 테스트는 `auth-service.test.js` 가 인프라 없이 커버).
+ * 실행에 필요한 env(.env): DATABASE_URL(또는 PG_URL)·REDIS_SESSION_URL·REDIS_RATE_URL·SESSION_SECRET.
+ *
+ * CSRF(쿠키 double-submit, ADR-051)가 켜져 있어 POST 마다 폼 토큰+쿠키를 왕복시킨다 — 실제 브라우저 폼과
+ * 같은 경로다. 세션 쿠키(mega.sid)도 누적 쿠키 jar 로 왕복한다.
+ */
+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.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('인증 흐름 E2E — sample/crud 실 redis+pg (ADR-155)', () => {
+  /** @type {Awaited<ReturnType<typeof bootApp>>} */
+  let boot
+  /** @type {any} */
+  let fastify
+  const EMAIL = `itest-auth-${Date.now()}@example.com`
+  const PASSWORD = 'secret-pass-123'
+  const NAME = 'Auth Tester'
+
+  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() // onReady → 세션 store connect(실 redis).
+    // 스키마 보장(마이그레이션과 동치, 멱등) — 테스트 전제. 실제 운영은 `mega migrate` 가 적용한다.
+    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])
+  })
+
+  afterAll(async () => {
+    if (!boot) return
+    await User.query('DELETE FROM users WHERE email = $1', [EMAIL]).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.db('primary').disconnect().catch(() => {})
+    MegaShutdown._reset()
+  })
+
+  test('비로그인: 랜딩(/)은 공개 200, /admin/users 는 로그인으로 302, /users API 는 401', async () => {
+    const home = await fastify.inject({ method: 'GET', url: '/' })
+    expect(home.statusCode).toBe(200)
+
+    const admin = await fastify.inject({ method: 'GET', url: '/admin/users' })
+    expect(admin.statusCode).toBe(302)
+    expect(admin.headers.location).toBe('/auth/login')
+
+    const api = await fastify.inject({ method: 'GET', url: '/users' })
+    expect(api.statusCode).toBe(401)
+    expect(api.json().error?.code).toBe('auth.required')
+  })
+
+  test('회원가입 → 자동 로그인 → 보호자원 접근 → API 접근 → 로그아웃 → 재차단', async () => {
+    /** @type {Record<string,string>} */
+    const jar = {}
+
+    // 1) 회원가입 폼 GET — _csrf 쿠키 + 토큰 확보.
+    const regForm = await fastify.inject({ method: 'GET', url: '/register' })
+    expect(regForm.statusCode).toBe(200)
+    applyCookies(regForm, jar)
+    const regToken = csrfFrom(regForm.body)
+
+    // 2) 회원가입 POST — 성공 시 자동 로그인(세션 발급) + /admin/users 로 302.
+    const reg = await fastify.inject({
+      method: 'POST',
+      url: '/register',
+      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
+      payload: form({ _csrf: regToken, name: NAME, email: EMAIL, password: PASSWORD }),
+    })
+    expect(reg.statusCode).toBe(302)
+    expect(reg.headers.location).toBe('/admin/users?notice=registered')
+    applyCookies(reg, jar)
+    expect(jar['mega.sid']).toBeTruthy() // 세션 쿠키 발급됨.
+
+    // 3) 보호 자원 GET — 세션 쿠키로 통과(200), 본문에 로그인 사용자 이름 표시.
+    const admin = await fastify.inject({ method: 'GET', url: '/admin/users', headers: { cookie: cookieHeader(jar) } })
+    expect(admin.statusCode).toBe(200)
+    expect(admin.body).toContain(NAME)
+    applyCookies(admin, jar)
+
+    // 4) JSON API GET — 같은 세션으로 통과(envelope ok).
+    const api = await fastify.inject({ method: 'GET', url: '/users', headers: { cookie: cookieHeader(jar) } })
+    expect(api.statusCode).toBe(200)
+    expect(api.json().ok).toBe(true)
+
+    // 5) 로그아웃 POST — 보호 페이지에서 받은 _csrf 토큰으로.
+    const logoutToken = csrfFrom(admin.body)
+    const logout = await fastify.inject({
+      method: 'POST',
+      url: '/auth/logout',
+      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
+      payload: form({ _csrf: logoutToken }),
+    })
+    expect(logout.statusCode).toBe(302)
+    expect(logout.headers.location).toBe('/auth/login?notice=logged_out')
+    applyCookies(logout, jar)
+
+    // 6) 로그아웃 후 보호 자원 재차단(302 → 로그인).
+    const blocked = await fastify.inject({ method: 'GET', url: '/admin/users', headers: { cookie: cookieHeader(jar) } })
+    expect(blocked.statusCode).toBe(302)
+    expect(blocked.headers.location).toBe('/auth/login')
+  })
+
+  test('잘못된 비밀번호 반복 → brute-force 잠금(423)', async () => {
+    const lockEmail = `itest-lock-${Date.now()}@example.com`
+    // 잠금 임계(기본 maxAttempts=5)까지 틀린 로그인을 반복한다. 없는 계정이라도 brute-force 는 subject(IP:email) 기준.
+    let lastStatus = 0
+    for (let i = 0; i < 6; i++) {
+      /** @type {Record<string,string>} */
+      const jar = {}
+      const formPage = await fastify.inject({ method: 'GET', url: '/auth/login' })
+      applyCookies(formPage, jar)
+      const token = csrfFrom(formPage.body)
+      const res = await fastify.inject({
+        method: 'POST',
+        url: '/auth/login',
+        headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
+        payload: form({ _csrf: token, email: lockEmail, password: 'definitely-wrong' }),
+      })
+      lastStatus = res.statusCode
+    }
+    // 임계 도달 후에는 잠금(423)으로 응답한다(401 invalid 가 아니라).
+    expect(lastStatus).toBe(423)
+  })
+})

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

@@ -0,0 +1,93 @@
+// @ts-check
+/**
+ * AuthService 단위 테스트(ADR-155) — 모델(static)을 스파이로 갈음해 DB 없이 비즈니스 로직을 검증한다.
+ * 해싱은 실 MegaHash(scrypt)를 그대로 써서 register→authenticate 왕복이 진짜로 맞물리는지 본다(인프라 불필요).
+ */
+import { describe, test, expect, vi, afterEach } from 'vitest'
+import { AuthService } from '../../../apps/main/services/auth-service.js'
+import { User } from '../../../apps/main/models/user.js'
+
+/** @returns {AuthService} */
+function makeService() {
+  return new AuthService(/** @type {any} */ ({ log: { debug() {} } }))
+}
+
+afterEach(() => vi.restoreAllMocks())
+
+describe('AuthService.register', () => {
+  test('유효 입력 → 해시 후 User.register 위임(평문 미저장)', async () => {
+    const reg = vi
+      .spyOn(User, 'register')
+      .mockResolvedValue(/** @type {any} */ ({ id: 1, name: 'Ada', email: 'ada@x.io', created_at: 't' }))
+    const out = await makeService().register({ name: ' Ada ', email: ' Ada@X.io ', password: 'secret-12' })
+    expect(out).toEqual({ id: 1, name: 'Ada', email: 'ada@x.io', created_at: 't' })
+    const arg = reg.mock.calls[0][0]
+    expect(arg.name).toBe('Ada') // trim.
+    expect(arg.email).toBe('ada@x.io') // trim + lowercase.
+    expect(arg.passwordHash).toMatch(/^\$scrypt\$/) // 평문이 아니라 scrypt 해시.
+    expect(arg.passwordHash).not.toContain('secret-12')
+  })
+
+  test('이름/이메일 누락 → MegaValidationError(auth.invalid)', async () => {
+    await expect(makeService().register({ name: '', email: 'a@b.c', password: 'secret-12' })).rejects.toMatchObject({
+      code: 'auth.invalid',
+    })
+  })
+
+  test('비밀번호 8자 미만 → MegaValidationError(auth.invalid)', async () => {
+    await expect(makeService().register({ name: 'Ada', email: 'a@b.c', password: 'short' })).rejects.toMatchObject({
+      code: 'auth.invalid',
+    })
+  })
+
+  test('이메일 중복(23505) → MegaConflictError(user.email_taken)', async () => {
+    vi.spyOn(User, 'register').mockRejectedValue(/** @type {any} */ (Object.assign(new Error('dup'), { code: '23505' })))
+    await expect(makeService().register({ name: 'Ada', email: 'a@b.c', password: 'secret-12' })).rejects.toMatchObject({
+      status: 409,
+      code: 'user.email_taken',
+    })
+  })
+})
+
+describe('AuthService.authenticate', () => {
+  test('올바른 비밀번호 → 신원 반환 + last_login 갱신', async () => {
+    const { MegaHash } = await import('mega-framework')
+    const hash = await MegaHash.password.hash('secret-12')
+    vi.spyOn(User, 'findByEmailWithHash').mockResolvedValue(
+      /** @type {any} */ ({ id: 7, name: 'Ada', email: 'ada@x.io', password_hash: hash }),
+    )
+    const touch = vi.spyOn(User, 'touchLastLogin').mockResolvedValue(undefined)
+    const out = await makeService().authenticate({ email: 'Ada@X.io', password: 'secret-12' })
+    expect(out).toEqual({ id: 7, name: 'Ada' })
+    expect(touch).toHaveBeenCalledWith(7)
+  })
+
+  test('틀린 비밀번호 → null(이유 비노출), last_login 미갱신', async () => {
+    const { MegaHash } = await import('mega-framework')
+    const hash = await MegaHash.password.hash('secret-12')
+    vi.spyOn(User, 'findByEmailWithHash').mockResolvedValue(
+      /** @type {any} */ ({ id: 7, name: 'Ada', email: 'ada@x.io', password_hash: hash }),
+    )
+    const touch = vi.spyOn(User, 'touchLastLogin').mockResolvedValue(undefined)
+    expect(await makeService().authenticate({ email: 'ada@x.io', password: 'wrong-pass' })).toBeNull()
+    expect(touch).not.toHaveBeenCalled()
+  })
+
+  test('없는 이메일 → null', async () => {
+    vi.spyOn(User, 'findByEmailWithHash').mockResolvedValue(null)
+    expect(await makeService().authenticate({ email: 'nope@x.io', password: 'secret-12' })).toBeNull()
+  })
+
+  test('비밀번호 미설정 계정(admin CRUD 생성) → null', async () => {
+    vi.spyOn(User, 'findByEmailWithHash').mockResolvedValue(
+      /** @type {any} */ ({ id: 3, name: 'NoPass', email: 'np@x.io', password_hash: null }),
+    )
+    expect(await makeService().authenticate({ email: 'np@x.io', password: 'secret-12' })).toBeNull()
+  })
+
+  test('이메일/비밀번호 공란 → null(조회 안 함)', async () => {
+    const find = vi.spyOn(User, 'findByEmailWithHash').mockResolvedValue(null)
+    expect(await makeService().authenticate({ email: '', password: '' })).toBeNull()
+    expect(find).not.toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,101 @@
+// @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()
+})

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

@@ -0,0 +1,144 @@
+// @ts-check
+/**
+ * ChatChannel 단위 테스트(ADR-158) — 라이프사이클 훅이 chat-bus(redis pub/sub) + roster HASH 를
+ * 올바르게 호출하는지 mock 으로 검증. 인프라 불필요(redis native·chat-bus 모듈은 spy).
+ *
+ * 채널은 cluster-wide 전파를 chat-bus.publish 에, 로컬 등록을 register/unregisterConn 에, 접속자 명단을
+ * redis HASH(hset/hvals/hdel)에 위임한다 — 그 위임 계약을 단언한다(app.broadcast/joinSession 미사용).
+ */
+import { describe, test, expect, vi, beforeEach } from 'vitest'
+
+// chat-bus(redis pub/sub) 모듈은 mock — 채널이 올바른 env 로 호출하는지만 본다.
+vi.mock('../../../apps/main/channels/chat-bus.js', () => ({
+  ensureSubscriber: vi.fn(),
+  registerConn: vi.fn(),
+  unregisterConn: vi.fn(),
+  publish: vi.fn(async () => {}),
+  ROSTER_KEY: 'ws:chat:roster',
+}))
+
+import { ChatChannel } from '../../../apps/main/channels/chat-channel.js'
+import * as chatBus from '../../../apps/main/channels/chat-bus.js'
+
+/** native redis spy — roster HASH + 기록 리스트. @param {object} [o] */
+function fakeNative({ roster = ['kim'], history = [] } = {}) {
+  return {
+    hset: vi.fn(async () => 1),
+    hvals: vi.fn(async () => roster),
+    hdel: vi.fn(async () => 1),
+    rpush: vi.fn(async () => 1),
+    ltrim: vi.fn(async () => 'OK'),
+    expire: vi.fn(async () => 1),
+    lrange: vi.fn(async () => history),
+  }
+}
+
+/** 채널 ctx mock — auth/app/cache/log. @param {object} [o] */
+function makeCtx({ roster = ['kim'], history = [], userName = 'kim' } = {}) {
+  const native = fakeNative({ roster, history })
+  return {
+    ctx: {
+      auth: { userId: 'u1', sessionId: 's1', userName },
+      app: { fastify: { log: { warn: vi.fn(), debug: vi.fn(), error: vi.fn() } } },
+      cache: vi.fn(() => ({ native })),
+      log: { warn: vi.fn(), debug: vi.fn(), error: vi.fn() },
+    },
+    native,
+  }
+}
+
+/** sock mock — send spy + id + isOpen. */
+function makeSock() {
+  return { id: 'conn-1', isOpen: true, send: vi.fn(), close: vi.fn() }
+}
+
+beforeEach(() => vi.clearAllMocks())
+
+describe('ChatChannel.onConnect', () => {
+  test('구독자 보장 + 로컬등록 + roster HSET + 기록재생 + 입장 publish(본인 제외) + 워커PID', async () => {
+    const { ctx, native } = makeCtx({
+      roster: ['kim', 'old'],
+      history: [JSON.stringify({ userId: 'u0', userName: 'old', text: 'hi', ts: 1 })],
+    })
+    const sock = makeSock()
+    await new ChatChannel().onConnect(sock, ctx)
+
+    expect(chatBus.ensureSubscriber).toHaveBeenCalledWith(ctx.app, native)
+    expect(chatBus.registerConn).toHaveBeenCalledWith(sock, { sessionId: 's1', userName: 'kim' })
+    expect(native.hset).toHaveBeenCalledWith('ws:chat:roster', 's1', 'kim')
+
+    // 본인에게: chat.history(me + items + 명단 + 워커PID).
+    const hist = sock.send.mock.calls.find(([m]) => m.type === 'chat.history')[0]
+    expect(hist.payload.me).toEqual({ userId: 'u1', userName: 'kim' })
+    expect(hist.payload.items).toHaveLength(1)
+    expect(hist.payload.online).toBe(2)
+    expect(hist.payload.members).toEqual(['kim', 'old'])
+    expect(hist.payload.workerPid).toBe(process.pid)
+
+    // 전 클러스터에: 입장 presence(본인 sessionId 제외).
+    const pub = chatBus.publish.mock.calls.at(-1)[1]
+    expect(pub).toMatchObject({
+      message: { type: 'chat.presence', payload: { event: 'join', userName: 'kim', online: 2 } },
+      exceptSessionIds: ['s1'],
+    })
+  })
+
+  test('redis 없으면 1011 로 닫는다(전파 transport 부재)', async () => {
+    const sock = makeSock()
+    const ctx = { auth: { userId: 'u1', sessionId: 's1', userName: 'kim' }, cache: vi.fn(() => ({ native: null })), log: { error: vi.fn() } }
+    await new ChatChannel().onConnect(sock, ctx)
+    expect(sock.close).toHaveBeenCalledWith(1011, expect.any(String))
+    expect(chatBus.registerConn).not.toHaveBeenCalled()
+  })
+
+  test('손상된 기록 1건은 건너뛰고 나머지는 재생(debug 로그)', async () => {
+    const { ctx } = makeCtx({ history: ['{bad', JSON.stringify({ userName: 'a', text: 'ok', ts: 2 })] })
+    const sock = makeSock()
+    await new ChatChannel().onConnect(sock, ctx)
+    const hist = sock.send.mock.calls.find(([m]) => m.type === 'chat.history')[0]
+    expect(hist.payload.items).toHaveLength(1)
+    expect(ctx.log.debug).toHaveBeenCalled()
+  })
+})
+
+describe('ChatChannel.chat.send', () => {
+  test('검증된 text 를 기록 적재 + 전 클러스터 publish(본인 포함)', async () => {
+    const { ctx, native } = makeCtx()
+    await new ChatChannel()['chat.send'](makeSock(), { type: 'chat.send', payload: { text: '  hello  ' } }, ctx)
+    expect(native.rpush).toHaveBeenCalled()
+    expect(native.ltrim).toHaveBeenCalledWith('ws:chat:history', -30, -1)
+    const pub = chatBus.publish.mock.calls.at(-1)[1]
+    expect(pub.message.type).toBe('chat.msg')
+    expect(pub.message.payload).toMatchObject({ userId: 'u1', userName: 'kim', text: 'hello' })
+    expect(pub.exceptSessionIds).toBeUndefined() // 본인도 echo.
+  })
+
+  test('공백뿐인 메시지는 무시(전파·적재 없음)', async () => {
+    const { ctx, native } = makeCtx()
+    await new ChatChannel()['chat.send'](makeSock(), { type: 'chat.send', payload: { text: '   ' } }, ctx)
+    expect(chatBus.publish).not.toHaveBeenCalled()
+    expect(native.rpush).not.toHaveBeenCalled()
+  })
+})
+
+describe('ChatChannel.onDisconnect', () => {
+  test('로컬 해제 + roster HDEL + 퇴장 publish(본인 제외)', async () => {
+    const { ctx, native } = makeCtx({ roster: [] })
+    const sock = makeSock()
+    await new ChatChannel().onDisconnect(sock, ctx)
+    expect(chatBus.unregisterConn).toHaveBeenCalledWith(sock)
+    expect(native.hdel).toHaveBeenCalledWith('ws:chat:roster', 's1')
+    const pub = chatBus.publish.mock.calls.at(-1)[1]
+    expect(pub.message).toMatchObject({ type: 'chat.presence', payload: { event: 'leave', userName: 'kim' } })
+    expect(pub.exceptSessionIds).toEqual(['s1'])
+  })
+
+  test('auth 없으면 로컬 해제만(전파 없음)', async () => {
+    const { ctx } = makeCtx()
+    ctx.auth = null
+    const sock = makeSock()
+    await new ChatChannel().onDisconnect(sock, ctx)
+    expect(chatBus.unregisterConn).toHaveBeenCalledWith(sock)
+    expect(chatBus.publish).not.toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,93 @@
+// @ts-check
+/**
+ * CronDemoService 단위 테스트 — 'demo' 캐시 native(incr/get/lpush/ltrim/lrange)를 가짜로 갈음해 redis 없이
+ * 카운터/이력 로직과 다음 실행 시각 계산(MegaCron)을 검증한다. 실 redis 흐름은 통합 검증(E2E)이 커버한다.
+ */
+import { describe, test, expect, vi } from 'vitest'
+import { CronDemoService } from '../../../apps/main/services/cron-demo-service.js'
+
+/** incr/get/lpush/ltrim/lrange 를 추적하는 가짜 native + ctx 를 만든다. */
+function makeCtx() {
+  /** @type {Map<string, number>} */
+  const counters = new Map()
+  /** @type {Map<string, string[]>} LIST(머리 삽입). */
+  const lists = new Map()
+  const native = {
+    /** @param {string} k */
+    async incr(k) {
+      const n = (counters.get(k) ?? 0) + 1
+      counters.set(k, n)
+      return n
+    },
+    /** @param {string} k */
+    async get(k) {
+      return counters.has(k) ? String(counters.get(k)) : null
+    },
+    /** @param {string} k @param {string} v */
+    async lpush(k, 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) => {
+      const arr = lists.get(k) ?? []
+      lists.set(k, arr.slice(0, stop + 1))
+      return 'OK'
+    }),
+    /** @param {string} k @param {number} start @param {number} stop */
+    async lrange(k, start, stop) {
+      return (lists.get(k) ?? []).slice(start, stop + 1)
+    },
+  }
+  const cache = { native }
+  const ctx = { log: { debug() {} }, cache: (/** @type {string} */ a) => (a === 'demo' ? cache : null) }
+  return { ctx, native, counters, lists }
+}
+
+describe('CronDemoService — tick', () => {
+  test('호출마다 카운터가 1씩 증가하고 이력 LIST 머리에 source 와 함께 쌓인다', async () => {
+    const { ctx, native, lists } = makeCtx()
+    const svc = new CronDemoService(/** @type {any} */ (ctx))
+    const first = await svc.tick('schedule')
+    expect(first).toMatchObject({ count: 1, source: 'schedule' })
+    expect(typeof first.at).toBe('string')
+    const second = await svc.tick('manual')
+    expect(second.count).toBe(2)
+    // LTRIM 으로 최근 N건만 유지(매 tick 호출).
+    expect(native.ltrim).toHaveBeenCalledWith(CronDemoService.HISTORY_KEY, 0, CronDemoService.HISTORY_MAX - 1)
+    const stored = (lists.get(CronDemoService.HISTORY_KEY) ?? []).map((s) => JSON.parse(s))
+    // 최신이 머리(앞) — manual 이 먼저.
+    expect(stored[0]).toMatchObject({ count: 2, source: 'manual' })
+    expect(stored[1]).toMatchObject({ count: 1, source: 'schedule' })
+  })
+})
+
+describe('CronDemoService — snapshot', () => {
+  test('누적 카운터 + 최신순 이력 + 다음 실행 시각(미래, 오름차순)을 돌려준다', async () => {
+    const { ctx } = makeCtx()
+    const svc = new CronDemoService(/** @type {any} */ (ctx))
+    await svc.tick('schedule')
+    await svc.tick('schedule')
+    const snap = await svc.snapshot()
+    expect(snap.count).toBe(2)
+    expect(snap.cron).toBe(CronDemoService.CRON_EXPR)
+    expect(snap.timezone).toBe(CronDemoService.TIMEZONE)
+    expect(snap.history).toHaveLength(2)
+    expect(snap.nextRuns.length).toBeGreaterThan(0)
+    // 모두 미래 + 오름차순.
+    const now = Date.now()
+    for (const d of snap.nextRuns) expect(d.getTime()).toBeGreaterThan(now)
+    for (let i = 1; i < snap.nextRuns.length; i++) {
+      expect(snap.nextRuns[i].getTime()).toBeGreaterThan(snap.nextRuns[i - 1].getTime())
+    }
+  })
+
+  test('카운터 미존재(get=null) 시 0 으로 본다', async () => {
+    const { ctx } = makeCtx()
+    const svc = new CronDemoService(/** @type {any} */ (ctx))
+    const snap = await svc.snapshot()
+    expect(snap.count).toBe(0)
+    expect(snap.history).toEqual([])
+  })
+})