mega-framework 0.1.0

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

@@ -0,0 +1,302 @@
+// @ts-check
+import { MegaService } from 'mega-framework'
+import { MegaHash, MegaAspCrypto } from 'mega-framework/lib'
+import { MegaValidationError } from 'mega-framework/errors'
+import { performance } from 'node:perf_hooks'
+import { randomUUID } from 'node:crypto'
+import { Buffer } from 'node:buffer'
+
+/**
+ * PerfService — /perf 벤치마크 로직(ADR-174). 파일명 `perf-service.js` → 자동 DI 이름 `perf`
+ * (ctx.services.perf, ADR-148). Node 내장 `perf_hooks.performance.now()` 로 시나리오별 per-iteration
+ * 지연을 직접 측정한다(외부 부하도구 autocannon/k6 미사용 — 신규 의존성 0).
+ *
+ * 측정 표면은 in-process(http/json/crypto)와 실제 어댑터 왕복(db/cache/session) 두 갈래다. in-process
+ * 시나리오는 프레임워크 공개 표면(MegaHash·MegaAspCrypto)을 그대로 호출해 암호화 비용을 잰다. 어댑터
+ * 시나리오는 `ctx.db`/`ctx.cache`/`ctx.app.sessionStore` 의 set/insert/select 왕복을 잰다.
+ *
+ * 안전장치(ADR-174): 시나리오별 유효 상한({@link SCENARIO_LIMITS})으로 반복·동시성을 clamp 한다. scrypt
+ * 해시(`crypto.hash`)는 호출당 ≈32 MiB(ADR-130)라 무제한 반복은 자기-DoS·OOM 위험이라 낮게 묶는다.
+ * clamp 가 일어나면 응답 `clamped` 필드 + debug 로그로 드러낸다(조용한 절삭 금지).
+ */
+export class PerfService extends MegaService {
+  /**
+   * 벤치마크 1회 실행. setup → 측정 → teardown(try/finally 로 보장).
+   * @param {{ scenario: string, iterations: number, concurrency?: number, payloadSize?: number }} input
+   * @returns {Promise<object>} 시나리오·실행 파라미터 + 통계(durationMs/rps/p50…/min/max/avg/ok/fail).
+   * @throws {MegaValidationError} `perf.unknown_scenario` - 미지원 시나리오. `perf.session_unavailable` - 세션 스토어 미배선.
+   */
+  async run(input) {
+    const scenario = String(input.scenario)
+    const limit = SCENARIO_LIMITS[scenario]
+    if (!limit) {
+      throw new MegaValidationError('perf.unknown_scenario', `PerfService.run: unknown scenario "${scenario}".`, {
+        details: { scenario, available: Object.keys(SCENARIO_LIMITS) },
+      })
+    }
+
+    // 시나리오별 유효 상한으로 clamp — 동시성 디폴트도 시나리오마다 다르다(scrypt 는 1).
+    const reqIter = input.iterations
+    const reqConc = input.concurrency ?? limit.defConc
+    const effIter = Math.min(reqIter, limit.maxIter)
+    const effConc = Math.min(reqConc, limit.maxConc)
+    const clamped = {}
+    if (effIter !== reqIter) clamped.iterations = { requested: reqIter, applied: effIter }
+    if (effConc !== reqConc) clamped.concurrency = { requested: reqConc, applied: effConc }
+    if (Object.keys(clamped).length > 0) {
+      this.log.debug?.({ scenario, clamped }, 'perf.run clamped to scenario limit')
+    }
+
+    const runId = randomUUID()
+    this.log.debug?.({ scenario, iterations: effIter, concurrency: effConc, runId }, 'perf.run enter')
+    const { iterate, teardown } = await this.#prepare(scenario, {
+      payloadSize: input.payloadSize,
+      runId,
+    })
+
+    try {
+      const stats = await this.#measure(effIter, effConc, iterate)
+      this.log.debug?.({ scenario, durationMs: stats.durationMs, rps: stats.rps }, 'perf.run done')
+      return {
+        scenario,
+        iterations: effIter,
+        concurrency: effConc,
+        payloadSize: input.payloadSize ?? 0,
+        ...stats,
+        ...(Object.keys(clamped).length > 0 ? { clamped } : {}),
+      }
+    } finally {
+      // teardown 은 비치명적이라도 실패를 묵지 않는다 — 측정 결과는 살리되 정리 실패는 warn 으로 남긴다.
+      try {
+        await teardown()
+      } catch (e) {
+        this.log.warn?.({ err: e, scenario, runId }, 'perf.run teardown failed')
+      }
+    }
+  }
+
+  /**
+   * 반복을 동시성만큼 청크(batch)로 나눠 실행하며 per-iteration 지연을 수집한다. 성공 표본만 통계에
+   * 넣고 실패는 fail 로 센다. 전체 wall-clock 으로 rps 를 낸다.
+   * @param {number} iterations @param {number} concurrency @param {(i: number) => Promise<void>} iterate
+   * @returns {Promise<object>} {@link summarize} 결과.
+   */
+  async #measure(iterations, concurrency, iterate) {
+    /** @type {number[]} 성공 iteration 의 per-iteration 지연(ms). */
+    const samples = []
+    const wallStart = performance.now()
+    for (let start = 0; start < iterations; start += concurrency) {
+      const end = Math.min(start + concurrency, iterations)
+      const batch = []
+      for (let i = start; i < end; i++) {
+        batch.push(this.#timed(iterate, i, samples))
+      }
+      await Promise.all(batch)
+    }
+    const wallMs = performance.now() - wallStart
+    return summarize(samples, wallMs, iterations)
+  }
+
+  /**
+   * 한 iteration 을 측정한다. 성공이면 지연을 samples 에 push, 실패면 묵지 않고 debug 로 남기고 통과
+   * (전체 실행은 계속, 실패 수는 summarize 가 total−성공 으로 계산).
+   * @param {(i: number) => Promise<void>} iterate @param {number} i @param {number[]} samples
+   * @returns {Promise<void>}
+   */
+  async #timed(iterate, i, samples) {
+    const t0 = performance.now()
+    try {
+      await iterate(i)
+      samples.push(performance.now() - t0)
+    } catch (e) {
+      this.log.debug?.({ err: /** @type {any} */ (e)?.message, i }, 'perf.iteration failed')
+    }
+  }
+
+  /**
+   * 시나리오별 setup → per-iteration 함수 + teardown 을 만든다. setup 비용(테이블/키 준비, 키 유도)은
+   * 측정 밖에서 1회만 치른다.
+   * @param {string} scenario @param {{ payloadSize?: number, runId: string }} opts
+   * @returns {Promise<{ iterate: (i: number) => Promise<void>, teardown: () => Promise<void> }>}
+   */
+  async #prepare(scenario, { payloadSize, runId }) {
+    const noTeardown = async () => {}
+
+    switch (scenario) {
+      case 'http.echo': {
+        // 순수 in-process 응답 — 핸들러 디스패치 비용의 하한(Promise 마이크로태스크 왕복)만 잰다.
+        const payload = { ok: true, value: 42 }
+        return { iterate: async () => { await Promise.resolve(payload) }, teardown: noTeardown }
+      }
+      case 'http.jsonSmall': {
+        // 작은(≈100B) 응답 직렬화/역직렬화 비용.
+        const obj = { id: 1, name: 'mega', tags: ['a', 'b', 'c'], nested: { x: 1, y: 2 }, active: true }
+        return { iterate: async () => { JSON.parse(JSON.stringify(obj)) }, teardown: noTeardown }
+      }
+      case 'http.jsonLarge': {
+        // payloadSize 바이트만큼의 페이로드 직렬화/역직렬화 — 큰 응답의 serialize 비용 곡선.
+        const size = clampInt(payloadSize, 0, 1_048_576, 65_536)
+        const obj = { data: 'x'.repeat(size) }
+        return { iterate: async () => { JSON.parse(JSON.stringify(obj)) }, teardown: noTeardown }
+      }
+      case 'crypto.hash': {
+        // scrypt 비밀번호 해시 비용(ADR-130 디폴트 파라미터, 호출당 ≈32 MiB) — 동시성을 낮게 묶는다.
+        return { iterate: async () => { await MegaHash.password.hash('benchmark-password') }, teardown: noTeardown }
+      }
+      case 'crypto.aspRoundtrip': {
+        // ASP 수송 암호(AES-256-GCM, ADR-053~060)의 encrypt→decrypt 왕복. 키 유도는 setup 1회만.
+        const key = MegaAspCrypto.deriveKey('perf-bench-secret', 'localhost', '/perf', '0000', 1_700_000_000_000)
+        const size = clampInt(payloadSize, 1, 1_048_576, 256)
+        const plain = Buffer.alloc(size, 0x61)
+        return {
+          iterate: async () => {
+            const blob = MegaAspCrypto.encryptTransport(key, plain)
+            MegaAspCrypto.decryptTransport(key, blob)
+          },
+          teardown: noTeardown,
+        }
+      }
+      case 'db.pg.insertSelect': {
+        // postgres 1행 INSERT + 1행 SELECT 왕복. run_id 로 동시 실행/잔여를 격리·정리한다.
+        const db = this.ctx.db('db')
+        const payload = 'x'.repeat(clampInt(payloadSize, 0, 4096, 64))
+        await db.query(
+          'CREATE TABLE IF NOT EXISTS perf_bench (id BIGSERIAL PRIMARY KEY, run_id TEXT, payload TEXT, created_at TIMESTAMPTZ DEFAULT now())',
+        )
+        return {
+          iterate: async () => {
+            const ins = await db.query('INSERT INTO perf_bench (run_id, payload) VALUES ($1, $2) RETURNING id', [runId, payload])
+            const id = ins.rows[0].id
+            await db.query('SELECT payload FROM perf_bench WHERE id = $1', [id])
+          },
+          teardown: async () => { await db.query('DELETE FROM perf_bench WHERE run_id = $1', [runId]) },
+        }
+      }
+      case 'db.mongo.insertFind': {
+        // mongo insertOne + findOne + deleteOne 왕복(SQL query 미구현 어댑터 — native 도큐먼트 API).
+        const coll = this.ctx.db('mongo').native.collection('perf_bench')
+        const payload = 'x'.repeat(clampInt(payloadSize, 0, 4096, 64))
+        return {
+          iterate: async () => {
+            const { insertedId } = await coll.insertOne({ runId, payload })
+            await coll.findOne({ _id: insertedId })
+            await coll.deleteOne({ _id: insertedId })
+          },
+          teardown: async () => { await coll.deleteMany({ runId }) },
+        }
+      }
+      case 'cache.redis.setGet': {
+        // redis SET(+TTL) → GET → DEL 왕복. 키는 run 네임스페이스(perf:bench:<runId>:*)로 격리.
+        const cache = this.ctx.cache('demo')
+        const payload = 'x'.repeat(clampInt(payloadSize, 0, 4096, 64))
+        return {
+          iterate: async (i) => {
+            const key = `perf:bench:${runId}:${i}`
+            await cache.set(key, payload, { ttl: 60 })
+            await cache.get(key)
+            await cache.del(key)
+          },
+          // del 이 매 iteration 정리하므로 별도 teardown 불필요(실패분은 TTL 60s 로 자동 만료).
+          teardown: noTeardown,
+        }
+      }
+      case 'session.createRead': {
+        // 세션 스토어(redis) save → load → destroy 왕복. ctx.app.sessionStore 는 세션 옵트인 시에만 존재.
+        const store = this.ctx.app?.sessionStore
+        if (!store) {
+          throw new MegaValidationError('perf.session_unavailable', 'PerfService.run: session store is not configured for this app.', {
+            details: { scenario },
+          })
+        }
+        return {
+          iterate: async (i) => {
+            const sid = `perf-bench-${runId}-${i}`
+            await store.save(sid, { userId: i, runId })
+            await store.load(sid)
+            await store.destroy(sid)
+          },
+          teardown: noTeardown,
+        }
+      }
+      default:
+        // SCENARIO_LIMITS 게이트를 통과했으면 도달 불가 — 방어적 fail-fast.
+        throw new MegaValidationError('perf.unknown_scenario', `PerfService.#prepare: no handler for "${scenario}".`, { details: { scenario } })
+    }
+  }
+}
+
+/**
+ * 시나리오별 유효 상한·동시성 디폴트(ADR-174). maxIter 는 자기-DoS/OOM 방어 상한(스키마 max 와 별개로
+ * 시나리오 비용에 맞춰 더 낮게), defConc 는 concurrency 미지정 시 기본값, maxConc 는 동시성 상한.
+ * @type {Record<string, { maxIter: number, defConc: number, maxConc: number }>}
+ */
+export const SCENARIO_LIMITS = Object.freeze({
+  'http.echo': { maxIter: 100_000, defConc: 10, maxConc: 100 },
+  'http.jsonSmall': { maxIter: 100_000, defConc: 10, maxConc: 100 },
+  'http.jsonLarge': { maxIter: 20_000, defConc: 10, maxConc: 50 },
+  'crypto.hash': { maxIter: 500, defConc: 1, maxConc: 4 },
+  'crypto.aspRoundtrip': { maxIter: 100_000, defConc: 10, maxConc: 50 },
+  'db.pg.insertSelect': { maxIter: 5_000, defConc: 10, maxConc: 50 },
+  'db.mongo.insertFind': { maxIter: 5_000, defConc: 10, maxConc: 50 },
+  'cache.redis.setGet': { maxIter: 10_000, defConc: 10, maxConc: 50 },
+  'session.createRead': { maxIter: 10_000, defConc: 10, maxConc: 50 },
+})
+
+/**
+ * 정수 입력을 [min,max] 로 clamp(미지정/비정수는 fallback). payloadSize 같은 선택 입력을 시나리오별
+ * 안전 범위로 정규화한다.
+ * @param {unknown} v @param {number} min @param {number} max @param {number} fallback @returns {number}
+ */
+function clampInt(v, min, max, fallback) {
+  if (typeof v !== 'number' || !Number.isFinite(v)) return fallback
+  return Math.max(min, Math.min(max, Math.trunc(v)))
+}
+
+/**
+ * 정렬된 표본에서 nearest-rank 백분위수를 뽑는다. 빈 표본은 0.
+ * @param {number[]} sorted - 오름차순 정렬된 표본. @param {number} p - 1..100.
+ * @returns {number} p 백분위 값(ms).
+ */
+export function percentile(sorted, p) {
+  const n = sorted.length
+  if (n === 0) return 0
+  const rank = Math.ceil((p / 100) * n)
+  const idx = Math.min(n - 1, Math.max(0, rank - 1))
+  return sorted[idx]
+}
+
+/**
+ * per-iteration 지연 표본 + wall-clock 으로 통계를 만든다. rps 는 전체 반복 수 / wall 초.
+ * @param {number[]} samples - 성공 iteration 의 지연(ms, 미정렬 허용). @param {number} wallMs - 전체 wall-clock(ms).
+ * @param {number} total - 시도한 전체 반복 수(성공+실패).
+ * @returns {{ durationMs: number, rps: number, avg: number, p50: number, p90: number, p95: number, p99: number, min: number, max: number, ok: number, fail: number }}
+ */
+export function summarize(samples, wallMs, total) {
+  const sorted = [...samples].sort((a, b) => a - b)
+  const n = sorted.length
+  const sum = sorted.reduce((acc, v) => acc + v, 0)
+  const wallSec = wallMs / 1000
+  return {
+    durationMs: round3(wallMs),
+    rps: wallSec > 0 ? round1(total / wallSec) : 0,
+    avg: n > 0 ? round3(sum / n) : 0,
+    p50: round3(percentile(sorted, 50)),
+    p90: round3(percentile(sorted, 90)),
+    p95: round3(percentile(sorted, 95)),
+    p99: round3(percentile(sorted, 99)),
+    min: n > 0 ? round3(sorted[0]) : 0,
+    max: n > 0 ? round3(sorted[n - 1]) : 0,
+    ok: n,
+    fail: total - n,
+  }
+}
+
+/** 소수 3자리 반올림(ms 정밀도). @param {number} v @returns {number} */
+function round3(v) {
+  return Math.round(v * 1000) / 1000
+}
+
+/** 소수 1자리 반올림(rps). @param {number} v @returns {number} */
+function round1(v) {
+  return Math.round(v * 10) / 10
+}

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

