Unverified Commit 8980f3a7 authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

Fix: Improved rewrite detection during optimistic routing (#93619)

When optimistic routing is enabled, the client uses responses it
receives from the server (during a navigation or a prefetch) to resolve
the routes of structurally similar URLs.

However, if the server rewrites a URL to a different path than the one
requested by the client, then we disable optimistic routing for that
pattern.

We detect a rewrite by comparing the route tree returned from the server
to the requested URL. If the route tree does not match, according to the
Next.js routing algorithm, then the route must have been rewritten; we
do not write this pattern into the client's route table.

The basic mechanism for this was already implemented, but there were
some cases we weren't handling correctly:

- A static or non-optional dynamic segment is reached with no URL part
to consume.
- A page leaf is reached with URL parts still pending.
- A dynamic segment whose URL part matches one of its known static
siblings (which would have taken precedence under normal routing).

These cases have been fixed. Regression tests live in
`optimistic-routing-rewrite-detection-regression/` and
`optimistic-routing-parallel-slot-catchall-regression/`.

---

Replaces #93578 (re-opened from an `origin` branch to satisfy CI
requirements).
parent c2062dc6
import { connection } from 'next/server'
import { LinkAccordion } from '../../../components/link-accordion'
export default async function ActualPage({
params,
......@@ -12,6 +13,7 @@ export default async function ActualPage({
<div id="actual-page">
<h1>Actual page</h1>
<p data-slug={slug}>Slug: {slug}</p>
<LinkAccordion href="/hub">Hub</LinkAccordion>
</div>
)
}
import { Suspense } from 'react'
import { connection } from 'next/server'
import { LinkAccordion } from '../../components/link-accordion'
async function HubContent() {
await connection()
return <div id="hub-content">Hub</div>
}
// Hub page used by rewrite-detection tests as a navigation target instead of
// `browser.back()`. Each visit lands on a fresh page where all accordions
// start closed, so previously-revealed Links can't be re-mounted by BFCache
// and trigger uncontrolled prefetches outside any `act` scope.
export default function HubPage() {
return (
<div>
<Suspense fallback="Loading hub...">
<HubContent />
</Suspense>
<ul>
<li>
<LinkAccordion href="/rewritten/second" prefetch={false}>
Rewritten Second
</LinkAccordion>
</li>
<li>
<LinkAccordion href="/search-rewrite?v=beta" prefetch={false}>
Search Rewrite Beta (v=beta → content=beta)
</LinkAccordion>
</li>
</ul>
</div>
)
}
import { LinkAccordion } from '../../components/link-accordion'
// Fully static page - no dynamic data access
export default function RewriteAlphaPage() {
return (
......@@ -6,6 +8,7 @@ export default function RewriteAlphaPage() {
<p id="rewrite-content" data-content="alpha">
Content: alpha
</p>
<LinkAccordion href="/hub">Hub</LinkAccordion>
</div>
)
}
import { LinkAccordion } from '../../components/link-accordion'
// Fully static page - no dynamic data access
export default function RewriteBetaPage() {
return (
......@@ -6,6 +8,7 @@ export default function RewriteBetaPage() {
<p id="rewrite-content" data-content="beta">
Content: beta
</p>
<LinkAccordion href="/hub">Hub</LinkAccordion>
</div>
)
}
......@@ -346,14 +346,26 @@ describe('optimistic-routing', () => {
// Wait for navigation to complete
await browser.elementById('actual-page')
// Step 2: Navigate back to home using browser back button
await browser.back()
await browser.elementById('rendered-route-history')
// Step 3: Navigate to /rewritten/second.
// This link has prefetch={false}. Even though we've "learned" the route
// from step 1, the route should be marked as having a dynamic rewrite,
// so we should NOT use the cached pattern.
// Step 2: Navigate forward to /hub. We use a hub page rather than
// browser.back() so that the previously-revealed /rewritten/first
// accordion can't be re-mounted from BFCache and trigger an
// uncontrolled prefetch outside any `act` scope. See
// .claude/skills/router-act/SKILL.md.
await act(async () => {
const revealHub = await browser.elementByCss(
'input[data-link-accordion="/hub"]'
)
await revealHub.click()
const linkHub = await browser.elementByCss('a[href="/hub"]')
await linkHub.click()
})
await browser.elementById('hub-content')
// Step 3: From /hub, reveal /rewritten/second. This link has
// prefetch={false}. Even though /rewritten/first was visited in
// step 1, that response was marked as a dynamic rewrite, so the
// router must not reuse it as a prediction for /rewritten/second —
// meaning no prefetch should fire on reveal.
await act(async () => {
const revealSecond = await browser.elementByCss(
'input[data-link-accordion="/rewritten/second"]'
......@@ -370,13 +382,12 @@ describe('optimistic-routing', () => {
await browser.elementById('actual-page')
// Verify using rendered route history that no wrong params were rendered.
// If route prediction incorrectly used a cached pattern, we'd see "first"
// briefly flash before "second".
// If the router had reused step 1's response as a prediction, we'd see
// "first" briefly flash before "second".
expect(await getRenderedRouteHistory(browser)).toEqual([
{ url: '/', params: {} },
{ url: '/rewritten/first', params: { slug: 'first' } },
// Back to home
{ url: '/', params: {} },
{ url: '/hub', params: {} },
// Should go directly to "second" with no intermediate wrong params
{ url: '/rewritten/second', params: { slug: 'second' } },
])
......@@ -408,14 +419,23 @@ describe('optimistic-routing', () => {
const contentAlpha = await browser.elementById('rewrite-content')
expect(await contentAlpha.getAttribute('data-content')).toBe('alpha')
// Step 2: Go back to home
await browser.back()
await browser.elementById('rendered-route-history')
// Step 2: Navigate forward to /hub instead of using browser.back() to
// avoid BFCache restoring previously-opened accordions and triggering
// uncontrolled prefetches. See .claude/skills/router-act/SKILL.md.
await act(async () => {
const revealHub = await browser.elementByCss(
'input[data-link-accordion="/hub"]'
)
await revealHub.click()
const linkHub = await browser.elementByCss('a[href="/hub"]')
await linkHub.click()
})
await browser.elementById('hub-content')
// Step 3: Navigate to /search-rewrite?v=beta.
// This link has prefetch={false} - if the route was incorrectly cached as
// predictable, we'd see "alpha" instead of "beta" because the static page
// would be served from cache.
// Step 3: From /hub, reveal /search-rewrite?v=beta.
// This link has prefetch={false} - if the router had reused step 1's
// response as a prediction, we'd see "alpha" instead of "beta" because
// the static page would be served from cache.
await act(async () => {
const revealBeta = await browser.elementByCss(
'input[data-link-accordion="/search-rewrite?v=beta"]'
......@@ -430,8 +450,9 @@ describe('optimistic-routing', () => {
await linkBeta.click()
})
// Verify we see "beta", not "alpha"
// If this shows "alpha", the route was incorrectly using a cached pattern.
// Verify we see "beta", not "alpha".
// If this shows "alpha", the router incorrectly reused step 1's
// response as a prediction for /search-rewrite?v=beta.
const contentBeta = await browser.elementById('rewrite-content')
expect(await contentBeta.getAttribute('data-content')).toBe('beta')
})
......
import { Suspense } from 'react'
import { connection } from 'next/server'
async function DynamicProject() {
await connection()
return <h1>PROJECT PAGE</h1>
}
export default function ProjectPage() {
return (
<main>
<Suspense fallback={<div id="project-loading">Loading project...</div>}>
<DynamicProject />
</Suspense>
</main>
)
}
import { ReactNode } from 'react'
export default function TeamLayout({
children,
actions,
}: {
children: ReactNode
actions: ReactNode
}) {
return (
<>
<div>{children}</div>
<div>{actions}</div>
</>
)
}
import { Suspense } from 'react'
import { connection } from 'next/server'
import { LinkAccordion } from '../../../components/link-accordion'
async function DynamicOverview({
params,
}: {
params: Promise<{ teamSlug: string }>
}) {
await connection()
const { teamSlug } = await params
return (
<>
<h1>TEAM OVERVIEW</h1>
<ul>
<li>
<LinkAccordion href={`/${teamSlug}/myproject`}>Project</LinkAccordion>
</li>
</ul>
</>
)
}
export default function OverviewPage({
params,
}: {
params: Promise<{ teamSlug: string }>
}) {
return (
<main>
<Suspense fallback={<div id="overview-loading">Loading overview...</div>}>
<DynamicOverview params={params} />
</Suspense>
</main>
)
}
import { ReactNode } from 'react'
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
import { LinkAccordion } from '../components/link-accordion'
export default function Home() {
return (
<main>
<h1>HOME</h1>
<ul>
<li>
<LinkAccordion href="/myteam">Team</LinkAccordion>
</li>
</ul>
</main>
)
}
'use client'
import Link, { type LinkProps } from 'next/link'
import { useState } from 'react'
export function LinkAccordion({
href,
children,
prefetch,
}: {
href: LinkProps['href']
children: React.ReactNode
prefetch?: LinkProps['prefetch']
}) {
const [isVisible, setIsVisible] = useState(false)
return (
<>
<input
type="checkbox"
checked={isVisible}
onChange={() => setIsVisible(!isVisible)}
data-link-accordion={href}
/>
{isVisible ? (
<Link href={href} prefetch={prefetch}>
{children}
</Link>
) : (
`${children} (link is hidden)`
)}
</>
)
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
cacheComponents: true,
experimental: {
optimisticRouting: true,
},
// The bug being regressed requires the response for /[teamSlug] to
// exercise its `@actions/[...catchAll]` parallel slot even though the
// canonical URL has no parts left to feed the catch-all. The simplest
// reproducer is a rewrite that maps the single-segment URL into a
// longer destination: the response describes a route shape that
// includes the catch-all slot, but the canonical URL is short enough
// that no parts reach the catch-all under normal routing.
async rewrites() {
return [
{
source: '/:teamSlug',
destination: '/:teamSlug/overview',
},
]
},
}
module.exports = nextConfig
import { nextTestSetup } from 'e2e-utils'
import { createRouterAct } from 'router-act'
describe('optimistic routing - parallel slot catch-all regression', () => {
const { next, isNextDev } = nextTestSetup({
files: __dirname,
})
if (isNextDev) {
// Optimistic routing is a production-build feature; in dev mode the
// router does not have complete information about which routes
// exist, so prediction is disabled.
test('skipped in dev mode', () => {})
return
}
// Regression test: a route with a parallel slot whose route is a
// required catch-all (e.g., /[teamSlug] with an
// `@actions/[...catchAll]` slot) used to poison route prediction.
// After visiting /myteam, navigating to a longer sibling URL like
// /myteam/myproject would reuse a prediction derived from the
// @actions slot's catch-all, resolving the URL to the team-page
// content even though /myteam/myproject is a separate route. The
// router skipped the server fetch entirely under the (incorrect)
// assumption that the URL was already known.
//
// Detection: visit /myteam (which would teach the bad prediction).
// Then click /myteam/myproject and wait for a response containing
// "PROJECT PAGE". With the bug, no server fetch happens, so "PROJECT
// PAGE" never arrives and the `act` waiter rejects. With the fix, no
// prediction matches /myteam/myproject and a real server fetch
// delivers the project page.
it('does not match a parallel-slot catch-all for an unrelated sibling URL', async () => {
let act: ReturnType<typeof createRouterAct>
const browser = await next.browser('/', {
beforePageLoad(page) {
act = createRouterAct(page)
},
})
// Reveal + click /myteam (a /[teamSlug] route). Its layout
// includes an `@actions/[...catchAll]` parallel slot. Visiting
// /myteam would, under the bug, teach the router a prediction
// that wrongly matches longer sibling URLs.
await act(
async () => {
const toggle = await browser.elementByCss(
'input[data-link-accordion="/myteam"]'
)
await toggle.click()
const link = await browser.elementByCss('a[href="/myteam"]')
await link.click()
},
{ includes: 'TEAM OVERVIEW' }
)
expect(await browser.elementByCss('h1').text()).toBe('TEAM OVERVIEW')
// Reveal + click /myteam/myproject — a sibling URL whose data is
// not already cached. Without the fix, the router uses the
// incorrect prediction taught by the previous step and skips the
// server fetch; "PROJECT PAGE" never arrives and `act` rejects.
// With the fix, no prediction matches /myteam/myproject and a
// real server fetch delivers the project page.
await act(
async () => {
const toggle = await browser.elementByCss(
'input[data-link-accordion="/myteam/myproject"]'
)
await toggle.click()
const link = await browser.elementByCss('a[href="/myteam/myproject"]')
await link.click()
},
{ includes: 'PROJECT PAGE' }
)
expect(await browser.elementByCss('h1').text()).toBe('PROJECT PAGE')
})
})
import { Suspense } from 'react'
import { connection } from 'next/server'
async function DynamicOverview({
params,
}: {
params: Promise<{ teamSlug: string }>
}) {
await connection()
const { teamSlug } = await params
return (
<h1 id="overview-page" data-slug={teamSlug}>
Overview: {teamSlug}
</h1>
)
}
// Static visible deeper segment. Used by the static-visible-null test:
// the rewrite /team-shorter → /team-shorter/overview produces a response
// that walks through this segment with no URL part to feed it.
export default function OverviewPage({
params,
}: {
params: Promise<{ teamSlug: string }>
}) {
return (
<main>
<Suspense fallback={<div id="team-loading">Loading team...</div>}>
<DynamicOverview params={params} />
</Suspense>
</main>
)
}
import { Suspense } from 'react'
import { connection } from 'next/server'
async function DynamicTeam({
params,
}: {
params: Promise<{ teamSlug: string }>
}) {
await connection()
const { teamSlug } = await params
return (
<h1 id="team-page" data-slug={teamSlug}>
Team: {teamSlug}
</h1>
)
}
export default function TeamPage({
params,
}: {
params: Promise<{ teamSlug: string }>
}) {
return (
<main>
<Suspense fallback={<div id="team-loading">Loading team...</div>}>
<DynamicTeam params={params} />
</Suspense>
</main>
)
}
// The real /featured static page. At runtime the `beforeFiles` rewrite
// hijacks /featured requests and sends them through /[teamSlug], so this
// page is never actually served — but its presence on the filesystem
// matters: it makes /featured a static sibling of /[teamSlug], which is
// what makes the rewrite case observable to the router (a request for
// /featured could not have arrived at /[teamSlug] under normal routing).
export default function FeaturedPage() {
return (
<main>
<h1 id="featured-page">FEATURED</h1>
</main>
)
}
import { ReactNode } from 'react'
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
import { LinkAccordion } from '../components/link-accordion'
export default function Home() {
return (
<main>
<h1>HOME</h1>
<ul>
{/* The four prefetch URLs below each arrive via a rewrite that
produces a route shape the URL would not naturally route to.
Each test reveals one of them (default prefetch=true) to
populate the router's prediction state, then clicks one of
the click-targets below to check that no incorrect prediction
was learned. */}
<li>
<LinkAccordion href="/myteam/garbage">Tree-shorter</LinkAccordion>
</li>
<li>
<LinkAccordion href="/featured">Static-sibling</LinkAccordion>
</li>
<li>
<LinkAccordion href="/team-shorter">
Static-visible-null
</LinkAccordion>
</li>
{/* Click target — prefetch={false} so revealing it fires no
request. Inside an act scope, the test clicks this and
asserts that no /[teamSlug] loading boundary appears
instantly (which would only happen if the router had a
cached prediction for it). */}
<li>
<LinkAccordion href="/yourteam" prefetch={false}>
Your team
</LinkAccordion>
</li>
</ul>
</main>
)
}
'use client'
import Link, { type LinkProps } from 'next/link'
import { useState } from 'react'
export function LinkAccordion({
href,
children,
prefetch,
}: {
href: LinkProps['href']
children: React.ReactNode
prefetch?: LinkProps['prefetch']
}) {
const [isVisible, setIsVisible] = useState(false)
return (
<>
<input
type="checkbox"
checked={isVisible}
onChange={() => setIsVisible(!isVisible)}
data-link-accordion={href}
/>
{isVisible ? (
<Link href={href} prefetch={prefetch}>
{children}
</Link>
) : (
`${children} (link is hidden)`
)}
</>
)
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
cacheComponents: true,
experimental: {
optimisticRouting: true,
varyParams: true,
},
// Each rewrite below crafts one of the rewrite-affected response shapes
// we want to verify. They live in `beforeFiles` so they take precedence
// over the filesystem dynamic route — otherwise a 1-part URL like
// /featured would route directly to the filesystem (matched by the
// dynamic /[teamSlug]) without going through the rewrite, and we'd
// never observe the rewrite-affected response shape under test.
async rewrites() {
return {
beforeFiles: [
// Case "static-sibling": URL matches a known static sibling, but
// the rewrite sends it through the dynamic /[teamSlug] route.
{ source: '/featured', destination: '/some-team' },
// Case "static-visible-null": URL is shorter than the response,
// and the deeper segment is a visible static segment.
{ source: '/team-shorter', destination: '/team-shorter/overview' },
// Case "tree-shorter-than-url": URL is longer than the response.
{ source: '/:teamSlug/garbage', destination: '/:teamSlug' },
],
}
},
}
module.exports = nextConfig
import { nextTestSetup } from 'e2e-utils'
import { createRouterAct } from 'router-act'
describe('optimistic routing - rewrite detection regression', () => {
const { next, isNextDev } = nextTestSetup({
files: __dirname,
})
if (isNextDev) {
// Optimistic routing is a production-build feature; in dev mode the
// router does not have complete information about which routes
// exist, so prediction is disabled.
test('skipped in dev mode', () => {})
return
}
// The shape of every test below is the same:
//
// 1. Reveal a "prefetch" link whose URL arrives via a rewrite. The
// response describes a route shape the URL would not naturally
// route to. The router must not learn from this response as a
// prediction template — otherwise future navigations to other
// URLs of the same dynamic shape would receive an incorrect
// "free" prediction and could render a stale loading state
// instantly.
// 2. Reveal one of the click-target links (prefetch={false}).
// 3. Click it inside an act scope. With the bug, the router uses the
// rewrite-affected response as a prediction and the cached
// /[teamSlug] loading boundary appears synchronously. With the
// fix, no prediction is available and the loading boundary only
// appears once the server responds.
async function setupBrowser() {
let act: ReturnType<typeof createRouterAct>
const browser = await next.browser('/', {
beforePageLoad(page) {
act = createRouterAct(page)
},
})
return { browser, act: act! }
}
async function revealPrefetch(
browser: Awaited<ReturnType<typeof next.browser>>,
act: ReturnType<typeof createRouterAct>,
href: string
) {
await act(
async () => {
const toggle = await browser.elementByCss(
`input[data-link-accordion="${href}"]`
)
await toggle.click()
},
// Wait for the prefetch to complete by matching the loading
// boundary text in the response.
{ includes: 'Loading team' }
)
}
async function revealAndClick(
browser: Awaited<ReturnType<typeof next.browser>>,
act: ReturnType<typeof createRouterAct>,
href: string
) {
await act(async () => {
const toggle = await browser.elementByCss(
`input[data-link-accordion="${href}"]`
)
await toggle.click()
}, 'no-requests')
const link = await browser.elementByCss(`a[href="${href}"]`)
await act(async () => {
await link.click()
const teamLoading = await browser
.elementById('team-loading')
.catch(() => null)
expect(teamLoading).toBeNull()
})
}
it('does not predict from a rewrite that shortens the URL', async () => {
// The rewrite /myteam/garbage → /myteam produces a response whose
// route shape is one part shorter than the canonical URL.
const { browser, act } = await setupBrowser()
await revealPrefetch(browser, act, '/myteam/garbage')
await revealAndClick(browser, act, '/yourteam')
expect(
await (await browser.elementById('team-page')).getAttribute('data-slug')
).toBe('yourteam')
})
it('does not predict from a rewrite to a static-sibling URL', async () => {
// The rewrite /featured → /some-team produces a response that
// resolves through /[teamSlug] for a URL that, under normal
// routing, would have matched the static /featured page (a known
// sibling of /[teamSlug]).
const { browser, act } = await setupBrowser()
await revealPrefetch(browser, act, '/featured')
await revealAndClick(browser, act, '/yourteam')
expect(
await (await browser.elementById('team-page')).getAttribute('data-slug')
).toBe('yourteam')
})
it('does not predict when the rewrite hides a deeper static segment', async () => {
// The rewrite /team-shorter → /team-shorter/overview produces a
// response whose deeper visible-static segment (`overview`) has no
// URL part to match against under the canonical URL `/team-shorter`.
const { browser, act } = await setupBrowser()
await revealPrefetch(browser, act, '/team-shorter')
await revealAndClick(browser, act, '/yourteam')
expect(
await (await browser.elementById('team-page')).getAttribute('data-slug')
).toBe('yourteam')
})
// Note: a fourth case where the deeper segment is a regular dynamic
// (e.g. /team-dyn → /team-dyn/proj-1, response for /[teamSlug]/[project])
// does not have a regression test here. The pattern would land at the
// [project] trie node, which is only reachable via a 2-part click URL,
// and the cached page shell at that depth is rendered for the click
// regardless of whether the prediction was stored — so the loading
// boundary visible / not visible signal does not distinguish with-fix
// from without-fix at the UI level. The bailout for this case is still
// covered defensively by the same `paramType !== 'oc' && urlPart === null`
// check as case 2.
})
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment