@mandujs/core 0.18.22 → 0.19.2

package/src/runtime/cache.ts

@@ -0,0 +1,310 @@
+/**
+ * Mandu SSR Cache Layer
+ * ISR(Incremental Static Regeneration) + SWR(Stale-While-Revalidate) 지원
+ */
+
+// ========== Types ==========
+
+export interface CacheEntry {
+  /** 렌더링된 HTML */
+  html: string;
+  /** 직렬화된 loader 데이터 */
+  loaderData: unknown;
+  /** 응답 상태 코드 */
+  status: number;
+  /** 응답 헤더 */
+  headers: Record<string, string>;
+  /** 생성 시간 (ms) */
+  createdAt: number;
+  /** stale이 되는 시간 (ms) — createdAt + revalidate * 1000 */
+  revalidateAfter: number;
+  /** 무효화 태그 */
+  tags: string[];
+}
+
+export type CacheStatus = "HIT" | "STALE" | "MISS";
+
+export interface CacheLookupResult {
+  status: CacheStatus;
+  entry: CacheEntry | null;
+}
+
+export interface CacheStoreStats {
+  entries: number;
+  maxEntries?: number;
+  staleEntries?: number;
+  hits?: number;
+  staleHits?: number;
+  misses?: number;
+  hitRate?: number;
+}
+
+export interface CacheStore {
+  get(key: string): CacheEntry | null;
+  set(key: string, entry: CacheEntry): void;
+  delete(key: string): void;
+  /** pathname 부분 매칭으로 캐시 삭제 (키 형식: "routeId:pathname") */
+  deleteByPath(pathname: string): void;
+  deleteByTag(tag: string): void;
+  clear(): void;
+  readonly size: number;
+}
+
+// ========== Memory Cache (LRU) ==========
+
+export class MemoryCacheStore implements CacheStore {
+  private cache = new Map<string, CacheEntry>();
+  private tagIndex = new Map<string, Set<string>>();
+  private readonly maxEntries: number;
+  private hits = 0;
+  private staleHits = 0;
+  private misses = 0;
+
+  constructor(maxEntries: number = 1000) {
+    this.maxEntries = maxEntries;
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  get(key: string): CacheEntry | null {
+    return this.cache.get(key) ?? null;
+  }
+
+  /** LRU 접근 — HIT 확인 후에만 호출하여 stale 엔트리가 승격되지 않도록 */
+  touch(key: string): void {
+    const entry = this.cache.get(key);
+    if (entry) {
+      this.cache.delete(key);
+      this.cache.set(key, entry);
+    }
+  }
+
+  set(key: string, entry: CacheEntry): void {
+    // 기존 엔트리 태그 인덱스 정리
+    if (this.cache.has(key)) {
+      this.removeFromTagIndex(key);
+    }
+
+    // LRU eviction
+    if (this.cache.size >= this.maxEntries) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== undefined) {
+        this.removeFromTagIndex(oldest);
+        this.cache.delete(oldest);
+      }
+    }
+
+    this.cache.set(key, entry);
+
+    // 태그 인덱스 업데이트
+    for (const tag of entry.tags) {
+      let keys = this.tagIndex.get(tag);
+      if (!keys) {
+        keys = new Set();
+        this.tagIndex.set(tag, keys);
+      }
+      keys.add(key);
+    }
+  }
+
+  delete(key: string): void {
+    this.removeFromTagIndex(key);
+    this.cache.delete(key);
+  }
+
+  deleteByPath(pathname: string): void {
+    // 캐시 키 형식: "routeId:pathname?query" — pathname 부분이 일치하는 모든 키 삭제
+    const keysToDelete: string[] = [];
+    for (const key of this.cache.keys()) {
+      const keyPath = getCachePathname(key);
+      if (keyPath === pathname) {
+        keysToDelete.push(key);
+      }
+    }
+    for (const key of keysToDelete) {
+      this.delete(key);
+    }
+  }
+
+  deleteByTag(tag: string): void {
+    const keys = this.tagIndex.get(tag);
+    if (!keys) return;
+
+    for (const key of keys) {
+      this.cache.delete(key);
+      // 해당 key가 다른 태그에도 있으면 거기서도 제거
+      for (const [otherTag, otherKeys] of this.tagIndex) {
+        if (otherTag !== tag) {
+          otherKeys.delete(key);
+        }
+      }
+    }
+    this.tagIndex.delete(tag);
+  }
+
+  clear(): void {
+    this.cache.clear();
+    this.tagIndex.clear();
+  }
+
+  recordHit(): void {
+    this.hits += 1;
+  }
+
+  recordStale(): void {
+    this.staleHits += 1;
+  }
+
+  recordMiss(): void {
+    this.misses += 1;
+  }
+
+  getStats(): CacheStoreStats {
+    const now = Date.now();
+    const staleEntries = Array.from(this.cache.values()).filter((entry) => entry.revalidateAfter <= now).length;
+    const totalLookups = this.hits + this.staleHits + this.misses;
+
+    return {
+      entries: this.cache.size,
+      maxEntries: this.maxEntries,
+      staleEntries,
+      hits: this.hits,
+      staleHits: this.staleHits,
+      misses: this.misses,
+      hitRate: totalLookups > 0 ? this.hits / totalLookups : undefined,
+    };
+  }
+
+  private removeFromTagIndex(key: string): void {
+    const entry = this.cache.get(key);
+    if (!entry) return;
+    for (const tag of entry.tags) {
+      this.tagIndex.get(tag)?.delete(key);
+    }
+  }
+}
+
+function getCachePathname(key: string): string {
+  const colonIdx = key.indexOf(":");
+  const rawPath = colonIdx >= 0 ? key.slice(colonIdx + 1) : key;
+  try {
+    return new URL(rawPath, "http://mandu.local").pathname;
+  } catch {
+    const queryIdx = rawPath.indexOf("?");
+    return queryIdx >= 0 ? rawPath.slice(0, queryIdx) : rawPath;
+  }
+}
+
+// ========== Cache Lookup ==========
+
+/**
+ * 캐시 조회 — HIT / STALE / MISS 판정
+ */
+export function lookupCache(store: CacheStore, key: string): CacheLookupResult {
+  const entry = store.get(key);
+  if (!entry) {
+    if ("recordMiss" in store && typeof (store as MemoryCacheStore).recordMiss === "function") {
+      (store as MemoryCacheStore).recordMiss();
+    }
+    return { status: "MISS", entry: null };
+  }
+
+  const now = Date.now();
+  if (now < entry.revalidateAfter) {
+    if ("recordHit" in store && typeof (store as MemoryCacheStore).recordHit === "function") {
+      (store as MemoryCacheStore).recordHit();
+    }
+    // HIT: LRU 승격 (MemoryCacheStore만 해당)
+    if ("touch" in store && typeof (store as MemoryCacheStore).touch === "function") {
+      (store as MemoryCacheStore).touch(key);
+    }
+    return { status: "HIT", entry };
+  }
+
+  if ("recordStale" in store && typeof (store as MemoryCacheStore).recordStale === "function") {
+    (store as MemoryCacheStore).recordStale();
+  }
+  // STALE: LRU 승격하지 않음 — eviction 대상으로 유지
+  return { status: "STALE", entry };
+}
+
+/**
+ * 캐시 엔트리 생성
+ */
+export function createCacheEntry(
+  html: string,
+  loaderData: unknown,
+  revalidateSeconds: number,
+  tags: string[] = [],
+  status: number = 200,
+  headers: Record<string, string> = {}
+): CacheEntry {
+  const now = Date.now();
+  return {
+    html,
+    loaderData,
+    status,
+    headers,
+    createdAt: now,
+    revalidateAfter: now + revalidateSeconds * 1000,
+    tags,
+  };
+}
+
+/**
+ * 캐시된 Response 생성
+ */
+export function createCachedResponse(entry: CacheEntry, cacheStatus: CacheStatus): Response {
+  const age = Math.floor((Date.now() - entry.createdAt) / 1000);
+  return new Response(entry.html, {
+    status: entry.status,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      ...entry.headers,
+      "X-Mandu-Cache": cacheStatus,
+      "Age": String(age),
+    },
+  });
+}
+
+// ========== Global Cache + Revalidation API ==========
+
+let globalCacheStore: CacheStore | null = null;
+
+export function setGlobalCache(store: CacheStore): void {
+  globalCacheStore = store;
+}
+
+export function getGlobalCache(): CacheStore | null {
+  return globalCacheStore;
+}
+
+/**
+ * 특정 경로의 캐시 무효화
+ */
+export function revalidatePath(path: string): void {
+  if (!globalCacheStore) return;
+  globalCacheStore.deleteByPath(path);
+}
+
+/**
+ * 특정 태그의 모든 캐시 무효화
+ */
+export function revalidateTag(tag: string): void {
+  if (!globalCacheStore) return;
+  globalCacheStore.deleteByTag(tag);
+}
+
+export function getCacheStoreStats(store: CacheStore | null): CacheStoreStats | null {
+  if (!store) return null;
+
+  if ("getStats" in store && typeof (store as MemoryCacheStore).getStats === "function") {
+    return (store as MemoryCacheStore).getStats();
+  }
+
+  return {
+    entries: store.size,
+  };
+}