@@ -0,0 +1,75 @@
+// @ts-check
+import { MegaService } from 'mega-framework'
+import { User } from '../models/user.js'
+
+/**
+ * RedisDemoService — /demo/redis 데모 로직(ADR-157). 파일명 `redis-demo-service.js` → 자동 DI 이름
+ * `redisDemo`(ctx.services.redisDemo, ADR-148). 'demo' 캐시(redis db1)를 두 가지 방식으로 시연한다:
+ *
+ *   1) **방문 카운터** — 표준 캐시 표면(get/set)에 없는 원자적 INCR 가 필요하므로 `.native`(raw ioredis)로
+ *      `INCR`/`EXPIRE` 를 직접 호출한다(ADR-009 escape hatch). 누적 카운터 + 일자별 카운터(TTL 2일).
+ *   2) **쿼리 결과 캐시** — 표준 표면 `get/set`(JSON 직렬화 + TTL)으로 SQL 카운트(User.count)를 30초 캐싱한다.
+ *      hit/miss 와 남은 TTL(`.native.ttl`)을 함께 돌려줘 캐시 동작을 눈으로 보게 한다.
+ *
+ * 캐시 키는 'demo' 캐시 안에서 `demo:redis:*` 네임스페이스로 두어 다른 용도와 분리한다(같은 redis 인스턴스라도
+ * db1 단독 사용이라 충돌 위험은 없지만 가독성 목적).
+ */
+export class RedisDemoService extends MegaService {
+  /** 누적 방문 카운터 키. */
+  static VISITS_TOTAL_KEY = 'demo:redis:visits:total'
+  /** 일자별 방문 카운터 키 prefix(뒤에 YYYY-MM-DD). */
+  static VISITS_DAY_PREFIX = 'demo:redis:visits:'
+  /** 일자별 카운터 TTL(초) — 2일. 자정 경계 직후에도 전날 값이 잠시 남게 여유를 둔다. */
+  static VISITS_DAY_TTL = 172_800
+  /** 캐시 데모 키(SQL 카운트). */
+  static USER_COUNT_KEY = 'demo:redis:user-count'
+  /** 캐시 데모 TTL(초). */
+  static USER_COUNT_TTL = 30
+
+  /**
+   * 방문 1회 기록. 누적·당일 카운터를 원자적 INCR 로 올리고, 당일 키에는 TTL 을 건다.
+   * `.native`(ioredis)의 `INCR` 는 키가 없으면 0→1 로 시작한다(별도 초기화 불필요).
+   * @returns {Promise<{ total: number, today: number, date: string }>}
+   */
+  async recordVisit() {
+    const redis = this.ctx.cache('demo').native
+    const date = RedisDemoService.#today()
+    const dayKey = RedisDemoService.VISITS_DAY_PREFIX + date
+    const total = await redis.incr(RedisDemoService.VISITS_TOTAL_KEY)
+    const today = await redis.incr(dayKey)
+    // 매 방문마다 TTL 을 재설정(rolling) — 활동이 있는 한 당일 키는 유지되고, 멈추면 2일 뒤 자동 정리된다.
+    await redis.expire(dayKey, RedisDemoService.VISITS_DAY_TTL)
+    this.ctx.log?.debug?.({ total, today, date }, 'redis-demo.visit')
+    return { total, today, date }
+  }
+
+  /**
+   * 캐시된 사용자 수를 돌려준다. 캐시에 있으면 hit(+남은 TTL), 없으면 SQL 로 세어 30초 TTL 로 채운다(miss).
+   * @returns {Promise<{ value: number, isHit: boolean, ttlSeconds: number }>}
+   */
+  async getUserCountCached() {
+    const cache = this.ctx.cache('demo')
+    const cached = await cache.get(RedisDemoService.USER_COUNT_KEY)
+    if (cached !== null) {
+      // ioredis TTL: 남은 초(-1=무기한, -2=키 없음). 방금 hit 이라 양수가 정상.
+      const ttlSeconds = await cache.native.ttl(RedisDemoService.USER_COUNT_KEY)
+      this.ctx.log?.debug?.({ value: cached, ttlSeconds }, 'redis-demo.cache hit')
+      return { value: cached, isHit: true, ttlSeconds }
+    }
+    const value = await User.count()
+    await cache.set(RedisDemoService.USER_COUNT_KEY, value, { ttl: RedisDemoService.USER_COUNT_TTL })
+    this.ctx.log?.debug?.({ value }, 'redis-demo.cache miss — recomputed from SQL')
+    return { value, isHit: false, ttlSeconds: RedisDemoService.USER_COUNT_TTL }
+  }
+
+  /** 캐시 데모 키를 비운다(DEL — 다음 조회는 miss 로 재계산). @returns {Promise<void>} */
+  async clearUserCountCache() {
+    await this.ctx.cache('demo').del(RedisDemoService.USER_COUNT_KEY)
+    this.ctx.log?.debug?.('redis-demo.cache cleared')
+  }
+
+  /** 오늘 날짜(YYYY-MM-DD, 로컬). @returns {string} */
+  static #today() {
+    return new Date().toISOString().slice(0, 10)
+  }
+}

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

