wip

Author: gaojude

packages/next/errors.json

@@ -698,5 +698,6 @@
   "697": "Next DevTools: Can't render in this environment. This is a bug in Next.js",
   "698": "Next DevTools: App Dev Overlay is already mounted. This is a bug in Next.js",
   "699": "Next DevTools: Pages Dev Overlay is already mounted. This is a bug in Next.js",
-  "700": "Failed to persist Chrome DevTools workspace UUID. The Chrome DevTools Workspace needs to be reconnected after the next page reload."
+  "700": "Failed to persist Chrome DevTools workspace UUID. The Chrome DevTools Workspace needs to be reconnected after the next page reload.",
+  "701": "Next.js RSC redirect protocol error: Missing Location header. This may indicate either a Next.js bug or that a third-party proxy is not correctly implementing the RSC redirect protocol."
 }

packages/next/src/client/components/router-reducer/fetch-server-response.ts

@@ -28,6 +28,7 @@ import {
   NEXT_DID_POSTPONE_HEADER,
   NEXT_ROUTER_STALE_TIME_HEADER,
 } from '../app-router-headers'
+import { RSC_REDIRECT_STATUS_CODE } from '../../../shared/lib/constants'
 import { callServer } from '../../app-call-server'
 import { findSourceMapURL } from '../../app-find-source-map-url'
 import { PrefetchKind } from './router-reducer-types'
