mega-framework 0.1.0

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

@@ -0,0 +1,34 @@
+// @ts-check
+/**
+ * UserController — HTTP 컨트롤러(ADR-074: 베이스 없음, 정적 메서드만). 모델을 직접 import 하지 않고
+ * `ctx.services.user`(자동 DI, ADR-148)로 서비스를 거친다(ADR-022). 핸들러는 도메인 데이터만 반환하고
+ * envelope(`{ ok, data, meta }`)는 프레임워크가 감싼다(ADR-018/147).
+ */
+export class UserController {
+  /** GET /users — 목록 @param {any} _req @param {any} _reply @param {any} ctx */
+  static async index(_req, _reply, ctx) {
+    return ctx.services.user.list()
+  }
+
+  /** GET /users/:id — 단건(없으면 404 에러 envelope) @param {any} req @param {any} _reply @param {any} ctx */
+  static async show(req, _reply, ctx) {
+    return ctx.services.user.get(req.params.id)
+  }
+
+  /** POST /users — 생성(201) @param {any} req @param {any} reply @param {any} ctx */
+  static async create(req, reply, ctx) {
+    const user = await ctx.services.user.create(req.body)
+    reply.code(201)
+    return user
+  }
+
+  /** PUT /users/:id — 수정 @param {any} req @param {any} _reply @param {any} ctx */
+  static async update(req, _reply, ctx) {
+    return ctx.services.user.update(req.params.id, req.body ?? {})
+  }
+
+  /** DELETE /users/:id — 삭제 @param {any} req @param {any} _reply @param {any} ctx */
+  static async destroy(req, _reply, ctx) {
+    return ctx.services.user.remove(req.params.id)
+  }
+}

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

