@mandujs/core 0.54.1 → 0.54.3

package/src/runtime/devtools-adapter.ts

@@ -0,0 +1,68 @@
+import type { RoutesManifest } from "../spec/schema";
+import type { GuardConfig } from "../guard/types";
+import {
+  KITCHEN_PREFIX,
+  KitchenHandler,
+  recordRequest,
+  type RequestEntry,
+} from "../kitchen/kitchen-handler";
+
+export type RuntimeKitchenHandler = KitchenHandler;
+
+export interface RuntimeDevtoolsAdapter {
+  readonly kitchen: RuntimeKitchenHandler | null;
+  readonly dashboardPath: string | null;
+  start(): void;
+  stop(): void;
+  updateManifest(manifest: RoutesManifest): void;
+  handleRequest(req: Request, pathname: string): Promise<Response | null>;
+}
+
+export interface CreateRuntimeDevtoolsAdapterOptions {
+  isDev: boolean;
+  rootDir: string;
+  manifest: RoutesManifest;
+  guardConfig: GuardConfig | null;
+}
+
+export function createRuntimeDevtoolsAdapter(
+  options: CreateRuntimeDevtoolsAdapterOptions
+): RuntimeDevtoolsAdapter {
+  const kitchen = options.isDev
+    ? new KitchenHandler({
+      rootDir: options.rootDir,
+      manifest: options.manifest,
+      guardConfig: options.guardConfig,
+    })
+    : null;
+
+  return {
+    kitchen,
+    dashboardPath: kitchen ? KITCHEN_PREFIX : null,
+    start() {
+      if (kitchen) void kitchen.start();
+    },
+    stop() {
+      kitchen?.stop();
+    },
+    updateManifest(manifest: RoutesManifest) {
+      kitchen?.updateManifest(manifest);
+    },
+    async handleRequest(req: Request, pathname: string): Promise<Response | null> {
+      if (!kitchen || !pathname.startsWith(KITCHEN_PREFIX)) return null;
+      return await kitchen.handle(req, pathname);
+    },
+  };
+}
+
+export function shouldRecordRuntimeRequest(pathname: string): boolean {
+  return (
+    !pathname.startsWith("/.mandu/") &&
+    !pathname.startsWith(KITCHEN_PREFIX) &&
+    !pathname.startsWith("/__mandu/")
+  );
+}
+
+export function recordRuntimeRequest(entry: RequestEntry): void {
+  recordRequest(entry);
+}

package/src/runtime/escape.ts

@@ -3,12 +3,40 @@
  * <title>, <p> 등 텍스트 노드에 들어갈 문자열을 안전하게 처리.
  * 속성값과 달리 " ' 는 이스케이프 불필요.
  */
