Support rewrite request (Similarly to redirect)

.changeset/dirty-dolls-heal.md

@@ -0,0 +1,19 @@
+---
+'@builder.io/qwik-city': minor
+---
+
+FEAT: Added rewrite() to the RequestEvent object. It works like redirect but does not change the URL,
+      think of it as an internal redirect.
+
+Example usage:
+```ts
+export const onRequest: RequestHandler = async ({ url, rewrite }) => {
+  if (url.pathname.includes("/articles/the-best-article-in-the-world")) {
+    const artistId = db.getArticleByName("the-best-article-in-the-world");
+
+    // Url will remain /articles/the-best-article-in-the-world, but under the hood,
+    // will render /articles/${artistId}
+    throw rewrite(`/articles/${artistId}`);
+  }
+};
+```

packages/docs/src/routes/api/qwik-city-middleware-request-handler/index.mdx

@@ -717,6 +717,12 @@ Headers
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/middleware/request-handler/cookie.ts)
 
+## pathname
+
+```typescript
+readonly pathname: string;
+```
+
 ## RedirectMessage
 
 ```typescript
@@ -1020,6 +1026,29 @@ https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
 </td></tr>
 <tr><td>
 
+[originalUrl](#)
+
+</td><td>
+
+`readonly`
+
+</td><td>
+
+URL
+
+</td><td>
+
+The original HTTP request URL.
+
+This property was introduced to support the rewrite feature.
+
+If rewrite is called, the url property will be changed to the rewritten url. while originalUrl will stay the same(e.g the url inserted to the address bar).
+
+If rewrite is never called as part of the request, the url property and the originalUrl are equal.
+
+</td></tr>
+<tr><td>
+
 [params](#)
 
 </td><td>
@@ -1312,6 +1341,25 @@ https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections
 </td></tr>
 <tr><td>
 
+[rewrite](#)
+
+</td><td>
+
+`readonly`
+
+</td><td>
+
+(pathname: string) =&gt; [RewriteMessage](#rewritemessage)
+
+</td><td>
+
+When called, qwik-city will execute the path's matching route flow.
+
+The url in the browser will remain unchanged.
+
+</td></tr>
+<tr><td>
+
 [send](#)
 
 </td><td>
@@ -1462,6 +1510,76 @@ export interface ResolveValue
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/middleware/request-handler/types.ts)
 
+## RewriteMessage
+
+```typescript
+export declare class RewriteMessage extends AbortMessage
+```
+
+**Extends:** [AbortMessage](#abortmessage)
+
+<table><thead><tr><th>
+
+Constructor
+
+</th><th>
+
+Modifiers
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[(constructor)(pathname)](#)
+
+</td><td>
+
+</td><td>
+
+Constructs a new instance of the `RewriteMessage` class
+
+</td></tr>
+</tbody></table>
+
+<table><thead><tr><th>
+
+Property
+
+</th><th>
+
+Modifiers
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[pathname](#rewritemessage-pathname)
+
+</td><td>
+
+`readonly`
+
+</td><td>
+
+string
+
+</td><td>
+
+</td></tr>
+</tbody></table>
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/middleware/request-handler/rewrite-handler.ts)
+
 ## ServerError
 
 ```typescript

packages/docs/src/routes/docs/(qwikcity)/guides/rewrites/index.mdx

