@mandujs/core 0.12.2 → 0.13.1

package/src/router/index.ts

@@ -1,81 +1,81 @@
-/**
- * FS Routes Module
- *
- * 파일 시스템 기반 라우팅 시스템
- *
- * @module router
- *
- * @example
- * ```typescript
- * import { scanRoutes, generateManifest, watchFSRoutes } from "@mandujs/core/router";
- *
- * // 간편 스캔
- * const result = await scanRoutes("/path/to/project");
- * console.log(result.routes);
- *
- * // 매니페스트 생성
- * const { manifest } = await generateManifest("/path/to/project", {
- *   outputPath: ".mandu/manifest.json"
- * });
- *
- * // 감시 모드
- * const watcher = await watchFSRoutes("/path/to/project", {
- *   onChange: (result) => console.log("Routes updated!")
- * });
- * ```
- */
-
-// Types
-export type {
-  // Segment types
-  SegmentType,
-  RouteSegment,
-
-  // File types
-  ScannedFileType,
-  ScannedFile,
-
-  // Route config
-  FSRouteConfig,
-
-  // Scanner config
-  FSScannerConfig,
-
-  // Results
-  ScanResult,
-  ScanError,
-  ScanStats,
-} from "./fs-types";
-
-export { DEFAULT_SCANNER_CONFIG, FILE_PATTERNS, SEGMENT_PATTERNS } from "./fs-types";
-
-// Pattern utilities
-export {
-  parseSegment,
-  parseSegments,
-  segmentsToPattern,
-  pathToPattern,
-  detectFileType,
-  isPrivateFolder,
-  isGroupFolder,
-  generateRouteId,
-  calculateRoutePriority,
-  sortRoutesByPriority,
-  validateSegments,
-  patternsConflict,
-} from "./fs-patterns";
-
-// Scanner
-export { FSScanner, createFSScanner, scanRoutes } from "./fs-scanner";
-
-// Generator
-export type { GenerateResult, GenerateOptions, RouteChangeCallback, FSRoutesWatcher } from "./fs-routes";
-
-export {
-  fsRouteToRouteSpec,
-  scanResultToManifest,
-  mergeManifests,
-  generateManifest,
-  watchFSRoutes,
-  formatRoutesForCLI,
-} from "./fs-routes";
+/**
+ * FS Routes Module
+ *
+ * 파일 시스템 기반 라우팅 시스템
+ *
+ * @module router
+ *
+ * @example
+ * ```typescript
+ * import { scanRoutes, generateManifest, watchFSRoutes } from "@mandujs/core/router";
+ *
+ * // 간편 스캔
+ * const result = await scanRoutes("/path/to/project");
+ * console.log(result.routes);
+ *
+ * // 매니페스트 생성
+ * const { manifest } = await generateManifest("/path/to/project", {
+ *   outputPath: ".mandu/manifest.json"
+ * });
+ *
+ * // 감시 모드
+ * const watcher = await watchFSRoutes("/path/to/project", {
+ *   onChange: (result) => console.log("Routes updated!")
+ * });
+ * ```
+ */
+
+// Types
+export type {
+  // Segment types
+  SegmentType,
+  RouteSegment,
+
+  // File types
+  ScannedFileType,
+  ScannedFile,
+
+  // Route config
+  FSRouteConfig,
+
+  // Scanner config
+  FSScannerConfig,
+
+  // Results
+  ScanResult,
+  ScanError,
+  ScanStats,
+} from "./fs-types";
+
+export { DEFAULT_SCANNER_CONFIG, FILE_PATTERNS, SEGMENT_PATTERNS } from "./fs-types";
+
+// Pattern utilities
+export {
+  parseSegment,
+  parseSegments,
+  segmentsToPattern,
+  pathToPattern,
+  detectFileType,
+  isPrivateFolder,
+  isGroupFolder,
+  generateRouteId,
+  calculateRoutePriority,
+  sortRoutesByPriority,
+  validateSegments,
+  patternsConflict,
+} from "./fs-patterns";
+
+// Scanner
+export { FSScanner, createFSScanner, scanRoutes } from "./fs-scanner";
+
+// Generator
+export type { GenerateResult, GenerateOptions, RouteChangeCallback, FSRoutesWatcher } from "./fs-routes";
+
+export {
+  fsRouteToRouteSpec,
+  scanResultToManifest,
+  resolveAutoLinks,
+  generateManifest,
+  watchFSRoutes,
+  formatRoutesForCLI,
+} from "./fs-routes";

package/src/runtime/escape.ts

