@gaonjs/web 0.3.0 → 0.5.0

package/dist/app.d.ts

@@ -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 로 완전 비활성. */

package/dist/app.js

@@ -16,6 +16,7 @@ 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';
@@ -31,10 +32,25 @@ export async function createApp(opts) {
     // 심어(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) => {

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

@@ -47,6 +47,13 @@ export declare class ValidationError extends Error {
     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;
@@ -152,6 +159,17 @@ 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;
 }

package/dist/controller.js

@@ -27,6 +27,21 @@ export class ValidationError extends Error {
         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) {
@@ -62,6 +77,9 @@ const defaultContext = {
     requireAuth() {
         throw new Error('requireAuth: 인증 컨텍스트가 없습니다(단위 테스트 기본 컨텍스트).');
     },
+    notFound(message) {
+        throw notFoundError(message);
+    },
     // request/reply 는 실제 요청에서만 존재한다 — 기본 컨텍스트(단위 테스트·타입
     // 브리지)는 의도적으로 생략하므로 unknown 경유로 캐스트한다.
 };

package/dist/dispatch.js

@@ -8,7 +8,7 @@
 // 앱별 프리픽스는 createApp 의 캡슐화 스코프(register({ prefix }))가 담당하므로,
 // 여기서는 라우트를 프리픽스 없는 상대 경로로 등록한다 — 세션·CSRF 도 같은
 // 스코프에 갇혀 앱별 완전 분리가 성립한다(질문 13).
-import { isJsonResult, isRedirect, isRendered, rawActions, ValidationError, } 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';
@@ -113,6 +113,9 @@ function buildContext(request, reply, multipart) {
                 throw unauthorizedError();
             return this.currentUser;
         },
+        notFound(message) {
+            throw notFoundError(message);
+        },
         request,
         reply,
     };
@@ -182,6 +185,15 @@ 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

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,9 +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, isRendered, isRedirect, isJsonResult, 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 { 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,13 +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, isRendered, isRedirect, isJsonResult, ValidationError, } 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/web",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Gaon 웹 레이어: Fastify 통합·파일 기반 라우팅·보안 기본값 (구현 예정)",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,9 @@
     "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",
@@ -31,14 +34,11 @@
     "@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.2",
-    "@gaonjs/core": "0.1.4"
-  },
-  "scripts": {
-    "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json"
+    "jose": "^6.2.4"
   }
-}
+}