@mandujs/core 0.27.0 → 0.29.0

package/src/middleware/compose.ts

@@ -0,0 +1,134 @@
+/**
+ * Middleware composition — Phase 18.ε
+ *
+ * Builds a request pipeline from an array of `Middleware` layers and a
+ * final handler. The resulting function has Next.js / SvelteKit semantics:
+ *
+ *   - **Declaration order = outer-to-inner.** `compose(a, b, c)` runs
+ *     `a.handler(req, nextA)` first; `nextA()` runs `b.handler`, whose
+ *     `nextB()` runs `c.handler`, whose `nextC()` invokes `finalHandler`.
+ *
+ *   - **Short-circuit.** Any middleware may return a Response without
+ *     calling `next()`. Downstream middleware and the final handler are
+ *     skipped; the outer chain receives the short-circuit Response.
+ *
+ *   - **Rewrite.** `next(modifiedReq)` propagates `modifiedReq` to the
+ *     remainder of the chain. The current middleware still sees the
+ *     original `req` argument (no mutation).
+ *
+ *   - **Match filter.** Middleware with a `match(req) === false` are
+ *     skipped at their position in the chain — `next()` transparently
+ *     advances to the next layer.
+ *
+ *   - **Error propagation.** Throws inside middleware are re-thrown to
+ *     the caller. Mandu's outer `handleRequest` wraps this in the
+ *     framework's error boundary (error → 500 via `errorToResponse`),
+ *     so middleware authors never need their own top-level try/catch
+ *     unless they want to convert specific errors to specific responses.
+ *
+ *   - **Double-next guard.** Calling `next()` twice inside a single
+ *     middleware is a programming error (it would re-execute downstream
+ *     layers with duplicate side effects). The second call throws a
+ *     `MiddlewareError` with the offending middleware's name so the bug
+ *     surfaces immediately in dev.
+ *
+ * @see {@link Middleware} for the interface.
+ * @see `docs/architect/middleware-composition.md` for patterns.
+ */
+import type { Middleware } from "./define";
+
+/**
+ * The finalized request handler that sits at the bottom of the middleware
+ * chain. Typically this is `handleRequest(req, router, registry)` adapted
+ * to the `(req) => Promise<Response>` shape.
+ */
+export type FinalHandler = (req: Request) => Promise<Response>;
+
+/**
+ * The function produced by {@link compose}. Applies the middleware chain
+ * on top of `finalHandler` for the given request.
+ */
+export type ComposedHandler = (
+  req: Request,
+  finalHandler: FinalHandler
+) => Promise<Response>;
+
+/**
+ * Thrown when a middleware calls `next()` more than once. Identifies the
+ * middleware by name so the diagnostic is actionable.
+ */
+export class MiddlewareError extends Error {
+  override readonly name = "MiddlewareError";
+  constructor(
+    public readonly middlewareName: string,
+    message: string
+  ) {
+    super(`[${middlewareName}] ${message}`);
+  }
+}
+
+/**
+ * Compose a middleware chain. Zero middleware produces a passthrough:
+ * `compose()(req, final) === final(req)`.
+ */
+export function compose(...middlewares: Middleware[]): ComposedHandler {
+  // Defensive copy — callers mutating the source array after compose() must
+  // not affect the frozen pipeline. Also narrows index type for the inner
+  // recursion and makes an empty-array fast path trivial.
+  const chain = middlewares.slice();
+
+  if (chain.length === 0) {
+    return (req, finalHandler) => finalHandler(req);
+  }
+
+  return async function composed(
+    req: Request,
+    finalHandler: FinalHandler
+  ): Promise<Response> {
+    // Recursive dispatcher. `index` is the next middleware to try; `current`
+    // is the Request object that layer will receive. Each invocation either:
+    //   (a) index === chain.length → delegate to finalHandler(current)
+    //   (b) chain[index].match(current) === false → skip, recurse to next
+    //   (c) run chain[index].handler(current, next) where next() = dispatch(i+1, …)
+    async function dispatch(index: number, current: Request): Promise<Response> {
+      if (index >= chain.length) {
+        return finalHandler(current);
+      }
+      const mw = chain[index]!;
+
+      // Evaluate match filter. Throws in `match` are framework-bug territory —
+      // we surface them to the outer error boundary rather than papering over.
+      if (mw.match) {
+        let matched: boolean;
+        try {
+          matched = mw.match(current);
+        } catch (err) {
+          throw new MiddlewareError(
+            mw.name,
+            `\`match(req)\` threw: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+        if (!matched) {
+          return dispatch(index + 1, current);
+        }
+      }
+
+      // Single-use `next` guard — second invocation throws.
+      let nextCalled = false;
+      const next = (override?: Request): Promise<Response> => {
+        if (nextCalled) {
+          throw new MiddlewareError(
+            mw.name,
+            "next() was called more than once. Each middleware must call next() at most once."
+          );
+        }
+        nextCalled = true;
+        return dispatch(index + 1, override ?? current);
+      };
+
+      return mw.handler(current, next);
+    }
+
+    return dispatch(0, req);
+  };
+}

package/src/middleware/define.ts

@@ -0,0 +1,132 @@
+/**
+ * Canonical Middleware Composition API — Phase 18.ε
+ *
+ * This module defines Mandu's request-level middleware contract. It is the
+ * runtime analogue of Next.js `middleware.ts` and SvelteKit's `hooks.server.ts`
+ * `handle` sequence: each middleware is a thin onion layer that wraps the
+ * final route handler, can short-circuit by returning a Response without
+ * calling `next()`, and executes in declaration order (outermost first).
+ *
+ * This API is intentionally **request-level**, not context-level:
+ *
+ *   - `filling().use(...)` / `MiddlewarePlugin` — operates on a per-route
+ *     `ManduContext`. Good for inline concerns like `csrf()` / `session()`
+ *     / `secure()` that a single filling chain wants to compose.
+ *
+ *   - `Middleware` / `compose()` (this module) — operates on the raw
+ *     `Request` BEFORE route dispatch. Good for app-wide policies:
+ *     auth gates, tenant resolution, rate limiting, request logging,
+ *     rewrites, redirects.
+ *
+ * Both APIs co-exist. Bridge wrappers live alongside each individual
+ * middleware module (e.g. `csrf.ts` exports `csrfMiddleware(...)`) so users
+ * who want the canonical composition API for an existing middleware can
+ * plug it in without boilerplate.
+ *
+ * @example
+ * ```ts
+ * import { defineMiddleware, compose } from "@mandujs/core/middleware";
+ *
+ * const requestId = defineMiddleware({
+ *   name: "request-id",
+ *   async handler(req, next) {
+ *     const id = req.headers.get("x-request-id") ?? crypto.randomUUID();
+ *     const res = await next();
+ *     res.headers.set("x-request-id", id);
+ *     return res;
+ *   },
+ * });
+ *
+ * const authGate = defineMiddleware({
+ *   name: "auth-gate",
+ *   match: (req) => new URL(req.url).pathname.startsWith("/admin"),
+ *   async handler(req, next) {
+ *     if (!req.headers.get("authorization")) {
+ *       return new Response("Unauthorized", { status: 401 });
+ *     }
+ *     return next();
+ *   },
+ * });
+ *
+ * // In mandu.config.ts:
+ * export default {
+ *   middleware: [requestId, authGate],
+ * } satisfies ManduConfig;
+ * ```
+ */
+
+/**
+ * A request-level middleware. Runs BEFORE route dispatch in declaration order.
+ *
+ *   - `name` identifies the middleware in error messages and diagnostic traces.
+ *   - `match?` is an optional filter: middleware whose `match(req)` returns
+ *     `false` are skipped (the chain proceeds to the next middleware). Absent
+ *     means "always match".
+ *   - `handler(req, next)` does the actual work. Return a Response directly
+ *     to short-circuit (downstream middleware and the route handler are
+ *     skipped). Call `next()` to invoke the rest of the chain and receive
+ *     its Response — at which point you may mutate headers, re-wrap the
+ *     body, log, etc.
+ *
+ * The `req` argument is the Request the current layer sees; a middleware
+ * may pass a modified Request to `next()` by calling it with a Request
+ * argument (rewrite pattern). When called with no argument, `next()` uses
+ * the Request passed into the handler.
+ */
+export interface Middleware {
+  /** Display name used in diagnostics. Must be non-empty. */
+  name: string;
+  /**
+   * Optional route filter. When present and returns `false`, the chain
+   * skips this middleware entirely (proceeds to the next layer / final
+   * handler). When absent the middleware matches all requests.
+   *
+   * Must be synchronous and side-effect-free — `match` runs once per
+   * request per middleware and any throw short-circuits the chain with
+   * a 500 response.
+   */
+  match?: (req: Request) => boolean;
+  /**
+   * Middleware handler. Receives the current Request and a `next()` thunk
+   * that invokes the rest of the chain (or the final route handler, if
+   * this is the innermost middleware). Must return a Response.
+   *
+   * - Call `next()` to continue the chain with the same request.
+   * - Call `next(modifiedReq)` to continue with a rewritten request
+   *   (downstream middleware and the final handler see `modifiedReq`).
+   * - Return a Response directly WITHOUT calling `next()` to short-circuit.
+   */
+  handler: (
+    req: Request,
+    next: (req?: Request) => Promise<Response>
+  ) => Promise<Response>;
+}
+
+/**
+ * Ergonomic helper — passes the middleware object through unchanged but
+ * preserves full type inference and documents intent at the call site.
+ * Mirrors Next.js `defineMiddleware()` and SvelteKit `Handle` exports.
+ *
+ * @throws {TypeError} when `m` is missing `name` or `handler`, or when
+ *   `name` is empty. Fail-fast at definition time — we do NOT want a
+ *   silent no-op layer corrupting a composition chain.
+ */
+export function defineMiddleware(m: Middleware): Middleware {
+  if (!m || typeof m !== "object") {
+    throw new TypeError("[Mandu Middleware] defineMiddleware requires an object");
+  }
+  if (typeof m.name !== "string" || m.name.length === 0) {
+    throw new TypeError("[Mandu Middleware] defineMiddleware requires a non-empty `name`");
+  }
+  if (typeof m.handler !== "function") {
+    throw new TypeError(
+      `[Mandu Middleware] defineMiddleware requires a \`handler\` function (middleware "${m.name}")`
+    );
+  }
+  if (m.match !== undefined && typeof m.match !== "function") {
+    throw new TypeError(
+      `[Mandu Middleware] \`match\` must be a function when provided (middleware "${m.name}")`
+    );
+  }
+  return m;
+}

package/src/middleware/index.ts

@@ -1,50 +1,76 @@
-/**
- * Mandu Middleware Plugins
- * filling.use()로 조합 가능한 재사용 미들웨어
- */
-
-export { cors, type CorsMiddlewareOptions } from "./cors";
-export { jwt, type JwtMiddlewareOptions } from "./jwt";
-export { csrf, type CsrfMiddlewareOptions } from "./csrf";
-export { compress, type CompressMiddlewareOptions } from "./compress";
-export { logger, type LoggerMiddlewareOptions } from "./logger";
-export { timeout, type TimeoutMiddlewareOptions } from "./timeout";
-export {
-  session,
-  saveSession,
-  destroySession,
-  type SessionMiddlewareOptions,
-} from "./session";
-export {
-  oauth,
-  github,
-  google,
-  type OAuthOptions,
-  type OAuthProvider,
-  type OAuthProfile,
-} from "./oauth";
-export {
-  secure,
-  applySecureHeadersToResponse,
-  buildCsp,
-  DEFAULT_CSP_DIRECTIVES,
-  type SecureMiddlewareOptions,
-  type CspOptions,
-  type BuiltCsp,
-  type HstsOptions,
-  type ReferrerPolicyValue,
-} from "./secure";
-export {
-  rateLimit,
-  createRateLimitGuard,
-  createInMemoryStore,
-  createSqliteStore,
-  RateLimitError,
-  type RateLimitResult,
-  type RateLimitStore,
-  type RateLimitMiddleware,
-  type RateLimitMiddlewareOptions,
-  type RateLimitGuard,
-  type RateLimitGuardOptions,
-  type SqliteRateLimitStoreOptions,
-} from "./rate-limit";
+/**
+ * Mandu Middleware — two layers, one surface.
+ *
+ *   1. Filling-level (ctx-based): `.use(csrf(...))`, `.use(session(...))`
+ *      etc. Runs inside the per-route filling chain with a `ManduContext`.
+ *
+ *   2. Request-level (Phase 18.ε — canonical composition API):
+ *      `defineMiddleware(...)`, `compose(...)`. Runs BEFORE route
+ *      dispatch on the raw `Request`. Formalized in `define.ts` /
+ *      `compose.ts`; bridge wrappers for the existing ctx-based
+ *      middleware live in `bridge.ts`.
+ */
+
+// Phase 18.ε — canonical composition API.
+export {
+  defineMiddleware,
+  type Middleware,
+} from "./define";
+export {
+  compose,
+  MiddlewareError,
+  type ComposedHandler,
+  type FinalHandler,
+} from "./compose";
+export {
+  csrfMiddleware,
+  sessionMiddleware,
+  secureMiddleware,
+  rateLimitMiddleware,
+} from "./bridge";
+
+export { cors, type CorsMiddlewareOptions } from "./cors";
+export { jwt, type JwtMiddlewareOptions } from "./jwt";
+export { csrf, type CsrfMiddlewareOptions } from "./csrf";
+export { compress, type CompressMiddlewareOptions } from "./compress";
+export { logger, type LoggerMiddlewareOptions } from "./logger";
+export { timeout, type TimeoutMiddlewareOptions } from "./timeout";
+export {
+  session,
+  saveSession,
+  destroySession,
+  type SessionMiddlewareOptions,
+} from "./session";
+export {
+  oauth,
+  github,
+  google,
+  type OAuthOptions,
+  type OAuthProvider,
+  type OAuthProfile,
+} from "./oauth";
+export {
+  secure,
+  applySecureHeadersToResponse,
+  buildCsp,
+  DEFAULT_CSP_DIRECTIVES,
+  type SecureMiddlewareOptions,
+  type CspOptions,
+  type BuiltCsp,
+  type HstsOptions,
+  type ReferrerPolicyValue,
+} from "./secure";
+export {
+  rateLimit,
+  createRateLimitGuard,
+  createInMemoryStore,
+  createSqliteStore,
+  RateLimitError,
+  type RateLimitResult,
+  type RateLimitStore,
+  type RateLimitMiddleware,
+  type RateLimitMiddlewareOptions,
+  type RateLimitGuard,
+  type RateLimitGuardOptions,
+  type SqliteRateLimitStoreOptions,
+} from "./rate-limit";

package/src/router/fs-patterns.test.ts

@@ -0,0 +1,96 @@
+/**
+ * fs-patterns — pattern detection unit tests (Phase 18.β)
+ *
+ * Focused counterpart to tests/router/route-conventions.test.ts —
+ * co-located with the module so `bun test src/router/` alone exercises
+ * all detection paths without needing a tmpdir fixture. Keeps the
+ * per-symbol tests cheap enough to be run in watch mode.
+ */
+import { describe, it, expect } from "bun:test";
+import {
+  detectFileType,
+  parseSegment,
+  parseSegments,
+  segmentsToPattern,
+  isGroupFolder,
+  validateSegments,
+} from "./fs-patterns";
+
+describe("fs-patterns — convention file detection", () => {
+  it("detects loading.tsx / loading.ts / loading.jsx / loading.js", () => {
+    expect(detectFileType("loading.tsx")).toBe("loading");
+    expect(detectFileType("loading.ts")).toBe("loading");
+    expect(detectFileType("loading.jsx")).toBe("loading");
+    expect(detectFileType("loading.js")).toBe("loading");
+  });
+
+  it("detects error.tsx / error.ts", () => {
+    expect(detectFileType("error.tsx")).toBe("error");
+    expect(detectFileType("error.ts")).toBe("error");
+  });
+
+  it("detects not-found.tsx / not-found.ts", () => {
+    expect(detectFileType("not-found.tsx")).toBe("not-found");
+    expect(detectFileType("not-found.ts")).toBe("not-found");
+  });
+
+  it("does NOT treat notfound.tsx (missing dash) as a convention", () => {
+    expect(detectFileType("notfound.tsx")).toBeNull();
+    expect(detectFileType("not_found.tsx")).toBeNull();
+  });
+
+  it("does NOT confuse loading.island.tsx for a loading convention", () => {
+    // Island suffix wins first (detectFileType checks island before loading)
+    expect(detectFileType("loading.island.tsx")).toBe("island");
+  });
+});
+
+describe("fs-patterns — route groups", () => {
+  it("identifies (marketing) as a group segment", () => {
+    expect(isGroupFolder("(marketing)")).toBe(true);
+    expect(isGroupFolder("(auth)")).toBe(true);
+    expect(isGroupFolder("marketing")).toBe(false);
+    expect(isGroupFolder("(not-matching")).toBe(false);
+  });
+
+  it("parses (name) as type=group with no param", () => {
+    const seg = parseSegment("(marketing)");
+    expect(seg.type).toBe("group");
+    expect(seg.paramName).toBeUndefined();
+  });
+
+  it("strips group segments from URL patterns", () => {
+    expect(segmentsToPattern(parseSegments("(mkt)/pricing/page.tsx"))).toBe("/pricing");
+    expect(segmentsToPattern(parseSegments("(a)/(b)/c/page.tsx"))).toBe("/c");
+  });
+});
+
+describe("fs-patterns — optional catch-all", () => {
+  it("parses [[...slug]] as optionalCatchAll with paramName", () => {
+    const seg = parseSegment("[[...slug]]");
+    expect(seg.type).toBe("optionalCatchAll");
+    expect(seg.paramName).toBe("slug");
+  });
+
+  it("emits :param*? pattern for optionalCatchAll", () => {
+    const pattern = segmentsToPattern(parseSegments("docs/[[...path]]/page.tsx"));
+    expect(pattern).toBe("/docs/:path*?");
+  });
+
+  it("distinguishes [[...x]] (optional) from [...x] (required)", () => {
+    expect(parseSegment("[...x]").type).toBe("catchAll");
+    expect(parseSegment("[[...x]]").type).toBe("optionalCatchAll");
+  });
+
+  it("rejects catch-all mid-path via validateSegments", () => {
+    const segs = parseSegments("[[...any]]/after/page.tsx");
+    const r = validateSegments(segs);
+    expect(r.valid).toBe(false);
+  });
+
+  it("accepts optional catch-all at the end", () => {
+    const segs = parseSegments("docs/[[...rest]]/page.tsx");
+    const r = validateSegments(segs);
+    expect(r.valid).toBe(true);
+  });
+});

package/src/router/fs-routes.ts

@@ -82,6 +82,7 @@ export function fsRouteToRouteSpec(fsRoute: FSRouteConfig): RouteSpec {
         : {}),
       ...(fsRoute.loadingModule ? { loadingModule: normalizePath(fsRoute.loadingModule) } : {}),
       ...(fsRoute.errorModule ? { errorModule: normalizePath(fsRoute.errorModule) } : {}),
+      ...(fsRoute.notFoundModule ? { notFoundModule: normalizePath(fsRoute.notFoundModule) } : {}),
     };
     return pageRoute;
   }

package/src/router/fs-scanner.ts

@@ -241,6 +241,7 @@ export class FSScanner {
     const layoutMap = new Map<string, ScannedFile>();
     const loadingMap = new Map<string, ScannedFile>();
     const errorMap = new Map<string, ScannedFile>();
+    const notFoundMap = new Map<string, ScannedFile>();
     const islandMap = new Map<string, ScannedFile[]>();
     const routeFiles: ScannedFile[] = [];
     const metadataFiles: ScannedFile[] = [];
@@ -258,6 +259,9 @@ export class FSScanner {
         case "error":
           errorMap.set(dirPath, file);
           break;
+        case "not-found":
+          notFoundMap.set(dirPath, file);
+          break;
         case "island": {
           const existing = islandMap.get(dirPath);
           if (existing) {
@@ -392,9 +396,13 @@ export class FSScanner {
         }
       }
 
-      // 로딩/에러 모듈 찾기
+      // 로딩/에러/404 모듈 찾기 — nearest-ancestor resolution.
+      // Phase 18.β: `not-found.tsx` joins `loading.tsx`/`error.tsx` in
+      // walking up the segment tree so a deeply nested route inherits
+      // its parent's 404 UI unless it declares its own.
       const loadingModule = this.findClosestSpecialFile(file.segments, loadingMap);
       const errorModule = this.findClosestSpecialFile(file.segments, errorMap);
+      const notFoundModule = this.findClosestSpecialFile(file.segments, notFoundMap);
 
       const route: FSRouteConfig = {
         id: routeId,
@@ -407,6 +415,7 @@ export class FSScanner {
         layoutChain,
         loadingModule,
         errorModule,
+        notFoundModule,
         sourceFile: file.absolutePath,
       };
 

package/src/router/fs-types.ts

@@ -129,6 +129,14 @@ export interface FSRouteConfig {
   /** 에러 UI 모듈 경로 */
   errorModule?: string;
 
+  /**
+   * 404 UI 모듈 경로. Nearest ancestor `not-found.tsx` resolved via
+   * `findClosestSpecialFile` at scan time. Used at runtime when a page
+   * loader calls `notFound()` or — for unmatched URLs — when the root
+   * route carries one. Phase 18.β — Next.js App Router parity.
+   */
+  notFoundModule?: string;
+
   /** Hydration 설정 */
   hydration?: HydrationConfig;