@gaonjs/web 0.2.2 → 0.5.0

package/dist/app.d.ts

@@ -1,4 +1,4 @@
-import { type FastifyInstance, type FastifyServerOptions } from 'fastify';
+import { type FastifyInstance, type FastifyRequest, type FastifyServerOptions } from 'fastify';
 import { type FastifyCorsOptions } from '@fastify/cors';
 import { type GaonNats } from '@gaonjs/async';
 import type { RouteDef } from './routes.js';
@@ -27,6 +27,12 @@ export interface AppSpec {
      * 이름별로 모은 맵. realtime(NATS)이 설정된 경우에만 활성.
      */
     readonly channels?: ChannelMap;
+    /**
+     * app.config.ts 의 `hosts:` — 이 앱이 응답할 도메인(v0.16 §3.3).
+     * 생략해도 `<앱이름>.localhost` 관례는 자동 성립한다(host-router).
+     * 지정 시 그 도메인들도 이 앱으로 라우팅된다.
+     */
+    readonly hosts?: readonly string[];
 }
 export interface SecurityOptions {
     /** CORS 설정. 기본은 same-origin 만 허용(origin:false). false 로 완전 비활성. */
@@ -44,6 +50,19 @@ export interface CreateAppOptions {
     /** 서명 쿠키·CSRF 용 비밀. 생략 시 env GAON_COOKIE_SECRET. */
     readonly cookieSecret?: string;
     readonly security?: SecurityOptions;
+    /**
+     * 업로드(multipart) 한도(§7 — this.params()/this.file() 처리). 생략 시
+     * 파일당 10MB. false 로 multipart 파싱 비활성.
+     */
+    readonly uploads?: {
+        readonly maxFileSize?: number;
+        readonly maxFiles?: number;
+    } | false;
+    /**
+     * 요청별 훅 — onRequest 시점에 매 요청 실행된다. i18n 언어 감지처럼
+     * 요청 컨텍스트(ALS)를 심어야 하는 배터리를 web 결합 없이 배선하는 통로다.
+     */
+    readonly onRequest?: (request: FastifyRequest) => void | Promise<void>;
     readonly fastify?: FastifyServerOptions;
     /**
      * 실시간 백본(§7 · M6). 설정하면 채널(ws)이 활성화된다. nats 커넥션은

package/dist/app.js

@@ -10,10 +10,13 @@ import Fastify from 'fastify';
 import cookie from '@fastify/cookie';
 import cors from '@fastify/cors';
 import rateLimit from '@fastify/rate-limit';
+import multipart from '@fastify/multipart';
 import { hostname } from 'node:os';
 import { randomUUID } from 'node:crypto';
+import { enterLogContext, rootLogger, setRootLogger } from '@gaonjs/core';
 import { createChannelRuntime } from '@gaonjs/async';
 import { prefixFor, registerApp } from './dispatch.js';
+import { resolveHostRewrite } from './host-router.js';
 import { registerSession } from './session.js';
 import { jwtAuthAugment, sessionAuthAugment } from './auth.js';
 import { registerChannels, registerWebSocketSupport, } from './websocket.js';
@@ -23,7 +26,40 @@ import { verifyToken } from './jwt.js';
  * 켜고, 각 앱의 라우트를 프리픽스 아래 등록한다. listen 은 호출자가 한다.
  */
 export async function createApp(opts) {
-    const app = Fastify(opts.fastify);
+    // 로거를 하나로 통일한다(§7 구조화 로깅) — Fastify 의 요청 자동 로그와
+    // 어디서나 쓰는 전역 log.* 가 같은 pino 인스턴스를 공유한다. Fastify 가
+    // 요청 ID(req.id)를 관리하고, onRequest 훅이 그 ID 를 전역 log 컨텍스트에
+    // 심어(enterLogContext) 요청 처리 중 모든 log.* 에 자동 전파한다.
+    const logger = rootLogger();
+    setRootLogger(logger);
+    // <앱>.localhost 매핑 준비 — 앱별 프리픽스·hosts 를 한 표로 만든다(v0.16 §3.3).
+    // rewriteUrl 은 라우트 해석 이전에 실행돼 URL 을 다시 쓰면 그대로 라우터가
+    // 새 URL 을 매칭한다(Fastify 문서 · rewriteUrl 옵션).
+    const hostBindings = opts.apps.map((s) => ({
+        name: s.name,
+        prefix: s.prefix ?? prefixFor(s.name),
+        hosts: (s.hosts ?? []).map((h) => h.toLowerCase()),
+    }));
+    const app = Fastify({
+        loggerInstance: logger,
+        // 분산 추적: 클라이언트가 x-request-id 를 주면 이어받는다.
+        requestIdHeader: 'x-request-id',
+        // <앱>.localhost / app.config.ts hosts: → URL 을 앱 프리픽스로 재작성.
+        // 관례에 없는 host 는 그대로 통과(원 프리픽스 접근이 계속 동작).
+        rewriteUrl: (req) => {
+            const rawUrl = req.url ?? '/';
+            const rewritten = resolveHostRewrite({ host: req.headers?.host, url: rawUrl }, hostBindings);
+            return rewritten ?? rawUrl;
+        },
+        ...opts.fastify,
+    });
+    app.addHook('onRequest', async (request) => {
+        enterLogContext({ requestId: request.id });
+        // 요청별 훅(예: i18n 언어 감지 → enterLanguage). web 은 i18n 을 모르고,
+        // 부트스트랩이 이 콜백으로 언어 컨텍스트를 심어 결합을 피한다.
+        if (opts.onRequest)
+            await opts.onRequest(request);
+    });
     const security = opts.security ?? {};
     // 실시간 채널 런타임 — 프로세스당 하나(전 앱 공유, NATS 는 호출자 소유).
     let runtime;
@@ -52,6 +88,14 @@ export async function createApp(opts) {
         const rl = security.rateLimit ?? {};
         await app.register(rateLimit, { max: rl.max ?? 100, timeWindow: rl.timeWindow ?? '1 minute' });
     }
+    // 업로드(multipart) — this.params()/this.file() 이 업로드를 처리한다(§7).
+    // parts() 스트리밍을 쓰므로 attachFieldsToBody 는 끈다(디스패처가 파싱).
+    if (opts.uploads !== false) {
+        const up = opts.uploads ?? {};
+        await app.register(multipart, {
+            limits: { fileSize: up.maxFileSize ?? 10 * 1024 * 1024, files: up.maxFiles ?? 10 },
+        });
+    }
     // 앱마다 캡슐화 스코프에 등록한다 — 세션·CSRF·라우트가 그 앱 프리픽스에
     // 갇혀 앱별 완전 분리가 성립한다(질문 13). 프리픽스는 스코프가 건다.
     for (const spec of opts.apps) {

package/dist/auth.d.ts

@@ -7,7 +7,7 @@ export declare function isUnauthorized(e: unknown): boolean;
 export interface AuthOptions {
     /**
      * session.userId → 사용자 로드. 앱이 도메인 모델로 구현한다(예:
-     * (id) => User.query().where('id','=',BigInt(id)).first()). falsy 반환은
+     * (id) => User.where('id','=',BigInt(id)).first()). falsy 반환은
      * 비로그인 취급. web 이 data 를 직접 import 하지 않게 하는 이음새다.
      */
     loadUser(id: unknown): Promise<GaonCurrentUser | null | undefined> | GaonCurrentUser | null | undefined;

package/dist/controller.d.ts

@@ -17,7 +17,51 @@ export interface JsonResult {
     readonly json: unknown;
     readonly status?: number;
 }
+/**
+ * 업로드된 파일 한 개(multipart). 본문은 버퍼로 미리 읽혀 있어, 스토리지에
+ * 그대로 저장한다(§7 — this.params() 가 업로드도 처리):
+ *   const f = this.file('avatar')
+ *   if (f) await Storage.put(`avatars/${user.id}.png`, f.buffer, { contentType: f.mimetype })
+ */
+export interface UploadedFile {
+    /** 폼 필드명. */
+    readonly field: string;
+    /** 원본 파일명. */
+    readonly filename: string;
+    /** MIME 타입. */
+    readonly mimetype: string;
+    /** 파일 본문(스토리지에 그대로 넣을 수 있다). */
+    readonly buffer: Buffer;
+    /** 바이트 크기. */
+    readonly size: number;
+}
 export type ActionResult<P = unknown> = Rendered<P> | Redirect | JsonResult | void;
+/**
+ * 검증 실패(스키마 오류) — this.params/body/query 가 던진다. 디스패처가 잡아
+ * 422 JSON 응답으로 자동 변환한다(§7.5.3 — 에러가 곧 수리 안내서). 어느 키가
+ * 어느 출처(route/body/query)에서 왔고 왜 거부됐는지, 스키마 어느 파일을
+ * 어떻게 고쳐야 하는지까지 메시지에 담는다.
+ */
+export declare class ValidationError extends Error {
+    readonly status: 422;
+    readonly issues: readonly ValidationIssue[];
+    constructor(message: string, issues: readonly ValidationIssue[]);
+}
+/**
+ * this.notFound() 가 던지는 404 신호를 만든다. requireAuth 의 unauthorizedError
+ * 와 같은 방식(마커 프로퍼티) — 디스패처가 응답 분기에서 404 로 마감한다.
+ */
+export declare function notFoundError(message?: string): Error;
+/** 던져진 값이 404 신호인지 판정한다(디스패처가 응답 분기에 사용). */
+export declare function isNotFound(e: unknown): boolean;
+export interface ValidationIssue {
+    /** 문제 필드 이름. */
+    readonly field: string;
+    /** 어느 출처에서 값이 왔는지 — route/body/query/none. */
+    readonly source: 'route' | 'body' | 'query' | 'none';
+    /** 사람이 읽는 사유(예: "필수 값이 없습니다", "숫자 변환 실패"). */
+    readonly reason: string;
+}
 /**
  * 현재 로그인 사용자의 모양. 앱이 declaration merging 으로 자기 User 필드를
  * 얹는다(GaonRouteMap·GaonTables 와 동일 관례) — `gaon g auth` 스캐폴드가
@@ -63,14 +107,41 @@ export interface ControllerContext {
     /** JSON 응답(API/JWT 앱). 값은 응답 경계에서 직렬화된다(bigint/Date/hidden §4.2). */
     json(data: unknown, status?: number): JsonResult;
     /**
-     * 폼 입력을 모델 form 의 Row 모양으로 읽는다. 현재는 요청 본문의 타입
-     * 있는 통로다 — 스키마 파생 검증(실패 시 자동 422, §5.2)은 model 의 form
-     * 이 런타임 컬럼 메타를 실어야 가능하며(현재 form._row 는 팬텀), 그 확장은
-     * data 레이어와 함께 후속으로 둔다.
+     * 폼 입력을 모델 form 의 Row 모양으로 읽는다. 병합 우선순위는 **라우트
+     * 파라미터 > body > query** (errata E-3 §5.1). 라우트 파라미터는 body/query 로
+     * 절대 덮어써지지 않아 파라미터 오염 공격이 원천 차단된다. 중복 키
+     * (`?tag=a&tag=b`)는 스키마 필드가 배열이면 배열로, 아니면 마지막 값이
+     * 이긴다. 스키마 검증 실패는 ValidationError 로 던져지고 디스패처가 422
+     * JSON 으로 응답한다(§7.5.3).
+     *
+     * 인자 없이 부르면 병합된 모든 입력을 그대로(any) 돌려준다. 프로토타입 단계
+     * 하위호환용이며, 스키마 없는 접근은 대량 할당을 막지 못하므로 실 사용에서는
+     * `this.params(Form)` 을 권장한다.
      */
+    params(): Record<string, unknown>;
     params<T>(form: {
         readonly _row: T;
     }): T;
+    /**
+     * 탈출구(§5.4) — body 만 읽는다. 웹훅처럼 라우트 파라미터·쿼리와 섞을 이유가
+     * 없는 드문 경우에 쓴다. 검증은 params 와 동일하게 스키마 파생.
+     */
+    body(): Record<string, unknown>;
+    body<T>(form: {
+        readonly _row: T;
+    }): T;
+    /** 탈출구(§5.4) — query 만 읽는다. 중복 키 규칙은 params 와 동일. */
+    query(): Record<string, unknown>;
+    query<T>(form: {
+        readonly _row: T;
+    }): T;
+    /**
+     * 업로드된 파일 목록(multipart 요청). 비-multipart 요청은 빈 배열.
+     * 파일 본문은 이미 버퍼로 읽혀 있어 Storage.put 에 바로 넣을 수 있다(§7).
+     */
+    files(): readonly UploadedFile[];
+    /** 필드명으로 업로드 파일 하나를 고른다(없으면 undefined). */
+    file(field: string): UploadedFile | undefined;
     /**
      * 세션 저장소(§7 세션 배터리). 세션 앱에서만 존재하고, JWT/API 앱은
      * undefined 다. 로그인은 `this.session.userId = ...` 로 사용자를 심는다.
@@ -88,9 +159,29 @@ export interface ControllerContext {
      * 리다이렉트(폼/Inertia)하거나 401(API)로 응답한다. 로그인 상태면 사용자를 돌려준다.
      */
     requireAuth(): GaonCurrentUser;
+    /**
+     * 리소스 부재 가드 — 404 로 응답한다. requireAuth 와 동형으로 예외를 던져
+     * 디스패처가 404 로 마감한다(never 반환이라 `return this.notFound()` 이후로는
+     * 값이 존재하는 것으로 좁혀진다):
+     *   const post = await Post.find(id)
+     *   if (!post) return this.notFound()   // 이 뒤로 post 는 non-null
+     *   return this.render('posts/Show', { post })
+     * never 를 반환하므로 액션의 추론 반환 타입(Rendered<P>)을 넓히지 않아
+     * 타입 브리지(pageProps/api)가 그대로 유지된다.
+     */
+    notFound(message?: string): never;
     readonly request: FastifyRequest;
     readonly reply: FastifyReply;
 }
+/**
+ * 값이 페이지 렌더 결과인가? — 디스패처 응답 분기와 스캐폴드 예시에서 쓴다.
+ * page·props 두 키가 정확히 있고 다른 응답 마커(json/redirect)가 없어야 한다.
+ */
+export declare function isRendered(v: unknown): v is Rendered<unknown>;
+/** 값이 리다이렉트 결과인가? */
+export declare function isRedirect(v: unknown): v is Redirect;
+/** 값이 명시적 JsonResult(this.json) 결과인가? */
+export declare function isJsonResult(v: unknown): v is JsonResult;
 /** 디스패처가 raw(미바인딩) 액션 맵을 꺼내는 키. */
 export declare const RAW_ACTIONS: unique symbol;
 /** 컨트롤러 객체에서 raw 액션 맵을 읽는다(디스패처 전용). */

package/dist/controller.js

@@ -12,6 +12,36 @@
 // 그 컨텍스트로 호출한다. 그래서 controller() 는 raw(미바인딩) 액션을
 // 심볼로 노출한다. 반환 객체 자체는 기본 컨텍스트에 바인딩돼 있어 단위
 // 테스트에서 c.index() 를 그대로 호출할 수 있다(this.render 동작).
+/**
+ * 검증 실패(스키마 오류) — this.params/body/query 가 던진다. 디스패처가 잡아
+ * 422 JSON 응답으로 자동 변환한다(§7.5.3 — 에러가 곧 수리 안내서). 어느 키가
+ * 어느 출처(route/body/query)에서 왔고 왜 거부됐는지, 스키마 어느 파일을
+ * 어떻게 고쳐야 하는지까지 메시지에 담는다.
+ */
+export class ValidationError extends Error {
+    status = 422;
+    issues;
+    constructor(message, issues) {
+        super(message);
+        this.name = 'ValidationError';
+        this.issues = issues;
+    }
+}
+/** this.notFound() 가 던지는 리소스 부재 신호. unauthorizedError 와 동형 마커. */
+const NOT_FOUND = Symbol.for('gaon.web.notFound');
+/**
+ * this.notFound() 가 던지는 404 신호를 만든다. requireAuth 의 unauthorizedError
+ * 와 같은 방식(마커 프로퍼티) — 디스패처가 응답 분기에서 404 로 마감한다.
+ */
+export function notFoundError(message) {
+    const e = new Error(message ?? 'Not Found');
+    e[NOT_FOUND] = true;
+    return e;
+}
+/** 던져진 값이 404 신호인지 판정한다(디스패처가 응답 분기에 사용). */
+export function isNotFound(e) {
+    return (typeof e === 'object' && e !== null && e[NOT_FOUND] === true);
+}
 /** 요청 없이 호출되는 기본 컨텍스트(단위 테스트·타입 브리지). */
 const defaultContext = {
     render(page, props) {
@@ -26,6 +56,18 @@ const defaultContext = {
     params(_form) {
         return undefined;
     },
+    body(_form) {
+        return undefined;
+    },
+    query(_form) {
+        return undefined;
+    },
+    files() {
+        return [];
+    },
+    file() {
+        return undefined;
+    },
     session: undefined,
     csrfToken() {
         return '';
@@ -35,9 +77,32 @@ const defaultContext = {
     requireAuth() {
         throw new Error('requireAuth: 인증 컨텍스트가 없습니다(단위 테스트 기본 컨텍스트).');
     },
+    notFound(message) {
+        throw notFoundError(message);
+    },
     // request/reply 는 실제 요청에서만 존재한다 — 기본 컨텍스트(단위 테스트·타입
     // 브리지)는 의도적으로 생략하므로 unknown 경유로 캐스트한다.
 };
+/**
+ * 값이 페이지 렌더 결과인가? — 디스패처 응답 분기와 스캐폴드 예시에서 쓴다.
+ * page·props 두 키가 정확히 있고 다른 응답 마커(json/redirect)가 없어야 한다.
+ */
+export function isRendered(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'page' in v &&
+        'props' in v &&
+        !('json' in v) &&
+        !('redirect' in v));
+}
+/** 값이 리다이렉트 결과인가? */
+export function isRedirect(v) {
+    return typeof v === 'object' && v !== null && 'redirect' in v;
+}
+/** 값이 명시적 JsonResult(this.json) 결과인가? */
+export function isJsonResult(v) {
+    return typeof v === 'object' && v !== null && 'json' in v;
+}
 /** 디스패처가 raw(미바인딩) 액션 맵을 꺼내는 키. */
 export const RAW_ACTIONS = Symbol.for('gaon.web.rawActions');
 /** 컨트롤러 객체에서 raw 액션 맵을 읽는다(디스패처 전용). */

package/dist/dispatch.js

@@ -8,11 +8,34 @@
 // 앱별 프리픽스는 createApp 의 캡슐화 스코프(register({ prefix }))가 담당하므로,
 // 여기서는 라우트를 프리픽스 없는 상대 경로로 등록한다 — 세션·CSRF 도 같은
 // 스코프에 갇혀 앱별 완전 분리가 성립한다(질문 13).
-import { rawActions, } from './controller.js';
+import { isJsonResult, isNotFound, isRedirect, isRendered, notFoundError, rawActions, ValidationError, } from './controller.js';
 import { inertiaRedirect, renderInertia } from './inertia.js';
 import { serializeProps } from './serialize.js';
 import { isUnauthorized, unauthorizedError } from './auth.js';
-function buildContext(request, reply) {
+import { coerceParams, mergeSources } from './params.js';
+async function parseMultipart(request) {
+    const fields = {};
+    const files = [];
+    // @fastify/multipart 의 parts() 비동기 이터레이터 — 파일은 즉시 버퍼로 흡수한다.
+    const parts = request.parts();
+    for await (const part of parts) {
+        if (part.type === 'file') {
+            const buffer = await part.toBuffer();
+            files.push({
+                field: part.fieldname,
+                filename: part.filename,
+                mimetype: part.mimetype,
+                buffer,
+                size: buffer.length,
+            });
+        }
+        else {
+            fields[part.fieldname] = part.value;
+        }
+    }
+    return { fields, files };
+}
+function buildContext(request, reply, multipart) {
     // 세션·CSRF 는 @fastify/session · csrf-protection 이 전역 증강으로 붙이지만,
     // 세션 배터리를 등록한 앱에서만 런타임에 존재한다(JWT/API 앱은 undefined).
     const req = request;
@@ -31,6 +54,24 @@ function buildContext(request, reply) {
                 delete sess.userId;
         },
     };
+    // 세 출처를 미리 뽑아 둔다 — this.params/body/query 가 모두 같은 값을 본다.
+    const routeParams = request.params ?? undefined;
+    const bodyObj = multipart
+        ? multipart.fields
+        : (request.body ?? undefined);
+    const queryObj = (() => {
+        const q = request.query;
+        if (!q || typeof q !== 'object')
+            return undefined;
+        // Fastify 기본 qs 파서가 배열/스칼라를 갈라 준다. 문자열화만 통일.
+        const out = {};
+        for (const [k, v] of Object.entries(q)) {
+            if (v === undefined || v === null)
+                continue;
+            out[k] = Array.isArray(v) ? v.map((x) => String(x)) : String(v);
+        }
+        return out;
+    })();
     return {
         render(page, props) {
             return { page, props };
@@ -41,8 +82,27 @@ function buildContext(request, reply) {
         json(data, status) {
             return { json: data, status };
         },
-        params(_form) {
-            return (request.body ?? {});
+        // 병합 우선순위: 라우트 > body > query (errata E-3 §5.1). 라우트 파라미터는
+        // body/query 로 절대 덮어써지지 않는다. 인자 없이 부르면 모든 병합값 그대로.
+        params: ((form) => {
+            const { merged, sources } = mergeSources(routeParams, bodyObj, queryObj);
+            return coerceParams(form, merged, sources);
+        }),
+        // 탈출구: body 만 (§5.4).
+        body: ((form) => {
+            const { merged, sources } = mergeSources(undefined, bodyObj, undefined);
+            return coerceParams(form, merged, sources);
+        }),
+        // 탈출구: query 만 (§5.4). 중복 키 규칙은 params 와 동일.
+        query: ((form) => {
+            const { merged, sources } = mergeSources(undefined, undefined, queryObj);
+            return coerceParams(form, merged, sources);
+        }),
+        files() {
+            return multipart?.files ?? [];
+        },
+        file(field) {
+            return multipart?.files.find((f) => f.field === field);
         },
         session: sess,
         csrfToken: () => (rep.generateCsrf ? rep.generateCsrf() : ''),
@@ -53,27 +113,41 @@ function buildContext(request, reply) {
                 throw unauthorizedError();
             return this.currentUser;
         },
+        notFound(message) {
+            throw notFoundError(message);
+        },
         request,
         reply,
     };
 }
 function finish(request, reply, result, version) {
-    if (result == null) {
+    if (result === undefined || result === null) {
         reply.code(204).send();
         return;
     }
-    if ('redirect' in result) {
+    // 응답 분기 — 렌더 → Inertia, 리다이렉트 → 302/303, JsonResult(this.json) → JSON,
+    // 그 외 객체·배열·원시값(errata E-3) → JSON 자동. 반환값이 곧 응답이다.
+    if (isRedirect(result)) {
         inertiaRedirect(request, reply, result.redirect);
         return;
     }
-    if ('json' in result) {
+    if (isJsonResult(result)) {
         reply
             .code(result.status ?? 200)
             .header('Content-Type', 'application/json; charset=utf-8')
             .send(JSON.stringify(serializeProps(result.json)));
         return;
     }
-    renderInertia(request, reply, result.page, result.props, { version });
+    if (isRendered(result)) {
+        renderInertia(request, reply, result.page, result.props, { version });
+        return;
+    }
+    // JSON 액션 (errata E-3): 액션이 render/redirect/json 없이 평범한 객체·배열·
+    // 원시값을 반환하면 자동 JSON 응답. serializeProps 로 bigint/Date/hidden 처리.
+    reply
+        .code(200)
+        .header('Content-Type', 'application/json; charset=utf-8')
+        .send(JSON.stringify(serializeProps(result)));
 }
 /**
  * 한 앱의 라우트를 (프리픽스가 이미 걸린) Fastify 스코프에 등록한다.
@@ -89,7 +163,13 @@ export function registerApp(app, dispatch, opts = {}) {
         if (typeof fn !== 'function')
             continue;
         const handler = async (request, reply) => {
-            const ctx = buildContext(request, reply);
+            // multipart 업로드면 파일·필드를 먼저 파싱해 컨텍스트에 싣는다(§7).
+            // isMultipart 는 요청 메서드다 — 분리 호출하면 this 가 유실되므로 그대로 부른다.
+            const reqMp = request;
+            const multipart = typeof reqMp.isMultipart === 'function' && reqMp.isMultipart()
+                ? await parseMultipart(request)
+                : undefined;
+            const ctx = buildContext(request, reply, multipart);
             if (opts.augment)
                 await opts.augment(ctx, request, reply);
             let result;
@@ -105,6 +185,23 @@ export function registerApp(app, dispatch, opts = {}) {
                         reply.code(401).send({ error: 'Unauthorized' });
                     return reply;
                 }
+                if (isNotFound(err)) {
+                    // this.notFound(): 리소스 부재 → 404 JSON. Inertia 요청이면 클라이언트가
+                    // 비-2xx 를 에러 모달로 처리한다(ValidationError 422 와 동형 마감).
+                    reply
+                        .code(404)
+                        .header('Content-Type', 'application/json; charset=utf-8')
+                        .send(JSON.stringify({ error: 'Not Found', message: err.message }));
+                    return reply;
+                }
+                if (err instanceof ValidationError) {
+                    // errata E-3: 검증 실패 → 422 JSON 자동. issues 는 필드·출처·사유 배열.
+                    reply
+                        .code(422)
+                        .header('Content-Type', 'application/json; charset=utf-8')
+                        .send(JSON.stringify({ error: 'ValidationError', message: err.message, issues: err.issues }));
+                    return reply;
+                }
                 throw err;
             }
             if (reply.sent)

package/dist/host-router.d.ts

@@ -0,0 +1,20 @@
+/** 앱 하나에 대한 라우팅 관례. */
+export interface AppHostBinding {
+    readonly name: string;
+    /** URL 프리픽스(관례: web → '/', 그 외 → '/<name>'). */
+    readonly prefix: string;
+    /** app.config.ts 의 hosts: 배열(운영 도메인). 소문자로 정규화된 값. */
+    readonly hosts: readonly string[];
+}
+/** onRequest 훅이 호출자에게 판단을 위임하기 위해 쓰는 최소 뷰. */
+export interface RequestView {
+    /** Host 헤더 그대로(포트 포함 가능). */
+    readonly host: string | undefined;
+    /** 현재 URL(예: '/foo?bar=1'). */
+    readonly url: string;
+}
+/**
+ * 요청 하나에 대한 URL 재작성을 계산한다(순수 함수 — 테스트 편의).
+ * 재작성이 필요 없으면 undefined 를 낸다.
+ */
+export declare function resolveHostRewrite(req: RequestView, bindings: readonly AppHostBinding[]): string | undefined;

package/dist/host-router.js

@@ -0,0 +1,114 @@
+// @gaonjs/web · Host 헤더 기반 앱 라우팅 (v0.16 §3.3 · v0.11 확정)
+//
+// v0.16 §3.3 정본:
+//   "개발 모드에서는 로컬 도메인 매핑을 기본 지원한다(v0.11 확정) — 앱은
+//    admin.localhost 처럼 <앱이름>.localhost 로도 접근되며, 프리픽스
+//    접근(/admin)도 함께 동작한다."
+//
+// 구현 전략: Fastify 라우트는 이미 앱별 프리픽스(admin → /admin) 아래 등록
+// 돼 있다(app.ts createApp). 이 훅은 요청 URL 을 **먼저** 재작성한다:
+//
+//   Host: admin.localhost:3000, URL: /foo
+//     → URL: /admin/foo   (기존 프리픽스 라우팅이 받는다)
+//
+// 그러면 앱별 세션·라우트 스코프가 그대로 성립한다 — 새 라우팅 층을 만드는
+// 대신 한 층만 추가한다(The One Way · §1.1).
+//
+// 규칙:
+//  1) Host 가 정확히 `<앱이름>.localhost` 또는 `<앱이름>.localhost:<port>`
+//     이고, 그 앱이 실제로 등록돼 있으면 URL 을 `/<앱이름>` 프리픽스로 재작성.
+//  2) 이미 그 프리픽스가 URL 에 있으면(예: 사용자가 이미 명시적으로 접근)
+//     재작성하지 않는다 — 중복 프리픽스 방지.
+//  3) app.config.ts 의 hosts: 배열에 지정된 도메인도 동일하게 처리(운영 도메인
+//     매핑까지 자연스럽게 확장).
+//  4) web 앱(프리픽스 '/')은 재작성 대상이 아니다 — web.localhost 로 오면
+//     원래 URL 이 그대로 web 앱 라우팅(프리픽스 '/')에 도달한다.
+//  5) 매칭 실패는 조용히 통과(no-op) — 다른 앱 프리픽스 접근이 계속 동작한다.
+/**
+ * 요청 하나에 대한 URL 재작성을 계산한다(순수 함수 — 테스트 편의).
+ * 재작성이 필요 없으면 undefined 를 낸다.
+ */
+export function resolveHostRewrite(req, bindings) {
+    const host = normalizeHost(req.host);
+    if (!host)
+        return undefined;
+    // 1) 명시 hosts 우선 — 운영 도메인(예: 'admin.example.com').
+    // 2) 그다음 <앱이름>.localhost 관례.
+    const match = matchApp(host, bindings);
+    if (!match)
+        return undefined;
+    // web 앱(프리픽스 '/')은 URL 을 건들지 않는다.
+    if (match.prefix === '/' || match.prefix === '')
+        return undefined;
+    // 이미 프리픽스가 붙어 있으면 no-op(중복 방지).
+    if (urlStartsWithPrefix(req.url, match.prefix))
+        return undefined;
+    return joinPrefix(match.prefix, req.url);
+}
+/** Host 헤더에서 포트를 벗기고 소문자화한다. IPv6([::1]:port)는 대상 외. */
+function normalizeHost(host) {
+    if (!host)
+        return undefined;
+    const trimmed = host.trim().toLowerCase();
+    if (!trimmed)
+        return undefined;
+    // IPv6 는 브래킷 형태 · 개발 모드 대상이 아님(관례는 localhost 서브도메인).
+    if (trimmed.startsWith('['))
+        return trimmed;
+    const colon = trimmed.lastIndexOf(':');
+    // 콜론이 있고 뒤가 숫자만이면 포트로 간주해 제거.
+    if (colon > 0 && /^\d+$/.test(trimmed.slice(colon + 1))) {
+        return trimmed.slice(0, colon);
+    }
+    return trimmed;
+}
+/** host 가 어떤 앱에 속하는지 찾는다. */
+function matchApp(host, bindings) {
+    // 1) hosts: 명시 매칭 — 가장 강함(운영 정합).
+    for (const b of bindings) {
+        if (b.hosts.some((h) => h === host))
+            return b;
+    }
+    // 2) <이름>.localhost 관례.
+    //    예: 'admin.localhost' → 앱 이름 'admin'.
+    if (host.endsWith('.localhost')) {
+        const sub = host.slice(0, -'.localhost'.length);
+        // 서브도메인이 정확히 앱 이름과 같아야 한다(다단계 서브도메인은 제외).
+        if (sub && !sub.includes('.')) {
+            const found = bindings.find((b) => b.name === sub);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+/** URL 이 특정 프리픽스(경로 부분)로 시작하는지 안전 검사. */
+function urlStartsWithPrefix(url, prefix) {
+    // 프리픽스 정규화: 앞 '/' 보장 · 끝 '/' 제거.
+    const p = normalizePrefix(prefix);
+    if (p === '/')
+        return true;
+    // URL 은 쿼리·해시를 앞뒤로 가질 수 있어 pathname 만 잘라 비교.
+    const q = url.indexOf('?');
+    const pathname = q >= 0 ? url.slice(0, q) : url;
+    if (pathname === p)
+        return true;
+    return pathname.startsWith(p + '/');
+}
+/** URL 앞에 프리픽스를 붙인다(중복 슬래시 방지). */
+function joinPrefix(prefix, url) {
+    const p = normalizePrefix(prefix);
+    if (p === '/')
+        return url;
+    if (url.startsWith('/'))
+        return p + url;
+    return p + '/' + url;
+}
+function normalizePrefix(prefix) {
+    if (!prefix || prefix === '/')
+        return '/';
+    let p = prefix.startsWith('/') ? prefix : '/' + prefix;
+    if (p.length > 1 && p.endsWith('/'))
+        p = p.slice(0, -1);
+    return p;
+}

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export declare const version: string;
 export { routes, type RouteBuilder, type RouteDef, type RouteEntry, type HttpMethod, } from "./routes.js";
-export { controller, rawActions, RAW_ACTIONS, type Rendered, type Redirect, type JsonResult, type ActionResult, type ControllerContext, type AuthApi, type JwtApi, type JwtTokens, type GaonCurrentUser, } from "./controller.js";
+export { controller, rawActions, RAW_ACTIONS, isRendered, isRedirect, isJsonResult, isNotFound, notFoundError, ValidationError, type Rendered, type Redirect, type JsonResult, type ActionResult, type ControllerContext, type AuthApi, type JwtApi, type JwtTokens, type GaonCurrentUser, type ValidationIssue, } from "./controller.js";
+export { mergeSources, coerceParams, normalizeQuery, type ParsedQuery, type Source, } from "./params.js";
 export { collectRoutes, renderRoutesDts, generateRoutesDts, toImportSpecifier, bindingName, type DiscoveredRoute, } from "./generator.js";
 export { createApp, type AppSpec, type SecurityOptions, type CreateAppOptions, } from "./app.js";
+export { resolveHostRewrite, type AppHostBinding, type RequestView, } from "./host-router.js";
 export { registerApp, prefixFor, type AppDispatch, type DispatchOptions, type ContextExtras, } from "./dispatch.js";
 export { registerSession, type AppSessionOptions, } from "./session.js";
 export { redisSessionStore, type RedisStoreOptions, } from "./redisStore.js";

package/dist/index.js

@@ -10,11 +10,15 @@ export const version = VERSION;
 // 라우팅 DSL (§5.1) — 타입 브리지 + 실행 레이어 라우트 표
 export { routes, } from "./routes.js";
 // controller() — this.render/redirect/params/currentUser (§5.2·§7)
-export { controller, rawActions, RAW_ACTIONS, } from "./controller.js";
+export { controller, rawActions, RAW_ACTIONS, isRendered, isRedirect, isJsonResult, isNotFound, notFoundError, ValidationError, } from "./controller.js";
+// this.params 안전 규칙 (errata E-3 §5.1~5.4)
+export { mergeSources, coerceParams, normalizeQuery, } from "./params.js";
 // routes.d.ts 생성기 (앱별 타입 브리지)
 export { collectRoutes, renderRoutesDts, generateRoutesDts, toImportSpecifier, bindingName, } from "./generator.js";
 // HTTP 실행 레이어 (Fastify 앱 팩토리·보안 기본값)
 export { createApp, } from "./app.js";
+// Host 헤더 기반 앱 라우팅 (v0.16 §3.3 · <앱>.localhost 매핑)
+export { resolveHostRewrite, } from "./host-router.js";
 // 라우트 디스패치 (라우트 표 → Fastify 등록)
 export { registerApp, prefixFor, } from "./dispatch.js";
 // 세션 배터리 (앱별 분리 + CSRF · Redis 스토어)

package/dist/params.d.ts

@@ -0,0 +1,29 @@
+/** 파싱된 쿼리 표현 — 배열 값(?a=1&a=2)을 원본대로 보존한다. */
+export type ParsedQuery = Record<string, string | string[] | undefined>;
+/** 어느 출처에서 값이 왔는지 추적한다(에러 메시지·감시용). */
+export type Source = 'route' | 'body' | 'query';
+/**
+ * 세 출처를 우선순위로 병합한다. 라우트 파라미터가 최우선(§5.1) — body/query 로
+ * 덮어써지지 않는다. 반환 객체는 병합값만 담고, 출처 지도는 별도로 반환한다.
+ */
+export declare function mergeSources(route: Record<string, unknown> | undefined, body: Record<string, unknown> | undefined, query: ParsedQuery | undefined): {
+    merged: Record<string, unknown>;
+    sources: Record<string, Source>;
+};
+/**
+ * 원본 문자열 쿼리(?tag=a&tag=b)를 ParsedQuery 로 정규화. Fastify 는 기본
+ * qs 파서로 이미 배열/스칼라를 갈라 준다 — 단, 스칼라 값을 스키마 배열
+ * 필드에 태우거나 배열 값을 스칼라 필드에 태우는 상황을 coerceParams 에서
+ * 함께 다룬다. 여기선 형태 통일만.
+ */
+export declare function normalizeQuery(raw: unknown): ParsedQuery;
+/**
+ * 병합된 입력을 스키마(form._row 뒤에 있는 컬럼 정의)에 맞춰 강제 변환·검증한다.
+ * 스키마에 없는 키는 결과에서 제거해 대량 할당을 차단한다(§5.3).
+ *
+ * form 은 두 모양을 지원한다:
+ *  · 완전한 TableDef({ name, defs }): model.form 또는 스키마 자체.
+ *  · `{ _row: T }` 팬텀 만 있는 폼(레거시 · 스캐폴드): 컬럼 정보가 없으므로
+ *    타입 통과용으로 병합값을 그대로 반환(대량 할당은 스키마 있는 폼에서만 차단).
+ */
+export declare function coerceParams<T>(form: unknown, merged: Record<string, unknown>, sources: Record<string, Source>): T;

package/dist/params.js

@@ -0,0 +1,179 @@
+// @gaonjs/web · this.params 안전 규칙 (errata E-3 §5.1~5.4)
+//
+// 병합 우선순위(고정 · 설정 불가): **라우트 파라미터 > body > query**.
+// 라우트 파라미터는 body/query 로 절대 덮어써지지 않아 파라미터 오염
+// 공격이 원천 차단된다.
+//
+// 중복 키 규칙(`?tag=a&tag=b`):
+//   · 스키마 필드가 배열 타입이면 배열로 수집
+//   · 아니면 마지막 값(last-wins)
+// this.params('key') 단일 접근도 같은 규칙.
+//
+// 탈출구(§5.4): this.body(schema) · this.query(schema) 로 한 출처만 읽는다.
+//
+// 스키마 검증 실패는 ValidationError 로 던지고, 디스패처가 422 JSON 으로
+// 응답한다. 메시지는 "어떤 키가 어느 출처에서 왔고 왜 거부됐는지 → 스키마
+// 어느 파일 어떻게 고치라"까지 담는다(§7.5.3).
+//
+// 이 모듈은 controller/dispatch 에서 분리해 단위 테스트가 용이하도록 했다
+// — 병합·강제 변환·검증은 순수 함수다.
+import { ValidationError } from './controller.js';
+/**
+ * 세 출처를 우선순위로 병합한다. 라우트 파라미터가 최우선(§5.1) — body/query 로
+ * 덮어써지지 않는다. 반환 객체는 병합값만 담고, 출처 지도는 별도로 반환한다.
+ */
+export function mergeSources(route, body, query) {
+    const merged = {};
+    const sources = {};
+    // 우선순위 낮은 순으로 채우고, 높은 순으로 덮는다.
+    if (query) {
+        for (const [k, v] of Object.entries(query)) {
+            if (v === undefined)
+                continue;
+            merged[k] = v;
+            sources[k] = 'query';
+        }
+    }
+    if (body) {
+        for (const [k, v] of Object.entries(body)) {
+            if (v === undefined)
+                continue;
+            merged[k] = v;
+            sources[k] = 'body';
+        }
+    }
+    if (route) {
+        for (const [k, v] of Object.entries(route)) {
+            if (v === undefined)
+                continue;
+            merged[k] = v;
+            sources[k] = 'route';
+        }
+    }
+    return { merged, sources };
+}
+/**
+ * 원본 문자열 쿼리(?tag=a&tag=b)를 ParsedQuery 로 정규화. Fastify 는 기본
+ * qs 파서로 이미 배열/스칼라를 갈라 준다 — 단, 스칼라 값을 스키마 배열
+ * 필드에 태우거나 배열 값을 스칼라 필드에 태우는 상황을 coerceParams 에서
+ * 함께 다룬다. 여기선 형태 통일만.
+ */
+export function normalizeQuery(raw) {
+    const out = {};
+    if (typeof raw !== 'object' || raw === null)
+        return out;
+    for (const [k, v] of Object.entries(raw)) {
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v))
+            out[k] = v.map((x) => String(x));
+        else
+            out[k] = String(v);
+    }
+    return out;
+}
+/**
+ * 병합된 입력을 스키마(form._row 뒤에 있는 컬럼 정의)에 맞춰 강제 변환·검증한다.
+ * 스키마에 없는 키는 결과에서 제거해 대량 할당을 차단한다(§5.3).
+ *
+ * form 은 두 모양을 지원한다:
+ *  · 완전한 TableDef({ name, defs }): model.form 또는 스키마 자체.
+ *  · `{ _row: T }` 팬텀 만 있는 폼(레거시 · 스캐폴드): 컬럼 정보가 없으므로
+ *    타입 통과용으로 병합값을 그대로 반환(대량 할당은 스키마 있는 폼에서만 차단).
+ */
+export function coerceParams(form, merged, sources) {
+    const defs = tableDefsOf(form);
+    if (!defs) {
+        // 스키마 정보 없음 — 병합값 그대로. 레거시 호환.
+        return merged;
+    }
+    const out = {};
+    const issues = [];
+    for (const [name, def] of Object.entries(defs)) {
+        const raw = merged[name];
+        if (raw === undefined || raw === null || raw === '') {
+            if (!def._meta.hasDefault && !def._meta.nullable) {
+                issues.push({
+                    field: name,
+                    source: sources[name] ?? 'none',
+                    reason: `필수 값이 없습니다.`,
+                });
+            }
+            continue;
+        }
+        try {
+            out[name] = coerceOne(def, raw);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            issues.push({ field: name, source: sources[name] ?? 'none', reason: msg });
+        }
+    }
+    if (issues.length > 0)
+        throw makeValidationError(form, issues);
+    return out;
+}
+function tableDefsOf(form) {
+    if (typeof form !== 'object' || form === null)
+        return undefined;
+    const t = form;
+    if (t.defs && typeof t.defs === 'object')
+        return t.defs;
+    return undefined;
+}
+function coerceOne(def, raw) {
+    const t = def._meta.sqlType;
+    // 배열 값(중복 키)이 스칼라 컬럼에 들어오면 마지막 값을 취한다 — 스키마 상
+    // 배열 필드는 아직 없으므로(§4.1 데이터 타입 v1) 항상 스칼라화한다.
+    const v = Array.isArray(raw) ? raw[raw.length - 1] : raw;
+    switch (t) {
+        case 'bigserial':
+        case 'bigint':
+            return coerceBigInt(v);
+        case 'boolean':
+            return coerceBoolean(v);
+        case 'timestamptz':
+            return coerceDate(v);
+        case 'varchar':
+        case 'text':
+            return String(v);
+        default:
+            return v;
+    }
+}
+function coerceBigInt(v) {
+    if (typeof v === 'bigint')
+        return v;
+    if (typeof v === 'number' && Number.isInteger(v))
+        return BigInt(v);
+    if (typeof v === 'string' && /^-?\d+$/.test(v.trim()))
+        return BigInt(v.trim());
+    throw new Error(`정수(bigint) 로 변환할 수 없습니다: ${JSON.stringify(v)}`);
+}
+function coerceBoolean(v) {
+    if (typeof v === 'boolean')
+        return v;
+    if (v === 'true' || v === '1' || v === 1)
+        return true;
+    if (v === 'false' || v === '0' || v === 0)
+        return false;
+    throw new Error(`불리언으로 변환할 수 없습니다: ${JSON.stringify(v)}`);
+}
+function coerceDate(v) {
+    if (v instanceof Date)
+        return v;
+    const d = new Date(String(v));
+    if (isNaN(d.getTime()))
+        throw new Error(`날짜로 변환할 수 없습니다: ${JSON.stringify(v)}`);
+    return d;
+}
+function makeValidationError(form, issues) {
+    const tblName = typeof form === 'object' && form !== null && 'name' in form
+        ? String(form.name)
+        : '(unknown)';
+    const lines = issues.map((i) => `  · ${i.field} ← ${i.source}: ${i.reason}`).join('\n');
+    const msg = `[@gaonjs/web] 요청 검증 실패 (${issues.length}건 · 테이블 '${tblName}'):\n${lines}\n` +
+        `→ 위 필드를 확인하거나, domain/schema/${tblName}.ts 의 컬럼 정의를 요청과 맞추세요.\n` +
+        `→ 라우트 파라미터로 받는 값이면 라우트 경로(:${issues[0]?.field ?? 'x'})가 존재하는지도 확인하세요.`;
+    return new ValidationError(msg, issues);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/web",
-  "version": "0.2.2",
+  "version": "0.5.0",
   "description": "Gaon 웹 레이어: Fastify 통합·파일 기반 라우팅·보안 기본값 (구현 예정)",
   "type": "module",
   "license": "MIT",
@@ -23,21 +23,22 @@
     "dist",
     "README.md"
   ],
+  "scripts": {
+    "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json"
+  },
   "dependencies": {
     "@fastify/cookie": "^11.1.2",
     "@fastify/cors": "^11.3.0",
     "@fastify/csrf-protection": "^8.0.0",
+    "@fastify/multipart": "^10.1.0",
     "@fastify/rate-limit": "^11.1.0",
     "@fastify/session": "^11.1.2",
     "@fastify/websocket": "^11.0.2",
+    "@gaonjs/async": "workspace:*",
+    "@gaonjs/core": "workspace:*",
     "bcryptjs": "^3.0.3",
     "fastify": "^5.10.0",
     "ioredis": "^5.11.1",
-    "jose": "^6.2.4",
-    "@gaonjs/async": "0.2.1",
-    "@gaonjs/core": "0.1.3"
-  },
-  "scripts": {
-    "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json"
+    "jose": "^6.2.4"
   }
-}
+}