@mandujs/core 0.54.12 → 0.54.14

package/src/runtime/page-render-response.ts

@@ -1,106 +1,208 @@
-import type React from "react";
-import type { BundleManifest } from "../bundler/types";
-import type { HydrationConfig } from "../spec/schema";
-import type { CookieManager } from "../filling/context";
-import { renderSSR, renderStreamingResponse, resolveAsyncElement } from "./ssr";
-
-export interface PageRenderResponseOptions {
-  app: React.ReactElement;
-  useStreaming: boolean;
-  title: string;
-  headTags: string;
-  isDev: boolean;
-  hmrPort?: number;
-  routeId: string;
-  routePattern: string;
-  layoutChain?: string[];
-  hydration?: HydrationConfig;
-  bundleManifest?: BundleManifest;
-  loaderData: unknown;
-  cssPath?: string | false;
-  transitions?: boolean;
-  prefetch?: boolean;
-  spa?: boolean;
-  devtools?: boolean;
-  islandPreWrapped?: boolean;
-  cookies?: CookieManager;
-}
-
-export async function renderPageResponse(
-  options: PageRenderResponseOptions
-): Promise<Response> {
-  let app = options.app;
-
-  if (!options.useStreaming) {
-    app = (await resolveAsyncElement(app)) as React.ReactElement;
-  }
-
-  const response = options.useStreaming
-    ? await renderStreamingPageResponse(app, options)
-    : renderNonStreamingPageResponse(app, options);
-
-  return options.cookies ? options.cookies.applyToResponse(response) : response;
-}
-
-async function renderStreamingPageResponse(
-  app: React.ReactElement,
-  options: PageRenderResponseOptions
-): Promise<Response> {
-  return renderStreamingResponse(app, {
-    title: options.title,
-    headTags: options.headTags,
-    isDev: options.isDev,
-    hmrPort: options.hmrPort,
-    routeId: options.routeId,
-    routePattern: options.routePattern,
-    layoutChain: options.layoutChain,
-    hydration: options.hydration,
-    bundleManifest: options.bundleManifest,
-    criticalData: options.loaderData as Record<string, unknown> | undefined,
-    enableClientRouter: true,
-    cssPath: options.cssPath,
-    transitions: options.transitions,
-    prefetch: options.prefetch,
-    spa: options.spa,
-    devtools: options.devtools,
-    onShellReady: () => {
-      if (options.isDev) {
-        console.log(`[Mandu Streaming] Shell ready: ${options.routeId}`);
-      }
-    },
-    onMetrics: (metrics) => {
-      if (options.isDev) {
-        console.log(`[Mandu Streaming] Metrics for ${options.routeId}:`, {
-          shellReadyTime: `${metrics.shellReadyTime}ms`,
-          allReadyTime: `${metrics.allReadyTime}ms`,
-          hasError: metrics.hasError,
-        });
-      }
-    },
-  });
-}
-
-function renderNonStreamingPageResponse(
-  app: React.ReactElement,
-  options: PageRenderResponseOptions
-): Response {
-  return renderSSR(app, {
-    title: options.title,
-    headTags: options.headTags,
-    isDev: options.isDev,
-    hmrPort: options.hmrPort,
-    routeId: options.routeId,
-    hydration: options.hydration,
-    bundleManifest: options.bundleManifest,
-    serverData: options.loaderData,
-    enableClientRouter: true,
-    routePattern: options.routePattern,
-    cssPath: options.cssPath,
-    islandPreWrapped: !!options.islandPreWrapped,
-    transitions: options.transitions,
-    prefetch: options.prefetch,
-    spa: options.spa,
-    devtools: options.devtools,
-    layoutChain: options.layoutChain,
-  });
-}
+import React from "react";
+import type { BundleManifest } from "../bundler/types";
+import type { HydrationConfig } from "../spec/schema";
+import type { CookieManager } from "../filling/context";
+import { renderSSR, renderStreamingResponse, resolveAsyncElement } from "./ssr";
+import { serializeProps } from "../client/serialize";
+
+export interface InlineClientHydrationTarget {
+  routeId: string;
+  src: string;
+  priority: NonNullable<HydrationConfig["priority"]>;
+  component: unknown;
+}
+
+export interface PageRenderResponseOptions {
+  app: React.ReactElement;
+  useStreaming: boolean;
+  title: string;
+  headTags: string;
+  isDev: boolean;
+  hmrPort?: number;
+  routeId: string;
+  routePattern: string;
+  layoutChain?: string[];
+  hydration?: HydrationConfig;
+  bundleManifest?: BundleManifest;
+  loaderData: unknown;
+  cssPath?: string | false;
+  transitions?: boolean;
+  prefetch?: boolean;
+  spa?: boolean;
+  devtools?: boolean;
+  islandPreWrapped?: boolean;
+  inlineClientHydration?: InlineClientHydrationTarget;
+  cookies?: CookieManager;
+}
+
+export async function renderPageResponse(
+  options: PageRenderResponseOptions
+): Promise<Response> {
+  let app = options.app;
+  let islandPreWrapped = !!options.islandPreWrapped;
+
+  if (!options.useStreaming) {
+    if (options.inlineClientHydration) {
+      const resolved = await resolveAndWrapInlineClientHydration(
+        app,
+        options.inlineClientHydration,
+      );
+      app = resolved.node as React.ReactElement;
+      islandPreWrapped = islandPreWrapped || resolved.didWrap;
+    } else {
+      app = (await resolveAsyncElement(app)) as React.ReactElement;
+    }
+  }
+
+  const effectiveOptions = islandPreWrapped === !!options.islandPreWrapped
+    ? options
+    : { ...options, islandPreWrapped };
+
+  const response = options.useStreaming
+    ? await renderStreamingPageResponse(app, effectiveOptions)
+    : renderNonStreamingPageResponse(app, effectiveOptions);
+
+  return options.cookies ? options.cookies.applyToResponse(response) : response;
+}
+
+async function resolveAndWrapInlineClientHydration(
+  node: React.ReactNode,
+  target: InlineClientHydrationTarget,
+  counter = { value: 0 },
+): Promise<{ node: React.ReactNode; didWrap: boolean }> {
+  if (node == null || typeof node !== "object") {
+    return { node, didWrap: false };
+  }
+
+  if (Array.isArray(node)) {
+    let didWrap = false;
+    const children = await Promise.all(
+      node.map(async (child) => {
+        const result = await resolveAndWrapInlineClientHydration(child, target, counter);
+        didWrap = didWrap || result.didWrap;
+        return result.node;
+      }),
+    );
+    return { node: children, didWrap };
+  }
+
+  if (!React.isValidElement(node)) {
+    return { node, didWrap: false };
+  }
+
+  const element = node as React.ReactElement<Record<string, unknown>>;
+  const type = element.type;
+
+  if (type === target.component) {
+    const id = `${target.routeId}--${counter.value++}`;
+    return {
+      node: React.createElement(
+        "div",
+        {
+          "data-mandu-island": id,
+          "data-mandu-src": target.src,
+          "data-mandu-priority": target.priority,
+          "data-hydrate": priorityToHydrate(target.priority),
+          "data-props": serializeProps(element.props ?? {}),
+          style: { display: "contents" },
+        },
+        element,
+      ),
+      didWrap: true,
+    };
+  }
+
+  if (typeof type === "function" && !isClassComponent(type)) {
+    const rendered = await (type as (props: Record<string, unknown>) => React.ReactNode | Promise<React.ReactNode>)(
+      element.props ?? {},
+    );
+    return resolveAndWrapInlineClientHydration(rendered, target, counter);
+  }
+
+  const props = element.props;
+  const rawChildren = props?.children as React.ReactNode | undefined;
+  if (rawChildren === undefined) {
+    return { node: element, didWrap: false };
+  }
+
+  const resolvedChildren = await resolveAndWrapInlineClientHydration(rawChildren, target, counter);
+  if (!resolvedChildren.didWrap && resolvedChildren.node === rawChildren) {
+    return { node: element, didWrap: false };
+  }
+
+  const cloned = Array.isArray(resolvedChildren.node)
+    ? React.cloneElement(element, undefined, ...resolvedChildren.node)
+    : React.cloneElement(element, undefined, resolvedChildren.node);
+  return { node: cloned, didWrap: resolvedChildren.didWrap };
+}
+
+function isClassComponent(type: Function): boolean {
+  return !!(type.prototype && type.prototype.isReactComponent);
+}
+
+function priorityToHydrate(priority: InlineClientHydrationTarget["priority"]): string {
+  return priority === "immediate" ? "load" : priority;
+}
+
+async function renderStreamingPageResponse(
+  app: React.ReactElement,
+  options: PageRenderResponseOptions
+): Promise<Response> {
+  return renderStreamingResponse(app, {
+    title: options.title,
+    headTags: options.headTags,
+    isDev: options.isDev,
+    hmrPort: options.hmrPort,
+    routeId: options.routeId,
+    routePattern: options.routePattern,
+    layoutChain: options.layoutChain,
+    hydration: options.hydration,
+    bundleManifest: options.bundleManifest,
+    criticalData: options.loaderData as Record<string, unknown> | undefined,
+    enableClientRouter: true,
+    cssPath: options.cssPath,
+    transitions: options.transitions,
+    prefetch: options.prefetch,
+    spa: options.spa,
+    devtools: options.devtools,
+    onShellReady: () => {
+      if (options.isDev) {
+        console.log(`[Mandu Streaming] Shell ready: ${options.routeId}`);
+      }
+    },
+    onMetrics: (metrics) => {
+      if (options.isDev) {
+        console.log(`[Mandu Streaming] Metrics for ${options.routeId}:`, {
+          shellReadyTime: `${metrics.shellReadyTime}ms`,
+          allReadyTime: `${metrics.allReadyTime}ms`,
+          hasError: metrics.hasError,
+        });
+      }
+    },
+  });
+}
+
+function renderNonStreamingPageResponse(
+  app: React.ReactElement,
+  options: PageRenderResponseOptions
+): Response {
+  return renderSSR(app, {
+    title: options.title,
+    headTags: options.headTags,
+    isDev: options.isDev,
+    hmrPort: options.hmrPort,
+    routeId: options.routeId,
+    hydration: options.hydration,
+    bundleManifest: options.bundleManifest,
+    serverData: options.loaderData,
+    enableClientRouter: true,
+    routePattern: options.routePattern,
+    cssPath: options.cssPath,
+    islandPreWrapped: !!options.islandPreWrapped,
+    transitions: options.transitions,
+    prefetch: options.prefetch,
+    spa: options.spa,
+    devtools: options.devtools,
+    layoutChain: options.layoutChain,
+  });
+}

