@rangojs/router 0.0.0-experimental.002d056c

package/skills/middleware/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: middleware
+description: Define middleware for authentication, logging, and request processing in @rangojs/router
+argument-hint: [middleware-name]
+---
+
+# Middleware
+
+Middleware runs before/after route handlers using the onion model.
+
+## Execution Model
+
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
+There are two levels of middleware with different execution scopes:
+
+### Global middleware (`router.use()`)
+
+Registered on the router instance. Wraps the **entire request**, including server actions, rendering, and progressive enhancement (PE) re-renders.
+
+```typescript
+const router = createRouter<AppEnv>({})
+  .use(loggerMiddleware) // all routes
+  .use("/admin/*", authMiddleware) // pattern-scoped
+  .routes(urlpatterns);
+```
+
+### Route middleware (`middleware()` in `urls()`)
+
+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).
+
+```
+Request flow (with action):
+  global mw -> action executes -> route mw -> layout -> handler -> loaders
+
+Request flow (no action):
+  global mw -> route mw -> layout -> handler -> loaders
+
+Progressive enhancement (no-JS form POST):
+  global mw -> action executes -> route mw -> full page re-render
+```
+
+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.
+
+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.
+
+### Revalidation Contracts with Middleware-Backed Trees
+
+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.
+
+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 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
+  ),
+]);
+```
+
+You can package those contracts as importable helpers to avoid repeating
+`revalidate(...)` at each segment:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateCart = () => [revalidate(revalidateCartData)];
+
+layout(CartLayout, () => [
+  middleware(cartRenderMiddleware),
+  revalidateCart(),
+  parallel({ "@cart": CartSummary }, () => [revalidateCart()]),
+]);
+```
+
+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.
+
+## Basic Middleware
+
+```typescript
+import type { Middleware } from "@rangojs/router";
+
+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("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),
+
+  // Layout with scoped middleware
+  layout(<AdminLayout />, () => [
+    middleware(authMiddleware),  // Only for admin routes
+
+    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" }),
+]);
+```
+
+## Middleware with Multiple Handlers
+
+```typescript
+// Spread multiple middleware from a single export
+export const shopMiddleware = [loggerMiddleware, mockAuthMiddleware];
+
+// In routes
+layout(<ShopLayout />, () => [
+  middleware(...shopMiddleware),
+
+  path("/shop", ShopIndex, { name: "shop" }),
+])
+```
+
+## Middleware Context
+
+```typescript
+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");
+};
+```
+
+### Typed context variables in middleware
+
+Use `createVar<T>()` for type-safe data sharing between middleware and handlers:
+
+```typescript
+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();
+};
+
+// 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,
+});
+
+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();
+};
+```
+
+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 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();
+};
+```
+
+## Logger Middleware
+
+```typescript
+export const loggerMiddleware: Middleware = async (ctx, next) => {
+  const start = Date.now();
+
+  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
+
+```typescript
+export const rateLimitMiddleware: Middleware = async (ctx, next) => {
+  const ip = ctx.request.headers.get("CF-Connecting-IP") ?? "unknown";
+  const key = `rate-limit:${ip}`;
+
+  const count = await ctx.env.KV.get(key);
+  const requests = count ? parseInt(count) : 0;
+
+  if (requests > 100) {
+    throw new Response("Too Many Requests", { status: 429 });
+  }
+
+  await ctx.env.KV.put(key, String(requests + 1), {
+    expirationTtl: 60,
+  });
+
+  await next();
+};
+```
+
+## Complete Example
+
+```typescript
+// 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();
+};
+
+export const mockAuthMiddleware: Middleware = async (ctx, next) => {
+  // Mock user for development
+  ctx.set("user", { id: "1", name: "Demo User" });
+  await next();
+};
+
+export const requireAuthMiddleware: Middleware = async (ctx, next) => {
+  if (!ctx.get("user")) {
+    throw new Response("Unauthorized", { status: 401 });
+  }
+  await next();
+};
+
+// urls.tsx
+import { urls } from "@rangojs/router";
+import {
+  loggerMiddleware,
+  mockAuthMiddleware,
+  requireAuthMiddleware,
+} from "./middleware";
+
+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" }),
+  ]),
+]);
+```

package/skills/mime-routes/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: mime-routes
+description: Content negotiation — serve different response types (RSC, JSON, text, XML) from the same URL based on Accept header
+argument-hint: [negotiate|vary|accept]
+---
+
+# Content Negotiation (MIME Routes)
+
+Content negotiation lets you register multiple response types on the same URL pattern.
+The router inspects the `Accept` header and dispatches to the matching handler.
+All negotiated responses include `Vary: Accept` for correct CDN/cache behavior.
+
+See also: `/response-routes` for the base response route API (path.json, path.text, etc.).
+
+## Defining Negotiated Routes
+
+Declare the same URL pattern with both an RSC route and one or more response-type routes.
+Order within the `urls()` array does not matter — the trie merges them at build time.
+
+```typescript
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path, layout, include }) => [
+  // RSC page + JSON API on the same URL
+  path("/products/:id", ProductPage, { name: "product" }),
+  path.json(
+    "/products/:id",
+    (ctx) => {
+      return db.getProduct(ctx.params.id);
+    },
+    { name: "productJson" },
+  ),
+]);
+```
+
+When a browser requests `/products/42` (`Accept: text/html`), the RSC page renders.
+When an API client requests the same URL (`Accept: application/json`), the JSON handler runs.
+
+## Negotiation Rules
+
+1. **Q-value priority** — higher `q` wins (`Accept: application/json;q=0.9, text/html;q=1.0` serves RSC)
+2. **Client order tiebreaker** — when q-values are equal, the type listed first in Accept wins (matches Express/Hono behavior)
+3. **Specific MIME match** — the variant whose MIME type appears in Accept wins
+4. **Wildcard / empty Accept** — `*/*` and missing Accept fall back to route definition order (the first-defined variant wins)
+5. **All responses** on a negotiated URL get `Vary: Accept` header, including the RSC side
+
+RSC participates as a `text/html` candidate alongside response-type variants.
+There is no special short-circuit — RSC follows the same negotiation rules as other types.
+
+The MIME mapping used for matching:
+
+| Tag                  | MIME type                                                    |
+| -------------------- | ------------------------------------------------------------ |
+| RSC (plain `path()`) | `text/html` (negotiation) / `text/x-component` (wire format) |
+| `json`               | `application/json`                                           |
+| `text`               | `text/plain`                                                 |
+| `xml`                | `application/xml`                                            |
+| `html`               | `text/html`                                                  |
+| `md`                 | `text/markdown`                                              |
+
+RSC routes negotiate as `text/html` but respond with `text/x-component` (the RSC wire format).
+The browser's RSC runtime decodes this transparently — clients requesting `text/html` get
+the RSC page rendered normally.
+
+Tags `image`, `stream`, and `any` are pass-through and do not participate in Accept matching.
+
+## Multiple Response Types
+
+A single URL can have an RSC route plus multiple response-type variants:
+
+```typescript
+export const urlpatterns = urls(({ path }) => [
+  path("/data", DataPage, { name: "data" }),
+  path.json("/data", () => ({ format: "json" }), { name: "dataJson" }),
+  path.text("/data", () => "plain text", { name: "dataText" }),
+  path.xml("/data", () => "<root>xml</root>", { name: "dataXml" }),
+]);
+```
+
+- `Accept: text/html` — RSC page
+- `Accept: application/json` — JSON handler
+- `Accept: text/plain` — text handler
+- `Accept: application/xml` — XML handler
+- `Accept: */*` — first variant (JSON, since it was registered first)
+
+## Wildcard Routes
+
+Content negotiation works with wildcard `/*` patterns:
+
+```typescript
+path("/files/*", FileBrowserPage, { name: "files" }),
+path.json("/files/*", (ctx) => {
+  const filePath = ctx.params["*"];
+  return { entries: listDir(filePath) };
+}, { name: "filesJson" }),
+```
+
+## Response-Only Negotiation (No RSC Primary)
+
+Two or more response-type routes can share a URL without an RSC route.
+The last registered route becomes the primary; earlier ones become variants:
+
+```typescript
+path.json("/api/data", () => ({ format: "json" }), { name: "dataJson" }),
+path.text("/api/data", () => "plain text version", { name: "dataText" }),
+```
+
+Without an RSC primary, there is no `text/html` candidate — the Accept header
+picks among the response-type candidates directly.
+
+## How It Works
+
+1. **Build time**: `buildRouteTrie()` calls `mergeLeaves()` when multiple routes share a pattern.
+   RSC routes become the primary trie leaf; response-type routes are stored in the `nv`
+   (negotiate variants) array on the leaf. The `rf` (rsc-first) flag tracks definition order.
+2. **Runtime**: `previewRoute()` reads `negotiateVariants` from the trie match result.
+   It parses the `Accept` header (extracting q-values and order), builds a candidate list
+   (RSC as `text/html` + response-type variants), and calls `pickNegotiateVariant()`.
+3. **Candidate matching**: walks the client's sorted Accept list (by q desc, then order asc),
+   matching each entry against candidates. Wildcards (`*/*`, `text/*`) fall back to definition order.
+4. **Vary header**: both the response-route handler wrapper and the RSC handler wrapper
+   append `Vary: Accept` when the `negotiated` flag is set on the preview result.
+
+## Caching Considerations
+
+`Vary: Accept` is set automatically on all negotiated responses. This tells CDNs and
+HTTP caches to store separate entries per Accept header value. No additional cache
+configuration is needed for negotiated routes — the framework handles it.