@@ -0,0 +1,69 @@
+// @ts-check
+import { MegaService, MegaTracing } from 'mega-framework'
+
+/**
+ * TracingDemoService — /demo/tracing 분산 추적 데모 로직(ADR-104/126/163). 파일명 `tracing-demo-service.js` →
+ * 자동 DI 이름 `tracingDemo`(ctx.services.tracingDemo, ADR-148).
+ *
+ * 코어가 모든 HTTP 요청에 루트 span 을 깔고(mega-app onRequest), 활성 span 의 trace_id 를 로그 mixin 으로도
+ * 주입한다. 본 서비스는 현재 요청의 trace_id 를 읽고(MegaTracing.currentTraceIds), 최근 trace 목록을 redis
+ * LIST 에 남겨(LPUSH+LTRIM) Zipkin 딥링크로 잇는다. 키는 'demo' 캐시 안 `demo:trace:*` 네임스페이스다.
+ *
+ * 트레이싱은 옵트인(.env MEGA_OTEL_ENABLED)이고, exporter(otlp→collector→Zipkin) 경로로 span 이 흘러간다.
+ * OFF 면 currentTraceIds() 가 null 이라 화면이 비활성 안내를 보여준다.
+ */
+export class TracingDemoService extends MegaService {
+  /** 최근 trace 이력 LIST 키. */
+  static RECENT_KEY = 'demo:trace:recent'
+  /** 이력 보관 최대 건수(LTRIM 유지). */
+  static RECENT_MAX = 15
+
+  /**
+   * Zipkin UI base URL — `MEGA_OTEL_ZIPKIN_API`(.../api/v2)에서 API 경로를 떼 UI 루트를 만든다(신규 env 키 없이
+   * 기존 값 재사용). 미설정이면 docker 기본값. trace 딥링크는 `${base}/zipkin/traces/<traceId>`.
+   * @returns {string}
+   */
+  static zipkinBase() {
+    const api = process.env.MEGA_OTEL_ZIPKIN_API || 'http://localhost:9411/api/v2'
+    return api.replace(/\/api\/v2\/?$/, '')
+  }
+
+  /**
+   * 현재 요청의 trace_id 를 최근 이력에 1건 기록한다(있을 때만). 트레이싱 OFF(traceId 없음)면 no-op.
+   * @param {string} route - 기록할 라우트 라벨(표시용).
+   * @returns {Promise<string|null>} 기록한 trace_id(없으면 null).
+   */
+  async record(route) {
+    const ids = MegaTracing.currentTraceIds()
+    if (!ids) return null
+    const redis = this.ctx.cache('demo').native
+    const at = new Date().toISOString()
+    await redis.lpush(TracingDemoService.RECENT_KEY, JSON.stringify({ traceId: ids.traceId, spanId: ids.spanId, route, at }))
+    await redis.ltrim(TracingDemoService.RECENT_KEY, 0, TracingDemoService.RECENT_MAX - 1)
+    this.ctx.log?.debug?.({ traceId: ids.traceId, route }, 'tracing-demo.record')
+    return ids.traceId
+  }
+
+  /**
+   * 화면 렌더용 스냅샷 — 활성 여부 + 현재 trace_id + 최근 trace 목록 + Zipkin base + service name.
+   * @returns {Promise<{
+   *   enabled: boolean,
+   *   current: { traceId: string, spanId: string } | null,
+   *   recent: Array<{ traceId: string, spanId: string, route: string, at: string }>,
+   *   zipkinBase: string,
+   *   serviceName: string,
+   * }>}
+   */
+  async snapshot() {
+    const redis = this.ctx.cache('demo').native
+    const rawList = await redis.lrange(TracingDemoService.RECENT_KEY, 0, TracingDemoService.RECENT_MAX - 1)
+    const recent = rawList.map((/** @type {string} */ s) => JSON.parse(s))
+    return {
+      enabled: MegaTracing.isEnabled(),
+      current: MegaTracing.currentTraceIds(),
+      recent,
+      zipkinBase: TracingDemoService.zipkinBase(),
+      serviceName: process.env.MEGA_OTEL_SERVICE_NAME || 'mega-app',
+    }
+  }
+}

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