@@ -0,0 +1,45 @@
+---
+title: Rewrites | Guides
+description: Learn how to use rewrites in Qwik City.
+contributors:
+  - omerman
+updated_at: '2025-05-04T19:43:33Z'
+created_at: '2025-05-04T23:45:13Z'
+---
+
+# Rewrites
+
+Sometimes you want to redirect a user from the current page to another page,
+but you want to keep the current URL in the browser history.
+
+Let's say a user tries to access an article which is indexed by its name,
+e.g `/articles/qwik-is-very-quick`.
+but in our code, we access it by its id, on our directory structure.
+
+```
+src/routes/articles/
+├── [id]
+├─── index.tsx
+```
+
+
+```tsx title="src/routes/[email protected]"
+import type { RequestHandler } from "@builder.io/qwik-city";
+
+export const onRequest: RequestHandler = async ({ url, rewrite }) => {
+  const pattern = /^\/articles\/(.*)$/;
+  // Detects /articles/<article-name>, returns null if url does not match the pattern.
+  const match = url.pathname.match(pattern);
+  if (match) {
+    const articleName = match[1];
+    const { id } = await db.getArticleByName(articleName);
+    throw rewrite(`/articles/${id}`);
+  }
+};
+```
+
+The `rewrite()` function, which was destructured in the RequestHandler function arguments, is invoked with a pathname string.
+
+```tsx
+throw rewrite(`/articles/777/`);
+```

packages/qwik-city/src/buildtime/vite/dev-server.ts

