@mandujs/core 0.28.0 → 0.29.0

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;