@@ -0,0 +1,48 @@
+// @ts-check
+import { MegaService } from 'mega-framework'
+
+/**
+ * UploadDemoService — /demo/upload 파일 업로드 데모 로직(ADR-133/163). 파일명 `upload-demo-service.js` →
+ * 자동 DI 이름 `uploadDemo`(ctx.services.uploadDemo, ADR-148).
+ *
+ * `req.saveUploads()`(코어 multipart)가 임시 디렉터리에 저장한 결과 메타(파일명/크기/MIME)를 redis LIST 에
+ * 남겨(LPUSH+LTRIM) 화면에 최근 업로드 목록으로 보여준다. 저장된 실제 파일의 절대경로(savedAs)는 서버 내부
+ * 정보라 화면·이력엔 담지 않는다. 키는 'demo' 캐시 안 `demo:upload:*` 네임스페이스다.
+ */
+export class UploadDemoService extends MegaService {
+  /** 최근 업로드 이력 LIST 키. */
+  static RECENT_KEY = 'demo:upload:recent'
+  /** 이력 보관 최대 건수(LTRIM 유지). */
+  static RECENT_MAX = 15
+
+  /**
+   * 저장 결과 메타를 최근 이력에 기록한다(파일별 1건). 저장 경로(path)는 프로젝트 루트 기준 상대경로다
+   * (서버 절대경로 비노출 — 데모에선 위치 확인이 목적).
+   * @param {Array<{ filename: string, bytes: number, mimetype: string, path: string }>} saved - 저장 결과 메타.
+   * @returns {Promise<void>}
+   */
+  async record(saved) {
+    if (!Array.isArray(saved) || saved.length === 0) return
+    const redis = this.ctx.cache('demo').native
+    const at = new Date().toISOString()
+    for (const f of saved) {
+      await redis.lpush(
+        UploadDemoService.RECENT_KEY,
+        JSON.stringify({ filename: f.filename, bytes: f.bytes, mimetype: f.mimetype, path: f.path ?? null, at }),
+      )
+    }
+    await redis.ltrim(UploadDemoService.RECENT_KEY, 0, UploadDemoService.RECENT_MAX - 1)
+    this.ctx.log?.debug?.({ files: saved.length }, 'upload-demo.record')
+  }
+
+  /**
+   * 화면 렌더용 스냅샷 — 최근 업로드 메타 목록.
+   * @returns {Promise<{ recent: Array<{ filename: string, bytes: number, mimetype: string, path: string|null, at: string }> }>}
+   */
+  async snapshot() {
+    const redis = this.ctx.cache('demo').native
+    const rawList = await redis.lrange(UploadDemoService.RECENT_KEY, 0, UploadDemoService.RECENT_MAX - 1)
+    const recent = rawList.map((/** @type {string} */ s) => JSON.parse(s))
+    return { recent }
+  }
+}

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