package/src/runtime/rate-limit.ts

@@ -0,0 +1,231 @@
+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;
+}
+
+export interface NormalizedRateLimitOptions {
+  windowMs: number;
+  max: number;
+  message: string;
+  statusCode: number;
+  headers: boolean;
+  trustProxy: boolean;
+  maxKeys: number;
+}
+
+export interface RateLimitDecision {
+  allowed: boolean;
+  limit: number;
+  remaining: number;
+  resetAt: number;
+}
+
+export 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);
+        return options.trustProxy ? sanitized : `unverified:${sanitized}`;
+      }
+    }
+
+    return "default";
+  }
+}
+
+export 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,
+  };
+}
+
+export 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,
+  });
+}
+
+export 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);
+}
+
+/**
+ * Create standalone rate limiter for custom API handlers.
+ *
+ * @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);
+ *   return new Response('OK');
+ * }
+ * ```
+ */
+export function createRateLimiter(options?: RateLimitOptions) {
+  const normalized = normalizeRateLimitOptions(options || true);
+  if (!normalized) {
+    throw new Error("Rate limiter options must be truthy");
+  }
+
+  const limiter = new MemoryRateLimiter();
+
+  return {
+    /**
+     * Check if request is allowed.
+     */
+    check(req: Request, routeId: string): RateLimitDecision {
+      return limiter.consume(req, routeId, normalized);
+    },
+
+    /**
+     * Create 429 response for denied request.
+     */
+    createResponse(decision: RateLimitDecision): Response {
+      return createRateLimitResponse(decision, normalized);
+    },
+
+    /**
+     * Add rate limit headers to successful response.
+     */
+    addHeaders(response: Response, decision: RateLimitDecision): Response {
+      return appendRateLimitHeaders(response, decision, normalized);
+    },
+  };
+}

