@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.20dbba0c

package/skills/middleware/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: middleware
-description: Define middleware for authentication, logging, and request processing in rsc-router
+description: Define middleware for authentication, logging, and request processing in @rangojs/router
 argument-hint: [middleware-name]
 ---
 
@@ -8,435 +8,363 @@ argument-hint: [middleware-name]
 
 Middleware runs before/after route handlers using the onion model.
 
-## Router-Level Middleware
+## Execution Model
 
-Register middleware on the router with `.use()`:
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
 
-```typescript
-// router.tsx
-import { createRSCRouter } from "rsc-router/server";
-
-const router = createRSCRouter<AppEnv>({ document: Document })
-  // Global middleware (runs for ALL routes)
-  .use(loggerMiddleware)
-  .use(requestIdMiddleware)
-
-  // Pattern-based middleware (runs for matching paths)
-  .use("/admin/*", adminAuthMiddleware)
-  .use("/api/*", rateLimitMiddleware)
-  .use("/api/:version/*", apiVersionMiddleware)
-
-  // Routes with scoped middleware
-  .routes("/shop", shopRoutes)
-  .use(shopAuthMiddleware)  // Only runs for /shop/* routes
-  .map(() => import("./handlers/shop"));
-```
-
-**Pattern matching:**
-- `*` - Match all routes
-- `/admin/*` - Match `/admin` and anything under it
-- `/users/:id` - Match `/users/123`, extract `{ id: "123" }`
-- `/api/:version/*` - Match `/api/v1/users`, extract `{ version: "v1" }`
+There are two levels of middleware with different execution scopes:
 
-## Middleware Scoping Rules
+### Global middleware (`router.use()`)
 
-**Key insight:** `.map()` returns the **router** (not the builder), so after `.map()` you're back to global scope.
+Registered on the router instance. Wraps the **entire request**, including server actions, rendering, and progressive enhancement (PE) re-renders.
 
 ```typescript
-const router = createRSCRouter<AppEnv>({ document: Document })
-  // GLOBAL - no mount prefix
-  .use(loggerMiddleware)           // Runs for ALL routes
-
-  // SCOPED to /shop/*
-  .routes("/shop", shopRoutes)
-  .use(shopAuthMiddleware)         // Only /shop/*
-  .use("/cart/*", cartMiddleware)  // Only /shop/cart/*
-  .map(() => import("./handlers/shop"))
-
-  // GLOBAL again - .map() returned router, not builder
-  .use(anotherMiddleware)          // Runs for ALL routes (including /admin)
-
-  // SCOPED to /admin/*
-  .routes("/admin", adminRoutes)
-  .use(adminAuthMiddleware)        // Only /admin/*
-  .map(() => import("./handlers/admin"))
-
-  // GLOBAL again
-  .use(finalMiddleware);           // Runs for ALL routes
-```
-
-**The chain structure:**
-```
-router.use()     → returns router (global middleware)
-router.routes()  → returns builder (scoped to mount prefix)
-builder.use()    → returns builder (middleware scoped to mount prefix)
-builder.map()    → returns router (ends scope, back to global)
+const router = createRouter<AppEnv>({})
+  .use(loggerMiddleware) // all routes
+  .use("/admin/*", authMiddleware) // pattern-scoped
+  .routes(urlpatterns);
 ```
 
-**Example execution order:**
-```typescript
-.use(A)                    // Global: all routes
-.routes("/shop", shop)
-  .use(B)                  // Scoped: /shop/*
-  .use("/vip/*", C)        // Scoped: /shop/vip/*
-  .map(...)
-.use(D)                    // Global: all routes
-.routes("/admin", admin)
-  .use(E)                  // Scoped: /admin/*
-  .map(...)
-.use(F)                    // Global: all routes
-```
+When the router has a `basename`, pattern-scoped `.use()` patterns are automatically prefixed. For example, with `basename: "/app"`, `.use("/admin/*", mw)` matches `/app/admin/*`.
 