@@ -0,0 +1,65 @@
+// @ts-check
+import { MegaService } from 'mega-framework'
+import { MegaNotFoundError, MegaValidationError, MegaConflictError } from 'mega-framework/errors'
+import { User } from '../models/user.js'
+
+/**
+ * UserService — user 도메인 비즈니스 로직(ADR-022). 컨트롤러는 모델을 직접 만지지 않고 이 서비스를
+ * 거친다. 파일명 `user-service.js` → 자동 DI 이름 `user`(ctx.services.user, ADR-148). 모델 import 는
+ * 서비스에서만 허용(유일한 모델 접근 경로).
+ */
+export class UserService extends MegaService {
+  /** @returns {Promise<object[]>} */
+  async list() {
+    this.log.debug?.('user.list')
+    return User.list()
+  }
+
+  /** @param {string|number} id @returns {Promise<object>} @throws {MegaNotFoundError} */
+  async get(id) {
+    const user = await User.findById(Number(id))
+    if (!user) throw new MegaNotFoundError('user.not_found', `User ${id} not found`, { details: { id } })
+    return user
+  }
+
+  /** @param {{ name?: unknown, email?: unknown }} input @returns {Promise<object>} */
+  async create(input) {
+    const name = typeof input?.name === 'string' ? input.name.trim() : ''
+    const email = typeof input?.email === 'string' ? input.email.trim() : ''
+    if (!name || !email) {
+      throw new MegaValidationError('user.invalid', 'name and email are required', { details: { name: !!name, email: !!email } })
+    }
+    try {
+      return await User.create({ name, email })
+    } catch (err) {
+      // postgres unique_violation(23505) → 이메일 중복은 도메인 충돌(409)로 매핑(P4 — 명시 처리 후 throw).
+      if (/** @type {any} */ (err)?.code === '23505') {
+        throw new MegaConflictError('user.email_taken', `email '${email}' already exists`, { details: { email }, cause: err })
+      }
+      throw err
+    }
+  }
+
+  /** @param {string|number} id @param {{ name?: string, email?: string }} patch @returns {Promise<object>} @throws {MegaNotFoundError} @throws {MegaConflictError} */
+  async update(id, patch) {
+    let updated
+    try {
+      updated = await User.update(Number(id), { name: patch?.name, email: patch?.email })
+    } catch (err) {
+      // create() 와 동일 — 이메일 중복(unique_violation 23505)은 도메인 충돌(409)로 매핑(P4 — 명시 처리 후 throw).
+      if (/** @type {any} */ (err)?.code === '23505') {
+        throw new MegaConflictError('user.email_taken', `email '${patch?.email}' already exists`, { details: { email: patch?.email }, cause: err })
+      }
+      throw err
+    }
+    if (!updated) throw new MegaNotFoundError('user.not_found', `User ${id} not found`, { details: { id } })
+    return updated
+  }
+
+  /** @param {string|number} id @returns {Promise<{ deleted: true }>} @throws {MegaNotFoundError} */
+  async remove(id) {
+    const ok = await User.remove(Number(id))
+    if (!ok) throw new MegaNotFoundError('user.not_found', `User ${id} not found`, { details: { id } })
+    return { deleted: true }
+  }
+}