package/src/runtime/request-middleware.ts

@@ -1,31 +1,31 @@
-import {
-  compose as composeMiddleware,
-  type ComposedHandler,
-  type FinalHandler,
-} from "../middleware/compose";
-import type { Middleware } from "../middleware/define";
-
-export type { ComposedHandler, FinalHandler };
-
-export function buildRequestMiddlewareChain(
-  middleware: Middleware[] | undefined
-): ComposedHandler | undefined {
-  return middleware && middleware.length > 0
-    ? composeMiddleware(...middleware)
-    : undefined;
-}
-
-export interface RunRequestMiddlewareOptions {
-  req: Request;
-  middlewareChain: ComposedHandler | undefined;
-  finalHandler: FinalHandler;
-  skipMiddleware?: boolean;
-}
-
-export async function runRequestMiddleware(
-  options: RunRequestMiddlewareOptions
-): Promise<Response | undefined> {
-  const { req, middlewareChain, finalHandler, skipMiddleware = false } = options;
-  if (skipMiddleware || !middlewareChain) return undefined;
-  return middlewareChain(req, finalHandler);
-}
+import {
+  compose as composeMiddleware,
+  type ComposedHandler,
+  type FinalHandler,
+} from "../middleware/compose";
+import type { Middleware } from "../middleware/define";
+
+export type { ComposedHandler, FinalHandler };
+
+export function buildRequestMiddlewareChain(
+  middleware: Middleware[] | undefined
+): ComposedHandler | undefined {
+  return middleware && middleware.length > 0
+    ? composeMiddleware(...middleware)
+    : undefined;
+}
+
+export interface RunRequestMiddlewareOptions {
+  req: Request;
+  middlewareChain: ComposedHandler | undefined;
+  finalHandler: FinalHandler;
+  skipMiddleware?: boolean;
+}
+
+export async function runRequestMiddleware(
+  options: RunRequestMiddlewareOptions
+): Promise<Response | undefined> {
+  const { req, middlewareChain, finalHandler, skipMiddleware = false } = options;
+  if (skipMiddleware || !middlewareChain) return undefined;
+  return middlewareChain(req, finalHandler);
+}

