mega-framework 0.1.0

package/sample/crud/apps/main/controllers/auth-controller.js

@@ -0,0 +1,144 @@
+// @ts-check
+/**
+ * AuthController — 로그인·로그아웃·회원가입 HTTP 컨트롤러(ADR-074: 베이스 없음, 정적 메서드만, ADR-155).
+ *
+ * 인증 검증은 `ctx.services.auth`(AuthService)에 위임하고, 여기서는 **세션·brute-force·뷰** 를 다룬다:
+ *   - brute-force: `ctx.bruteForce`(redis, ADR-049/130) — subject 는 `IP:email`(계정 잠금 DoS 회피, I-1).
+ *   - 세션: 로그인 성공 시 `session.regenerate()`(세션 고정 공격 방지) 후 userId/userName 을 심는다.
+ *   - 뷰: 실패는 폼을 에러와 함께 다시 렌더(JSON envelope 대신, web-controller 와 같은 패턴).
+ *
+ * CSRF(디폴트 ON)는 폼 `_csrf` 토큰을 요구하므로 폼 뷰에 `reply.generateCsrf()` 토큰을 심는다.
+ */
+import { MegaValidationError, MegaConflictError } from 'mega-framework/errors'
+import { currentUser } from '../middleware/web-auth.js'
+
+/** 로그인 성공 후 도착지(관리 UI). */
+const HOME_REDIRECT = '/admin/users'
+
+/** 로그인 폼 알림(?notice=) → 로케일 키 화이트리스트(임의 t() 조회 방지). */
+const NOTICE_KEYS = new Set(['logged_out', 'registered'])
+
+/**
+ * 로그인 성공 시 세션을 새 sid 로 재발급(고정 공격 방지)하고 신원을 심는다.
+ * @param {any} req @param {{ id: any, name: string }} user @returns {Promise<void>}
+ */
+async function establishSession(req, user) {
+  req.session.userId = user.id
+  req.session.userName = user.name
+  await req.session.regenerate()
+}
+
+export class AuthController {
+  /** GET /auth/login — 로그인 폼. 이미 로그인했으면 관리 UI 로. @param {any} req @param {any} reply @param {any} ctx */
+  static async loginForm(req, reply, ctx) {
+    if (currentUser(req)) return reply.redirect(HOME_REDIRECT)
+    const key = String(req.query?.notice ?? '')
+    const notice = NOTICE_KEYS.has(key) ? ctx.t(`auth_notice_${key}`) : null
+    return ctx.render('auth/login', {
+      title: ctx.t('login_title', '로그인'),
+      values: {},
+      notice,
+      currentUser: null,
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** POST /auth/login — 인증 → 세션 생성 → 관리 UI. 잠김/실패 시 폼 재렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async login(req, reply, ctx) {
+    const email = typeof req.body?.email === 'string' ? req.body.email.trim().toLowerCase() : ''
+    const password = typeof req.body?.password === 'string' ? req.body.password : ''
+    // subject = IP:email — email 단독 잠금은 피해자 계정을 공격자가 잠그는 DoS 가 가능(I-1).
+    const subject = `${req.ip}:${email}`
+    const bf = ctx.bruteForce
+
+    const status = await bf.check(subject)
+    if (status.isLocked) {
+      return AuthController.#renderLogin(reply, ctx, { email }, ctx.t('login_locked', '로그인 시도가 너무 많습니다. 잠시 후 다시 시도하세요.'), 423)
+    }
+
+    const user = await ctx.services.auth.authenticate({ email, password })
+    if (!user) {
+      const after = await bf.fail(subject)
+      const msg = after.isLocked ? ctx.t('login_locked', '로그인 시도가 너무 많습니다. 잠시 후 다시 시도하세요.') : ctx.t('login_failed', '이메일 또는 비밀번호가 올바르지 않습니다.')
+      return AuthController.#renderLogin(reply, ctx, { email }, msg, after.isLocked ? 423 : 401)
+    }
+
+    await bf.reset(subject)
+    await establishSession(req, user)
+    req.log?.debug?.({ userId: user.id }, 'auth.login ok')
+    return reply.redirect(HOME_REDIRECT)
+  }
+
+  /** POST /auth/logout — 세션 파기 → 로그인 페이지. @param {any} req @param {any} reply */
+  static async logout(req, reply) {
+    if (req.session?.userId != null) await req.session.destroy()
+    return reply.redirect('/auth/login?notice=logged_out')
+  }
+
+  /** GET /register — 회원가입 폼. 이미 로그인했으면 관리 UI 로. @param {any} req @param {any} reply @param {any} ctx */
+  static async registerForm(req, reply, ctx) {
+    if (currentUser(req)) return reply.redirect(HOME_REDIRECT)
+    return ctx.render('auth/register', {
+      title: ctx.t('register_title', '회원가입'),
+      values: {},
+      invalid: null,
+      currentUser: null,
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** POST /register — 계정 생성 → 자동 로그인 → 관리 UI. 검증/충돌 시 폼 재렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async register(req, reply, ctx) {
+    try {
+      const user = await ctx.services.auth.register(req.body ?? {})
+      await establishSession(req, user)
+      req.log?.debug?.({ userId: user.id }, 'auth.register ok — auto login')
+      return reply.redirect(`${HOME_REDIRECT}?notice=registered`)
+    } catch (err) {
+      if (err instanceof MegaValidationError || err instanceof MegaConflictError) {
+        reply.code(err instanceof MegaConflictError ? 409 : 400)
+        return ctx.render('auth/register', {
+          title: ctx.t('register_title', '회원가입'),
+          values: { name: req.body?.name ?? '', email: req.body?.email ?? '' },
+          invalid: AuthController.#invalidFields(err),
+          error: err.message,
+          currentUser: null,
+          csrfToken: reply.generateCsrf(),
+        })
+      }
+      throw err // 미지 에러는 프레임워크 글로벌 핸들러로.
+    }
+  }
+
+  /**
+   * 로그인 폼 재렌더 헬퍼(상태코드 + 에러 메시지 + 입력 보존 + 새 CSRF 토큰).
+   * @param {any} reply @param {any} ctx @param {{ email: string }} values @param {string} error @param {number} code
+   */
+  static #renderLogin(reply, ctx, values, error, code) {
+    reply.code(code)
+    return ctx.render('auth/login', {
+      title: ctx.t('login_title', '로그인'),
+      values,
+      error,
+      notice: null,
+      currentUser: null,
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /**
+   * 회원가입 검증/충돌 에러 → 폼 is-invalid 표시용 필드 맵.
+   * @param {unknown} err @returns {{ name: boolean, email: boolean, password: boolean }}
+   */
+  static #invalidFields(err) {
+    if (err instanceof MegaValidationError) {
+      const d = /** @type {any} */ (err).details ?? {}
+      // auth-service 는 details.{name,email,password} = "값이 유효한가"(true=정상) 로 준다 → 없으면 invalid.
+      return { name: !d.name, email: !d.email, password: !d.password }
+    }
+    if (err instanceof MegaConflictError) {
+      return { name: false, email: true, password: false } // 이메일 중복.
+    }
+    return { name: false, email: false, password: false }
+  }
+}

package/sample/crud/apps/main/controllers/cron-controller.js

@@ -0,0 +1,34 @@
+// @ts-check
+/**
+ * CronController — /demo/cron 스케줄러 데모 UI(MPA) HTTP 컨트롤러(ADR-074: 베이스 없음, 정적 메서드, ADR-157).
+ *
+ * `ctx.services.cronDemo`(자동 DI)로 누적 실행 횟수·최근 실행 이력·다음 실행 시각을 EJS 로 렌더한다. 수동 실행은
+ * POST(PRG) — CSRF 폼 토큰을 심는다. 자동 실행(30초 주기)은 `mega scheduler` 프로세스의 CronCounterSchedule
+ * 이 같은 redis 에 쌓으므로, 수동/자동 실행이 한 이력에 함께 보인다.
+ */
+import { currentUser } from '../middleware/web-auth.js'
+
+/** 알림 쿼리(?notice=) → 로케일 키 화이트리스트(임의 t() 조회 방지). */
+const NOTICE_KEYS = new Set(['triggered'])
+
+export class CronController {
+  /** GET /demo/cron — 실행 횟수 + 이력 + 다음 실행 시각 렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async index(req, reply, ctx) {
+    const snap = await ctx.services.cronDemo.snapshot()
+    const key = String(req.query?.notice ?? '')
+    const notice = NOTICE_KEYS.has(key) ? ctx.t(`cron_notice_${key}`, { defaultValue: '스케줄 작업을 즉시 1회 실행했습니다.' }) : null
+    return ctx.render('cron/index', {
+      title: ctx.t('cron_title', { defaultValue: '스케줄러 데모 (MegaSchedule)' }),
+      snap,
+      notice,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** POST /demo/cron/run — 지금 즉시 1회 실행 → 리다이렉트(PRG). @param {any} _req @param {any} reply @param {any} ctx */
+  static async runNow(_req, reply, ctx) {
+    await ctx.services.cronDemo.tick('manual')
+    return reply.redirect('/demo/cron?notice=triggered')
+  }
+}

package/sample/crud/apps/main/controllers/guide-controller.js

@@ -0,0 +1,37 @@
+// @ts-check
+/**
+ * GuideController — /guide 가이드 뷰어 HTTP 컨트롤러(ADR-074: 베이스 없음, 정적 메서드만).
+ *
+ * `ctx.services.guide`(자동 DI)로 docs/guide 의 마크다운을 서버사이드 렌더한 HTML 을 EJS 뷰로 내보낸다.
+ * 브라우저 JS 를 추가하지 않으므로(CSP script-src 'self' 호환) 코드 하이라이트도 전부 서버에서 끝낸다.
+ * navbar 의 로그아웃 폼이 CSRF 토큰을 요구하므로 데모 다른 페이지와 동일하게 currentUser·csrfToken 을 넘긴다.
+ */
+import { currentUser } from '../middleware/web-auth.js'
+
+export class GuideController {
+  /** GET /guide — 가이드 목록(카드 그리드). @param {any} req @param {any} reply @param {any} ctx */
+  static async index(req, reply, ctx) {
+    const guides = await ctx.services.guide.listGuides()
+    return ctx.render('guide/index', {
+      title: ctx.t('guide_index_title', '가이드'),
+      guides,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** GET /guide/:slug — 단일 가이드(좌측 목차 + 우측 본문). @param {any} req @param {any} reply @param {any} ctx */
+  static async page(req, reply, ctx) {
+    const slug = String(req.params?.slug ?? '')
+    // renderGuide 가 화이트리스트 밖 slug 에 MegaNotFoundError 를 던진다(전역 에러 핸들러가 404 로 매핑).
+    const guide = await ctx.services.guide.renderGuide(slug)
+    const guides = await ctx.services.guide.listGuides()
+    return ctx.render('guide/page', {
+      title: guide.title,
+      guide,
+      guides,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+}

package/sample/crud/apps/main/controllers/jobs-controller.js

@@ -0,0 +1,43 @@
+// @ts-check
+/**
+ * JobsController — /demo/jobs 잡 큐 데모 UI(MPA) HTTP 컨트롤러(ADR-074: 정적 메서드, ADR-157).
+ *
+ * `ctx.services.jobsDemo`(자동 DI)로 EmailJob 을 enqueue 하고(NATS JetStream), 워커가 처리해 남긴 이벤트
+ * 타임라인과 DLQ 격리분을 EJS 로 렌더한다. enqueue 는 POST(PRG) — CSRF 폼 토큰을 심는다.
+ */
+import { currentUser } from '../middleware/web-auth.js'
+
+/** 발송 시뮬레이션 모드 화이트리스트(폼 입력 검증). */
+const MODES = ['ok', 'flaky', 'fail']
+/** 알림 쿼리(?notice=) → 로케일 키 화이트리스트. */
+const NOTICE_KEYS = new Set(['enqueued'])
+
+export class JobsController {
+  /** GET /demo/jobs — enqueue 폼 + 처리 이벤트 + DLQ 상태 렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async index(req, reply, ctx) {
+    const [events, dlq] = await Promise.all([ctx.services.jobsDemo.events(), ctx.services.jobsDemo.dlq()])
+    const key = String(req.query?.notice ?? '')
+    const notice = NOTICE_KEYS.has(key) ? ctx.t(`jobs_notice_${key}`, { defaultValue: '잡을 큐에 넣었습니다. 워커가 처리하면 아래 이벤트에 나타납니다.' }) : null
+    return ctx.render('jobs/index', {
+      title: ctx.t('jobs_title', { defaultValue: '잡 큐 데모 (MegaJob)' }),
+      events,
+      dlq,
+      modes: MODES,
+      notice,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** POST /demo/jobs/enqueue — EmailJob 1건 enqueue → 리다이렉트(PRG). @param {any} req @param {any} reply @param {any} ctx */
+  static async enqueue(req, reply, ctx) {
+    const body = req.body ?? {}
+    const mode = MODES.includes(body.mode) ? body.mode : 'ok'
+    const rawTo = typeof body.to === 'string' ? body.to.trim() : ''
+    const to = rawTo.length > 0 ? rawTo : 'demo@example.com'
+    // 잡 식별자 — 시도 카운터/이벤트 키에 쓰인다. 같은 페이로드 중복 enqueue 도 서로 구분되게 유니크하게 만든다.
+    const id = `email-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+    await ctx.services.jobsDemo.enqueue({ id, to, mode })
+    return reply.redirect('/demo/jobs?notice=enqueued')
+  }
+}

package/sample/crud/apps/main/controllers/logs-controller.js

@@ -0,0 +1,35 @@
+// @ts-check
+/**
+ * LogsController — /demo/logs 구조적 로깅 데모 UI(MPA) HTTP 컨트롤러(ADR-074: 정적 메서드, ADR-163).
+ *
+ * `ctx.services.logsDemo`(자동 DI)로 실제 pino 로그를 emit 하고, 안전 메타데이터 이력을 EJS 로 렌더한다.
+ * emit 은 POST(PRG) — CSRF 폼 토큰을 심는다. 실제 마스킹·trace_id 첨부·구조적 NDJSON 은 서버 콘솔에서 확인하며,
+ * 화면은 emit 사실과 trace 상관(trace_id)을 보여준다.
+ */
+import { currentUser } from '../middleware/web-auth.js'
+
+/** 알림 쿼리(?notice=) → 로케일 키 화이트리스트. */
+const NOTICE_KEYS = new Set(['emitted'])
+
+export class LogsController {
+  /** GET /demo/logs — 최근 emit 메타 + emit 폼 렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async index(req, reply, ctx) {
+    const snap = await ctx.services.logsDemo.snapshot()
+    const key = String(req.query?.notice ?? '')
+    const notice = NOTICE_KEYS.has(key) ? ctx.t(`logs_notice_${key}`, '로그를 emit 했습니다. 서버 콘솔에서 구조적 출력을 확인하세요.') : null
+    return ctx.render('logs/index', {
+      title: ctx.t('logs_title', '구조적 로깅'),
+      snap,
+      notice,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** POST /demo/logs/emit — 선택 레벨로 로그 1건 emit → 리다이렉트(PRG). @param {any} req @param {any} reply @param {any} ctx */
+  static async emit(req, reply, ctx) {
+    const body = req.body ?? {}
+    await ctx.services.logsDemo.emit(body.level, body.message)
+    return reply.redirect('/demo/logs?notice=emitted')
+  }
+}

package/sample/crud/apps/main/controllers/metrics-controller.js

@@ -0,0 +1,22 @@
+// @ts-check
+/**
+ * MetricsController — /demo/metrics 관측(메트릭) 데모 UI(MPA) HTTP 컨트롤러(ADR-074: 정적 메서드, ADR-163).
+ *
+ * `ctx.services.metricsDemo`(자동 DI)가 `MegaMetrics.collect()`를 파싱한 요약을 EJS 카드로 렌더한다.
+ * raw `/metrics`(Prometheus scrape 포맷)는 loopback IP allowList(mega.config.js health, ADR-131)로 보호되며,
+ * 본 페이지는 그 데이터를 사람 친화 카드로 보여준 뒤 raw 링크를 함께 건다.
+ */
+import { currentUser } from '../middleware/web-auth.js'
+
+export class MetricsController {
+  /** GET /demo/metrics — HTTP/잡/WS/process 카운터 요약 렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async index(req, reply, ctx) {
+    const snap = await ctx.services.metricsDemo.snapshot()
+    return ctx.render('metrics/index', {
+      title: ctx.t('metrics_title', '메트릭'),
+      snap,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+}

package/sample/crud/apps/main/controllers/note-controller.js

@@ -0,0 +1,116 @@
+// @ts-check
+/**
+ * NoteController — mongo notes 데모 UI(MPA) HTTP 컨트롤러(ADR-074: 베이스 없음, 정적 메서드만, ADR-157).
+ *
+ * users 의 WebController 와 같은 패턴 — `ctx.services.note`(자동 DI)를 거쳐 EJS 뷰를 서버사이드 렌더하고,
+ * 생성/수정/삭제 후엔 PRG(Post/Redirect/Get)로 목록으로 리다이렉트한다. 검증 에러는 폼을 에러와 함께
+ * 다시 렌더한다. CSRF(디폴트 ON)는 폼 `_csrf` 토큰을 요구하므로 폼 뷰에 `reply.generateCsrf()` 를 심는다.
+ */
+import { MegaNotFoundError, MegaValidationError } from 'mega-framework/errors'
+import { currentUser } from '../middleware/web-auth.js'
+
+/** 알림 쿼리(?notice=) → 로케일 키 화이트리스트(임의 t() 조회 방지). */
+const NOTICE_KEYS = new Set(['created', 'updated', 'deleted'])
+/** 알림 키별 한국어 fallback(locale 누락 시 표시할 값). @type {Record<string, string>} */
+const NOTICE_DEFAULTS = {
+  created: '노트를 생성했습니다.',
+  updated: '노트를 수정했습니다.',
+  deleted: '노트를 삭제했습니다.',
+}
+
+export class NoteController {
+  /** GET /demo/notes — 목록(+ ?notice= 알림, 삭제 폼 CSRF). @param {any} req @param {any} reply @param {any} ctx */
+  static async list(req, reply, ctx) {
+    const notes = await ctx.services.note.list()
+    const key = String(req.query?.notice ?? '')
+    const notice = NOTICE_KEYS.has(key) ? ctx.t(`notes_notice_${key}`, { defaultValue: NOTICE_DEFAULTS[key] }) : null
+    return ctx.render('notes/list', {
+      title: ctx.t('notes_title', { defaultValue: '노트 (MongoDB)' }),
+      notes,
+      notice,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** GET /demo/notes/new — 신규 폼. @param {any} req @param {any} reply @param {any} ctx */
+  static async newForm(req, reply, ctx) {
+    return ctx.render('notes/new', {
+      title: ctx.t('notes_new_title', { defaultValue: '노트 추가' }),
+      values: {},
+      invalid: null,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** POST /demo/notes — 생성 → 목록 리다이렉트(PRG). 검증 시 폼 재렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async create(req, reply, ctx) {
+    try {
+      await ctx.services.note.create(req.body ?? {})
+      return reply.redirect('/demo/notes?notice=created')
+    } catch (err) {
+      if (err instanceof MegaValidationError) {
+        reply.code(400)
+        return ctx.render('notes/new', {
+          title: ctx.t('notes_new_title', { defaultValue: '노트 추가' }),
+          values: req.body ?? {},
+          invalid: { title: true },
+          error: err.message,
+          currentUser: currentUser(req),
+          csrfToken: reply.generateCsrf(),
+        })
+      }
+      throw err // 미지 에러는 프레임워크 글로벌 핸들러로.
+    }
+  }
+
+  /** GET /demo/notes/:id/edit — 수정 폼(사전 채움). 없으면 목록으로. @param {any} req @param {any} reply @param {any} ctx */
+  static async editForm(req, reply, ctx) {
+    try {
+      const note = await ctx.services.note.get(req.params.id)
+      return ctx.render('notes/edit', {
+        title: ctx.t('notes_edit_title', { defaultValue: '노트 수정' }),
+        values: note,
+        invalid: null,
+        currentUser: currentUser(req),
+        csrfToken: reply.generateCsrf(),
+      })
+    } catch (err) {
+      if (err instanceof MegaNotFoundError) return reply.redirect('/demo/notes')
+      throw err
+    }
+  }
+
+  /** POST /demo/notes/:id — 수정 → 목록 리다이렉트(PRG). 검증 시 폼 재렌더, 없으면 목록으로. @param {any} req @param {any} reply @param {any} ctx */
+  static async update(req, reply, ctx) {
+    try {
+      await ctx.services.note.update(req.params.id, req.body ?? {})
+      return reply.redirect('/demo/notes?notice=updated')
+    } catch (err) {
+      if (err instanceof MegaValidationError) {
+        reply.code(400)
+        return ctx.render('notes/edit', {
+          title: ctx.t('notes_edit_title', { defaultValue: '노트 수정' }),
+          values: { id: req.params.id, ...(req.body ?? {}) },
+          invalid: { title: true },
+          error: err.message,
+          currentUser: currentUser(req),
+          csrfToken: reply.generateCsrf(),
+        })
+      }
+      if (err instanceof MegaNotFoundError) return reply.redirect('/demo/notes')
+      throw err
+    }
+  }
+
+  /** POST /demo/notes/:id/delete — 삭제 → 목록 리다이렉트(PRG). 없으면 그대로 목록으로. @param {any} req @param {any} reply @param {any} ctx */
+  static async destroy(req, reply, ctx) {
+    try {
+      await ctx.services.note.remove(req.params.id)
+    } catch (err) {
+      if (!(err instanceof MegaNotFoundError)) throw err
+    }
+    return reply.redirect('/demo/notes?notice=deleted')
+  }
+}

package/sample/crud/apps/main/controllers/perf-controller.js

@@ -0,0 +1,38 @@
+// @ts-check
+/**
+ * PerfController — /perf 벤치마크 데모 UI + 실행 엔드포인트(ADR-074: 베이스 없음, 정적 메서드만, ADR-157).
+ *
+ * GET /perf 는 시나리오 선택·실행 폼이 든 EJS 페이지를 렌더한다. POST /perf/run 은 AJAX(JSON) 엔드포인트로
+ * `ctx.services.perf`(자동 DI)에 측정을 위임하고 도메인 결과만 반환한다 — envelope(`{ ok, data, meta }`)는
+ * 프레임워크가 감싼다(ADR-018/147). JSON 요청이라 CSRF 는 토큰 면제 + Origin 검증으로 통과한다(ADR-051).
+ */
+import { currentUser } from '../middleware/web-auth.js'
+
+/** UI 드롭다운에 보일 시나리오 목록(라벨 키는 i18n). 서비스 SCENARIO_LIMITS 와 동일 집합이어야 한다. */
+const SCENARIOS = Object.freeze([
+  'http.echo',
+  'http.jsonSmall',
+  'http.jsonLarge',
+  'crypto.hash',
+  'crypto.aspRoundtrip',
+  'db.pg.insertSelect',
+  'db.mongo.insertFind',
+  'cache.redis.setGet',
+  'session.createRead',
+])
+
+export class PerfController {
+  /** GET /perf — 벤치마크 UI 렌더. @param {any} req @param {any} _reply @param {any} ctx */
+  static async index(req, _reply, ctx) {
+    return ctx.render('perf/index', {
+      title: ctx.t('perf_title', '성능 벤치마크'),
+      scenarios: SCENARIOS,
+      currentUser: currentUser(req),
+    })
+  }
+
+  /** POST /perf/run — 벤치마크 1회 실행 → 결과 반환(프레임워크가 envelope 로 감쌈). @param {any} req @param {any} _reply @param {any} ctx */
+  static async run(req, _reply, ctx) {
+    return ctx.services.perf.run(req.body)
+  }
+}

package/sample/crud/apps/main/controllers/redis-controller.js

@@ -0,0 +1,36 @@
+// @ts-check
+/**
+ * RedisController — /demo/redis 데모 UI(MPA) HTTP 컨트롤러(ADR-074: 베이스 없음, 정적 메서드만, ADR-157).
+ *
+ * `ctx.services.redisDemo`(자동 DI)를 거쳐 방문 카운터(INCR/EXPIRE)와 쿼리 결과 캐시(GET/SET/TTL/DEL) 상태를
+ * EJS 뷰로 렌더한다. 캐시 비우기는 POST(PRG) — CSRF(디폴트 ON) 토큰을 폼에 심는다(reply.generateCsrf()).
+ */
+import { currentUser } from '../middleware/web-auth.js'
+
+/** 알림 쿼리(?notice=) → 로케일 키 화이트리스트(임의 t() 조회 방지). */
+const NOTICE_KEYS = new Set(['cache_cleared'])
+
+export class RedisController {
+  /** GET /demo/redis — 방문 기록 + 캐시 상태 렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async index(req, reply, ctx) {
+    const visits = await ctx.services.redisDemo.recordVisit()
+    // 'cache' 는 EJS 예약 로컬(컴파일 캐시 플래그) — 프레임워크가 렌더 시 덮어쓰므로 다른 이름을 쓴다(template.js).
+    const cacheState = await ctx.services.redisDemo.getUserCountCached()
+    const key = String(req.query?.notice ?? '')
+    const notice = NOTICE_KEYS.has(key) ? ctx.t(`redis_notice_${key}`, { defaultValue: '캐시를 비웠습니다.' }) : null
+    return ctx.render('redis/index', {
+      title: ctx.t('redis_title', { defaultValue: 'Redis 데모' }),
+      visits,
+      cacheState,
+      notice,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** POST /demo/redis/clear — 캐시 비우기 → 리다이렉트(PRG). @param {any} _req @param {any} reply @param {any} ctx */
+  static async clearCache(_req, reply, ctx) {
+    await ctx.services.redisDemo.clearUserCountCache()
+    return reply.redirect('/demo/redis?notice=cache_cleared')
+  }
+}

package/sample/crud/apps/main/controllers/tracing-controller.js

@@ -0,0 +1,43 @@
+// @ts-check
+/**
+ * TracingController — /demo/tracing 분산 추적 데모 UI(MPA) HTTP 컨트롤러(ADR-074: 정적 메서드, ADR-163).
+ *
+ * `ctx.services.tracingDemo`(자동 DI)로 현재 요청 trace_id 와 최근 trace 목록을 렌더하고, 각 trace 를
+ * Zipkin 딥링크로 잇는다. 응답 헤더 `x-trace-id` 에도 현재 trace_id 를 실어, 브라우저 개발자도구/curl 로
+ * 바로 추적 ID 를 확인할 수 있게 한다. "trace 생성" 버튼은 `ctx.tracer.span`(사용자 직접 span, ADR-126)으로
+ * 자식 span 을 하나 깔아 DB 핑을 수행한 뒤 PRG 로 돌아온다 — Zipkin 에 다층 span 트리가 보이게 한다.
+ */
+import { currentUser } from '../middleware/web-auth.js'
+
+/** 알림 쿼리(?notice=) → 로케일 키 화이트리스트. */
+const NOTICE_KEYS = new Set(['generated'])
+
+export class TracingController {
+  /** GET /demo/tracing — 현재 trace_id + 최근 trace 목록 렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async index(req, reply, ctx) {
+    await ctx.services.tracingDemo.record('GET /demo/tracing')
+    const snap = await ctx.services.tracingDemo.snapshot()
+    if (snap.current) reply.header('x-trace-id', snap.current.traceId)
+    const key = String(req.query?.notice ?? '')
+    const notice = NOTICE_KEYS.has(key) ? ctx.t(`tracing_notice_${key}`, 'trace 를 생성했습니다. 잠시 후 Zipkin 에서 확인할 수 있습니다.') : null
+    return ctx.render('tracing/index', {
+      title: ctx.t('tracing_title', '분산 추적'),
+      snap,
+      notice,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** POST /demo/tracing/generate — 사용자 span 으로 DB 핑 1회 → 최근 이력에 기록 → 리다이렉트(PRG). @param {any} _req @param {any} reply @param {any} ctx */
+  static async generate(_req, reply, ctx) {
+    // ctx.tracer.span — 활성 HTTP span 의 자식으로 'demo.tracing.work' span 을 깐다. 안에서 가벼운 DB 핑을
+    // 돌려(어댑터 자동 span 도 자식으로 중첩, ADR-114) Zipkin 에 span 트리가 만들어지게 한다.
+    await ctx.tracer.span('demo.tracing.work', async (/** @type {any} */ span) => {
+      span.setAttribute('demo.kind', 'manual-generate')
+      await ctx.db('db').query('SELECT 1')
+    })
+    await ctx.services.tracingDemo.record('POST /demo/tracing/generate')
+    return reply.redirect('/demo/tracing?notice=generated')
+  }
+}

package/sample/crud/apps/main/controllers/upload-controller.js

@@ -0,0 +1,98 @@
+// @ts-check
+/**
+ * UploadController — /demo/upload 파일 업로드 데모 UI(MPA) HTTP 컨트롤러(ADR-074: 정적 메서드, ADR-133/163).
+ *
+ * GET 은 업로드 폼 + 최근 업로드 목록을 EJS 로 렌더한다. POST 는 코어 `req.saveUploads()`(MIME 게이트 +
+ * 경로탐색 차단 + 스트리밍 저장 + 트레이싱·메트릭, ADR-133)로 저장 디렉터리에 저장하고 메타를 JSON envelope
+ * 으로 돌려준다. multipart 폼은 CSRF 토큰을 **헤더**(`csrf-token`)로 보내야 하므로(스트리밍 body 는 preHandler
+ * 시점에 미파싱) 업로드는 `upload-demo.js` 의 fetch + FormData 로 제출한다.
+ *
+ * 다운로드(GET /demo/upload/file/:name)는 **정적 서빙이 아니라 소스에서 파일을 읽어 전송**한다 — 인증
+ * (`webRequireAuth`, 라우트 가드)된 사용자만 받을 수 있다(가드를 떼면 공개로 전환 가능). 파일명은 basename +
+ * 디렉터리 내부 검증으로 경로 탐색을 막는다.
+ *
+ * 저장 디렉터리는 **설정(.env `DEMO_UPLOAD_DIR`)** 으로 받는다(미설정 시 `var/uploads`). 상대경로는 프로젝트
+ * 루트(`process.cwd()`, views.dir/staticAssets.dir 과 같은 규약 ADR-151) 기준으로 해석한다.
+ */
+import { join, relative, isAbsolute, resolve, sep, basename, extname } from 'node:path'
+import { createReadStream } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import { MegaNotFoundError } from 'mega-framework/errors'
+import { currentUser } from '../middleware/web-auth.js'
+
+/** 저장 디렉터리 설정값 — .env `DEMO_UPLOAD_DIR`(상대/절대). 미설정 시 `var/uploads`(프로젝트 루트 상대). */
+const UPLOAD_DIR_SETTING = (process.env.DEMO_UPLOAD_DIR ?? '').trim() || join('var', 'uploads')
+
+/** 확장자 → MIME(다운로드 content-type). 미지원 확장자는 octet-stream(강제 다운로드). */
+const EXT_MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.pdf': 'application/pdf',
+  '.txt': 'text/plain; charset=utf-8',
+}
+
+/**
+ * 저장 절대 디렉터리. 설정이 절대경로면 그대로, 상대면 `process.cwd()` 기준.
+ * @returns {string}
+ */
+function uploadDir() {
+  return isAbsolute(UPLOAD_DIR_SETTING) ? UPLOAD_DIR_SETTING : join(process.cwd(), UPLOAD_DIR_SETTING)
+}
+
+export class UploadController {
+  /** GET /demo/upload — 업로드 폼 + 최근 업로드 목록 렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async index(req, reply, ctx) {
+    const snap = await ctx.services.uploadDemo.snapshot()
+    return ctx.render('upload/index', {
+      title: ctx.t('upload_title', { defaultValue: '파일 업로드' }),
+      snap,
+      uploadDir: UPLOAD_DIR_SETTING,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** POST /demo/upload — multipart 저장 → 메타 JSON 반환(fetch 제출). @param {any} req @param {any} _reply @param {any} ctx */
+  static async upload(req, _reply, ctx) {
+    // saveUploads 가 MIME 비허용(415)·크기 초과(413)면 throw → 글로벌 핸들러가 에러 envelope 로 응답한다.
+    const saved = await req.saveUploads(uploadDir())
+    // 저장 경로는 프로젝트 루트 기준 상대경로로 환산(서버 절대경로 노출 회피, 데모에선 위치 확인이 목적).
+    const files = saved.map((/** @type {any} */ f) => ({
+      filename: f.filename,
+      bytes: f.bytes,
+      mimetype: f.mimetype,
+      path: relative(process.cwd(), f.savedAs),
+    }))
+    await ctx.services.uploadDemo.record(files)
+    return { files }
+  }
+
+  /** GET /demo/upload/file/:name — 저장된 파일을 소스에서 읽어 전송(인증 필요). @param {any} req @param {any} reply @param {any} ctx */
+  static async download(req, reply, ctx) {
+    // basename 으로 디렉터리 성분 제거(경로 탐색 1차 차단) — 'a/../b' / '../etc' 류를 단일 파일명으로.
+    const safe = basename(String(req.params?.name ?? ''))
+    const dir = resolve(uploadDir())
+    const abs = resolve(dir, safe)
+    // 2차 방어 — 최종 경로가 저장 디렉터리 내부(dir/<파일>)가 아니면 거부.
+    if (safe.length === 0 || !abs.startsWith(dir + sep)) {
+      throw new MegaNotFoundError('upload.not_found', `File '${safe}' not found.`)
+    }
+    // 존재·정규 파일 확인 — 없거나 디렉터리면 404.
+    try {
+      const st = await stat(abs)
+      if (!st.isFile()) throw new MegaNotFoundError('upload.not_found', `File '${safe}' not found.`)
+    } catch (err) {
+      if (err instanceof MegaNotFoundError) throw err
+      throw new MegaNotFoundError('upload.not_found', `File '${safe}' not found.`, { cause: err })
+    }
+    ctx.log?.debug?.({ file: safe }, 'upload-demo.download')
+    // 소스에서 스트리밍 전송(정적 서빙 아님). 스트림 payload 라 Fastify 가 envelope 직렬화를 건너뛴다.
+    reply.header('content-disposition', `attachment; filename="${encodeURIComponent(safe)}"`)
+    reply.type(EXT_MIME[extname(safe).toLowerCase()] ?? 'application/octet-stream')
+    return reply.send(createReadStream(abs))
+  }
+}