@mandujs/core 0.32.0 → 0.33.1

package/src/runtime/server.ts

@@ -1,5 +1,5 @@
 import type { Server } from "bun";
-import type { RoutesManifest, RouteSpec, HydrationConfig } from "../spec/schema";
+import type { RoutesManifest, RouteSpec, HydrationConfig, StaticParamSetSchema } from "../spec/schema";
 import type { BundleManifest } from "../bundler/types";
 import type { ManduFilling, RenderMode } from "../filling/filling";
 import { ManduContext, CookieManager } from "../filling/context";
@@ -531,6 +531,14 @@ export interface ServerOptions {
    * `secureMiddleware`, `rateLimitMiddleware`).
    */
   middleware?: Middleware[];
+  /**
+   * Phase 18.τ — plugins contributing `defineMiddlewareChain()` +
+   * lifecycle observers. Plugin middleware are PREPENDED to
+   * `options.middleware` so they run BEFORE user-declared layers. Both
+   * fields are optional; omission is a zero-overhead passthrough.
+   */
+  plugins?: readonly import("../plugins/hooks").ManduPlugin[];
+  configHooks?: Partial<import("../plugins/hooks").ManduHooks>;
   /**
    * Phase 18.κ — tRPC-like typed RPC endpoints.
    *
@@ -589,6 +597,25 @@ export interface ServerOptions {
    * use `ctx.locale.code` and ignore `ctx.t`.
    */
   messages?: MessageRegistry;
