@rangojs/router 0.0.0-experimental.29 → 0.0.0-experimental.30

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.29",
+  version: "0.0.0-experimental.30",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.29",
+  "version": "0.0.0-experimental.30",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/src/router/handler-context.ts

@@ -9,7 +9,7 @@ import { _getRequestContext } from "../server/request-context.js";
 import { getSearchSchema, isRouteRootScoped } from "../route-map-builder.js";
 import { parseSearchParams, serializeSearchParams } from "../search-params.js";
 import { contextGet, contextSet } from "../context-var.js";
-import { NOCACHE_SYMBOL } from "../cache/taint.js";
+import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
 
@@ -213,6 +213,24 @@ export function createHandlerContext<TEnv>(
   const stubResponse =
     requestContext?.res ?? new Response(null, { status: 200 });
 
+  // Guard mutating Headers methods so they throw inside "use cache" functions.
+  const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
+  const guardedHeaders = new Proxy(stubResponse.headers, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function") {
+        if (MUTATING_HEADERS_METHODS.has(prop as string)) {
+          return (...args: any[]) => {
+            assertNotInsideCacheExec(requestContext, "headers");
+            return value.apply(target, args);
+          };
+        }
+        return value.bind(target);
+      }
+      return value;
+    },
+  });
+
   const ctx: InternalHandlerContext<any, TEnv> = {
     params,
     build: false,
@@ -221,6 +239,7 @@ export function createHandlerContext<TEnv>(
     search: searchSchema ? resolvedSearchParams : {},
     pathname,
     url,
+    originalUrl: new URL(request.url),
     env: bindings,
     var: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as HandlerContext<
@@ -228,10 +247,11 @@ export function createHandlerContext<TEnv>(
       TEnv
     >["get"],
     set: ((keyOrVar: any, value: any) => {
+      assertNotInsideCacheExec(requestContext, "set");
       contextSet(variables, keyOrVar, value);
     }) as HandlerContext<any, TEnv>["set"],
     res: stubResponse, // Stub response for setting headers
-    headers: stubResponse.headers, // Shorthand for res.headers
+    headers: guardedHeaders, // Guarded shorthand for res.headers
     // Placeholder use() - will be replaced with actual implementation during request
     use: () => {
       throw new Error("ctx.use() called before loaders were initialized");
@@ -304,6 +324,7 @@ export function createPrerenderContext<TEnv>(
     search: {},
     pathname,
     url: syntheticUrl,
+    originalUrl: syntheticUrl,
     get env(): TEnv {
       return throwUnavailable("env");
     },
@@ -385,6 +406,9 @@ export function createStaticContext<TEnv>(
     get url(): URL {
       return throwUnavailable("url");
     },
+    get originalUrl(): URL {
+      return throwUnavailable("originalUrl");
+    },
     get env(): TEnv {
       return throwUnavailable("env");
     },

package/src/router/middleware-types.ts

@@ -57,9 +57,15 @@ export interface MiddlewareContext<
   /** Original request */
   request: Request;
 
-  /** Parsed URL */
+  /** Parsed URL (with internal `_rsc*` params stripped) */
   url: URL;
 
+  /**
+   * The original request URL with all parameters intact, including
+   * internal `_rsc*` transport params.
+   */
+  originalUrl: URL;
+
   /** URL pathname */
   pathname: string;
 
@@ -73,16 +79,7 @@ export interface MiddlewareContext<
   params: TParams;
 
   /**
-   * Response stub (read-only). Before `next()`, returns the shared response stub
-   * where headers and cookies accumulate. After `next()`, returns the downstream response.
-   *
-   * Use `ctx.header()` to set response headers, or `cookies()` for cookie mutations.
-   * To replace the response entirely, return a new `Response` from the middleware.
-   */
-  readonly res: Response;
-
-  /**
-   * Shorthand for ctx.res.headers — response headers.
+   * Response headers.
    * Before `next()`, returns headers from the shared response stub.
    * After `next()`, returns headers from the downstream response.
    */
@@ -101,11 +98,10 @@ export interface MiddlewareContext<
   var: DefaultVars;
 
   /**
-   * Set a response header - can be called before or after `next()`
+   * Set a response header - can be called before or after `next()`.
    *
    * When called before `next()`, headers are queued and merged into the final response.
    * When called after `next()`, headers are set directly on the response.
-   * Shorthand for `ctx.res.headers.set()`.
    */
   header(name: string, value: string): void;
 
@@ -202,7 +198,7 @@ export interface MiddlewareEntry<TEnv = any> {
 }
 
 /**
- * Mutable response holder - allows ctx.res to be updated after next() is called
+ * Mutable response holder - tracks the current response through the middleware chain.
  */
 export interface ResponseHolder {
   response: Response | null;

package/src/router/middleware.ts

@@ -163,9 +163,25 @@ export function createMiddlewareContext<TEnv>(
   // Cookie operations are handled by the standalone cookies() function which
   // delegates to the shared RequestContext internally.
   // The runtime implementation - types are enforced at call sites via MiddlewareContext<TEnv>
+  // Internal helper: resolve the current response (stub before next(), real after).
+  // Not exposed on the public MiddlewareContext type — use ctx.headers instead.
+  const getResponse = (): Response => {
+    if (isPreNext()) {
+      const reqCtx = _getRequestContext();
+      if (reqCtx) return reqCtx.res;
+    }
+    if (!responseHolder.response) {
+      throw new Error(
+        "Response is not available - responseHolder was not initialized",
+      );
+    }
+    return responseHolder.response;
+  };
+
   return {
     request,
     url,
+    originalUrl: new URL(request.url),
     pathname: url.pathname,
     searchParams: url.searchParams,
     env: env as MiddlewareContext<TEnv>["env"],
@@ -180,28 +196,8 @@ export function createMiddlewareContext<TEnv>(
       ) as MiddlewareContext<TEnv>["routeName"];
     },
 
-    get res(): Response {
-      // Before next(): return shared RequestContext stub so headers
-      // set via ctx.header() are visible on ctx.res.
-      if (isPreNext()) {
-        const reqCtx = _getRequestContext();
-        if (reqCtx) return reqCtx.res;
-      }
-      if (!responseHolder.response) {
-        throw new Error(
-          "ctx.res is not available - responseHolder was not initialized",
-        );
-      }
-      return responseHolder.response;
-    },
-    set res(_: Response) {
-      throw new Error(
-        "ctx.res is read-only. Use ctx.header() to set response headers, or cookies() for cookie mutations.",
-      );
-    },
-
     get headers(): Headers {
-      return this.res.headers;
+      return getResponse().headers;
     },
 
     get: ((keyOrVar: any) =>
@@ -302,9 +298,9 @@ export function matchMiddleware<TEnv>(
  *
  * Features:
  * - `await next()` returns actual Response
- * - `ctx.res` available after `await next()` (like Hono's `c.res`)
- * - `ctx.header()` shorthand for setting headers
- * - Forgiving: if middleware doesn't return, uses `ctx.res`
+ * - `ctx.headers` available before and after `await next()`
+ * - `ctx.header()` shorthand for setting a single header
+ * - Forgiving: if middleware doesn't return, uses the downstream response
  * - Short-circuit: return Response to stop chain
  * - Error catching: try/catch around `next()` works
  */

package/src/router/prerender-match.ts

@@ -101,6 +101,7 @@ export async function matchForPrerender<TEnv = any>(
       env: {} as TEnv,
       request: new Request("http://prerender" + pathname),
       url: new URL("http://prerender" + pathname),
+      originalUrl: new URL("http://prerender" + pathname),
       pathname,
       searchParams: new URLSearchParams(),
       var: variables,
@@ -331,6 +332,7 @@ export async function renderStaticSegment<TEnv = any>(
     env: {} as TEnv,
     request: syntheticRequest,
     url: syntheticUrl,
+    originalUrl: syntheticUrl,
     pathname: "/",
     searchParams: syntheticUrl.searchParams,
     var: {},

package/src/server/request-context.ts

@@ -49,8 +49,13 @@ export interface RequestContext<
   env: TEnv;
   /** Original HTTP request */
   request: Request;
-  /** Parsed URL (system params like _rsc* are NOT filtered here) */
+  /** Parsed URL (with internal `_rsc*` params stripped) */
   url: URL;
+  /**
+   * The original request URL with all parameters intact, including
+   * internal `_rsc*` transport params.
+   */
+  originalUrl: URL;
   /** URL pathname */
   pathname: string;
   /** URL search params (system params like _rsc* are NOT filtered here) */
@@ -72,12 +77,7 @@ export interface RequestContext<
    * Initially empty, then set to matched params
    */
   params: TParams;
-  /**
-   * Stub response for setting headers/cookies (read-only).
-   * Headers set here are merged into the final response.
-   * Use header() or setStatus() to mutate response headers/status.
-   * Use cookies().set()/cookies().delete() for cookie mutations.
-   */
+  /** @internal Stub response for collecting headers/cookies. Use ctx.headers or ctx.header() instead. */
   readonly res: Response;
 
   /** @internal Get a cookie value (effective: request + response mutations). Use cookies().get() instead. */
@@ -301,6 +301,7 @@ export type PublicRequestContext<
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
+  | "res"
 >;
 
 // AsyncLocalStorage instance for request context
@@ -556,6 +557,7 @@ export function createRequestContext<TEnv>(
     env,
     request,
     url,
+    originalUrl: new URL(request.url),
     pathname: url.pathname,
     searchParams: url.searchParams,
     var: variables,

package/src/types/handler-context.ts

@@ -228,9 +228,17 @@ export type HandlerContext<
    */
   pathname: string;
   /**
-   * The full URL object (with system params filtered).
+   * The full URL object (with internal `_rsc*` params stripped).
+   * Use this for application logic — routing, link generation, display.
    */
   url: URL;
+  /**
+   * The original request URL with all parameters intact, including
+   * internal `_rsc*` transport params. Use `ctx.url` for application
+   * logic — this is only needed for advanced cases like debugging
+   * or custom cache keying.
+   */
+  originalUrl: URL;
   /**
    * Platform bindings (DB, KV, secrets, etc.).
    * Access resources like `ctx.env.DB`, `ctx.env.KV`.
@@ -267,21 +275,7 @@ export type HandlerContext<
     <T>(contextVar: ContextVar<T>, value: T): void;
   } & (<K extends keyof DefaultVars>(key: K, value: DefaultVars[K]) => void);
   /**
-   * Stub response for setting headers/cookies.
-   * Headers set here are merged into the final response.
-   *
-   * @example
-   * ```typescript
-   * route("product", (ctx) => {
-   *   ctx.res.headers.set("Cache-Control", "s-maxage=60");
-   *   return <ProductPage />;
-   * });
-   * ```
-   */
-  res: Response;
-  /**
-   * Shorthand for ctx.res.headers - response headers.
-   * Headers set here are merged into the final response.
+   * Response headers. Headers set here are merged into the final response.
    *
    * @example
    * ```typescript
@@ -436,6 +430,8 @@ export type InternalHandlerContext<
   TEnv = DefaultEnv,
   TSearch extends SearchSchema = {},
 > = HandlerContext<TParams, TEnv, TSearch> & {
+  /** @internal Stub response for collecting headers/cookies. */
+  res: Response;
   /** Prerender-only control flow helper, attached when the runtime context supports it. */
   passthrough?: () => unknown;
   /** Current segment ID for handle data attribution. */