@@ -0,0 +1,137 @@
+// @ts-check
+/**
+ * WebController — 관리 UI(MPA) HTTP 컨트롤러(ADR-074: 베이스 없음, 정적 메서드만).
+ *
+ * JSON REST API(`/users`, user-controller.js)와 같은 `ctx.services.user`(자동 DI, ADR-148)를 거치되,
+ * 도메인 데이터를 반환하는 대신 EJS 뷰를 서버사이드 렌더한다(ADR-011/136). 폼 제출(urlencoded)은
+ * `@fastify/formbody`(ADR-151)가 `req.body` 로 파싱하고, 생성/수정 후엔 PRG(Post/Redirect/Get)로
+ * 목록으로 리다이렉트한다. 검증/충돌 에러는 폼을 에러 표시와 함께 다시 렌더한다(JSON envelope 대신).
+ *
+ * CSRF(ADR-051, 디폴트 ON)는 폼 `_csrf` 토큰을 요구하므로, 폼을 담은 뷰는 `reply.generateCsrf()`로
+ * 토큰을 발급해 hidden input 으로 심는다.
+ */
+import { MegaNotFoundError, MegaValidationError, MegaConflictError } from 'mega-framework/errors'
+import { currentUser } from '../middleware/web-auth.js'
+
+/** 알림 쿼리(?notice=) → 로케일 키 화이트리스트(임의 t() 조회 방지). */
+const NOTICE_KEYS = new Set(['created', 'updated', 'deleted'])
+
+/**
+ * 검증/충돌 에러에서 어떤 필드가 잘못됐는지 계산한다(폼 is-invalid 표시용).
+ * @param {unknown} err
+ * @returns {{ name: boolean, email: boolean }}
+ */
+function invalidFields(err) {
+  if (err instanceof MegaValidationError) {
+    const d = /** @type {any} */ (err).details ?? {}
+    // user-service 는 details.{name,email} = "값이 있는가"(true=정상) 로 준다 → 없으면 invalid.
+    return { name: !d.name, email: !d.email }
+  }
+  if (err instanceof MegaConflictError) {
+    return { name: false, email: true } // 이메일 중복.
+  }
+  return { name: false, email: false }
+}
+
+export class WebController {
+  /** GET / — 랜딩 페이지(공개). @param {any} req @param {any} reply @param {any} ctx */
+  static async home(req, reply, ctx) {
+    // 로그인 상태면 navbar 로그아웃 폼(POST+CSRF)이 토큰을 쓰므로 공개 페이지에서도 발급한다.
+    return ctx.render('home', { title: ctx.t('home_title', '사용자 CRUD 관리'), currentUser: currentUser(req), csrfToken: reply.generateCsrf() })
+  }
+
+  /** GET /admin/users — 목록(+ ?notice= 알림, 삭제 폼 CSRF 토큰). @param {any} req @param {any} reply @param {any} ctx */
+  static async list(req, reply, ctx) {
+    const users = await ctx.services.user.list()
+    const key = String(req.query?.notice ?? '')
+    const notice = NOTICE_KEYS.has(key) ? ctx.t(`notice_${key}`) : null
+    return ctx.render('users/list', {
+      title: ctx.t('users_title', '사용자 목록'),
+      users,
+      notice,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** GET /admin/users/new — 신규 폼. @param {any} req @param {any} reply @param {any} ctx */
+  static async newForm(req, reply, ctx) {
+    return ctx.render('users/new', {
+      title: ctx.t('new_title', '사용자 추가'),
+      values: {},
+      invalid: null,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /** POST /admin/users — 생성 → 목록 리다이렉트(PRG). 검증/충돌 시 폼 재렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async create(req, reply, ctx) {
+    try {
+      await ctx.services.user.create(req.body ?? {})
+      return reply.redirect('/admin/users?notice=created')
+    } catch (err) {
+      if (err instanceof MegaValidationError || err instanceof MegaConflictError) {
+        reply.code(err instanceof MegaConflictError ? 409 : 400)
+        return ctx.render('users/new', {
+          title: ctx.t('new_title', '사용자 추가'),
+          values: req.body ?? {},
+          invalid: invalidFields(err),
+          error: err.message,
+          currentUser: currentUser(req),
+          csrfToken: reply.generateCsrf(),
+        })
+      }
+      throw err // 미지 에러는 프레임워크 글로벌 핸들러로.
+    }
+  }
+
+  /** GET /admin/users/:id/edit — 수정 폼(사전 채움). 없으면 목록으로. @param {any} req @param {any} reply @param {any} ctx */
+  static async editForm(req, reply, ctx) {
+    try {
+      const user = await ctx.services.user.get(req.params.id)
+      return ctx.render('users/edit', {
+        title: ctx.t('edit_title', '사용자 수정'),
+        values: user,
+        invalid: null,
+        currentUser: currentUser(req),
+        csrfToken: reply.generateCsrf(),
+      })
+    } catch (err) {
+      if (err instanceof MegaNotFoundError) return reply.redirect('/admin/users')
+      throw err
+    }
+  }
+
+  /** POST /admin/users/:id — 수정 → 목록 리다이렉트(PRG). 검증/충돌 시 폼 재렌더, 없으면 목록으로. @param {any} req @param {any} reply @param {any} ctx */
+  static async update(req, reply, ctx) {
+    try {
+      await ctx.services.user.update(req.params.id, req.body ?? {})
+      return reply.redirect('/admin/users?notice=updated')
+    } catch (err) {
+      if (err instanceof MegaValidationError || err instanceof MegaConflictError) {
+        reply.code(err instanceof MegaConflictError ? 409 : 400)
+        return ctx.render('users/edit', {
+          title: ctx.t('edit_title', '사용자 수정'),
+          values: { id: req.params.id, ...(req.body ?? {}) },
+          invalid: invalidFields(err),
+          error: err.message,
+          currentUser: currentUser(req),
+          csrfToken: reply.generateCsrf(),
+        })
+      }
+      if (err instanceof MegaNotFoundError) return reply.redirect('/admin/users')
+      throw err
+    }
+  }
+
+  /** POST /admin/users/:id/delete — 삭제 → 목록 리다이렉트(PRG). 없으면 그대로 목록으로. @param {any} req @param {any} reply @param {any} ctx */
+  static async destroy(req, reply, ctx) {
+    try {
+      await ctx.services.user.remove(req.params.id)
+    } catch (err) {
+      if (!(err instanceof MegaNotFoundError)) throw err
+    }
+    return reply.redirect('/admin/users?notice=deleted')
+  }
+}

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

@@ -0,0 +1,57 @@
+// @ts-check
+/**
+ * WorkerController — /demo/worker CPU 워커 풀 데모 UI HTTP 컨트롤러(ADR-074/124, ADR-157).
+ *
+ * `ctx.workers['hash']`(boot 가 config.workers 로 배선) 으로 SHA-256 N회 반복 같은 CPU-bound 작업을 worker_threads
+ * 풀에서 돌린다. 계산은 AJAX(JSON)로 실행하고(폼 아닌 JSON → CSRF 토큰 면제 + Origin 검증, ADR-051), 페이지의
+ * 하트비트 ping 이 계산 도중에도 계속 응답받는 걸 보여줘 **메인 스레드 non-block** 을 시연한다.
+ */
+import { currentUser } from '../middleware/web-auth.js'
+import { HashWorker } from '../workers/hash-worker.js'
+
+/** 반복 횟수 기본/최소/최대 — 과도한 입력으로 워커를 장시간 점유하지 않게 상한을 둔다. 기본값은 계산이
+ *  몇 초 걸리도록 잡아, 실행 중에도 하트비트가 계속 도는(메인 스레드 non-block) 모습을 눈으로 보게 한다. */
+const ROUNDS_DEFAULT = 5_000_000
+const ROUNDS_MIN = 100_000
+const ROUNDS_MAX = 20_000_000
+/** 워커 task 타임아웃(ms) — 상한 반복도 여유 있게 끝나도록. */
+const RUN_TIMEOUT_MS = 60_000
+
+export class WorkerController {
+  /** GET /demo/worker — 실행 폼 + 풀 정보 + 하트비트 영역 렌더. @param {any} req @param {any} reply @param {any} ctx */
+  static async index(req, reply, ctx) {
+    return ctx.render('worker/index', {
+      title: ctx.t('worker_title', { defaultValue: 'CPU 워커 데모 (MegaWorker)' }),
+      pool: { name: HashWorker.name, mode: HashWorker.mode, poolSize: HashWorker.poolSize },
+      defaultRounds: ROUNDS_DEFAULT,
+      currentUser: currentUser(req),
+      csrfToken: reply.generateCsrf(),
+    })
+  }
+
+  /**
+   * POST /demo/worker/run — CPU-bound 해시를 워커 풀에서 실행하고 결과(JSON)를 돌려준다. JSON 요청이라 CSRF
+   * 토큰 없이 Origin 검증만 거친다(ADR-051). @param {any} req @param {any} reply @param {any} ctx
+   */
+  static async run(req, reply, ctx) {
+    const body = req.body ?? {}
+    const requested = Number(body.rounds)
+    const rounds = Number.isFinite(requested)
+      ? Math.min(ROUNDS_MAX, Math.max(ROUNDS_MIN, Math.floor(requested)))
+      : ROUNDS_DEFAULT
+    const startedAt = Date.now()
+    const out = await ctx.workers['hash'].run('sha256Loop', { input: 'mega', rounds }, { timeoutMs: RUN_TIMEOUT_MS })
+    const ms = Date.now() - startedAt
+    ctx.log?.debug?.({ rounds, ms }, 'worker-demo.run')
+    // 프레임워크가 JSON 응답을 { ok, data, meta } 엔벨로프로 감싸므로(정본 응답 포맷) 본문은 data 에 담긴다.
+    return reply.send({ digest: out.digest, rounds: out.rounds, ms })
+  }
+
+  /**
+   * GET /demo/worker/ping — 즉시 응답하는 하트비트(JSON). 워커 계산이 도는 동안에도 이 응답이 끊김 없이
+   * 빨라야 메인 스레드가 안 막힌 것이다. @param {any} _req @param {any} reply @param {any} _ctx
+   */
+  static async ping(_req, reply, _ctx) {
+    return reply.send({ ok: true, at: new Date().toISOString() })
+  }
+}

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

@@ -0,0 +1,29 @@
+// @ts-check
+/**
+ * WsController — /demo/ws 실시간 채팅 데모 페이지(MPA) HTTP 컨트롤러(ADR-158, ADR-074 정적 메서드만).
+ *
+ * 채팅 자체는 WebSocket(/ws/chat)으로 흐르므로 이 컨트롤러는 셸 페이지만 렌더한다 — 접속 스크립트
+ * (ws-chat.js)와 WASM MegaSocket 이 브라우저에서 ASP E: 프레임으로 연결한다. 페이지는 `webRequireAuth`
+ * 뒤라 currentUser 가 보장된다.
+ *
+ * ASP 공유-키: WASM 클라이언트도 서버와 같은 masterSecret 으로 키를 유도해야 하므로(공유-키 구조),
+ * 서버 env(ASP_MASTER_SECRET)를 페이지에 주입한다. CSP(script-src 'self')가 인라인 스크립트를 막으므로
+ * 시크릿은 **data 속성**으로 심고 외부 스크립트(ws-chat.js)가 읽는다(인라인 주입 불가).
+ */
+import { currentUser } from '../middleware/web-auth.js'
+
+export class WsController {
+  /** GET /demo/ws — 채팅 셸 렌더(로그인 필요). @param {any} req @param {any} reply @param {any} ctx */
+  static async index(req, reply, ctx) {
+    return ctx.render('ws/index', {
+      title: ctx.t('ws_title', { defaultValue: '실시간 채팅 (WebSocket + ASP)' }),
+      currentUser: currentUser(req),
+      // navbar 로그아웃 폼(POST+CSRF)이 토큰을 쓴다(로그인 상태 페이지).
+      csrfToken: reply.generateCsrf(),
+      // WS 엔드포인트 경로 — 클라가 location.host 와 합쳐 ws(s):// URL 을 만든다.
+      wsPath: '/ws/chat',
+      // WASM MegaSocket 의 ASP masterSecret(공유-키). data 속성으로 전달.
+      aspSecret: process.env.ASP_MASTER_SECRET ?? '',
+    })
+  }
+}

package/sample/crud/apps/main/jobs/email-job.js

@@ -0,0 +1,72 @@
+// @ts-check
+import { MegaJob } from 'mega-framework'
+
+/** 'flaky' 모드가 성공하는 시도 번호 — 1번째 시도는 실패(throw)하고 2번째 시도에 성공한다(재시도 시연). */
+const FLAKY_SUCCEED_ON = 2
+/** 시도 카운터 키 TTL(초) — 데모 잡은 짧게 살고 사라진다. */
+const ATTEMPT_TTL = 600
+
+/**
+ * EmailJob — /demo/jobs 데모 잡(ADR-028/119). `mega worker` 프로세스(ecosystem instances:2)가 소비한다
+ * (config.jobs). 실제 메일은 보내지 않고 발송을 **시뮬레이션**하며, payload.mode 로 세 가지 흐름을 시연한다:
+ *
+ *   - `ok`    : 1번째 시도에 바로 성공(sent).
+ *   - `flaky` : 1번째 시도는 throw(일시 실패) → MegaJobQueue 가 재시도(p-retry, static retries/backoff) →
+ *               2번째 시도에 성공. "일시 오류는 그냥 throw 하면 재시도된다"(MegaJob 정본)를 보여준다.
+ *   - `fail`  : 매 시도 throw(영구 실패) → 재시도 소진 후 DLQ(`<subject>.dlq`)로 격리된다.
+ *
+ * 각 시도를 'demo' 캐시(redis)에 기록해(시도 카운터 + 이벤트 LIST) 웹 페이지가 처리 타임라인을 보여준다.
+ * NATS durable consumer group(같은 durable 이름)이라 instances:2 워커가 메시지를 자연 분산 처리한다(중복 X).
+ */
+export class EmailJob extends MegaJob {
+  static subject = 'demo.email'
+  static bus = 'jobs'
+  static concurrency = 2
+  // 추가 재시도 2회(첫 시도 포함 최대 3회). 데모 체감용으로 백오프를 짧게 둔다(기본 1s~30s 대신 0.5s~2s).
+  static retries = 2
+  static backoff = { type: 'exponential', initial: 500, max: 2000 }
+
+  /** 이벤트 LIST 키(LPUSH → 최신이 앞). 웹이 LRANGE 로 읽는다. */
+  static EVENTS_KEY = 'demo:jobs:events'
+  /** 이벤트 보관 최대 건수. */
+  static EVENTS_MAX = 30
+
+  /**
+   * 메시지 1건 처리. throw 하면 MegaJobQueue 가 재시도/DLQ 를 담당하므로 일시·영구 실패는 그냥 throw 한다.
+   * @param {{ id: string, to: string, subject?: string, mode: 'ok'|'flaky'|'fail' }} payload
+   * @param {Record<string, any>} ctx - worker 프로세스 컨텍스트(ctx.cache('demo') 글로벌 키).
+   * @returns {Promise<{ id: string, status: 'sent', attempt: number }>}
+   * @throws {Error} flaky 의 1번째 시도, fail 의 모든 시도 — 재시도/DLQ 트리거.
+   */
+  async run(payload, ctx) {
+    const { id, to, mode } = payload
+    const redis = ctx.cache('demo').native
+    // 시도 카운터를 원자적으로 올린다 — 재시도(같은 메시지 재실행)마다 1씩 증가해 흐름을 추적한다.
+    const attempt = await redis.incr(`demo:jobs:attempt:${id}`)
+    await redis.expire(`demo:jobs:attempt:${id}`, ATTEMPT_TTL)
+    ctx.log?.debug?.({ id, mode, attempt }, 'email-job.run')
+
+    if (mode === 'flaky' && attempt < FLAKY_SUCCEED_ON) {
+      await EmailJob.#logEvent(redis, { id, to, mode, attempt, status: 'retry' })
+      throw new Error(`EmailJob ${id}: simulated transient failure on attempt ${attempt} (will retry)`)
+    }
+    if (mode === 'fail') {
+      await EmailJob.#logEvent(redis, { id, to, mode, attempt, status: 'failed' })
+      throw new Error(`EmailJob ${id}: simulated permanent failure on attempt ${attempt} (bound for DLQ)`)
+    }
+    // ok, 또는 flaky 가 충분히 재시도된 뒤 → 발송 성공.
+    await EmailJob.#logEvent(redis, { id, to, mode, attempt, status: 'sent' })
+    return { id, status: 'sent', attempt }
+  }
+
+  /**
+   * 처리 이벤트 1건을 redis LIST 머리에 넣고 최근 N건만 남긴다.
+   * @param {any} redis - ioredis 핸들(ctx.cache('demo').native).
+   * @param {{ id: string, to: string, mode: string, attempt: number, status: 'retry'|'failed'|'sent' }} event
+   * @returns {Promise<void>}
+   */
+  static async #logEvent(redis, event) {
+    await redis.lpush(EmailJob.EVENTS_KEY, JSON.stringify({ ...event, at: new Date().toISOString() }))
+    await redis.ltrim(EmailJob.EVENTS_KEY, 0, EmailJob.EVENTS_MAX - 1)
+  }
+}

package/sample/crud/apps/main/locales/client/en.json

@@ -0,0 +1,3 @@
+{
+  "app_title": "CRUD sample"
+}

package/sample/crud/apps/main/locales/client/ko.json

@@ -0,0 +1,3 @@
+{
+  "app_title": "CRUD 샘플"
+}

package/sample/crud/apps/main/locales/server/en.json

@@ -0,0 +1,316 @@
+{
+  "nav_metrics": "Metrics",
+  "nav_tracing": "Tracing",
+  "nav_logs": "Logs",
+  "nav_upload": "Upload",
+  "nav_docs": "API Docs",
+  "nav_guide": "Guide",
+  "nav_perf": "Performance",
+  "nav_demo": "Demo",
+  "perf_title": "Performance Benchmark",
+  "perf_subtitle": "Measures throughput and latency of core framework surfaces (HTTP, crypto, DB, cache, session) directly with Node's built-in perf_hooks.",
+  "perf_form_title": "Run Benchmark",
+  "perf_form_desc": "Pick a scenario and iteration count; per-iteration latency is collected to compute percentiles.",
+  "perf_scenario_label": "Scenario",
+  "perf_iterations_label": "Iterations",
+  "perf_concurrency_label": "Concurrency",
+  "perf_payload_label": "Payload (bytes)",
+  "perf_limit_hint": "Leave concurrency/payload blank to use per-scenario defaults. Each scenario has iteration/concurrency caps for safety; exceeding them is clamped automatically and flagged in the result.",
+  "perf_run_btn": "Run",
+  "perf_clear_btn": "Clear results",
+  "perf_error": "Run failed:",
+  "perf_results_title": "Results",
+  "perf_results_desc": "Each run prepends a row. Lower time (ms) is better; higher RPS is better.",
+  "perf_results_empty": "No runs yet.",
+  "perf_col_scenario": "Scenario",
+  "perf_col_iter": "Iter",
+  "perf_col_conc": "Conc",
+  "perf_col_duration": "Duration(ms)",
+  "perf_col_rps": "RPS",
+  "perf_col_avg": "Avg(ms)",
+  "perf_col_min": "Min",
+  "perf_col_max": "Max",
+  "perf_col_okfail": "OK/Fail",
+  "guide_index_title": "Guide",
+  "guide_index_subtitle": "A collection of MEGA-FRAMEWORK usage guides.",
+  "guide_index_welcome": "Pick a topic to read. Code samples are pre-highlighted on the server.",
+  "guide_toc": "Contents",
+  "guide_back": "Back to list",
+  "metrics_title": "Metrics",
+  "metrics_subtitle": "Prometheus /metrics counters shown as human-friendly cards (this web process).",
+  "metrics_disabled": "Metrics are disabled. Check health.exposeMetrics in mega.config.js.",
+  "metrics_http_title": "HTTP requests",
+  "metrics_http_desc": "Cumulative request count by status class.",
+  "metrics_http_total": "Total requests",
+  "metrics_process_title": "Process",
+  "metrics_process_desc": "Memory, uptime and CPU usage of this web process.",
+  "metrics_process_heap": "Heap used",
+  "metrics_process_rss": "RSS",
+  "metrics_process_uptime": "Uptime",
+  "metrics_process_cpu": "CPU time",
+  "metrics_jobs_title": "Job queue",
+  "metrics_jobs_desc": "Cumulative job processing events (linked to the jobs demo).",
+  "metrics_jobs_enqueued": "Enqueued",
+  "metrics_jobs_processed": "Processed",
+  "metrics_jobs_retried": "Retried",
+  "metrics_jobs_dlq": "DLQ",
+  "metrics_ws_title": "WebSocket",
+  "metrics_ws_desc": "Cumulative WS messages (linked to the chat demo).",
+  "metrics_ws_total": "Total messages",
+  "metrics_ws_empty": "No WS messages yet.",
+  "metrics_routes_title": "Requests by route",
+  "metrics_routes_desc": "Top routes by request count.",
+  "metrics_routes_empty": "No requests recorded yet.",
+  "metrics_routes_route": "Route",
+  "metrics_routes_count": "Count",
+  "metrics_raw_hint": "Raw (Prometheus scrape format):",
+  "tracing_title": "Distributed tracing",
+  "tracing_subtitle": "Links the current request's trace_id and recent traces to Zipkin.",
+  "tracing_notice_generated": "Trace generated. It will appear in Zipkin shortly.",
+  "tracing_disabled": "Tracing is disabled. Set MEGA_OTEL_ENABLED=true in .env and restart.",
+  "tracing_current_title": "Current request trace",
+  "tracing_current_desc": "The trace_id of the request that opened this page (also sent as the x-trace-id response header).",
+  "tracing_trace_id": "trace_id",
+  "tracing_span_id": "span_id",
+  "tracing_open_zipkin": "Open in Zipkin",
+  "tracing_no_current": "No current trace (tracing disabled).",
+  "tracing_generate": "Generate trace",
+  "tracing_generate_hint": "Runs a DB ping inside a user span to build a multi-level span tree.",
+  "tracing_zipkin_title": "Zipkin",
+  "tracing_zipkin_desc": "Traces are exported via OTLP → collector → Zipkin.",
+  "tracing_service": "Service name",
+  "tracing_ui": "Zipkin UI",
+  "tracing_export_hint": "Export has some latency, so a freshly generated trace appears in Zipkin after a short delay.",
+  "tracing_recent_title": "Recent traces",
+  "tracing_recent_desc": "Recently recorded trace_ids.",
+  "tracing_recent_empty": "No traces recorded yet.",
+  "tracing_recent_at": "Time",
+  "tracing_recent_route": "Route",
+  "tracing_view": "View",
+  "logs_title": "Structured logging",
+  "logs_subtitle": "Emit pino logs and see trace_id correlation and secret masking.",
+  "logs_notice_emitted": "Log emitted. Check the structured output in the server console.",
+  "logs_emit_title": "Emit log",
+  "logs_emit_desc": "Sends one log line at the chosen level through the real logger.",
+  "logs_level": "Level",
+  "logs_message": "Message",
+  "logs_message_ph": "e.g. a demo log line",
+  "logs_emit_btn": "emit",
+  "logs_redact_hint": "token/password/secret fields in the log payload are masked as [Redacted] in console output, and the active trace_id is attached automatically (ADR-141). Check the server console.",
+  "logs_recent_title": "Recent emits",
+  "logs_recent_desc": "Safe metadata of emitted logs (secrets excluded).",
+  "logs_recent_empty": "No logs emitted yet.",
+  "logs_recent_at": "Time",
+  "logs_recent_trace": "trace_id",
+  "upload_title": "File upload",
+  "upload_subtitle": "Saves multipart uploads to a project folder and shows metadata + download links.",
+  "upload_form_title": "Upload",
+  "upload_form_desc": "Upload image/PDF/text files (gated by MIME, size and count).",
+  "upload_file_label": "Choose files",
+  "upload_constraints": "Allowed: image/PDF/text · max 5MB · up to 3 at a time",
+  "upload_submit": "Upload",
+  "upload_error": "Upload failed:",
+  "upload_recent_title": "Recent uploads",
+  "upload_recent_desc": "Metadata of saved files (click a filename to download).",
+  "upload_recent_empty": "No files uploaded yet.",
+  "upload_dir_hint": "Saved under (relative to project root):",
+  "upload_recent_at": "Time",
+  "upload_recent_name": "Filename",
+  "upload_recent_path": "Saved path",
+  "upload_recent_mime": "MIME",
+  "upload_recent_size": "Size",
+  "nav_home": "Home",
+  "nav_users": "Users",
+  "theme_toggle": "Toggle theme",
+  "footer_built": "Built with MEGA-FRAMEWORK · Bootstrap 5",
+  "home_title": "User CRUD admin",
+  "home_subtitle": "Create, read, update, and delete a postgres-backed user resource through a Bootstrap 5 admin UI. The same service layer is also exposed as a JSON REST API.",
+  "home_cta_manage": "Manage users",
+  "home_cta_api": "JSON API (/users)",
+  "home_api_note": "Every request follows the canonical layer flow:",
+  "users_title": "Users",
+  "users_new": "Add user",
+  "users_empty": "No users yet.",
+  "col_id": "ID",
+  "col_name": "Name",
+  "col_email": "Email",
+  "col_created": "Created",
+  "col_actions": "Actions",
+  "action_edit": "Edit",
+  "action_delete": "Delete",
+  "delete_confirm_title": "Confirm delete",
+  "delete_confirm_body": "Really delete?",
+  "delete_confirm_cancel": "Cancel",
+  "delete_confirm_ok": "Delete",
+  "new_title": "Add user",
+  "edit_title": "Edit user",
+  "field_name": "Name",
+  "field_name_ph": "e.g. Ada Lovelace",
+  "field_name_required": "Please enter a name.",
+  "field_email": "Email",
+  "field_email_ph": "e.g. ada@example.com",
+  "field_email_required": "Please enter a valid email.",
+  "btn_create": "Create",
+  "btn_save": "Save",
+  "btn_cancel": "Cancel",
+  "notice_created": "User created.",
+  "notice_updated": "User updated.",
+  "notice_deleted": "User deleted.",
+  "field_password": "Password",
+  "field_password_hint": "Use at least 8 characters.",
+  "login_title": "Sign in",
+  "login_failed": "Incorrect email or password.",
+  "login_locked": "Too many attempts. Please try again later.",
+  "login_no_account": "Don't have an account?",
+  "register_title": "Sign up",
+  "register_have_account": "Already have an account?",
+  "btn_login": "Sign in",
+  "btn_logout": "Sign out",
+  "btn_register": "Sign up",
+  "auth_notice_logged_out": "You have been signed out.",
+  "auth_notice_registered": "Your account has been created.",
+  "nav_notes": "Notes (Mongo)",
+  "nav_redis": "Cache (Redis)",
+  "nav_ws": "Chat (WS+ASP)",
+  "notes_title": "Notes (MongoDB)",
+  "notes_subtitle": "Create, read, update, and delete a notes collection through the MongoDB document adapter.",
+  "notes_new": "Add note",
+  "notes_empty": "No notes yet.",
+  "notes_new_title": "Add note",
+  "notes_edit_title": "Edit note",
+  "notes_field_title": "Title",
+  "notes_field_title_ph": "e.g. Meeting memo",
+  "notes_field_title_required": "Please enter a title.",
+  "notes_field_body": "Body",
+  "notes_field_body_ph": "Write the content (optional).",
+  "notes_notice_created": "Note created.",
+  "notes_notice_updated": "Note updated.",
+  "notes_notice_deleted": "Note deleted.",
+  "redis_title": "Redis demo",
+  "redis_subtitle": "Demonstrates a visit counter (atomic INCR/EXPIRE) and a cached query result (GET/SET/TTL/DEL) via the Redis adapter.",
+  "redis_visits_title": "Visit counter",
+  "redis_visits_desc": "Each time you open this page the counter is atomically incremented. The daily counter auto-expires after 2 days.",
+  "redis_visits_total": "Total visits",
+  "redis_visits_today": "Today",
+  "redis_cache_title": "Cached query result",
+  "redis_cache_desc": "Caches the user count in Redis for 30s. A hit skips SQL; a miss recomputes from SQL.",
+  "redis_cache_hit": "Cache hit",
+  "redis_cache_miss": "Cache miss",
+  "redis_cache_ttl": "TTL left",
+  "redis_cache_reload": "Reload",
+  "redis_cache_clear": "Clear cache",
+  "redis_notice_cache_cleared": "Cache cleared.",
+  "home_demo_notes": "Mongo notes demo",
+  "home_demo_redis": "Redis cache demo",
+  "home_demo_ws": "WebSocket chat demo",
+  "ws_title": "Realtime chat (WebSocket + ASP)",
+  "ws_subtitle": "Connects to /ws/chat with the WASM MegaSocket. Messages are ASP-encrypted (E: frames), encrypted/decrypted in the browser, and broadcast to the whole channel by the server.",
+  "ws_asp_badge": "ASP encrypted",
+  "ws_asp_badge_title": "Every message is encrypted with AES-256-GCM (E: frames) in both directions.",
+  "ws_status_connecting": "Connecting…",
+  "ws_status_open": "Connected",
+  "ws_status_closed": "Disconnected",
+  "ws_status_error": "Error",
+  "ws_online": "{n} online",
+  "ws_presence_join": "{user} joined.",
+  "ws_presence_leave": "{user} left.",
+  "ws_empty": "No messages yet. Be the first to say hi.",
+  "ws_input_placeholder": "Type a message…",
+  "ws_send": "Send",
+  "ws_encrypted_note": "Messages are encrypted with ASP (AES-256-GCM) E: frames in transit.",
+  "nav_cron": "Scheduler (Cron)",
+  "nav_jobs": "Job Queue (NATS)",
+  "nav_worker": "Workers (Threads)",
+  "home_demo_cron": "Scheduler demo",
+  "home_demo_jobs": "Job queue demo",
+  "home_demo_worker": "CPU worker demo",
+  "cron_title": "Scheduler demo (MegaSchedule)",
+  "cron_subtitle": "The mega scheduler process bumps a Redis counter atomically every 30 seconds. Duplicate runs across instances are prevented by a distributed lock (redlock leader election).",
+  "cron_counter_title": "Run counter",
+  "cron_counter_desc": "Each scheduled run (or manual trigger below) increments a Redis counter by one.",
+  "cron_counter_total": "Total runs",
+  "cron_run_now": "Run now",
+  "cron_run_hint": "Runs the same job once immediately without waiting for the cron time (manual trigger).",
+  "cron_next_title": "Next run times",
+  "cron_next_desc": "The next five scheduled run times computed by croner (pure calculation, no timer).",
+  "cron_next_soonest": "soonest",
+  "cron_history_title": "Recent run history",
+  "cron_history_desc": "The last 10 runs are kept in a Redis LIST (LPUSH + LTRIM). Scheduled and manual runs stack together.",
+  "cron_history_empty": "No runs yet. Start the scheduler process or trigger a run manually above.",
+  "cron_history_at": "Run time",
+  "cron_history_source": "Source",
+  "cron_source_schedule": "schedule",
+  "cron_source_manual": "manual",
+  "cron_notice_triggered": "Ran the scheduled job once immediately.",
+  "jobs_title": "Job queue demo (MegaJob)",
+  "jobs_subtitle": "Enqueue an EmailJob to NATS JetStream and the mega worker process consumes it. Transient failures retry; permanent failures are isolated to the DLQ.",
+  "jobs_enqueue_title": "Enqueue an email job",
+  "jobs_enqueue_desc": "Nothing is actually sent — only processing is simulated. The mode demonstrates success / retry / permanent failure.",
+  "jobs_enqueue_btn": "Enqueue",
+  "jobs_reload": "Reload",
+  "jobs_field_to": "Recipient",
+  "jobs_field_mode": "Mode",
+  "jobs_mode_ok": "Success",
+  "jobs_mode_flaky": "Retry",
+  "jobs_mode_fail": "Permanent failure",
+  "jobs_mode_ok_hint": "succeeds on the first attempt",
+  "jobs_mode_flaky_hint": "1st attempt fails → retry → 2nd succeeds",
+  "jobs_mode_fail_hint": "every attempt fails → DLQ after retries are exhausted",
+  "jobs_dlq_title": "DLQ (isolated jobs)",
+  "jobs_dlq_desc": "Where permanently failed jobs land after retries are exhausted (a NATS stream). For analysis and reprocessing.",
+  "jobs_dlq_empty": "No jobs have reached the DLQ yet.",
+  "jobs_dlq_failed_at": "Failed at",
+  "jobs_dlq_deliveries": "Deliveries",
+  "jobs_dlq_error": "Error",
+  "jobs_dlq_payload": "Payload",
+  "jobs_events_title": "Processing events",
+  "jobs_events_desc": "The timeline the worker logs per attempt (newest first). Retries show the same job multiple times.",
+  "jobs_events_empty": "No jobs processed yet. Enqueue one above and start the mega worker process.",
+  "jobs_events_at": "Time",
+  "jobs_events_id": "Job ID",
+  "jobs_events_attempt": "Attempt",
+  "jobs_events_status": "Status",
+  "jobs_status_sent": "sent",
+  "jobs_status_retry": "retry",
+  "jobs_status_failed": "failed",
+  "jobs_notice_enqueued": "Job enqueued. Once a worker processes it, it appears in the events below.",
+  "worker_title": "CPU worker demo (MegaWorker)",
+  "worker_subtitle": "Runs CPU-bound work like N rounds of SHA-256 in a worker_threads pool. A heartbeat confirms the server still answers other requests instantly while computing (main thread non-blocking).",
+  "worker_run_title": "Run a hash computation",
+  "worker_run_desc": "Chain-hashes SHA-256 for the given number of rounds — on a worker thread, not the main thread.",
+  "worker_run_btn": "Run on worker",
+  "worker_rounds_label": "Rounds",
+  "worker_pool_mode": "mode",
+  "worker_pool_size": "pool size",
+  "worker_error": "Run failed:",
+  "worker_result_rounds": "Rounds",
+  "worker_result_ms": "Elapsed",
+  "worker_result_digest": "Final hash",
+  "worker_heartbeat_title": "Main-thread heartbeat",
+  "worker_heartbeat_desc": "Pings the server every second. If this latency stays small while the worker computes, the main thread is not blocked.",
+  "worker_heartbeat_count": "pings",
+  "worker_heartbeat_latency": "recent round-trip",
+  "worker_heartbeat_last": "last ping",
+  "worker_heartbeat_proof": "If the computation ran on the main thread, these pings would freeze until it finished. On a worker thread, they keep ticking.",
+  "server": {
+    "internal": "Internal server error"
+  },
+  "validation": {
+    "failed": "Validation failed."
+  },
+  "auth": {
+    "required": "Authentication required"
+  },
+  "upload": {
+    "unsupported_media_type": "Unsupported media type.",
+    "too_large": "File exceeds the size limit.",
+    "not_found": "File not found."
+  },
+  "guide": {
+    "not_found": "Guide not found."
+  },
+  "csrf": {
+    "invalid_token": "Invalid csrf token",
+    "missing_secret": "Missing csrf secret"
+  }
+}