+  /**
+   * Issue #217 — suppress the "🥟 Mandu server listening"/"🥟 Mandu Dev
+   * Server listening" banner printed at boot. The HTTP listener still
+   * binds and `ManduServer.server.port` still reports the chosen port;
+   * only the stdout banner (plus its auxiliary lines — HMR hint, CORS
+   * hint, static-file hint, streaming hint, Kitchen hint, "also
+   * reachable at" hint) is gated.
+   *
+   * Intended for internal callers such as the build-time prerender
+   * orchestrator that spin up a transient listener on an ephemeral
+   * port (`port: 0`) and tear it down seconds later — the banner's
+   * URL is always wrong by the time a human (or an LLM reading build
+   * logs) tries to curl it, so printing it causes confusion.
+   *
+   * User-facing commands (`mandu dev`, `mandu start`) leave this
+   * `undefined` / `false` to preserve the normal banner. Default:
+   * `false`.
+   */
+  silent?: boolean;
 }
 
 export interface ManduServer {
@@ -1317,6 +1344,155 @@ function createStaticErrorResponse(status: 400 | 403 | 404 | 500): Response {
   return new Response(body, { status });
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Static asset cache policy — Issue #218
+//
+// The `immutable` Cache-Control directive is a *contract* with browsers:
+// "the bytes at this URL will never change." Violating it (by overwriting a
+// stable-name file between builds) means users keep stale CSS/JS until they
+// hard-refresh. Mandu historically emitted `/.mandu/client/globals.css`
+// and `/.mandu/client/runtime*.js` with fixed URLs but stamped the response
+// with `immutable`, which is the exact failure mode.
+//
+// Policy:
+//   - Hashed URL  (e.g. `.../chunk.a1b2c3d4.js`) → `immutable` is safe,
+//     1-year max-age.
+//   - Stable URL  (no hash in filename) → `max-age=0, must-revalidate`.
+//     The client revalidates on every request; a matching `If-None-Match`
+//     short-circuits to 304 with no body, so the cost is one HEAD-sized
+//     round-trip, not a full re-download.
+//
+// Strong ETag (content-hash) is emitted for every `/.mandu/client/*`
+// response so conditional GETs are cheap. We use `Bun.hash` (wyhash, ~5GB/s)
+// for the digest and cache results keyed by `path + size + mtime` to avoid
+// re-hashing on every hit.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Heuristic: does the filename look like it carries a content hash?
+ *
+ * Matches:
+ *   - `name.<hash>.ext`      where hash is >=8 hex chars (e.g. `chunk.a1b2c3d4.js`)
+ *   - `name-<hash>.ext`      (e.g. `vendor-8f3a2b9c.js`)
+ *   - `name.<hash>.chunk.ext` common bundler shape
+ *
+ * A hash segment is 8+ lowercase hex chars. Longer digests (16, 20, 32) also
+ * match. We deliberately avoid matching ALL-hex short names like `abc.js`
+ * (requires min length 8).
+ */
+function hasContentHashInFilename(filename: string): boolean {
+  // `.` or `-` separator, 8+ hex chars, then `.` before extension
+  // Examples that match: chunk.a1b2c3d4.js, vendor-8f3a2b9c.js, app.1234567890abcdef.css
+  // Examples that DON'T match: globals.css, runtime.js, chunk.js
+  return /[.\-][a-f0-9]{8,}\.[a-z0-9]+$/i.test(filename);
+}
+
+/**
+ * Compute Cache-Control for a static asset.
+ *
+ * - Dev: no caching (always refetch).
+ * - Prod, hashed filename: `public, max-age=31536000, immutable` (1 year).
+ * - Prod, stable filename: `public, max-age=0, must-revalidate` (force
+ *   revalidation; 304 via `If-None-Match` keeps it cheap).
+ */
+function computeStaticCacheControl(filename: string, isDev: boolean): string {
+  if (isDev) return "no-cache, no-store, must-revalidate";
+  if (hasContentHashInFilename(filename)) {
+    return "public, max-age=31536000, immutable";
+  }
+  return "public, max-age=0, must-revalidate";
+}
+
+/**
+ * In-process ETag cache keyed by absolute filePath. Entry is invalidated
+ * when `size` or `mtime` changes. Avoids re-hashing hot files on every
+ * request. The hot path is a single lookup + two scalar compares.
+ */
+interface EtagCacheEntry {
+  size: number;
+  mtime: number;
+  etag: string;
+}
+const etagCache = new Map<string, EtagCacheEntry>();
+const ETAG_CACHE_MAX = 2048;
+
+/** Cheap LRU eviction: drop oldest insert when over cap. */
+function evictEtagCacheIfNeeded(): void {
+  if (etagCache.size <= ETAG_CACHE_MAX) return;
+  const oldestKey = etagCache.keys().next().value;
+  if (oldestKey !== undefined) etagCache.delete(oldestKey);
+}
+
+/**
+ * Compute a strong ETag from file bytes (Bun.hash / wyhash). Cached by
+ * `path + size + mtime` so we only re-hash when the file changes.
+ *
+ * Strong (not weak `W/`) because we actually hashed the payload — this
+ * preserves byte-range / delta semantics per RFC 7232.
+ */
+async function computeStrongEtag(
+  filePath: string,
+  file: import("bun").BunFile,
+): Promise<string> {
+  const size = file.size;
+  const mtime = file.lastModified;
+
+  const cached = etagCache.get(filePath);
+  if (cached && cached.size === size && cached.mtime === mtime) {
+    return cached.etag;
+  }
+
+  // Bun.hash returns a number/bigint; stringify in base36 for compact ETag.
+  // Fall back to size+mtime-derived ETag if hashing ever throws (edge-runtime
+  // polyfills etc. — `Bun.hash` is a Bun-native primitive).
+  let digest: string;
+  try {
+    const bytes = await file.arrayBuffer();
+    const h = Bun.hash(bytes);
+    digest = typeof h === "bigint" ? h.toString(36) : Number(h).toString(36);
+  } catch {
+    digest = `${size.toString(36)}-${mtime.toString(36)}`;
+  }
+
+  const etag = `"${digest}"`;
+  etagCache.set(filePath, { size, mtime, etag });
+  evictEtagCacheIfNeeded();
+  return etag;
+}
+
+/** Exposed for tests — allows clearing the ETag cache between cases. */
+export function __clearStaticEtagCacheForTests(): void {
+  etagCache.clear();
+}
+
+/**
+ * RFC 7232 §3.2 — `If-None-Match` comparison.
+ *
+ * Accepts:
+ *   - `*` wildcard (matches any current representation)
+ *   - a single ETag (`"abc"` or `W/"abc"`)
+ *   - a comma-separated list
+ *
+ * Uses weak-comparison semantics (strip leading `W/`) because that is the
+ * RFC-prescribed form for `If-None-Match`; a strong server-side ETag still
+ * matches a weak client token if the opaque-string portion is equal.
+ */
+function matchesEtag(ifNoneMatch: string, currentEtag: string): boolean {
+  const trimmed = ifNoneMatch.trim();
+  if (trimmed === "*") return true;
+
+  const normalize = (tag: string): string => {
+    const t = tag.trim();
+    return t.startsWith("W/") ? t.slice(2) : t;
+  };
+
+  const currentNormalized = normalize(currentEtag);
+  for (const part of trimmed.split(",")) {
+    if (normalize(part) === currentNormalized) return true;
+  }
+  return false;
+}
+
 /**
  * 경로가 허용된 디렉토리 내에 있는지 검증
  * Path traversal 공격 방지
@@ -1433,26 +1609,39 @@ async function serveStaticFile(pathname: string, settings: ServerRegistrySetting
     }
 
     const mimeType = getMimeType(filePath);
+    const filename = path.basename(filePath);
 
-    // Cache-Control 헤더 설정
+    // Cache-Control — Issue #218: `immutable` is only safe when the URL
+    // contains a content hash. Stable-name bundles (globals.css, runtime.js)
+    // must use `max-age=0, must-revalidate` or clients will serve stale
+    // bytes until a hard refresh.
+    //
+    // Bundle files go through the hash-aware policy; non-bundle assets
+    // (public/*, favicon, etc.) keep the conservative 1-day cache they had
+    // before — they're user-controlled and unlikely to change per deploy.
     let cacheControl: string;
     if (settings.isDev) {
-      // 개발 모드: 캐시 없음
       cacheControl = "no-cache, no-store, must-revalidate";
     } else if (isBundleFile) {
-      // 프로덕션 번들: 1년 캐시 (파일명에 해시 포함 가정)
-      cacheControl = "public, max-age=31536000, immutable";
+      cacheControl = computeStaticCacheControl(filename, /* isDev */ false);
     } else {
-      // 프로덕션 일반 정적 파일: 1일 캐시
       cacheControl = "public, max-age=86400";
     }
 