@@ -0,0 +1,44 @@
+/**
+ * HTML 속성값 이스케이프
+ * XSS 방지를 위해 HTML 속성값에 들어갈 문자열을 안전하게 처리
+ */
+export function escapeHtmlAttr(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * Inline script의 JSON 데이터 이스케이프
+ * <script> 태그 내부의 JSON을 안전하게 처리
+ */
+export function escapeJsonForInlineScript(value: string): string {
+  return value
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/'/g, "\\u0027")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+/**
+ * JavaScript 문자열 리터럴 이스케이프
+ * JS 코드 내부의 문자열 보간에 사용
+ */
+export function escapeJsString(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/"/g, "\\u0022")
+    .replace(/'/g, "\\u0027")
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}

package/src/runtime/server.ts

@@ -29,6 +29,183 @@ import {
 } from "./cors";
 import { validateImportPath } from "./security";
 
+export interface RateLimitOptions {
+  windowMs?: number;
+  max?: number;
+  message?: string;
+  statusCode?: number;
+  headers?: boolean;
+  /**
+   * Reverse proxy 헤더를 신뢰할지 여부
+   * - false(기본): X-Forwarded-For 등을 읽지만 spoofing 가능성을 표시
+   * - true: 전달된 클라이언트 IP를 완전히 신뢰
+   * 주의: trustProxy: false여도 클라이언트 구분을 위해 헤더를 사용하므로
+   *       IP spoofing이 가능합니다. 신뢰할 수 있는 프록시 뒤에서만 사용하세요.
+   */
+  trustProxy?: boolean;
+  /**
+   * 메모리 보호를 위한 최대 key 수
+   * - 초과 시 오래된 key부터 제거
+   */
+  maxKeys?: number;
+}
+
+interface NormalizedRateLimitOptions {
+  windowMs: number;
+  max: number;
+  message: string;
+  statusCode: number;
+  headers: boolean;
+  trustProxy: boolean;
+  maxKeys: number;
+}
+
+interface RateLimitDecision {
+  allowed: boolean;
+  limit: number;
+  remaining: number;
+  resetAt: number;
+}
+
+class MemoryRateLimiter {
+  private readonly store = new Map<string, { count: number; resetAt: number }>();
+  private lastCleanupAt = 0;
+
+  consume(req: Request, routeId: string, options: NormalizedRateLimitOptions): RateLimitDecision {
+    const now = Date.now();
+    this.maybeCleanup(now, options);
+
+    const key = `${this.getClientKey(req, options)}:${routeId}`;
+    const current = this.store.get(key);
+
+    if (!current || current.resetAt <= now) {
+      const resetAt = now + options.windowMs;
+      this.store.set(key, { count: 1, resetAt });
+      this.enforceMaxKeys(options.maxKeys);
+      return { allowed: true, limit: options.max, remaining: Math.max(0, options.max - 1), resetAt };
+    }
+
+    current.count += 1;
+    this.store.set(key, current);
+
+    return {
+      allowed: current.count <= options.max,
+      limit: options.max,
+      remaining: Math.max(0, options.max - current.count),
+      resetAt: current.resetAt,
+    };
+  }
+
+  private maybeCleanup(now: number, options: NormalizedRateLimitOptions): void {
+    if (now - this.lastCleanupAt < Math.max(1_000, options.windowMs)) {
+      return;
+    }
+
+    this.lastCleanupAt = now;
+    for (const [key, entry] of this.store.entries()) {
+      if (entry.resetAt <= now) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  private enforceMaxKeys(maxKeys: number): void {
+    while (this.store.size > maxKeys) {
+      const oldestKey = this.store.keys().next().value;
+      if (!oldestKey) break;
+      this.store.delete(oldestKey);
+    }
+  }
+
+  private getClientKey(req: Request, options: NormalizedRateLimitOptions): string {
+    const candidates = [
+      req.headers.get("x-forwarded-for")?.split(",")[0]?.trim(),
+      req.headers.get("x-real-ip")?.trim(),
+      req.headers.get("cf-connecting-ip")?.trim(),
+      req.headers.get("true-client-ip")?.trim(),
+      req.headers.get("fly-client-ip")?.trim(),
+    ];
+
+    for (const candidate of candidates) {
+      if (candidate) {
+        const sanitized = candidate.slice(0, 64);
+        // trustProxy: false면 경고를 위해 prefix 추가 (spoofing 가능)
+        return options.trustProxy ? sanitized : `unverified:${sanitized}`;
+      }
+    }
+
+    // 헤더가 전혀 없는 경우만 fallback (로컬 개발 환경)
+    return "default";
+  }
+}
+
+function normalizeRateLimitOptions(options: boolean | RateLimitOptions | undefined): NormalizedRateLimitOptions | false {
+  if (!options) return false;
+  if (options === true) {
+    return {
+      windowMs: 60_000,
+      max: 100,
+      message: "Too Many Requests",
+      statusCode: 429,
+      headers: true,
+      trustProxy: false,
+      maxKeys: 10_000,
+    };
+  }
+
+  const windowMs = Number.isFinite(options.windowMs) ? Math.max(1_000, options.windowMs!) : 60_000;
+  const max = Number.isFinite(options.max) ? Math.max(1, Math.floor(options.max!)) : 100;
+  const statusCode = Number.isFinite(options.statusCode)
+    ? Math.min(599, Math.max(400, Math.floor(options.statusCode!)))
+    : 429;
+  const maxKeys = Number.isFinite(options.maxKeys)
+    ? Math.max(100, Math.floor(options.maxKeys!))
+    : 10_000;
+
+  return {
+    windowMs,
+    max,
+    message: options.message ?? "Too Many Requests",
+    statusCode,
+    headers: options.headers ?? true,
+    trustProxy: options.trustProxy ?? false,
+    maxKeys,
+  };
+}
+
+function appendRateLimitHeaders(response: Response, decision: RateLimitDecision, options: NormalizedRateLimitOptions): Response {
+  if (!options.headers) return response;
+
+  const headers = new Headers(response.headers);
+  const retryAfterSec = Math.max(1, Math.ceil((decision.resetAt - Date.now()) / 1000));
+
+  headers.set("X-RateLimit-Limit", String(decision.limit));
+  headers.set("X-RateLimit-Remaining", String(decision.remaining));
+  headers.set("X-RateLimit-Reset", String(Math.floor(decision.resetAt / 1000)));
+  headers.set("Retry-After", String(retryAfterSec));
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+function createRateLimitResponse(decision: RateLimitDecision, options: NormalizedRateLimitOptions): Response {
+  const response = Response.json(
+    {
+      error: "rate_limit_exceeded",
+      message: options.message,
+      limit: decision.limit,
+      remaining: decision.remaining,
+      retryAfter: Math.max(1, Math.ceil((decision.resetAt - Date.now()) / 1000)),
+    },
+    { status: options.statusCode }
+  );
+
+  return appendRateLimitHeaders(response, decision, options);
+}
+
 // ========== MIME Types ==========
 const MIME_TYPES: Record<string, string> = {
   // JavaScript
@@ -107,6 +284,10 @@ export interface ServerOptions {
    * - false: 기존 renderToString 사용 (기본값)
    */
   streaming?: boolean;
+  /**
+   * API 라우트 Rate Limit 설정
+   */
+  rateLimit?: boolean | RateLimitOptions;
   /**
    * CSS 파일 경로 (SSR 링크 주입용)
    * - string: 해당 경로로 <link> 주입 (예: "/.mandu/client/globals.css")
@@ -203,6 +384,7 @@ export interface ServerRegistrySettings {
   publicDir: string;
   cors?: CorsOptions | false;
   streaming: boolean;
+  rateLimit?: NormalizedRateLimitOptions | false;
   /**
    * CSS 파일 경로 (SSR 링크 주입용)
    * - string: 해당 경로로 <link> 주입
@@ -230,12 +412,14 @@ export class ServerRegistry {
   /** Error 로더 (모듈 경로 → 로더 함수) */
   readonly errorLoaders: Map<string, ErrorLoader> = new Map();
   createAppFn: CreateAppFn | null = null;
+  rateLimiter: MemoryRateLimiter | null = null;
   settings: ServerRegistrySettings = {
     isDev: false,
     rootDir: process.cwd(),
     publicDir: "public",
     cors: false,
     streaming: false,
+    rateLimit: false,
   };
 
   registerApiHandler(routeId: string, handler: ApiHandler): void {
@@ -375,6 +559,7 @@ export class ServerRegistry {
     this.errorComponents.clear();
     this.errorLoaders.clear();
     this.createAppFn = null;
+    this.rateLimiter = null;
   }
 }
 
@@ -923,6 +1108,18 @@ async function handleRequestInternal(
 
   // 3. 라우트 종류별 처리
   if (route.kind === "api") {
+    const rateLimitOptions = settings.rateLimit;
+    if (rateLimitOptions && registry.rateLimiter) {
+      const decision = registry.rateLimiter.consume(req, route.id, rateLimitOptions);
+      if (!decision.allowed) {
+        return ok(createRateLimitResponse(decision, rateLimitOptions));
+      }
+
+      const apiResult = await handleApiRoute(req, route, params, registry);
+      if (!apiResult.ok) return apiResult;
+      return ok(appendRateLimitHeaders(apiResult.value, decision, rateLimitOptions));
+    }
+
     return handleApiRoute(req, route, params, registry);
   }
 
@@ -938,7 +1135,7 @@ async function handleRequestInternal(
     message: `Unknown route kind: ${route.kind}`,
     summary: "알 수 없는 라우트 종류 - 프레임워크 버그",
     fix: {
-      file: "spec/routes.manifest.json",
+      file: ".mandu/routes.manifest.json",
       suggestion: "라우트의 kind는 'api' 또는 'page'여야 합니다",
     },
     route: { id: route.id, pattern: route.pattern },
@@ -957,29 +1154,29 @@ function isPortInUseError(error: unknown): boolean {
   return code === "EADDRINUSE" || message.includes("EADDRINUSE") || message.includes("address already in use");
 }
 
-function startBunServerWithFallback(options: {
-  port: number;
-  hostname?: string;
-  fetch: (req: Request) => Promise<Response>;
-}): { server: Server; port: number; attempts: number } {
-  const { port: startPort, hostname, fetch } = options;
-  let lastError: unknown = null;
-
-  // Port 0: let Bun/OS pick an available ephemeral port.
-  if (startPort === 0) {
-    const server = Bun.serve({
-      port: 0,
-      hostname,
-      fetch,
-    });
-    return { server, port: server.port ?? 0, attempts: 0 };
-  }
-
-  for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt++) {
-    const candidate = startPort + attempt;
-    if (candidate < 1 || candidate > 65535) {
-      continue;
-    }
+function startBunServerWithFallback(options: {
+  port: number;
+  hostname?: string;
+  fetch: (req: Request) => Promise<Response>;
+}): { server: Server; port: number; attempts: number } {
+  const { port: startPort, hostname, fetch } = options;
+  let lastError: unknown = null;
+
+  // Port 0: let Bun/OS pick an available ephemeral port.
+  if (startPort === 0) {
+    const server = Bun.serve({
+      port: 0,
+      hostname,
+      fetch,
+    });
+    return { server, port: server.port ?? 0, attempts: 0 };
+  }
+
+  for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt++) {
+    const candidate = startPort + attempt;
+    if (candidate < 1 || candidate > 65535) {
+      continue;
+    }
     try {
       const server = Bun.serve({
         port: candidate,
@@ -1011,6 +1208,7 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     publicDir = "public",
     cors = false,
     streaming = false,
+    rateLimit = false,
     cssPath: cssPathOption,
     registry = defaultRegistry,
   } = options;
@@ -1027,6 +1225,7 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
 
   // CORS 옵션 파싱
   const corsOptions: CorsOptions | false = cors === true ? {} : cors;
+  const rateLimitOptions = normalizeRateLimitOptions(rateLimit);
 
   if (!isDev && cors === true) {
     console.warn("⚠️  [Security Warning] CORS is set to allow all origins.");
@@ -1044,9 +1243,12 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     publicDir,
     cors: corsOptions,
     streaming,
+    rateLimit: rateLimitOptions,
     cssPath,
   };
 
+  registry.rateLimiter = rateLimitOptions ? new MemoryRateLimiter() : null;
+
   const router = new Router(manifest.routes);
 
   // Fetch handler with CORS support (registry를 클로저로 캡처)
@@ -1112,3 +1314,58 @@ export const apiHandlers = defaultRegistry.apiHandlers;
 export const pageLoaders = defaultRegistry.pageLoaders;
 export const pageHandlers = defaultRegistry.pageHandlers;
 export const routeComponents = defaultRegistry.routeComponents;
+
+// ========== Rate Limiting Public API ==========
+
+/**
+ * Rate limiter 인스턴스 생성
+ * API 핸들러에서 직접 사용 가능
+ *
+ * @example
+ * ```typescript
+ * import { createRateLimiter } from '@mandujs/core/runtime/server';
+ *
+ * const limiter = createRateLimiter({ max: 5, windowMs: 60000 });
+ *
+ * export async function POST(req: Request) {
+ *   const decision = limiter.check(req, 'my-api-route');
+ *   if (!decision.allowed) {
+ *     return limiter.createResponse(decision);
+ *   }
+ *   // ... 정상 로직
+ * }
+ * ```
+ */
+export function createRateLimiter(options?: RateLimitOptions) {
+  const normalized = normalizeRateLimitOptions(options || true);
+  if (!normalized) {
+    throw new Error('Rate limiter options cannot be false');
+  }
+
+  const limiter = new MemoryRateLimiter();
+
+  return {
+    /**
+     * Rate limit 체크
+     * @param req Request 객체 (IP 추출용)
+     * @param routeId 라우트 식별자 (동일 IP라도 라우트별로 독립적인 limit)
+     */
+    check(req: Request, routeId: string): RateLimitDecision {
+      return limiter.consume(req, routeId, normalized);
+    },
+
+    /**
+     * Rate limit 초과 시 429 응답 생성
+     */
+    createResponse(decision: RateLimitDecision): Response {
+      return createRateLimitResponse(decision, normalized);
+    },
+
+    /**
+     * 정상 응답에 Rate limit 헤더 추가
+     */
+    addHeaders(response: Response, decision: RateLimitDecision): Response {
+      return appendRateLimitHeaders(response, decision, normalized);
+    },
+  };
+}