mega-framework 0.1.7 → 0.1.9

package/sample/crud/docs/guide/02-router-controller.md

@@ -0,0 +1,497 @@
+# Router + Controller
+
+MEGA-FRAMEWORK 의 HTTP/WebSocket 라우트를 정의하고, 컨트롤러로 요청을 처리하고,
+응답을 일관된 형태(envelope)로 돌려주는 방법을 다룬다.
+
+라우트 파일은 앱의 `apps/<app>/routes/*.js` 에 두면 부팅 시 **자동으로 로딩**된다.
+각 파일은 `router` 를 받는 함수를 default export 한다.
+
+```js
+// apps/main/routes/users.js
+import { UserController } from '../controllers/user-controller.js'
+
+export default (router) => {
+  router.http.get('/users', UserController.index)
+  router.http.post('/users', UserController.create)
+}
+```
+
+---
+
+## 라우트 정의 — `router.http.<method>()` / `router.ws()`
+
+### HTTP
+
+`router.http` 는 HTTP 메서드 7종을 메서드로 가진 객체다.
+시그니처는 **메서드별로** 부른다 — `router.http(method, ...)` 가 아니라
+`router.http.get(...)`, `router.http.post(...)` 처럼 쓴다.
+
+```js
+router.http.get(path, handler, opts)
+router.http.post(path, handler, opts)
+router.http.put(path, handler, opts)
+router.http.patch(path, handler, opts)
+router.http.delete(path, handler, opts)
+router.http.head(path, handler, opts)
+router.http.options(path, handler, opts)
+```
+
+- **`path`**: 라우트 경로(`'/users'`, `'/users/:id'`). 비어 있으면 부팅 시 throw.
+- **`handler`**: 함수. inline async 함수 또는 컨트롤러 정적 메서드 참조
+  (`UserController.index`). 함수가 아니면 부팅 시 throw.
+- **`opts`**: 아래 표 참고(생략 가능).
+
+| opts 키       | 설명                                                                 |
+| ------------- | -------------------------------------------------------------------- |
+| `schema`      | AJV(JSON Schema) 검증 — `body` / `params` / `querystring` / `headers` |
+| `before`      | preHandler 단계 미들웨어 배열(인증·rate limit·검증)                  |
+| `transform`   | preSerialization 이른 단계 변환 배열(envelope wrap 전, HTTP 전용)    |
+| `after`       | onResponse 단계 side-effect 배열(로깅·메트릭, HTTP 전용)             |
+| `openapi`     | OpenAPI 메타 — `{ tags, summary, description, deprecated }`          |
+
+### 자동 로딩 규칙
+
+- `apps/<app>/routes/` 안의 `*.js` 파일을 **이름 정렬 순**으로 모두 로딩한다.
+- `*.test.js` 파일은 제외된다.
+- 각 파일은 **default export 가 함수**여야 한다. 아니면 부팅 시
+  `route.file_no_default` 로 throw(우회 없이 즉시 실패).
+- default export 가 `async` 여도 된다 — 로더가 `await mod.default(router)` 로 기다린다.
+
+### WebSocket
+
+```js
+router.ws(path, ChannelClass, opts)
+```
+
+- **`ChannelClass`**: `MegaWebSocketController` 를 상속한 채널 클래스여야 한다
+  (부팅 시 상속 검증, 아니면 throw).
+- **`opts.before`**: upgrade 인증 미들웨어(WS 는 `before` 만 지원).
+- **`opts.schemas`**: `{ [메시지타입]: JSONSchema }` — 메시지 type 별 payload 스키마.
+  등록 시점에 AJV 로 사전 컴파일되고, 수신 메시지의 `type` 에 스키마가 있으면 dispatch
+  직전에 검증한다. 위반 시 `ws.invalid_payload` error envelope 로 응답(연결은 유지).
+- `transform` / `after` 는 **HTTP 전용**이라 WS 에 넘기면 throw.
+
+```js
+// apps/main/routes/ws.js
+import { ChatChannel } from '../channels/chat-channel.js'
+import { makeWsRequireAuth } from '../middleware/ws-auth.js'
+
+const CHAT_SEND_SCHEMA = {
+  type: 'object',
+  required: ['text'],
+  properties: { text: { type: 'string', minLength: 1, maxLength: 500 } },
+  additionalProperties: false,
+}
+
+export default (router) => {
+  router.ws('/ws/chat', ChatChannel, {
+    before: [makeWsRequireAuth(router.app)],
+    schemas: { 'chat.send': CHAT_SEND_SCHEMA },
+  })
+}
+```
+
+### 파일 전체 미들웨어 — `router.use()`
+
+```js
+router.use(middleware) // 이 라우트 파일의 모든 라우트에 적용
+```
+
+실행 순서: **전역 → 앱 → 파일(`router.use`) → 라우트(`before` opts) → handler**.
+
+---
+
+## Controller
+
+컨트롤러는 **베이스 클래스 없이 정적 메서드만** 가진 클래스다.
+라우트는 컨트롤러의 정적 메서드를 핸들러로 참조한다.
+
+```js
+// apps/main/controllers/user-controller.js
+export class UserController {
+  /** GET /users — 목록 */
+  static async index(req, reply, ctx) {
+    return ctx.services.user.list()
+  }
+
+  /** GET /users/:id — 단건 */
+  static async show(req, reply, ctx) {
+    return ctx.services.user.get(req.params.id)
+  }
+
+  /** POST /users — 생성(201) */
+  static async create(req, reply, ctx) {
+    const user = await ctx.services.user.create(req.body)
+    reply.code(201)
+    return user
+  }
+}
+```
+
+### 핸들러 시그니처 — `(req, reply, ctx)`
+
+핸들러는 **위치 인자 3개**를 받는다.
+
+- **`req`**: Fastify 요청. `req.params` / `req.body` / `req.query` / `req.headers`.
+- **`reply`**: Fastify 응답. `reply.code(201)`, `reply.header(...)`, `reply.send(...)`.
+- **`ctx`**: 요청 단위 컨텍스트(아래 표). 요청당 한 번 만들어 미들웨어와 핸들러가 공유한다.
+
+> 라우트·컨트롤러는 **모델을 직접 import 하지 않는다**. 도메인 로직은
+> `ctx.services.<name>` 서비스를 거친다. 컨트롤러는 요청을 받아 서비스를 호출하고
+> 도메인 데이터를 반환하는 얇은 층이다.
+
+### `ctx` 표면
+
+| ctx 항목            | 설명                                                                  |
+| ------------------- | --------------------------------------------------------------------- |
+| `ctx.services.<n>`  | 요청별 lazy 서비스 DI. 미등록 이름 접근은 즉시 throw                   |
+| `ctx.db(alias)`     | DB 어댑터(별명 → 공유 인스턴스). raw 핸들은 `.native`                  |
+| `ctx.cache(alias)`  | 캐시 어댑터                                                           |
+| `ctx.bus(alias)`    | 메시지 버스 어댑터                                                    |
+| `ctx.lock(alias)`   | 분산 락 어댑터                                                        |
+| `ctx.workers`       | CPU 워커 풀 — `ctx.workers.<name>.run(task)`                          |
+| `ctx.t(key, ...)`   | server scope 번역기(i18n). 미등록이면 key/defaultValue 그대로 반환    |
+| `ctx.lang`          | i18n 미들웨어가 결정한 현재 언어(미활성 시 null)                      |
+| `ctx.session`       | 요청별 세션 객체(미활성/미로드 시 null)                              |
+| `ctx.user`          | 인증 사용자(`{ id, roles }`). 인증 가드가 채움                        |
+| `ctx.render(view)`  | 템플릿 렌더(`reply.render` 위임). 템플릿 미설정 앱은 fail-fast        |
+| `ctx.log`           | 요청 로거(pino). `ctx.log.debug(...)`                                 |
+| `ctx.requestId`     | 요청 id                                                              |
+| `ctx.app`           | 바인딩된 MegaApp                                                      |
+
+> `db` / `cache` / `bus` / `lock` 은 **별명을 받는 함수**다 — `ctx.db` 가 아니라
+> `ctx.db('primary')` 처럼 호출한다. 별명은 `app.config.js` 의
+> `databases` / `caches` / `buses` / `locks` 에 선언한 것만 쓸 수 있고,
+> 미선언 별명은 즉시 throw 한다(오타가 조용히 통과하지 않게).
+
+---
+
+## Envelope — 응답 자동 포장
+
+모든 HTTP 응답은 `{ ok, data|error, meta }` 형태로 통일된다.
+**핸들러는 도메인 데이터만 반환**하고, framework 가 envelope 으로 감싼다.
+
+### 성공
+
+핸들러가 반환한 raw data 는 preSerialization 마지막 단계에서 wrap 된다.
+
+```js
+static async show(req, reply, ctx) {
+  return ctx.services.user.get(req.params.id) // { id, name, email }
+}
+```
+
+응답:
+
+```json
+{
+  "ok": true,
+  "data": { "id": "1", "name": "Henry", "email": "h@example.com" },
+  "meta": { "request_id": "req-1", "took_ms": 3 }
+}
+```
+
+### 실패
+
+도메인/HTTP 에러를 throw 하면 글로벌 에러 핸들러가 error envelope 으로 변환한다.
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "user.not_found",
+    "message": "User 99 not found",
+    "details": { "id": "99" }
+  },
+  "meta": { "request_id": "req-2" }
+}
+```
+
+> `error.message` 는 i18n 옵트인 앱에서 에러 `code`(예: `user.not_found`)를 locale 키로
+> lookup 해 번역된다. 키가 없으면 원본 message 를 그대로 쓴다.
+
+### envelope 판별
+
+이미 `{ ok, data|error }` 모양이면 다시 감싸지 않고 그대로 통과시킨다.
+판별 기준은 **`ok`(boolean) 가 있으면서 `data` 또는 `error` 키도 있을 때**다.
+
+스트림(`reply.send(stream)`)·정적 파일처럼 envelope 대상이 아닌 응답은 그대로 전송된다.
+
+---
+
+## Middleware — `before` / `after` / `transform`
+
+미들웨어는 **모두 async 함수**다(콜백 `done` 스타일은 미지원).
+
+### before — preHandler
+
+인증·검증·rate limit 처럼 핸들러 **이전**에 도는 가드. 응답을 보내면
+이후 미들웨어·핸들러는 skip 된다(reply 단락). throw 하면 글로벌 핸들러가
+error envelope 으로 변환한다.
+
+```js
+import { requireAuth } from 'mega-framework/auth'
+
+export default (router) => {
+  const guarded = { before: [requireAuth] }
+  router.http.get('/users', UserController.index, guarded)
+  router.http.post('/users', UserController.create, guarded)
+}
+```
+
+### transform — preSerialization (HTTP 전용)
+
+핸들러가 만든 **raw data 를 envelope wrap 전에** 변환한다.
+시그니처는 `(req, reply, payload)` 이고 변환된 payload 를 반환한다.
+
+```js
+const stripSecret = async (req, reply, payload) => {
+  const { secret, ...rest } = payload
+  return rest
+}
+router.http.get('/me', MeController.show, { transform: [stripSecret] })
+```
+
+실행 순서: **transform → envelope wrap**. 즉 transform 은 항상 `data` 안에 들어갈
+값만 만지고, `ok`/`meta` 는 framework 가 채운다.
+
+### after — onResponse (HTTP 전용)
+
+응답 **전송 후** 도는 side-effect(audit 로그·메트릭). 응답에는 영향이 없고,
+throw 해도 응답이 깨지지 않는다 — 대신 **warn 로그**로 표면화된다(묵살 금지).
+
+```js
+const auditLog = async (req, reply) => {
+  req.log.info({ user: req.user?.id, route: req.url }, 'user mutated')
+}
+router.http.post('/users', UserController.create, { after: [auditLog] })
+```
+
+---
+
+## AJV 스키마 검증
+
+`opts.schema` 는 Fastify 네이티브 AJV 검증으로 그대로 전달된다.
+`body` / `params` / `querystring` / `headers` 를 검증할 수 있다.
+
+```js
+const idParams = {
+  type: 'object',
+  properties: { id: { type: 'string' } },
+}
+const userBody = {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string' },
+    email: { type: 'string', format: 'email' },
+  },
+}
+
+router.http.put('/users/:id', UserController.update, {
+  schema: { params: idParams, body: userBody },
+})
+```
+
+검증 실패 시 글로벌 핸들러가 **400 validation envelope** 으로 변환한다.
+`error.code` 는 `validation.failed`, `error.details` 는 **배열**이다.
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "validation.failed",
+    "message": "Validation failed for body",
+    "details": [
+      { "field": "email", "rule": "format", "value": { "format": "email" }, "message": "must match format \"email\"" }
+    ]
+  },
+  "meta": { "request_id": "req-3" }
+}
+```
+
+> `password` / `secret` / `token` 처럼 민감한 필드명은 `details.value` 가
+> `[REDACTED]` 로 마스킹된다(시크릿 노출 방지).
+
+---
+
+## CSRF
+
+CSRF 보호는 **기본 ON** 이다. `app.config.js` 의 top-level `csrf` 키로 옵션을 주거나
+`csrf: false` 로 끌 수 있다. 쿠키 double-submit 방식이다.
+
+- **JSON 요청**(`application/json`): 토큰 대신 **Origin/Referer 검증**.
+  Origin 헤더가 없는 비브라우저 클라(API)는 통과(CSRF 는 브라우저 쿠키 공격이라 해당 없음).
+  허용 host 와 불일치하면 403 `csrf.origin_mismatch`.
+- **폼 요청**(`x-www-form-urlencoded` / `multipart/form-data`): **토큰 검증**.
+  HTML 폼 auto-submit 이 CSRF 의 주 공격 벡터라 토큰을 강제한다.
+  실패 시 403 `csrf.invalid_token`.
+
+토큰은 뷰에서 `reply.generateCsrf()` 로 만들어 폼에 심는다.
+
+```js
+static async newForm(req, reply, ctx) {
+  return ctx.render('users/new', { csrfToken: reply.generateCsrf() })
+}
+```
+
+```html
+<!-- 일반 HTML 폼 — 숨은 필드 _csrf -->
+<form method="post" action="/users">
+  <input type="hidden" name="_csrf" value="<%= csrfToken %>" />
+  ...
+</form>
+```
+
+> **multipart 폼**은 스트리밍 body 라 preHandler 시점에 `_csrf` 필드를 못 읽는다.
+> 따라서 토큰을 **헤더**(`csrf-token`)로 보내야 한다 — `fetch` + `FormData` 로 제출한다.
+
+health·metrics 처럼 면제할 라우트는 라우트 `config: { skipCsrf: true }` 로 우회한다.
+
+---
+
+## multipart (파일 업로드)
+
+multipart 는 **옵트인**이다. `app.config.js` 에 `upload` 설정이 있을 때만 등록되고,
+없으면 multipart 요청은 415(파서 없음)로 거부된다.
+
+```js
+// app.config.js
+export default {
+  upload: {
+    maxFileSize: 10 * 1024 * 1024, // 기본 10 MB. 초과 시 413
+    maxFiles: 5,                   // 개수 초과 시 413
+    allowedMimeTypes: ['image/png', 'image/*'], // 빈 배열=전부 허용. 비허용 시 415
+  },
+}
+```
+
+컨트롤러에서는 `req.saveUploads(destDir)` 로 저장한다. 파일명 살균(경로 탐색 차단) +
+스트리밍 저장 + MIME 게이트가 적용되고, 저장된 파일 메타 배열을 반환한다.
+
+```js
+static async upload(req, reply, ctx) {
+  // 비허용 MIME(415)·크기 초과(413)면 throw → 글로벌 핸들러가 error envelope 응답
+  const saved = await req.saveUploads(uploadDir())
+  const files = saved.map((f) => ({
+    filename: f.filename,
+    bytes: f.bytes,
+    mimetype: f.mimetype,
+  }))
+  return { files }
+}
+```
+
+저수준 접근이 필요하면 `req.file()`(단일) / `req.files()`(다중)도 MIME 화이트리스트
+게이트로 감싸져 제공된다.
+
+---
+
+## 에러 처리
+
+도메인/HTTP 에러는 **`mega-framework/errors`** 의 `MegaHttpError` 계열을 throw 하면,
+글로벌 에러 핸들러(error-mapper)가 알맞은 HTTP status + error envelope 으로 자동 매핑한다.
+
+| 에러 클래스                     | status | 기본 code                       |
+| ------------------------------- | ------ | ------------------------------- |
+| `MegaValidationError`           | 400    | `validation.failed`             |
+| `MegaAuthError`                 | 401    | `auth.required`                 |
+| `MegaForbiddenError`            | 403    | `auth.forbidden`                |
+| `MegaNotFoundError`             | 404    | `resource.not_found`            |
+| `MegaConflictError`             | 409    | `resource.conflict`             |
+| `MegaPayloadTooLargeError`      | 413    | `upload.too_large`              |
+| `MegaUnsupportedMediaTypeError` | 415    | `upload.unsupported_media_type` |
+| `MegaInternalError`             | 500    | `server.internal`               |
+
+```js
+import { MegaNotFoundError, MegaConflictError } from 'mega-framework/errors'
+
+// 서비스 계층 예시
+async get(id) {
+  const user = await User.find(id)
+  if (!user) {
+    throw new MegaNotFoundError('user.not_found', `User ${id} not found`, {
+      details: { id },
+    })
+  }
+  return user
+}
+```
+
+- 생성자: `new MegaHttpError계열(code, message, { details, cause })`.
+  `code` 는 `domain.error` 형식(ADR-016), `details` 는 object 또는 array.
+- `MegaError`(HTTP status 없는 도메인 에러)는 500 으로 매핑되며 code/message 는 보존된다.
+- Fastify/플러그인의 네이티브 4xx(413·415·CSRF 등)는 status·코드가 보존된다.
+- 일반 `Error`(스택 노출 위험)는 기본적으로 `server.internal` 로 마스킹된다
+  (내부 구현 누출 방지). 메시지·스택은 로그에만 남는다.
+
+### 인증 가드 — `mega-framework/auth`
+
+세션 기반 인증 가드를 `before` 미들웨어로 제공한다.
+
+```js
+import { requireAuth, requireRole } from 'mega-framework/auth'
+
+router.http.get('/me', MeController.show, { before: [requireAuth] })
+router.http.post('/users', UserController.create, { before: [requireRole('admin')] })
+```
+
+- `requireAuth`: 세션 `userId` 가 없으면 401 `auth.required`. 통과 시 `req.user`(`{ id, roles }`) 를 채운다.
+- `requireRole(...roles)`: 인증 + 역할 교집합 검사. 역할 부족이면 403 `auth.forbidden`.
+
+---
+
+## 함정 (실전에서 막히는 지점)
+
+### 1. async `before` 미들웨어는 arity 2 여야 한다
+
+Fastify 는 async `preHandler` 의 인자가 **3개 이상이면** 3번째를 콜백 `done` 으로
+오해해 `"Async function has too many arguments"` 로 **라우트 등록을 거부**한다.
+
+framework 의 인증 가드(`requireAuth` 등)는 `(req, reply, ctx)` 로 arity 3 이지만,
+라우터가 `before` 미들웨어를 **arity-2 래퍼**(`(req, reply) => fn(req, reply)`)로
+감싸 등록하므로 `{ before: [requireAuth] }` 가 그대로 동작한다.
+직접 만드는 `before` 미들웨어도 **`(req, reply)` 시그니처 + async** 로 작성한다.
+
+### 2. 핸들러 반환에 `ok` 를 섞지 말 것
+
+envelope 의 `ok` 는 framework 가 HTTP success 여부를 책임지는 필드다.
+핸들러가 도메인 데이터에 `ok` 를 직접 넣으면 안 된다.
+
+```js
+// ❌ 잘못 — data 안에 ok 가 박혀 { ok:true, data:{ ok:true, ... } } 로 이중 의미
+static async show() { return { ok: true, message: 'hi' } }
+
+// ✅ 도메인 데이터만 반환 — { ok:true, data:{ message:'hi' }, meta } 로 단일 ok
+static async show() { return { message: 'hi' } }
+```
+
+`{ ok:true, message }` 는 `data`/`error` 키가 없어 envelope 으로 인식되지 않고
+통째로 `data` 에 담겨 한 번 더 감싸진다(`data.ok`).
+
+### 3. 라우트 파일은 default export 가 함수여야 한다
+
+`apps/<app>/routes/*.js` 는 `export default (router) => { ... }` 형태여야 한다.
+함수가 아니면 부팅 시 `route.file_no_default` 로 즉시 실패한다.
+default 가 `async` 면 로더가 `await` 하므로 비동기 셋업도 안전하지만,
+라우트 등록은 그 함수 **안에서** 완료돼야 한다(다른 곳에서 떼어내 비동기로 등록 X).
+
+### 4. WS 는 `before` + `schemas` 만 받는다
+
+`router.ws()` 에 `transform` / `after` 를 넘기면 throw 한다(HTTP 전용).
+WS 메시지는 채널 안에서 type 으로 dispatch 되고, payload 검증은 `schemas` 로 한다.
+
+---
+
+## 관련 ADR
+
+- **ADR-005** — 응답 envelope 정책
+- **ADR-018** — 응답 자동 envelope 감싸기 / `isEnvelope` 판별
+- **ADR-019** — AJV(JSON Schema) 라우트 검증
+- **ADR-074** — 컨트롤러 정적 메서드 + `(req, reply, ctx)` 시그니처
+- **ADR-090** — AJV 검증 에러 → validation envelope 매핑(PII 마스킹)
+- **ADR-091** — before/transform/after 라이프사이클
+- **ADR-147** — 핸들러 반환에서 envelope `ok` 중복 제거
+- **ADR-148** — `ctx.services` 자동 DI
+- **ADR-156** — `before` 미들웨어 arity-2 래핑
+- **ADR-167** — routes-loader `await mod.default` / `isFile` 동형