-    // ETag: weak validator (파일 크기 + 최종 수정 시간)
-    const etag = `W/"${file.size.toString(36)}-${file.lastModified.toString(36)}"`;
-
-    // 304 Not Modified — 불필요한 전송 방지
+    // Strong ETag from content hash for bundle files — enables cheap 304
+    // round-trips when the client revalidates (`If-None-Match`).
+    // Non-bundle static files keep a weak size+mtime validator (same as
+    // pre-#218 behaviour) — we don't pay the hash cost for user-owned
+    // `public/*` content the framework doesn't control.
+    const etag = isBundleFile
+      ? await computeStrongEtag(filePath, file)
+      : `W/"${file.size.toString(36)}-${file.lastModified.toString(36)}"`;
+
+    // 304 Not Modified — unnecessary transfer avoidance. We compare the
+    // full `If-None-Match` string; RFC 7232 also allows a comma-separated
+    // list and `*`, so handle those two forms explicitly.
     const ifNoneMatch = request?.headers.get("If-None-Match");
-    if (ifNoneMatch === etag) {
+    if (ifNoneMatch && matchesEtag(ifNoneMatch, etag)) {
       return {
         handled: true,
         response: new Response(null, {
@@ -3404,6 +3593,57 @@ function stripLocaleForRedirectCheck(
 }
 // ─── End Phase 18.μ ──────────────────────────────────────────────────────
 
+// ─── Issue #214 — dynamicParams guard helper ────────────────────────────────
+/**
+ * True when the incoming `params` from the router matches one of the
+ * enumerated sets in `staticParams` (populated at build time from
+ * `generateStaticParams`). Used by the runtime #214 guard to decide
+ * whether a `dynamicParams: false` page must 404.
+ *
+ * Matching rules mirror `bundler/generate-static-params.ts`:
+ *   - Scalar segments compare as exact strings.
+ *   - Catch-all segments compare as slash-joined strings (the router
+ *     always materializes wildcards as a single string, whereas
+ *     `generateStaticParams` emits `string[]` — we normalize both
+ *     sides to the joined form for equality).
+ *
+ * When `staticParams` is undefined or empty, no URL can match — the
+ * route effectively becomes "no dynamic URLs at all", which is the
+ * documented behavior of `dynamicParams: false` + `generateStaticParams: []`.
+ */
+function paramsInStaticSet(
+  params: Record<string, string>,
+  staticParams: StaticParamSetSchema[] | undefined
+): boolean {
+  if (!staticParams || staticParams.length === 0) return false;
+  const paramKeys = Object.keys(params);
+  for (const entry of staticParams) {
+    if (!entry) continue;
+    let allMatch = true;
+    for (const key of paramKeys) {
+      const requestValue = params[key];
+      const declared = (entry as Record<string, string | string[] | undefined>)[key];
+      if (declared === undefined) {
+        // Optional catch-all that wasn't declared — router gives empty
+        // string in that case; anything else is a miss.
+        if (requestValue !== "") {
+          allMatch = false;
+          break;
+        }
+        continue;
+      }
+      const declaredJoined = Array.isArray(declared) ? declared.join("/") : declared;
+      if (declaredJoined !== requestValue) {
+        allMatch = false;
+        break;
+      }
+    }
+    if (allMatch) return true;
+  }
+  return false;
+}
+// ─── End Issue #214 ─────────────────────────────────────────────────────────
+
 async function handleRequestInternal(
   req: Request,
   router: Router,
@@ -3707,6 +3947,64 @@ async function handleRequestInternal(
 
   const { route, params } = match;
 
+  // ─── Issue #214 — dynamicParams guard ─────────────────────────────────────
+  // Runs AFTER γ's prerendered pass-through (step 0.5) and BEFORE ζ's
+  // per-route ISR cache dispatch (which lives inside `handlePageRoute`).
+  //
+  // Contract (Next.js parity):
+  //   - Page route opted into `dynamicParams: false` AND has `staticParams`
+  //     populated from `generateStaticParams` at build time → the incoming
+  //     params MUST match one of the known sets. Otherwise: 404.
+  //   - `dynamicParams: true` (or undefined) → default behavior unchanged.
+  //     Any dynamic URL falls through to SSR just like before.
+  //   - API + metadata routes are never gated — `dynamicParams` is
+  //     page-only.
+  //
+  // The guard short-circuits with `renderNotFoundPage` so per-route
+  // `not-found.tsx` / global `notFoundHandler` / built-in JSON 404 all
+  // render correctly without recursing through SSR. Cookies are not
+  // applied because no page loader has run yet — this check precedes
+  // loader dispatch by design.
+  if (
+    route.kind === "page" &&
+    (route as { dynamicParams?: boolean }).dynamicParams === false
+  ) {
+    const staticParams = (route as { staticParams?: StaticParamSetSchema[] })
+      .staticParams;
+    if (!paramsInStaticSet(params, staticParams)) {
+      const pageRouteForNF = route as {
+        id: string;
+        pattern: string;
+        layoutChain?: string[];
+        hydration?: HydrationConfig;
+        streaming?: boolean;
+        notFoundModule?: string;
+      };
+      const nfResponse = await renderNotFoundPage(
+        req,
+        pageRouteForNF,
+        params,
+        registry,
+        /* pageCookies */ undefined,
+        /* layoutCookies */ undefined,
+        /* layoutData */ undefined,
+        new Response(
+          JSON.stringify({
+            message: `No static param match for ${pathname}`,
+          }),
+          { status: 404, headers: { "Content-Type": "application/json" } }
+        )
+      );
+      if (settings.cors && isCorsRequest(req)) {
+        const corsOptions: CorsOptions =
+          typeof settings.cors === "object" ? settings.cors : {};
+        return ok(applyCorsToResponse(nfResponse, req, corsOptions));
+      }
+      return ok(nfResponse);
+    }
+  }
+  // ─── End Issue #214 ───────────────────────────────────────────────────────
+
   // 3. 라우트 종류별 처리
   if (route.kind === "api") {
     const rateLimitOptions = settings.rateLimit;
@@ -3860,6 +4158,13 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     scheduler: schedulerOption,
     i18n: i18nOption,
     messages: messagesOption,
+    plugins: pluginsOption,
+    configHooks: configHooksOption,
+    // #217 — internal flag: suppress the "listening" banner. Threaded
+    // through by `mandu build`'s transient prerender server so that
+    // ephemeral `port: 0` listeners don't confuse humans/LLMs with a
+    // URL that's already torn down by the time they curl it.
+    silent = false,
   } = options;
 
   // Phase 18.μ — validate i18n + messages shape. Both are branded via
@@ -3881,6 +4186,18 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
   // Phase 18.ε — build the request-level middleware chain once at boot.
   // `compose()` returns a passthrough when the list is empty; storing
   // `undefined` for "no middleware" keeps the hot path branch-free.
+  //
+  // Phase 18.τ — plugin-contributed middleware via `defineMiddlewareChain()`
+  // is resolved asynchronously OUTSIDE `startServer()` (which is sync).
+  // Drivers call `resolvePluginMiddleware({ plugins, configHooks, rootDir,
+  // mode })` and pass the resulting `Middleware[]` as a PREFIX of
+  // `options.middleware` before calling `startServer()`.
+  //
+  // `pluginsOption` / `configHooksOption` are still carried here so that
+  // lifecycle observers fired by drivers can reuse the same bundle; they
+  // are NOT consulted for the middleware chain itself.
+  void pluginsOption;
+  void configHooksOption;
   const middlewareChain: ComposedHandler | undefined =
     middlewareOption && middlewareOption.length > 0
       ? composeMiddleware(...middlewareOption)
@@ -4131,31 +4448,43 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
 
   const addresses = formatServerAddresses(hostname, actualPort);
 
-  if (isDev) {
-    console.log(`🥟 Mandu Dev Server listening at ${addresses.primary}`);
-    if (addresses.additional.length > 0) {
-      console.log(`   (also reachable at ${addresses.additional.join(", ")})`);
-    }
-    if (registry.settings.hmrPort) {
-      console.log(`🔥 HMR enabled on port ${registry.settings.hmrPort + PORTS.HMR_OFFSET}`);
-    }
-    console.log(`📂 Static files: /${publicDir}/, /.mandu/client/`);
-    if (corsOptions) {
-      console.log(`🌐 CORS enabled`);
-    }
-    if (streaming) {
-      console.log(`🌊 Streaming SSR enabled`);
-    }
-    if (registry.kitchen) {
-      console.log(`🍳 Kitchen dashboard at ${addresses.primary}/__kitchen`);
-    }
-  } else {
-    console.log(`🥟 Mandu server listening at ${addresses.primary}`);
-    if (addresses.additional.length > 0) {
-      console.log(`   (also reachable at ${addresses.additional.join(", ")})`);
-    }
-    if (streaming) {
-      console.log(`🌊 Streaming SSR enabled`);
+  // ─── #217 — gate the boot banner on `!silent` ─────────────────────────
+  // `silent: true` is passed by internal callers that spawn a transient
+  // listener on an ephemeral port (e.g. the build-time prerender
+  // orchestrator). The HTTP listener still binds; only the stdout banner
+  // — "🥟 Mandu server listening" / "🥟 Mandu Dev Server listening" plus
+  // its auxiliary lines (additional addresses, HMR, static-file hint,
+  // CORS, streaming, Kitchen) — is suppressed. User-facing commands
+  // (`mandu dev`, `mandu start`) leave `silent` undefined/false and
+  // therefore see the banner unchanged.
+  // ─── End #217 ─────────────────────────────────────────────────────────
+  if (!silent) {
+    if (isDev) {
+      console.log(`🥟 Mandu Dev Server listening at ${addresses.primary}`);
+      if (addresses.additional.length > 0) {
+        console.log(`   (also reachable at ${addresses.additional.join(", ")})`);
+      }
+      if (registry.settings.hmrPort) {
+        console.log(`🔥 HMR enabled on port ${registry.settings.hmrPort + PORTS.HMR_OFFSET}`);
+      }
+      console.log(`📂 Static files: /${publicDir}/, /.mandu/client/`);
+      if (corsOptions) {
+        console.log(`🌐 CORS enabled`);
+      }
+      if (streaming) {
+        console.log(`🌊 Streaming SSR enabled`);
+      }
+      if (registry.kitchen) {
+        console.log(`🍳 Kitchen dashboard at ${addresses.primary}/__kitchen`);
+      }
+    } else {
+      console.log(`🥟 Mandu server listening at ${addresses.primary}`);
+      if (addresses.additional.length > 0) {
+        console.log(`   (also reachable at ${addresses.additional.join(", ")})`);
+      }
+      if (streaming) {
+        console.log(`🌊 Streaming SSR enabled`);
+      }
     }
   }
 

package/src/spec/schema.ts

@@ -80,6 +80,13 @@ const RouteSpecBase = {
   streaming: z.boolean().optional(),
 };
 
+// ---- Static params (Issue #214) ----
+// StaticParamSet values mirror `bundler/generate-static-params.ts` —
+// scalar params are strings, catch-all params are `string[]`.
+const StaticParamValue = z.union([z.string(), z.array(z.string())]);
+const StaticParamSet = z.record(StaticParamValue);
+export type StaticParamSetSchema = z.infer<typeof StaticParamSet>;
+
 // ---- Page 라우트 ----
 export const PageRouteSpec = z
   .object({
@@ -93,6 +100,20 @@ export const PageRouteSpec = z
     loadingModule: z.string().optional(),
     errorModule: z.string().optional(),
     notFoundModule: z.string().optional(),
+    /**
+     * Issue #214 — when `false`, the runtime rejects dynamic URLs
+     * whose params aren't in `staticParams` with a 404 instead of
+     * falling through to SSR. Undefined or `true` preserves the
+     * default "SSR on miss" behavior (Next.js parity).
+     */
+    dynamicParams: z.boolean().optional(),
+    /**
+     * Issue #214 — populated at build time from `generateStaticParams`.
+     * Consulted by the runtime #214 guard together with `dynamicParams`
+     * to decide whether an incoming param set is allowed. Scalar values
+     * are strings; catch-all values are string arrays.
+     */
+    staticParams: z.array(StaticParamSet).optional(),
   })
   .refine(
     (route) => {
@@ -159,6 +180,10 @@ export const RouteSpec = z.discriminatedUnion("kind", [
     loadingModule: z.string().optional(),
     errorModule: z.string().optional(),
     notFoundModule: z.string().optional(),
+    // Issue #214 — see PageRouteSpec for contract. Kept optional so
+    // existing manifests load unchanged (default behavior: dynamic SSR).
+    dynamicParams: z.boolean().optional(),
+    staticParams: z.array(StaticParamSet).optional(),
   }),
   z.object({
     ...RouteSpecBase,