@@ -18,6 +18,7 @@ import { matchRoute } from '../../runtime/src/route-matcher';
 import { getMenuLoader } from '../../runtime/src/routing';
 import type {
   ActionInternal,
+  RebuildRouteInfoInternal,
   ContentMenu,
   LoadedRoute,
   LoaderInternal,
@@ -227,10 +228,27 @@ export function ssrDevMiddleware(ctx: BuildContext, server: ViteDevServer) {
             await server.ssrLoadModule('@qwik-serializer');
           const qwikSerializer = { _deserializeData, _serializeData, _verifySerializable };
 
+          const rebuildRouteInfo: RebuildRouteInfoInternal = async (url: URL) => {
+            const { serverPlugins, loadedRoute } = await resolveRoute(routeModulePaths, url);
+            const requestHandlers = resolveRequestHandlers(
+              serverPlugins,
+              loadedRoute,
+              req.method ?? 'GET',
+              false,
+              renderFn
+            );
+
+            return {
+              loadedRoute,
+              requestHandlers,
+            };
+          };
+
           const { completion, requestEv } = runQwikCity(
             serverRequestEv,
             loadedRoute,
             requestHandlers,
+            rebuildRouteInfo,
             ctx.opts.trailingSlash,
             ctx.opts.basePathname,
             qwikSerializer

packages/qwik-city/src/middleware/request-handler/index.ts

@@ -1,6 +1,7 @@
 export { getErrorHtml, ServerError } from './error-handler';
 export { mergeHeadersCookies } from './cookie';
 export { AbortMessage, RedirectMessage } from './redirect-handler';
+export { RewriteMessage } from './rewrite-handler';
 export { requestHandler } from './request-handler';
 export { _TextEncoderStream_polyfill } from './polyfill';
 export type {

packages/qwik-city/src/middleware/request-handler/middleware.request-handler.api.md

@@ -112,6 +112,7 @@ export interface RequestEventBase<PLATFORM = QwikCityPlatform> {
     readonly env: EnvGetter;
     readonly headers: Headers;
     readonly method: string;
+    readonly originalUrl: URL;
     readonly params: Readonly<Record<string, string>>;
     readonly parseBody: () => Promise<unknown>;
     readonly pathname: string;
@@ -134,6 +135,7 @@ export interface RequestEventCommon<PLATFORM = QwikCityPlatform> extends Request
     readonly locale: (local?: string) => string;
     // Warning: (ae-forgotten-export) The symbol "RedirectCode" needs to be exported by the entry point index.d.ts
     readonly redirect: (statusCode: RedirectCode, url: string) => RedirectMessage;
+    readonly rewrite: (pathname: string) => RewriteMessage;
     // Warning: (ae-forgotten-export) The symbol "SendMethod" needs to be exported by the entry point index.d.ts
     readonly send: SendMethod;
     // Warning: (ae-forgotten-export) The symbol "StatusCodes" needs to be exported by the entry point index.d.ts
@@ -174,6 +176,13 @@ export interface ResolveValue {
     <T>(action: Action<T>): Promise<T | undefined>;
 }
 
+// @public (undocumented)
+export class RewriteMessage extends AbortMessage {
+    constructor(pathname: string);
+    // (undocumented)
+    readonly pathname: string;
+}
+
 // @public (undocumented)
 export class ServerError<T = any> extends Error {
     constructor(status: number, data: T);

packages/qwik-city/src/middleware/request-handler/request-event.ts

@@ -12,6 +12,7 @@ import { createCacheControl } from './cache-control';
 import { Cookie } from './cookie';
 import { ServerError } from './error-handler';
 import { AbortMessage, RedirectMessage } from './redirect-handler';
+import { RewriteMessage } from './rewrite-handler';
 import { encoder } from './resolve-request-handlers';
 import type {
   CacheControl,
@@ -36,6 +37,7 @@ export const RequestRouteName = '@routeName';
 export const RequestEvSharedActionId = '@actionId';
 export const RequestEvSharedActionFormData = '@actionFormData';
 export const RequestEvSharedNonce = '@nonce';
+export const RequestEvIsRewrite = '@rewrite';
 
 export function createRequestEvent(
   serverRequestEv: ServerRequestEvent,
@@ -82,6 +84,18 @@ export function createRequestEvent(
     }
   };
 
+  const resetRoute = (
+    _loadedRoute: LoadedRoute | null,
+    _requestHandlers: RequestHandler<any>[],
+    _url = url
+  ) => {
+    loadedRoute = _loadedRoute;
+    requestHandlers = _requestHandlers;
+    url.pathname = _url.pathname;
+    url.search = _url.search;
+    routeModuleIndex = -1;
+  };
+
   const check = () => {
     if (writableStream !== null) {
       throw new Error('Response already sent');
@@ -133,17 +147,26 @@ export function createRequestEvent(
     [RequestEvLoaders]: loaders,
     [RequestEvMode]: serverRequestEv.mode,
     [RequestEvTrailingSlash]: trailingSlash,
-    [RequestEvRoute]: loadedRoute,
+    get [RequestEvRoute]() {
+      return loadedRoute;
+    },
     [RequestEvQwikSerializer]: qwikSerializer,
     cookie,
     headers,
     env,
     method: request.method,
     signal: request.signal,
-    params: loadedRoute?.[1] ?? {},
-    pathname: url.pathname,
+    originalUrl: new URL(url),
+    get params() {
+      return loadedRoute?.[1] ?? {};
+    },
+    get pathname() {
+      return url.pathname;
+    },
     platform,
-    query: url.searchParams,
+    get query() {
+      return url.searchParams;
+    },
     request,
     url,
     basePathname,
@@ -160,6 +183,8 @@ export function createRequestEvent(
 
     next,
 
+    resetRoute,
+
     exit,
 
     cacheControl: (cacheControl: CacheControl, target: CacheControlTarget = 'Cache-Control') => {
@@ -220,6 +245,15 @@ export function createRequestEvent(
       return new RedirectMessage();
     },
 
+    rewrite: (pathname: string) => {
+      check();
+      if (pathname.startsWith('http')) {
+        throw new Error('Rewrite does not support absolute urls');
+      }
+      sharedMap.set(RequestEvIsRewrite, true);
+      return new RewriteMessage(pathname.replace(/\/+/g, '/'));
+    },
+
     defer: (returnData) => {
       return typeof returnData === 'function' ? returnData : () => returnData;
     },
@@ -296,6 +330,19 @@ export interface RequestEventInternal extends RequestEvent, RequestEventLoader {
    * @returns `true`, if `getWritableStream()` has already been called.
    */
   isDirty(): boolean;
+
+  /**
+   * Reset the request event to the given route data.
+   *
+   * @param loadedRoute - The new loaded route.
+   * @param requestHandlers - The new request handlers.
+   * @param url - The new URL of the route.
+   */
+  resetRoute(
+    loadedRoute: LoadedRoute | null,
+    requestHandlers: RequestHandler<any>[],
+    url: URL
+  ): void;
 }
 
 export function getRequestLoaders(requestEv: RequestEventCommon) {