@mandujs/core 0.13.0 → 0.13.2

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);
   }
 
@@ -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);
+    },
+  };
+}