package/sample/crud/apps/main/views/auth/login.ejs

@@ -0,0 +1,57 @@
+<% layout('layouts/main') %>
+
+<div class="row justify-content-center">
+  <div class="col-md-6 col-lg-5">
+    <div class="card shadow-sm">
+      <div class="card-body p-4">
+        <h1 class="h4 mb-4 text-center"><%= t('login_title', '로그인') %></h1>
+
+        <% if (typeof notice !== 'undefined' && notice) { %>
+          <div class="alert alert-success" role="alert"><%= notice %></div>
+        <% } %>
+        <% if (typeof error !== 'undefined' && error) { %>
+          <div class="alert alert-danger" role="alert"><%= error %></div>
+        <% } %>
+
+        <form method="post" action="/auth/login" novalidate>
+          <input type="hidden" name="_csrf" value="<%= csrfToken %>" />
+
+          <div class="mb-3">
+            <label for="email" class="form-label"><%= t('field_email', '이메일') %></label>
+            <input
+              type="email"
+              class="form-control"
+              id="email"
+              name="email"
+              value="<%= values && values.email ? values.email : '' %>"
+              placeholder="<%= t('field_email_ph', '예: hong@example.com') %>"
+              autocomplete="username"
+              required
+            />
+          </div>
+
+          <div class="mb-4">
+            <label for="password" class="form-label"><%= t('field_password', '비밀번호') %></label>
+            <input
+              type="password"
+              class="form-control"
+              id="password"
+              name="password"
+              autocomplete="current-password"
+              required
+            />
+          </div>
+
+          <div class="d-grid">
+            <button type="submit" class="btn btn-primary"><%= t('btn_login', '로그인') %></button>
+          </div>
+        </form>
+
+        <p class="text-center text-body-secondary small mt-4 mb-0">
+          <%= t('login_no_account', '계정이 없으신가요?') %>
+          <a href="/register"><%= t('register_title', '회원가입') %></a>
+        </p>
+      </div>
+    </div>
+  </div>
+</div>