package/src/runtime/router.test.ts

@@ -157,10 +157,10 @@ describe("Wildcard Matching", () => {
 
     const result = router.match("/docs");
 
-    expect(result).not.toBeNull();
-    expect(result!.route.id).toBe("docs");
-    expect(result!.params).toEqual({});
-  });
+    expect(result).not.toBeNull();
+    expect(result!.route.id).toBe("docs");
+    expect(result!.params).toEqual({ path: "" });
+  });
 
   test("optional wildcard matches with remaining path", () => {
     const router = createRouter([

package/src/runtime/router.ts

@@ -415,12 +415,10 @@ export class Router {
             route,
           };
 
-          // Optional wildcard: 현재 노드도 매칭 가능하게 route 설정
-          if (isOptional && !node.route) {
-            node.route = route;
-          }
-          return;
-        }
+          // Optional wildcard base paths are matched from wildcardConfig so
+          // the named wildcard param is still materialized as an empty string.
+          return;
+        }
 
         // Regular parameter: :param
         const paramName = seg.slice(1);
@@ -528,12 +526,12 @@ export class Router {
       if (node.wildcardConfig.optional) {
         if (this.debug) {
           console.log(`[Router] Optional wildcard match: ${node.wildcardConfig.route.id} with empty path`);
-        }
-        return {
-          route: node.wildcardConfig.route,
-          params,
-        };
-      }
+        }
+        return {
+          route: node.wildcardConfig.route,
+          params: { ...params, [node.wildcardConfig.name]: "" },
+        };
+      }
       // Non-optional wildcard: /files/:path* does NOT match /files
       if (this.debug) {
         console.log(`[Router] Wildcard policy: ${pathname} does not match non-optional wildcard`);