-Result:
-- `/shop/products` → A, B, D, F
-- `/shop/vip/lounge` → A, B, C, D, F
-- `/admin/dashboard` → A, D, E, F
-- `/` (home) → A, D, F
+### Route middleware (`middleware()` in `urls()`)
 
-## Handler-Level Middleware
+Registered inside `urls()` callback. Wraps **rendering only** -- it does NOT wrap server action execution. Actions run before route middleware, so when route middleware executes during post-action revalidation, it can observe state that the action set (cookies, context variables, headers).
 
-Register middleware within route handlers using the `middleware()` helper:
+```
+Request flow (with action):
+  global mw -> action executes -> route mw -> layout -> handler -> loaders
 
-```typescript
-import { map } from "rsc-router/server";
+Request flow (no action):
+  global mw -> route mw -> layout -> handler -> loaders
 
-export default map<typeof routes>(({ route, middleware }) => [
-  // Handler-wide middleware
-  middleware(async (ctx, next) => {
-    console.log("Request started:", ctx.pathname);
-    const start = Date.now();
+Progressive enhancement (no-JS form POST):
+  global mw -> action executes -> route mw -> full page re-render
+```
 
-    await next();
+The contract is: **route middleware wraps rendering regardless of transport** (JS-enabled RSC stream or no-JS HTML). During PE re-render, route middleware observes action-set state (cookies, context variables) the same way it does during JS-enabled post-action revalidation.
 
-    const duration = Date.now() - start;
-    ctx.header("X-Response-Time", `${duration}ms`);
-  }),
+Revalidation is still partial. Route middleware wraps the render pass that
+does happen, but it does not force unrelated outer segments to recompute.
+If a child segment depends on data established by an outer handler/layout,
+revalidate that outer segment too, or have the child guard/reload the
+data itself.
 
-  route("index", IndexHandler),
-]);
-```
+### Revalidation Contracts with Middleware-Backed Trees
 
-## Route-Specific Middleware
+Middleware can establish request-level context (`ctx.set`) for segments that
+execute in the current render pass. It does not change partial revalidation
+boundaries between handler/layout/parallel segments.
 
-Apply middleware to individual routes:
+For shared segment data, use named revalidation contracts on both the producer
+and consumer segments, even when middleware is present in the chain.
 
 ```typescript
-export default map<typeof routes>(({ route, middleware }) => [
-  // No middleware
-  route("public", PublicPage),
-
-  // With route-specific middleware
-  route(
-    "dashboard",
-    (ctx) => <DashboardPage user={ctx.get("user")} />,
-    () => [
-      middleware(async (ctx, next) => {
-        const user = await getUser(ctx.request);
-        if (!user) throw redirect("/login");
-        ctx.set("user", user);
-        await next();
-      }),
-    ]
+export const revalidateCartData = ({ actionId }) =>
+  actionId?.includes("src/actions/cart.ts#") ?? false;
+
+layout(CartLayout, () => [
+  middleware(cartRenderMiddleware),
+  revalidate(revalidateCartData), // producer reruns
+  parallel(
+    { "@cart": CartSummary },
+    () => [revalidate(revalidateCartData)], // consumer reruns
   ),
 ]);
 ```
 
-## Middleware Context API
+You can package those contracts as importable helpers to avoid repeating
+`revalidate(...)` at each segment:
 
 ```typescript
-middleware(async (ctx, next) => {
-  // Request info
-  ctx.request        // Raw Request object
-  ctx.url            // URL object
-  ctx.pathname       // Current path
-  ctx.searchParams   // URLSearchParams
-  ctx.params         // Route parameters (from pattern)
-  ctx.env            // Platform bindings (Cloudflare, etc.)
-
-  // Variable storage (share data with handlers)
-  ctx.set("user", { id: "123", name: "John" });
-  ctx.get("user");   // Retrieve stored value
-
-  // Response headers
-  ctx.header("X-Custom", "value");
+import { revalidate } from "@rangojs/router";
 
-  // Cookies
-  ctx.cookie("session");           // Read request cookie
-  ctx.cookies();                   // Read all cookies as object
-  ctx.setCookie("auth", "token", { httpOnly: true, secure: true });
-  ctx.deleteCookie("old-session");
+export const revalidateCart = () => [revalidate(revalidateCartData)];
 
-  await next();
-
-  // After handler - access response
-  ctx.res;           // Response object (available after next())
-});
+layout(CartLayout, () => [
+  middleware(cartRenderMiddleware),
+  revalidateCart(),
+  parallel({ "@cart": CartSummary }, () => [revalidateCart()]),
+]);
 ```
 
-## Authentication Middleware
+Route middleware is the right place for per-route concerns that affect rendering (setting context variables for handlers, adding response headers, reading cookies set by actions). It is NOT the right place for action guards -- use global middleware for that.
 
-```typescript
-// middleware/auth.ts
-import { redirect } from "rsc-router/server";
+## Basic Middleware
 
-export const authMiddleware = async (ctx, next) => {
-  const session = ctx.request.headers.get("Authorization");
+```typescript
+import type { Middleware } from "@rangojs/router";
 
-  if (!session) {
-    throw redirect("/login");
-  }
+export const authMiddleware: Middleware = async (ctx, next) => {
+  const token = ctx.request.headers.get("Authorization");
 
-  const user = await verifySession(session);
-  if (!user) {
-    throw redirect("/login");
+  if (!token) {
+    throw new Response("Unauthorized", { status: 401 });
   }
 
+  const user = await verifyToken(token);
   ctx.set("user", user);
+
   await next();
 };
+```
+
+## Using Middleware in Routes
+
+```typescript
+import { urls } from "@rangojs/router";
+import { authMiddleware, loggerMiddleware } from "./middleware";
+
+export const urlpatterns = urls(({ path, layout, middleware }) => [
+  // Global middleware for all routes in this file
+  middleware(loggerMiddleware),
 
-// Usage in handler
-export default map<typeof routes>(({ route, layout, middleware }) => [
-  middleware(authMiddleware),
+  // Layout with scoped middleware
+  layout(<AdminLayout />, () => [
+    middleware(authMiddleware),  // Only for admin routes
 
-  layout(<DashboardLayout />, () => [
-    route("dashboard.index", (ctx) => {
-      const user = ctx.get("user"); // From middleware
-      return <Dashboard user={user} />;
-    }),
+    path("/admin", AdminDashboard, { name: "admin.index" }),
+    path("/admin/users", AdminUsers, { name: "admin.users" }),
   ]),
+
+  // Public routes (no auth middleware)
+  path("/", HomePage, { name: "home" }),
+  path("/about", AboutPage, { name: "about" }),
 ]);
 ```
 
-## Multiple Middleware (Onion Model)
+## Middleware with Multiple Handlers
 
 ```typescript
-export default map<typeof routes>(({ route, middleware }) => [
-  middleware(loggerMiddleware),    // 1st: Enter first, exit last
-  middleware(authMiddleware),      // 2nd: Enter second, exit second
-  middleware(rateLimitMiddleware), // 3rd: Enter third, exit first
+// Group multiple middleware in an array
+export const shopMiddleware = [loggerMiddleware, mockAuthMiddleware];
 
-  route("api", ApiHandler),        // Handler runs in the middle
-]);
-```
+// In routes — pass the array directly
+layout(<ShopLayout />, () => [
+  middleware(shopMiddleware),
 
-Execution order:
-```
-loggerMiddleware (enter)
-  authMiddleware (enter)
-    rateLimitMiddleware (enter)
-      ApiHandler executes
-    rateLimitMiddleware (exit)
-  authMiddleware (exit)
-loggerMiddleware (exit)
+  path("/shop", ShopIndex, { name: "shop" }),
+])
 ```
 
-## Scoped Middleware in Layouts
+## Wrapping Middleware (Scoped to Children)
 
-Apply middleware to layout children:
+Use the wrapping form to scope middleware to a subset of routes without
+introducing a visible layout:
 
 ```typescript
-export default map<typeof routes>(({ route, layout, middleware }) => [
-  // Public routes (no auth)
-  route("index", HomePage),
-  route("about", AboutPage),
+urls(({ path, middleware }) => [
+  // authMw only applies to /admin and /admin/settings
+  middleware(authMw, () => [
+    path("/admin", AdminPage, { name: "admin" }),
+    path("/admin/settings", SettingsPage, { name: "settings" }),
+  ]),
 
-  // Protected routes - middleware applies to layout and all children
-  layout(<DashboardLayout />, () => [
-    middleware(authMiddleware),  // Runs for all dashboard routes
+  // Public route — no authMw
+  path("/", HomePage, { name: "home" }),
+]);
+```
 
-    route("dashboard.index", DashboardPage),
-    route("dashboard.settings", SettingsPage),
-  ]),
+Multiple middleware with wrapping:
+
+```typescript
+middleware([authMw, loggingMw], () => [
+  path("/admin", AdminPage, { name: "admin" }),
 ]);
 ```
 
-## Loader Middleware
+This creates a transparent layout (`<Outlet />`) that carries the middleware.
+The middleware does not affect sibling routes outside the callback.
 
-Middleware specific to a loader:
+## Middleware Context
 
 ```typescript
-import { createLoader } from "rsc-router/server";
-
-export const UserProfileLoader = createLoader(
-  async (ctx) => {
-    const userId = ctx.get("userId"); // From loader middleware
-    return db.users.findUnique({ where: { id: userId } });
-  },
-  {
-    middleware: [
-      async (ctx, next) => {
-        const userId = ctx.params.id;
-        ctx.set("userId", userId);
-        await next();
-      },
-    ],
-  }
-);
+export const myMiddleware: Middleware = async (ctx, next) => {
+  // Access request
+  ctx.request; // Request object
+  ctx.url; // Parsed URL
+  ctx.params; // Route parameters
+
+  // Access platform bindings (plain bindings from createRouter<TEnv>())
+  ctx.env.DB; // D1Database
+  ctx.env.KV; // KVNamespace
+
+  // Set variables for downstream handlers (typed via RSCRouter.Vars)
+  ctx.set("user", { id: "123", name: "John" });
+
+  // Continue to next middleware/handler
+  await next();
+
+  // After handler (response intercepting)
+  console.log("Handler completed");
+};
 ```
 
-## Short-Circuit Middleware
+### Typed context variables in middleware
 
-Stop execution early by returning a Response or throwing:
+Use `createVar<T>()` for type-safe data sharing between middleware and handlers:
 
 ```typescript
-// Return Response to short-circuit
-export const maintenanceMiddleware = async (ctx, next) => {
-  if (isMaintenanceMode()) {
-    return new Response("Under Maintenance", { status: 503 });
-  }
+import { createVar } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
+
+interface AuthUser { id: string; email: string; role: string }
+export const CurrentUser = createVar<AuthUser>();
+
+export const authMiddleware: Middleware = async (ctx, next) => {
+  const token = ctx.request.headers.get("Authorization");
+  if (!token) throw new Response("Unauthorized", { status: 401 });
+
+  const user = await verifyToken(token);
+  ctx.set(CurrentUser, user);  // type-checked
   await next();
 };
 
-// Throw redirect
-export const redirectMiddleware = async (ctx, next) => {
-  if (ctx.pathname === "/old-path") {
-    throw redirect("/new-path");
-  }
-  await next();
+// In a handler -- typed read
+import { CurrentUser } from "./middleware";
+
+const Dashboard: Handler<"dashboard"> = (ctx) => {
+  const user = ctx.get(CurrentUser);  // typed as AuthUser | undefined
+  return <DashboardPage user={user!} />;
 };
+```
+
+This works alongside `ctx.get("key")` / `ctx.set("key", value)` (global typing
+via RSCRouter.Vars augmentation). Use `createVar` for route-local or feature-scoped
+data; use RSCRouter.Vars for app-wide middleware state.
+
+## Redirect with State in Middleware
+
+```typescript
+import { redirect, createLocationState } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
+
+export const FlashMessage = createLocationState<{ text: string }>({
+  flash: true,
+});
 
-// Return early for auth
-export const authGuard = async (ctx, next) => {
-  if (!isAuthenticated(ctx)) {
-    return new Response(null, {
-      status: 302,
-      headers: { Location: "/login" },
+export const requireAuthMiddleware: Middleware = async (ctx, next) => {
+  const token = ctx.request.headers.get("Authorization");
+  if (!token) {
+    return redirect("/login", {
+      state: [FlashMessage({ text: "Please log in to continue" })],
     });
   }
   await next();
 };
 ```
 
-## Error Handling Middleware
+Read the flash on the target page with `useLocationState(FlashMessage)`. The `{ flash: true }` option makes it auto-clear after first render. See `/hooks`.
+
+## Authentication Middleware
 
 ```typescript
-export const errorMiddleware = async (ctx, next) => {
-  try {
-    await next();
-  } catch (error) {
-    if (error instanceof AuthError) {
-      throw redirect("/login");
-    }
-    if (error instanceof NotFoundError) {
-      throw notFound();
-    }
-    // Re-throw other errors
-    throw error;
+export const requireAuthMiddleware: Middleware = async (ctx, next) => {
+  const user = ctx.get("user");
+
+  if (!user) {
+    throw new Response("Unauthorized", { status: 401 });
   }
+
+  await next();
+};
+
+export const permissionsMiddleware: Middleware = async (ctx, next) => {
+  const user = ctx.get("user");
+  const requiredPermission = "admin";
+
+  if (!user?.permissions?.includes(requiredPermission)) {
+    throw new Response("Forbidden", { status: 403 });
+  }
+
+  await next();
 };
 ```
 
-## CORS Middleware Example
+## Logger Middleware
 
 ```typescript
-export const corsMiddleware = async (ctx, next) => {
-  ctx.header("Access-Control-Allow-Origin", "*");
-  ctx.header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE");
-  ctx.header("Access-Control-Allow-Headers", "Content-Type, Authorization");
+export const loggerMiddleware: Middleware = async (ctx, next) => {
+  const start = Date.now();
 
-  if (ctx.method === "OPTIONS") {
-    return new Response(null, { status: 204 });
-  }
+  console.log(`[${ctx.request.method}] ${ctx.url.pathname}`);
 
   await next();
+
+  const duration = Date.now() - start;
+  console.log(`[${ctx.request.method}] ${ctx.url.pathname} - ${duration}ms`);
 };
 ```
 
-## Rate Limiting Middleware Example
+## Rate Limiting Middleware
 
 ```typescript
-const rateLimiter = new Map<string, number[]>();
-
-export const rateLimitMiddleware = async (ctx, next) => {
+export const rateLimitMiddleware: Middleware = async (ctx, next) => {
   const ip = ctx.request.headers.get("CF-Connecting-IP") ?? "unknown";
-  const now = Date.now();
-  const windowMs = 60000; // 1 minute
-  const maxRequests = 100;
+  const key = `rate-limit:${ip}`;
 
-  const requests = rateLimiter.get(ip) ?? [];
-  const recentRequests = requests.filter((t) => now - t < windowMs);
+  const count = await ctx.env.KV.get(key);
+  const requests = count ? parseInt(count) : 0;
 
-  if (recentRequests.length >= maxRequests) {
-    ctx.header("Retry-After", "60");
-    return new Response("Too Many Requests", { status: 429 });
+  if (requests > 100) {
+    throw new Response("Too Many Requests", { status: 429 });
   }
 
-  recentRequests.push(now);
-  rateLimiter.set(ip, recentRequests);
+  await ctx.env.KV.put(key, String(requests + 1), {
+    expirationTtl: 60,
+  });
 
   await next();
 };
 ```
 
-## Type-Safe Route Middleware
-
-Use `RouteMiddlewareFn` for type-safe params:
+## Complete Example
 
 ```typescript
-import type { RouteMiddlewareFn } from "rsc-router";
-import type { shopRoutes } from "./routes/shop";
-
-// Middleware with typed params from route definition
-export const productMiddleware: RouteMiddlewareFn<
-  typeof shopRoutes,
-  "shop.product"  // Route has :slug param
-> = async (ctx, next) => {
-  // ctx.params.slug is typed as string
-  console.log("Viewing product:", ctx.params.slug);
+// middleware/index.ts
+import type { Middleware } from "@rangojs/router";
+
+export const loggerMiddleware: Middleware = async (ctx, next) => {
+  console.log(`[${ctx.request.method}] ${ctx.url.pathname}`);
   await next();
 };
-```
 
-## Middleware Type Signatures
+export const mockAuthMiddleware: Middleware = async (ctx, next) => {
+  // Mock user for development
+  ctx.set("user", { id: "1", name: "Demo User" });
+  await next();
+};
 
-```typescript
-// Basic middleware function
-type MiddlewareFn<TEnv = any, TParams = Record<string, string>> = (
-  ctx: MiddlewareContext<TEnv, TParams>,
-  next: () => Promise<Response>
-) => Response | Promise<Response> | void | Promise<void>;
-
-// Middleware context
-interface MiddlewareContext<TEnv, TParams> {
-  request: Request;
-  url: URL;
-  pathname: string;
-  searchParams: URLSearchParams;
-  env: TEnv;
-  params: TParams;
-  res: Response;
-
-  cookie(name: string): string | undefined;
-  cookies(): Record<string, string>;
-  setCookie(name: string, value: string, options?: CookieOptions): void;
-  deleteCookie(name: string, options?: CookieOptions): void;
-
-  get<K extends string>(key: K): any;
-  set<K extends string>(key: K, value: any): void;
-  header(name: string, value: string): void;
-}
-```
+export const requireAuthMiddleware: Middleware = async (ctx, next) => {
+  if (!ctx.get("user")) {
+    throw new Response("Unauthorized", { status: 401 });
+  }
+  await next();
+};
 
-## Cookie Options
+// urls.tsx
+import { urls } from "@rangojs/router";
+import {
+  loggerMiddleware,
+  mockAuthMiddleware,
+  requireAuthMiddleware,
+} from "./middleware";
 
-```typescript
-interface CookieOptions {
-  domain?: string;
-  path?: string;
-  expires?: Date;
-  maxAge?: number;
-  httpOnly?: boolean;
-  secure?: boolean;
-  sameSite?: "strict" | "lax" | "none";
-}
-
-// Example
-ctx.setCookie("session", token, {
-  httpOnly: true,
-  secure: true,
-  sameSite: "lax",
-  maxAge: 60 * 60 * 24 * 7,  // 1 week
-  path: "/",
-});
+export const urlpatterns = urls(({ path, layout, middleware }) => [
+  // Global middleware
+  middleware(loggerMiddleware),
+  middleware(mockAuthMiddleware),
+
+  // Public routes
+  path("/", HomePage, { name: "home" }),
+
+  // Protected routes
+  layout(<AccountLayout />, () => [
+    middleware(requireAuthMiddleware),
+
+    path("/account", AccountPage, { name: "account" }),
+    path("/account/settings", SettingsPage, { name: "settings" }),
+  ]),
+]);
 ```