package/src/runtime/handler.ts

@@ -0,0 +1,65 @@
+/**
+ * Mandu Fetch Handler Factory
+ * 런타임 중립적 fetch handler 생성
+ * Bun.serve, Node.js http, Cloudflare Workers 등에서 공통 사용
+ */
+
+import type { Router } from "./router";
+import type { ServerRegistry } from "./server";
+import type {
+  MiddlewareFn,
+  MiddlewareConfig,
+  InternalMiddlewareContext,
+} from "./middleware";
+import { createMiddlewareContext, getMiddlewareMatch } from "./middleware";
+import { type CorsOptions, isCorsRequest, applyCorsToResponse } from "./cors";
+
+export interface FetchHandlerOptions {
+  router: Router;
+  registry: ServerRegistry;
+  corsOptions: CorsOptions | false;
+  middlewareFn: MiddlewareFn | null;
+  middlewareConfig: MiddlewareConfig | null;
+  handleRequest: (req: Request, router: Router, registry: ServerRegistry) => Promise<Response>;
+}
+
+/**
+ * 런타임 중립적 fetch handler 생성
+ * 미들웨어, CORS, 라우트 디스패치를 모두 포함
+ */
+export function createFetchHandler(options: FetchHandlerOptions): (req: Request) => Promise<Response> {
+  const { router, registry, corsOptions, handleRequest, middlewareFn, middlewareConfig } = options;
+
+  return async function fetchHandler(req: Request): Promise<Response> {
+    // 글로벌 미들웨어 실행 (라우트 매칭 전)
+    if (middlewareFn) {
+      const url = new URL(req.url);
+      const middlewareMatch = getMiddlewareMatch(url.pathname, middlewareConfig);
+      if (middlewareMatch.matched) {
+        const mwCtx = createMiddlewareContext(req, middlewareMatch.params);
+        try {
+          const response = await middlewareFn(mwCtx, async () => {
+            const rewrittenReq = (mwCtx as InternalMiddlewareContext).getRewrittenRequest();
+            return handleRequest(rewrittenReq ?? req, router, registry);
+          });
+
+          if (corsOptions && isCorsRequest(req)) {
+            return applyCorsToResponse(response, req, corsOptions);
+          }
+          return response;
+        } catch (error) {
+          console.error("[Mandu Middleware] Error:", error);
+          return new Response("Internal Server Error", { status: 500 });
+        }
+      }
+    }
+
+    const response = await handleRequest(req, router, registry);
+
+    if (corsOptions && isCorsRequest(req)) {
+      return applyCorsToResponse(response, req, corsOptions);
+    }
+
+    return response;
+  };
+}