@@ -328,9 +329,6 @@ export async function createFetch(
   // again, but this time we'll append the cache busting search param to prevent
   // a mismatch.
   //
-  // TODO: We can optimize Next.js's built-in middleware APIs by returning a
-  // custom status code, to prevent the browser from automatically following it.
-  //
   // This does not affect Server Action-based redirects; those are encoded
   // differently, as part of the Flight body. It only affects redirects that
   // occur in a middleware or a third-party proxy.
@@ -340,6 +338,25 @@ export async function createFetch(
     // This is to prevent a redirect loop. Same limit used by Chrome.
     const MAX_REDIRECTS = 20
     for (let n = 0; n < MAX_REDIRECTS; n++) {
+      // This is a custom status code used to handle RSC redirects.
+      // We use a custom status code to prevent the browser from automatically
+      // following the redirect, which would require an additional round trip.
+      // Instead, we can handle it on the client and immediately send a new RSC
+      // request to the new location.
+      if (browserResponse.status === RSC_REDIRECT_STATUS_CODE) {
+        const location = browserResponse.headers.get('Location')
+        if (!location) {
+          throw new Error(
+            'Next.js RSC redirect protocol error: Missing Location header. This may indicate either a Next.js bug or that a third-party proxy is not correctly implementing the RSC redirect protocol.'
+          )
+        }
+        fetchUrl = new URL(location, fetchUrl)
+        setCacheBustingSearchParam(fetchUrl, headers)
+        browserResponse = await fetch(fetchUrl, fetchOptions)
+        redirected = true
+        continue
+      }
+
       if (!browserResponse.redirected) {
         // The server did not perform a redirect.
         break

packages/next/src/client/components/router-reducer/set-cache-busting-search-param.ts

@@ -57,7 +57,13 @@ export const setCacheBustingSearchParam = (
   const rawQuery = existingSearch.startsWith('?')
     ? existingSearch.slice(1)
     : existingSearch
-  const pairs = rawQuery.split('&').filter(Boolean)
+
+  // Always remove any existing cache busting param and add a fresh one to ensure
+  // we have the correct value based on current request headers
+  const pairs = rawQuery
+    .split('&')
+    .filter(Boolean)
+    .filter((pair) => !pair.startsWith(`${NEXT_RSC_UNION_QUERY}=`))
   pairs.push(`${NEXT_RSC_UNION_QUERY}=${uniqueCacheKey}`)
   url.search = pairs.length ? `?${pairs.join('&')}` : ''
 }

packages/next/src/server/base-server.ts

@@ -68,6 +68,7 @@ import {
   APP_PATHS_MANIFEST,
   NEXT_BUILTIN_DOCUMENT,
   PAGES_MANIFEST,
+  RSC_REDIRECT_STATUS_CODE,
   STATIC_STATUS_PAGES,
   UNDERSCORE_NOT_FOUND_ROUTE,
   UNDERSCORE_NOT_FOUND_ROUTE_ENTRY,
@@ -3202,6 +3203,18 @@ export default abstract class Server<
       return null
     }
 
+    // TODO: add comment + gate by config.
+    // deals with `next start` redirect on static RSC pages.
+    // TODO: test that it's fine to return 200 here because that's what
+    //
+    if (
+      isRSCRequest &&
+      cacheEntry.value?.kind === CachedRouteKind.APP_PAGE &&
+      (cacheEntry.value.status === 307 || cacheEntry.value.status === 308)
+    ) {
+      cacheEntry.value.status = RSC_REDIRECT_STATUS_CODE
+    }
+
     const didPostpone =
       cacheEntry.value?.kind === CachedRouteKind.APP_PAGE &&
       typeof cacheEntry.value.postponed === 'string'

packages/next/src/server/config-shared.ts

@@ -1374,7 +1374,9 @@ export const defaultConfig = {
     viewTransition: false,
     routerBFCache: false,
     removeUncaughtErrorAndRejectionListeners: false,
-    validateRSCRequestHeaders: false,
+    validateRSCRequestHeaders:
+      // TODO: remove once we've confirmed this mode is stable
+      !!process.env.__NEXT_TEST_MODE,
     staleTimes: {
       dynamic: 0,
       static: 300,

packages/next/src/server/lib/router-server.ts

@@ -32,6 +32,7 @@ import {
   PHASE_PRODUCTION_SERVER,
   PHASE_DEVELOPMENT_SERVER,
   UNDERSCORE_NOT_FOUND_ROUTE,
+  RSC_REDIRECT_STATUS_CODE,
 } from '../../shared/lib/constants'
 import { RedirectStatusCode } from '../../client/components/redirect-status-code'
 import { DevBundlerService } from './dev-bundler-service'
@@ -59,6 +60,7 @@ import {
   handleChromeDevtoolsWorkspaceRequest,
   isChromeDevtoolsWorkspaceUrl,
 } from './chrome-devtools-workspace'
+import { RSC_HEADER } from '../../client/components/app-router-headers'
 
 const debug = setupDebug('next:router-server:main')
 const isNextFont = (pathname: string | null) =>
@@ -375,6 +377,16 @@ export async function initialize(opts: {
         invokedOutputs,
       })
 
+      // If it was somehow already intercepted, we should stop right away.
+      // TODO: comment + gate (maybe not needed)
+      if (statusCode === RSC_REDIRECT_STATUS_CODE) {
+        res.statusCode = RSC_REDIRECT_STATUS_CODE
+        const destination = url.format(parsedUrl)
+        res.setHeader('Location', destination)
+        res.end()
+        return
+      }
+
       if (res.closed || res.finished) {
         return
       }
@@ -425,9 +437,15 @@ export async function initialize(opts: {
       // handle redirect
       if (!bodyStream && statusCode && statusCode > 300 && statusCode < 400) {
         const destination = url.format(parsedUrl)
-        res.statusCode = statusCode
         res.setHeader('location', destination)
 
+        // TODO: comment + gate
+        if (req.headers[RSC_HEADER.toLowerCase()] === '1') {
+          res.statusCode = RSC_REDIRECT_STATUS_CODE
+          return res.end(destination)
+        }
+
+        res.statusCode = statusCode
         if (statusCode === RedirectStatusCode.PermanentRedirect) {
           res.setHeader('Refresh', `0;url=${destination}`)
         }

packages/next/src/server/web/adapter.ts

@@ -34,6 +34,7 @@ import { CloseController } from './web-on-close'
 import { getEdgePreviewProps } from './get-edge-preview-props'
 import { getBuiltinRequestContext } from '../after/builtin-request-context'
 import { getImplicitTags } from '../lib/implicit-tags'
+import { RSC_REDIRECT_STATUS_CODE } from '../../shared/lib/constants'
 
 export class NextRequestHint extends NextRequest {
   sourcePage: string
@@ -430,6 +431,20 @@ export async function adapter(
     }
   }
 
+  // TODO: comment + gate + gate by minimal mode!
+  if (
+    isRSCRequest &&
+    response &&
+    response.status >= 300 &&
+    response.status < 400
+  ) {
+    response = new Response(null, {
+      ...response,
+      status: RSC_REDIRECT_STATUS_CODE,
+      headers: response.headers,
+    })
+  }
+
   const finalResponse = response ? response : NextResponse.next()
 
   // Flight headers are not overridable / removable so they are applied at the end.

packages/next/src/shared/lib/constants.ts

@@ -149,3 +149,32 @@ export const SYSTEM_ENTRYPOINTS = new Set<string>([
   CLIENT_STATIC_FILES_RUNTIME_AMP,
   CLIENT_STATIC_FILES_RUNTIME_MAIN_APP,
 ])
+
+/**
+ * Custom HTTP status code used to signal a redirect for React Server Component (RSC)
+ * requests that should be handled by the client-side RSC router, rather than
+ * being automatically followed by the browser like standard 307/308 redirects.
+ *
+ * Purpose:
+ * - To bypass the browser's default redirect behavior, which typically forwards
+ * original request headers and might not be ideal for RSC's stateful navigation.
+ * - To empower the client-side RSC router to intercept this signal and initiate
+ * a new, clean fetch or navigation to the target URL specified in the 'Location' header.
+ * This allows for better control over the request lifecycle for the redirected route.
+ *
+ * How it's used:
+ * - Server-side: When an RSC route intends to perform a redirect (originally as a
+ * 307 or 308), the status code is transformed into this custom value.
+ * The response must also include a 'Location' header with the redirect target URL.
+ * - Client-side: The RSC router is programmed to recognize this specific status code.
+ * Upon detection, it extracts the target URL from the 'Location' header and
+ * handles the navigation programmatically.
+ *
+ * Choice of Value (e.g., 278):
+ * - The specific value (like 278) is chosen from the 2xx range (indicating success)
+ * but is not a standard HTTP status code with predefined browser actions for redirection.
+ * This ensures browsers won't automatically follow it, while still signaling a
+ * successful server determination that requires client action. It should be an
+ * officially unassigned status code to minimize conflicts.
+ */
+export const RSC_REDIRECT_STATUS_CODE = 278

test/e2e/rsc-redirect/app/about/page.tsx

@@ -0,0 +1,5 @@
+import React from 'react'
+
+export default function Page() {
+  return <div data-testid="about-page">About</div>
+}

test/e2e/rsc-redirect/app/layout.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react'
+import React from 'react'
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}

test/e2e/rsc-redirect/app/next-config-redirect/page.tsx

@@ -0,0 +1,8 @@
+export default function Page() {
+  return (
+    <div>
+      Next Config Redirect. This should redirect to /about by specifying a
+      redirect object in next.config.ts
+    </div>
+  )
+}

test/e2e/rsc-redirect/app/old-about/page.tsx

@@ -0,0 +1,8 @@
+export default function OldAbout() {
+  return (
+    <div>
+      Old About - you should not see this page because middleware should
+      redirect you to /about
+    </div>
+  )
+}

test/e2e/rsc-redirect/app/page.tsx

@@ -0,0 +1,29 @@
+import Link from 'next/link'
+import React from 'react'
+
+export default function Page() {
+  return (
+    <div>
+      <div>
+        <Link href="/next-config-redirect" prefetch={false}>
+          Go to Next Config Redirect Page
+        </Link>
+      </div>
+      <div>
+        <Link href="/rsc-redirect" prefetch={false}>
+          Go to RSC redirect page
+        </Link>
+      </div>
+      <div>
+        <Link href="/about" prefetch={false}>
+          Go to About Page
+        </Link>
+      </div>
+      <div>
+        <Link href="/old-about" prefetch={false}>
+          Go to (Old) About Page
+        </Link>
+      </div>
+    </div>
+  )
+}

test/e2e/rsc-redirect/app/rsc-redirect/page.tsx

@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation'
+
+export default function Page() {
+  redirect('/about')
+}

test/e2e/rsc-redirect/index.test.ts

@@ -0,0 +1,44 @@
+import { nextTestSetup } from 'e2e-utils'
+import { retry } from 'next-test-utils'
+
+describe('RSC Redirect', () => {
+  const { next, isNextDev } = nextTestSetup({
+    files: __dirname,
+  })
+
+  it.each([
+    { path: '/next-config-redirect', expectedStatus: 278 },
+    { path: '/old-about', expectedStatus: 278 },
+    { path: '/rsc-redirect', expectedStatus: isNextDev ? 200 : 278 },
+  ])(
+    'should handle $path redirect with correct status code',
+    async ({ path, expectedStatus }) => {
+      const statusCodes: number[] = []
+      const browser = await next.browser('/', {
+        beforePageLoad(page) {
+          page.on('response', (res) => {
+            statusCodes.push(res.status())
+          })
+        },
+      })
+
+      // Click the link
+      await browser.elementByCss(`a[href="${path}"]`).click()
+      await browser.waitForIdleNetwork()
+      // First check the URL to ensure we were redirected
+      await retry(async () => {
+        expect(await browser.url()).toBe(`${next.url}/about`)
+      })
+
+      // Then check the content to ensure the page loaded correctly
+      await browser.waitForElementByCss('[data-testid="about-page"]')
+      const content = await browser
+        .elementByCss('[data-testid="about-page"]')
+        .text()
+      expect(content).toBe('About')
+
+      // Finally check that the expected status code exists in the responses
+      expect(statusCodes).toContain(expectedStatus)
+    }
+  )
+})

test/e2e/rsc-redirect/middleware.ts

@@ -0,0 +1,11 @@
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  if (request.nextUrl.pathname === '/old-about') {
+    const url = request.nextUrl.clone()
+    url.pathname = '/about'
+    return NextResponse.redirect(url)
+  }
+  return NextResponse.next()
+}

test/e2e/rsc-redirect/next.config.ts

@@ -0,0 +1,20 @@
+import type { NextConfig } from 'next'
+
+const config: NextConfig = {
+  async redirects() {
+    return [
+      {
+        source: '/next-config-redirect',
+        destination: '/about',
+        permanent: false,
+      },
+    ]
+  },
+
+  experimental: {
+    // TODO: remove it to test flag auto enabled for all tests
+    validateRSCRequestHeaders: true,
+  },
+}
+
+export default config