278 status code for redirects from RSC requests

gaojude · gaojude · commit bfbaed874bc4 · 2025-06-10T19:13:46.000-04:00
diff --git a/packages/next/errors.json b/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."
 }
diff --git a/packages/next/src/client/components/router-reducer/fetch-server-response.ts b/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
diff --git a/packages/next/src/server/base-server.ts b/packages/next/src/server/base-server.ts
@@ -3051,7 +3051,9 @@ export default abstract class Server<
               // the previous fallback cache entry. This preserves the previous
               // behavior.
               if (isProduction) {
-                return toResponseCacheEntry(previousFallbackCacheEntry)
+                return toResponseCacheEntry(previousFallbackCacheEntry, {
+                  isRscRequest: isRSCRequest,
+                })
               }
 
               // We pass `undefined` and `null` as it doesn't apply to the pages
diff --git a/packages/next/src/server/config-shared.ts b/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,
diff --git a/packages/next/src/server/lib/router-server.ts b/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,18 @@ export async function initialize(opts: {
         invokedOutputs,
       })
 
+      // If a previous redirect was already intercepted & updated to RSC status code,
+      // e.g., in Middleware, we should short-circuit the request right away.
+      if (config.experimental.validateRSCRequestHeaders) {
+        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 +439,17 @@ 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)
 
+        // handle RSC redirect
+        if (config.experimental.validateRSCRequestHeaders) {
+          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}`)
         }
diff --git a/packages/next/src/server/web/adapter.ts b/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
@@ -96,6 +97,8 @@ function ensureTestApisIntercepted() {
   }
 }
 
+const minimalMode = process.env.NODE_ENV !== 'development'
+
 export async function adapter(
   params: AdapterOptions
 ): Promise<FetchEventResult> {
@@ -196,7 +199,7 @@ export async function adapter(
     ).IncrementalCache({
       appDir: true,
       fetchCache: true,
-      minimalMode: process.env.NODE_ENV !== 'development',
+      minimalMode: minimalMode,
       fetchCacheKeyPrefix: process.env.__NEXT_FETCH_CACHE_KEY_PREFIX,
       dev: process.env.NODE_ENV === 'development',
       requestHeaders: params.request.headers as any,
@@ -430,6 +433,22 @@ export async function adapter(
     }
   }
 
+  // Handles RSC redirects from Middleware.
+  if (minimalMode && process.env.__NEXT_CLIENT_VALIDATE_RSC_REQUEST_HEADERS) {
+    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.
diff --git a/packages/next/src/server/web/types.ts b/packages/next/src/server/web/types.ts
@@ -15,7 +15,10 @@ export interface RequestData {
     basePath?: string
     i18n?: I18NConfig | null
     trailingSlash?: boolean
-    experimental?: Pick<ExperimentalConfig, 'cacheLife' | 'authInterrupts'>
+    experimental?: Pick<
+      ExperimentalConfig,
+      'cacheLife' | 'authInterrupts' | 'validateRSCRequestHeaders'
+    >
   }
   page?: {
     name?: string
diff --git a/packages/next/src/shared/lib/constants.ts b/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
diff --git a/test/e2e/rsc-redirect/app/about/page.tsx b/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>
+}
diff --git a/test/e2e/rsc-redirect/app/layout.tsx b/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>
+  )
+}
diff --git a/test/e2e/rsc-redirect/app/next-config-redirect/page.tsx b/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>
+  )
+}
diff --git a/test/e2e/rsc-redirect/app/old-about/page.tsx b/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>
+  )
+}
diff --git a/test/e2e/rsc-redirect/app/page.tsx b/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>
+  )
+}
diff --git a/test/e2e/rsc-redirect/app/rsc-redirect/page.tsx b/test/e2e/rsc-redirect/app/rsc-redirect/page.tsx
@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation'
+
+export default function Page() {
+  redirect('/about')
+}
diff --git a/test/e2e/rsc-redirect/index.test.ts b/test/e2e/rsc-redirect/index.test.ts
@@ -0,0 +1,47 @@
+import { nextTestSetup } from 'e2e-utils'
+import { retry } from 'next-test-utils'
+
+describe('RSC Redirect', () => {
+  const { next } = nextTestSetup({
+    files: __dirname,
+  })
+
+  it.each([
+    { path: '/next-config-redirect', expectedStatus: 278 },
+    { path: '/old-about', expectedStatus: 278 },
+    { path: '/rsc-redirect', expectedStatus: 200 },
+  ])(
+    '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)
+      // Ensure we don't get standard HTTP redirect status codes
+      expect(statusCodes).not.toContain(307)
+      expect(statusCodes).not.toContain(308)
+    }
+  )
+})
diff --git a/test/e2e/rsc-redirect/middleware.ts b/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()
+}
diff --git a/test/e2e/rsc-redirect/next.config.ts b/test/e2e/rsc-redirect/next.config.ts
@@ -0,0 +1,15 @@
+import type { NextConfig } from 'next'
+
+const config: NextConfig = {
+  async redirects() {
+    return [
+      {
+        source: '/next-config-redirect',
+        destination: '/about',
+        permanent: false,
+      },
+    ]
+  },
+}
+
+export default config

Original file line number	Diff line number	Diff line change
`@@ -698,5 +698,6 @@`
`698`	`698`	`"697": "Next DevTools: Can't render in this environment. This is a bug in Next.js",`
`699`	`699`	`"698": "Next DevTools: App Dev Overlay is already mounted. This is a bug in Next.js",`
`700`	`700`	`"699": "Next DevTools: Pages Dev Overlay is already mounted. This is a bug in Next.js",`
`701`		`- "700": "Failed to persist Chrome DevTools workspace UUID. The Chrome DevTools Workspace needs to be reconnected after the next page reload."`
	`701`	`+ "700": "Failed to persist Chrome DevTools workspace UUID. The Chrome DevTools Workspace needs to be reconnected after the next page reload.",`
	`702`	`+ "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."`
`702`	`703`	`}`