-export function escapeHtmlText(value: string): string {
-  return value
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
-}
+export function escapeHtmlText(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Decode the small HTML entity set React can emit inside text metadata.
+ * Callers should still escape the returned string before writing HTML.
+ */
+export function decodeHtmlText(value: string): string {
+  return value.replace(/&(#x[0-9a-f]+|#\d+|amp|lt|gt|quot|apos|#39);/gi, (match, entity: string) => {
+    const normalized = entity.toLowerCase();
+    if (normalized === "amp") return "&";
+    if (normalized === "lt") return "<";
+    if (normalized === "gt") return ">";
+    if (normalized === "quot") return '"';
+    if (normalized === "apos" || normalized === "#39") return "'";
+    if (normalized.startsWith("#x")) {
+      const codePoint = Number.parseInt(normalized.slice(2), 16);
+      return isValidCodePoint(codePoint) ? String.fromCodePoint(codePoint) : match;
+    }
+    if (normalized.startsWith("#")) {
+      const codePoint = Number.parseInt(normalized.slice(1), 10);
+      return isValidCodePoint(codePoint) ? String.fromCodePoint(codePoint) : match;
+    }
+    return match;
+  });
+}
+
+function isValidCodePoint(value: number): boolean {
+  return Number.isInteger(value) && value >= 0 && value <= 0x10ffff;
+}
 
 /**
  * HTML 속성값 이스케이프

package/src/runtime/observability-lifecycle.ts

@@ -0,0 +1,290 @@
+import {
+  eventBus,
+  type EventType,
+  type ObservabilityEvent,
+  type ObservabilitySeverity,
+} from "../observability/event-bus";
+import {
+  HEAP_ENDPOINT,
+  METRICS_ENDPOINT,
+  buildMetricsResponse,
+  collectHeapSnapshot,
+  isObservabilityExposed,
+  recordHttpRequest,
+} from "../observability/metrics";
+import {
+  createTracerFromConfig,
+  runWithSpan,
+  setTracer,
+  type Tracer,
+  type TracerConfig,
+} from "../observability/tracing";
+import { collectPerfSnapshot } from "../perf/user-marks";
+
+export const INTERNAL_EVENTS_ENDPOINT = "/__mandu/events";
+
+export interface RuntimeRequestRecord {
+  id: string;
+  method: string;
+  path: string;
+  status: number;
+  duration: number;
+  timestamp: number;
+  cacheStatus?: string;
+}
+
+export interface RuntimeRequestObservation {
+  req: Request;
+  path: string;
+  status: number;
+  duration: number;
+  correlationId: string;
+  cacheStatus?: string;
+  error?: boolean;
+  recordRequest?: (entry: RuntimeRequestRecord) => void;
+}
+
+export interface RuntimeObservabilityLifecycle {
+  readonly tracer: Tracer | undefined;
+  handleEndpoint(req: Request, pathname: string): Response | null;
+  runRequest<T extends Response>(
+    req: Request,
+    requestStart: number,
+    correlationId: string,
+    handler: () => Promise<T>
+  ): Promise<T>;
+  recordHttpResponse(req: Request, response: Response | undefined): void;
+  recordDevRequest(observation: RuntimeRequestObservation): void;
+}
+
+export interface CreateRuntimeObservabilityLifecycleOptions {
+  isDev: boolean;
+  heapEndpoint?: boolean;
+  metricsEndpoint?: boolean;
+  tracing?: TracerConfig;
+}
+
+export function createRuntimeObservabilityLifecycle(
+  options: CreateRuntimeObservabilityLifecycleOptions
+): RuntimeObservabilityLifecycle {
+  const tracerInstance = createTracerFromConfig(options.tracing);
+  setTracer(tracerInstance);
+  const tracer = tracerInstance.enabled ? tracerInstance : undefined;
+
+  return {
+    tracer,
+    handleEndpoint(req, pathname) {
+      return handleRuntimeObservabilityEndpoint(req, pathname, options);
+    },
+    async runRequest(req, requestStart, correlationId, handler) {
+      if (!tracer || !tracer.enabled) {
+        return await handler();
+      }
+
+      const url = new URL(req.url);
+      const rootSpan = tracer.startSpanFromRequest("http.request", req, {
+        kind: "server",
+        attributes: {
+          "http.method": req.method,
+          "http.url": req.url,
+          "http.target": url.pathname,
+          "http.scheme": url.protocol.replace(":", ""),
+          "http.host": url.host,
+          "mandu.correlation_id": correlationId,
+          "mandu.request_start_ms": requestStart,
+        },
+      });
+
+      try {
+        const response = await runWithSpan(rootSpan, handler);
+        rootSpan.setAttribute("http.status_code", response.status);
+        if (response.status >= 500) {
+          rootSpan.setStatus("error", `HTTP ${response.status}`);
+        } else if (rootSpan.status === "unset") {
+          rootSpan.setStatus("ok");
+        }
+        return response;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        rootSpan.setStatus("error", message);
+        throw err;
+      } finally {
+        rootSpan.end();
+      }
+    },
+    recordHttpResponse(req, response) {
+      if (!response) return;
+      try {
+        recordHttpRequest(req.method, response.status);
+      } catch {
+        // Observability must never break the request path.
+      }
+    },
+    recordDevRequest(observation) {
+      recordRuntimeObservation(observation);
+    },
+  };
+}
+
+function handleRuntimeObservabilityEndpoint(
+  req: Request,
+  pathname: string,
+  options: CreateRuntimeObservabilityLifecycleOptions
+): Response | null {
+  if (pathname === INTERNAL_EVENTS_ENDPOINT) {
+    return handleEventsStreamRequest(req);
+  }
+  if (pathname === `${INTERNAL_EVENTS_ENDPOINT}/recent`) {
+    return handleEventsRecentRequest(req);
+  }
+  if (pathname === HEAP_ENDPOINT) {
+    if (!isObservabilityExposed(options.isDev, options.heapEndpoint)) return null;
+    const base = collectHeapSnapshot();
+    const perf = collectPerfSnapshot();
+    const body = { ...base, perf };
+    return new Response(JSON.stringify(body, null, 2), {
+      status: 200,
+      headers: {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-store",
+      },
+    });
+  }
+  if (pathname === METRICS_ENDPOINT) {
+    if (!isObservabilityExposed(options.isDev, options.metricsEndpoint)) return null;
+    return buildMetricsResponse();
+  }
+  return null;
+}
+
+function handleEventsStreamRequest(req: Request): Response {
+  const url = new URL(req.url);
+  const filterType = url.searchParams.get("type") || undefined;
+  const filterSeverity = url.searchParams.get("severity") || undefined;
+  const filterSource = url.searchParams.get("source") || undefined;
+  const filterTrace = url.searchParams.get("trace") || undefined;
+
+  const matches = (event: ObservabilityEvent): boolean => {
+    if (filterType && event.type !== filterType) return false;
+    if (filterSeverity && event.severity !== filterSeverity) return false;
+    if (filterSource && event.source !== filterSource) return false;
+    if (filterTrace && event.correlationId !== filterTrace) return false;
+    return true;
+  };
+
+  let unsubscribe: (() => void) | null = null;
+  let heartbeat: ReturnType<typeof setInterval> | null = null;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const encoder = new TextEncoder();
+      const send = (data: string, eventName?: string) => {
+        try {
+          const prefix = eventName ? `event: ${eventName}\n` : "";
+          controller.enqueue(encoder.encode(`${prefix}data: ${data}\n\n`));
+        } catch {
+          // Stream closed.
+        }
+      };
+
+      for (const event of eventBus.getRecent()) {
+        if (matches(event)) send(JSON.stringify(event));
+      }
+
+      unsubscribe = eventBus.on("*", (event) => {
+        if (matches(event)) send(JSON.stringify(event));
+      });
+
+      heartbeat = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(": heartbeat\n\n"));
+        } catch {
+          // Ignore closed streams.
+        }
+      }, 15000);
+
+      req.signal.addEventListener("abort", () => {
+        if (unsubscribe) {
+          unsubscribe();
+          unsubscribe = null;
+        }
+        if (heartbeat) {
+          clearInterval(heartbeat);
+          heartbeat = null;
+        }
+        try {
+          controller.close();
+        } catch {
+          // No-op when already closed.
+        }
+      });
+    },
+    cancel() {
+      if (unsubscribe) {
+        unsubscribe();
+        unsubscribe = null;
+      }
+      if (heartbeat) {
+        clearInterval(heartbeat);
+        heartbeat = null;
+      }
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-store, must-revalidate",
+      "Connection": "keep-alive",
+      "X-Accel-Buffering": "no",
+    },
+  });
+}
+
+function handleEventsRecentRequest(req: Request): Response {
+  const url = new URL(req.url);
+  const count = url.searchParams.get("count");
+  const type = url.searchParams.get("type") || undefined;
+  const severity = url.searchParams.get("severity") || undefined;
+  const windowParam = url.searchParams.get("windowMs");
+  const windowMs = windowParam ? Number(windowParam) : undefined;
+
+  const events = eventBus.getRecent(count ? Number(count) : undefined, {
+    type: type as EventType | undefined,
+    severity: severity as ObservabilitySeverity | undefined,
+  });
+  const stats = eventBus.getStats(windowMs);
+  return Response.json({ events, stats });
+}
+
+function recordRuntimeObservation(observation: RuntimeRequestObservation): void {
+  const cacheTag = observation.cacheStatus ? ` ${observation.cacheStatus}` : "";
+  console.log(
+    `[${new Date().toLocaleTimeString()}] ${observation.req.method} ${observation.path} ${observation.status} ${observation.duration}ms${cacheTag}`
+  );
+  observation.recordRequest?.({
+    id: observation.correlationId,
+    method: observation.req.method,
+    path: observation.path,
+    status: observation.status,
+    duration: observation.duration,
+    timestamp: Date.now(),
+    cacheStatus: observation.cacheStatus,
+  });
+  eventBus.emit({
+    type: "http",
+    severity: observation.status >= 500 ? "error" : observation.status >= 400 ? "warn" : "info",
+    source: "server",
+    correlationId: observation.correlationId,
+    message: `${observation.req.method} ${observation.path} ${observation.status}${cacheTag}`,
+    duration: observation.duration,
+    data: {
+      method: observation.req.method,
+      path: observation.path,
+      status: observation.status,
+      cache: observation.cacheStatus,
+      error: observation.error || undefined,
+    },
+  });
+}

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

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

package/src/runtime/request-middleware.ts

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