package/src/runtime/image-handler.ts

@@ -0,0 +1,195 @@
+/**
+ * Mandu Image Handler
+ * /_mandu/image?url=...&w=...&q=... 엔드포인트
+ * 온디맨드 리사이즈 + WebP/AVIF 포맷 협상 + 캐시
+ */
+
+import path from "path";
+
+// ========== Types ==========
+
+interface ImageOptions {
+  width: number;
+  quality: number;
+  format: "webp" | "jpeg" | "png" | "avif";
+  sourceContentType?: string;
+}
+
+interface ProcessedImageResult {
+  data: Uint8Array;
+  contentType: string;
+}
+
+// ========== Cache ==========
+
+const imageCache = new Map<string, { data: Uint8Array; contentType: string }>();
+const MAX_IMAGE_CACHE = 500;
+
+// ========== Handler ==========
+
+/**
+ * 이미지 최적화 요청 처리
+ * /_mandu/image?url=/photos/hero.jpg&w=800&q=80
+ */
+export async function handleImageRequest(
+  request: Request,
+  rootDir: string,
+  publicDir: string = "public"
+): Promise<Response | null> {
+  const url = new URL(request.url);
+  if (url.pathname !== "/_mandu/image") return null;
+
+  const src = url.searchParams.get("url");
+  const width = Number(url.searchParams.get("w") ?? 800);
+  const quality = Number(url.searchParams.get("q") ?? 80);
+
+  if (!src || width < 1 || width > 4096 || quality < 1 || quality > 100) {
+    return new Response("Invalid image parameters", { status: 400 });
+  }
+
+  // 보안: src가 /로 시작하고 traversal/null byte 없는지 확인
+  if (!src.startsWith("/") || src.includes("..") || src.includes("\0")) {
+    return new Response("Invalid image path", { status: 400 });
+  }
+
+  // 포맷 협상 (Accept 헤더 기반)
+  const format = negotiateFormat(request);
+  const cacheKey = `${src}:${width}:${quality}:${format}`;
+
+  // 캐시 확인
+  const cached = imageCache.get(cacheKey);
+  if (cached) {
+    return new Response(cached.data as unknown as BodyInit, {
+      headers: {
+        "Content-Type": cached.contentType,
+        "Cache-Control": "public, max-age=31536000, immutable",
+        "Vary": "Accept",
+        "X-Mandu-Image-Cache": "HIT",
+      },
+    });
+  }
+
+  // 원본 파일 경로 해석 + symlink traversal 방지
+  const allowedBaseDir = path.resolve(rootDir, publicDir);
+  const filePath = path.join(allowedBaseDir, src.slice(1));
+
+  // realpath로 symlink를 해석한 후 allowedBaseDir 내부인지 검증
+  let resolvedPath: string;
+  try {
+    const realFs = require("fs") as typeof import("fs");
+    resolvedPath = realFs.realpathSync(filePath);
+    const resolvedBase = realFs.realpathSync(allowedBaseDir);
+    if (!resolvedPath.startsWith(resolvedBase + path.sep) && resolvedPath !== resolvedBase) {
+      return new Response("Forbidden", { status: 403 });
+    }
+  } catch {
+    // realpath 실패 (broken symlink, 파일 없음) → 안전하게 404 반환
+    return new Response("Image not found", { status: 404 });
+  }
+  const file = Bun.file(resolvedPath);
+
+  if (!await file.exists()) {
+    return new Response("Image not found", { status: 404 });
+  }
+
+  try {
+    const original = await file.arrayBuffer();
+    const processed = await processImage(new Uint8Array(original), {
+      width,
+      quality,
+      format,
+      sourceContentType: getMimeForExtension(src),
+    });
+
+    // 캐시 저장 (LRU)
+    if (imageCache.size >= MAX_IMAGE_CACHE) {
+      const oldest = imageCache.keys().next().value;
+      if (oldest !== undefined) imageCache.delete(oldest);
+    }
+    imageCache.set(cacheKey, {
+      data: processed.data,
+      contentType: processed.contentType,
+    });
+
+    return new Response(processed.data as unknown as BodyInit, {
+      headers: {
+        "Content-Type": processed.contentType,
+        "Cache-Control": "public, max-age=31536000, immutable",
+        "Vary": "Accept",
+      },
+    });
+  } catch (error) {
+    console.error(`[Mandu Image] Processing failed for ${src}:`, error);
+    // 원본 파일 그대로 반환 (fallback)
+    return new Response(file, {
+      headers: {
+        "Content-Type": getMimeForExtension(src),
+        "Cache-Control": "public, max-age=86400",
+      },
+    });
+  }
+}
+
+// ========== Format Negotiation ==========
+
+function negotiateFormat(request: Request): "webp" | "jpeg" | "png" | "avif" {
+  const accept = request.headers.get("Accept") ?? "";
+  if (accept.includes("image/avif")) return "avif";
+  if (accept.includes("image/webp")) return "webp";
+  return "jpeg";
+}
+
+function getMimeForExtension(src: string): string {
+  const ext = path.extname(src).toLowerCase();
+  const map: Record<string, string> = {
+    ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+    ".png": "image/png", ".gif": "image/gif",
+    ".webp": "image/webp", ".avif": "image/avif",
+    ".svg": "image/svg+xml",
+  };
+  return map[ext] ?? "application/octet-stream";
+}
+
+// ========== Image Processing ==========
+
+/**
+ * 이미지 리사이즈 + 포맷 변환
+ * Bun의 내장 sharp 미지원 시 원본 반환 (graceful degradation)
+ */
+async function processImage(
+  data: Uint8Array,
+  options: ImageOptions
+): Promise<ProcessedImageResult> {
+  // sharp 사용 시도 (선택적 의존성)
+  try {
+    const sharp = require("sharp") as any;
+    let pipeline = sharp(Buffer.from(data)).resize(options.width);
+
+    switch (options.format) {
+      case "webp":
+        pipeline = pipeline.webp({ quality: options.quality });
+        break;
+      case "avif":
+        pipeline = pipeline.avif({ quality: options.quality });
+        break;
+      case "jpeg":
+        pipeline = pipeline.jpeg({ quality: options.quality });
+        break;
+      case "png":
+        pipeline = pipeline.png({ quality: options.quality });
+        break;
+    }
+
+    const result = await pipeline.toBuffer();
+    return {
+      data: new Uint8Array(result),
+      contentType: `image/${options.format}`,
+    };
+  } catch {
+    // sharp 미설치 시 원본 반환
+    return {
+      data,
+      contentType: options.sourceContentType ?? "application/octet-stream",
+    };
+  }
+}

package/src/runtime/index.ts

@@ -10,3 +10,15 @@ export * from "./trace";
 export * from "./logger";
 export * from "./boundary";
 export * from "./stable-selector";
+export {
+  revalidatePath,
+  revalidateTag,
+  getCacheStoreStats,
+  type CacheStore,
+  type CacheStoreStats,
+  MemoryCacheStore,
+} from "./cache";
+export { type MiddlewareContext, type MiddlewareNext, type MiddlewareFn, type MiddlewareConfig } from "./middleware";
+export { type ManduAdapter, type AdapterOptions, type AdapterServer } from "./adapter";
+export { adapterBun } from "./adapter-bun";
+export { createFetchHandler, type FetchHandlerOptions } from "./handler";