Unverified Commit 0556c918 authored by Janka Uryga's avatar Janka Uryga Committed by GitHub

[PPF] Instant validation for `ensureStatic = "shell" | "prefetch"` (#98249)

Adjusts Instant Validation internals to validate the `ShellStatic` stage
instead of `ShellRuntime` when `ensureStatic >= "shell"`. If that's the
case, the client will do a static request (and extract the shell from
it), so the app shell cannot access session data (unlike the PPF
default, where we use a runtime shell).

Note that in some cases, this might seem more restrictive than needed.
For `ensureStatic >= "shell"`, the client will do a static prefetch that
goes up to the `Static` stage which resolves more things, like static
`params`, `prefetch()` ( in the `PrefetchStatic` stage) and
`navigation()` (in the `NavigationStatic` stage). However:
1. The client expects to be able to rewind the static prefetch into a
shell and reuse it across the whole route, so we should be validating
that the shell is actually useful.
2. For `ensureStatic = "shell"`, we might still do a *runtime* prefetch
(with `<Link prefetch={true}>`), which will not have `navigation()`, and
validating `ShellStatic` catches that.

### Implementation notes

- I've renamed `RequestStore.needsAppShell` to
`RequestStore.needsRuntimeShell` (undoing a previous rename), because
the `ShellStatic` stage can _also_ be an App Shell, just not a _runtime_
one. The flag controls whether or not we're delaying link data until the
runtime stages, which we don't need to do if the shell is static.
- If we have `ensureStatic >= "shell"` set, we _won't_ set
`RequestStore.needsRuntimeShell` anymore, which means that the main
render can once again be re-used for both IV and SSV.
`prepareValidationInputsInPartialPrefetching` is changed accordingly.
We'll also set `revealAfterStage` to `StaticShell` to match what the
client would have prefetched.
- We add a new mode in instant validation,
`ValidationPrefetchKind.StaticAppShell`, which checks the prefetch at
the `ShellStatic` stage. This is enabled if we have `ensureStatic >=
"shell"`. the PPF default mode`ValidationPrefetchKind.RuntimeAppShell`
uses `ShellRuntime` instead.





### Tests

- IV should show an insight for unguarded `cookies()` if `ensureStatic
>= "shell"` (unlike the default behavior of app shells)
- IV should *still* show an insight for unguarded static `params`,
`prefetch()`, and `navigation()` regardless of `ensureStatic` (same as
default)
parent 07364140
......@@ -10,7 +10,11 @@ import {
type FullTransportNode,
type TransportSegmentData,
} from '../../../shared/lib/rsc-transport'
import { RenderStage } from '../staged-rendering'
import {
RENDER_STAGE_ADVANCE_ORDER,
RenderStage,
type AdvanceableRenderStage,
} from '../staged-rendering'
import { getServerModuleMap } from '../manifests-singleton'
import { runInSequentialTasks } from '../app-render-render-utils'
import { workAsyncStorage } from '../work-async-storage.external'
......@@ -166,12 +170,7 @@ function stringifySegment(segment: Segment): SegmentPath {
// 2. Separating a stream into segments
//===============================================================
export type SegmentStage =
| RenderStage.Static
| RenderStage.ShellRuntime
| RenderStage.Runtime
| RenderStage.NavigationRuntime
| RenderStage.Dynamic
export type SegmentStage = AdvanceableRenderStage
/** The stages that a prefetched segment can be in. */
export type PrefetchedSegmentStage = Exclude<SegmentStage, RenderStage.Dynamic>
......@@ -206,7 +205,16 @@ export async function collectStagedSegmentData(
let partialStages: SegmentStage[]
switch (prefetchKind) {
case ValidationPrefetchKind.Shell: {
case ValidationPrefetchKind.StaticAppShell: {
partialStages = [
RenderStage.ShellStatic,
RenderStage.PrefetchStatic,
RenderStage.NavigationStatic, // TODO(cache-stages): only if needed
RenderStage.Runtime,
]
break
}
case ValidationPrefetchKind.RuntimeAppShell: {
partialStages = [
RenderStage.ShellRuntime,
RenderStage.Runtime,
......@@ -283,7 +291,10 @@ async function collectSegmentDataForStage(
const currentStage = controller.currentStage
switch (currentStage) {
case RenderStage.Before:
case RenderStage.ShellStatic:
case RenderStage.PrefetchStatic:
case RenderStage.Static:
case RenderStage.NavigationStatic:
return 'Prerender'
case RenderStage.ShellRuntime: // TODO(app-shells) - proper environmentName
case RenderStage.Runtime:
......@@ -794,13 +805,11 @@ function createSegmentCache(): SegmentCache {
}
function createSegmentCacheItem(): SegmentCacheItem {
return {
[RenderStage.Static]: null,
[RenderStage.ShellRuntime]: null,
[RenderStage.Runtime]: null,
[RenderStage.NavigationRuntime]: null,
[RenderStage.Dynamic]: null,
const result: Partial<SegmentCacheItem> = {}
for (const stage of RENDER_STAGE_ADVANCE_ORDER) {
result[stage] = null
}
return result as SegmentCacheItem
}
function createSegmentCacheItemStageEntry(
......@@ -998,10 +1007,10 @@ export type ValidationPayloadResult = {
}
export enum ValidationPrefetchKind {
/** App Shells, for `<Link>` without `prefetch={true}` */
Shell = 1,
// TODO(app-shells): validate speculative prefetches
// Speculative = 2,
/** App Shells, for `<Link>` without `prefetch={true}`, including session data */
RuntimeAppShell = 1,
/** App Shells, for `<Link>` without `prefetch={true}`, only static data */
StaticAppShell = 2,
/** Behavior when Partial Prefetching is not enabled. */
LegacySpeculative = 3,
}
......@@ -1308,7 +1317,11 @@ export async function createCombinedPayloadAtDepth(
let stage: PrefetchedSegmentStage
switch (prefetchKind) {
case ValidationPrefetchKind.Shell: {
case ValidationPrefetchKind.StaticAppShell: {
stage = overrideStageForPartialSegments ?? RenderStage.ShellStatic
break
}
case ValidationPrefetchKind.RuntimeAppShell: {
stage = overrideStageForPartialSegments ?? RenderStage.ShellRuntime
break
}
......@@ -1431,7 +1444,11 @@ export async function createCombinedPayloadAtDepth(
let headStage: PrefetchedSegmentStage
switch (prefetchKind) {
case ValidationPrefetchKind.Shell: {
case ValidationPrefetchKind.StaticAppShell: {
headStage = overrideStageForPartialSegments ?? RenderStage.ShellStatic
break
}
case ValidationPrefetchKind.RuntimeAppShell: {
headStage = overrideStageForPartialSegments ?? RenderStage.ShellRuntime
break
}
......
......@@ -85,16 +85,16 @@ export interface RequestStore extends CommonWorkUnitStore {
* - if `false`, they will follow static semantics
* - if `true`, they will follow runtime semantics
*
* NOTE: Whenever the stage of a promise varies on `needsAppShell`,
* NOTE: Whenever the stage of a promise varies on `needsRuntimeShell`,
* we should also call `trackIncompatibleShellContent` to signal this.
* Otherwise, instant validation or static shell validation might incorrectly
* use a render that resolves it at an inappropriate time.
* */
needsAppShell?: boolean // DEV-only
needsRuntimeShell?: boolean // DEV-only
/**
* DEV-only, mutable.
* Whether any APIs that resolve in different stages in static and
* runtime prerenders (i.e. whose behavior varies on `needsAppShell`)
* runtime prerenders (i.e. whose behavior varies on `needsRuntimeShell`)
* were used during this render.
* */
hasIncompatibleShellContent?: boolean
......
......@@ -562,7 +562,7 @@ const logRuntimeUpgradeableFallback = process.env
/**
* Signals that we cannot recover both a runtime shell and a static (PPR) shell
* from the same render. Use this whenever the stage of a promise varies on
* `RequestStore.needsAppShell`.
* `RequestStore.needsRuntimeShell`.
* */
export function trackIncompatibleShellContent(
workUnitStore: RequestStore,
......
......@@ -99,7 +99,7 @@ export function unstable_prefetch(): Promise<void> {
if (stagedRendering) {
// We can either recover a static shell or a runtime shell, but not both.
trackIncompatibleShellContent(workUnitStore, '`unstable_prefetch()`')
const stage = workUnitStore.needsAppShell
const stage = workUnitStore.needsRuntimeShell
? RENDER_STAGES_BY_DATA_KIND.runtimeLinkData // Match the timing of 'prerender-runtime'.
: RENDER_STAGES_BY_DATA_KIND.staticLinkData // Match the timing of 'prerender'.
......@@ -252,7 +252,7 @@ export function unstable_navigation(): Promise<void> {
if (stagedRendering) {
// We can either recover a static shell or a runtime shell, but not both.
trackIncompatibleShellContent(workUnitStore, '`unstable_navigation()`')
const stage = workUnitStore.needsAppShell
const stage = workUnitStore.needsRuntimeShell
? RenderStage.NavigationRuntime // Match the timing of 'prerender-runtime'.
: RenderStage.NavigationStatic // Match the timing of 'prerender'.
......
......@@ -573,8 +573,8 @@ function createStagedRenderParamsImpl(
// so static params can resolve in the static stage, because session
// shells are handled with a separate render.
// However, in dev we might need to recover a session shell for instant validation.
// This is indicated by `needsAppShell`.
const staticParamsStage = workUnitStore.needsAppShell
// This is indicated by `needsRuntimeShell`.
const staticParamsStage = workUnitStore.needsRuntimeShell
? RENDER_STAGES_BY_DATA_KIND.runtimeLinkData
: RENDER_STAGES_BY_DATA_KIND.staticLinkData
......
......@@ -2788,7 +2788,6 @@ export async function cache(
cacheSignal.endRead()
cacheSignalReadEnded = true
}
let stage: AdvanceableRenderStage
if (!isPrefetchable) {
// An unprefetchable entry is excluded from prerenders, so it
......@@ -2803,7 +2802,7 @@ export async function cache(
workUnitStore,
'"use cache" excluded from app shells due to a short staletime'
)
stage = workUnitStore.needsAppShell
stage = workUnitStore.needsRuntimeShell
? RENDER_STAGES_BY_DATA_KIND.runtimeLinkData
: RENDER_STAGES_BY_DATA_KIND.staticLinkData
}
......@@ -3442,7 +3441,7 @@ export async function cache(
workUnitStore,
'"use cache" excluded from app shells due to a short staletime'
)
stage = workUnitStore.needsAppShell
stage = workUnitStore.needsRuntimeShell
? RENDER_STAGES_BY_DATA_KIND.runtimeLinkData
: RENDER_STAGES_BY_DATA_KIND.staticLinkData
}
......
......@@ -24,6 +24,11 @@ export default function Page() {
/partial-prefetching/session-data
</Link>
</li>
<li>
<Link href="/partial-prefetching/session-data-ensure-static">
/partial-prefetching/session-data-ensure-static
</Link>
</li>
<li>
<Link href="/partial-prefetching/link-data?prefetch=auto">
/partial-prefetching/link-data
......
import { connection } from 'next/server'
import { cookies } from 'next/headers'
import { Suspense } from 'react'
import { setTimeout } from 'timers/promises'
// Note: this is intended for partialPrefetching where
// shells can access session data.
// If the flag is not enabled globally, opt the page in manually to excercise both codepaths.
export const prefetch = process.env.__NEXT_PARTIAL_PREFETCHING
? 'auto'
: 'partial'
export const unstable_ensureStatic = 'shell'
async function SessionData() {
await cookies()
return <p id="session-data">session content</p>
}
async function Dynamic() {
await connection()
await setTimeout(1000)
return <p id="dynamic-data">dynamic content</p>
}
export default function Page() {
return (
<main>
<Suspense fallback={<p id="session-fallback">Loading session...</p>}>
<SessionData />
</Suspense>
<Suspense fallback={<p id="dynamic-fallback">Loading dynamic...</p>}>
<Dynamic />
</Suspense>
</main>
)
}
......@@ -423,44 +423,77 @@ describe('cache-components-dev-streaming', () => {
// TODO(app-shells): for some reason we can't observe the fallback here
// even though all the stream unblocking logic seems to work as intended.
it.failing(
'shows a Suspense fallback for link data on a client navigation (auto prefetch)',
async () => {
const browser = await next.browser('/')
// Record whether each Suspense fallback ever enters the DOM during the
// upcoming navigation.
const fallbackObserver = observeNodeAppearances(browser, [
'session-fallback',
'link-fallback',
'dynamic-fallback',
])
await fallbackObserver.observe()
await browser
.elementByCss(
'a[href="/partial-prefetching/link-data?prefetch=auto"]'
)
.click()
// Wait for the navigation to fully settle.
expect(
await browser.elementByCss('#link-data', { waitUntil: false }).text()
).toBe('link content')
expect(
await browser
.elementByCss('#dynamic-data', { waitUntil: false })
.text()
).toBe('dynamic content')
const appearanceCounts = await fallbackObserver.getResult()
expect(appearanceCounts).toEqual({
'session-fallback': 0,
'link-fallback': 1,
'dynamic-fallback': 1,
})
}
)
// NOTE: Deliberately doesn't use `it.failing` because it's too coarse-grained
// and we want to document existing behavior.
it('[FAILING] shows a Suspense fallback for session data on a client navigation when `ensureStatic = "shell"` is set (auto prefetch)', async () => {
const browser = await next.browser('/')
// Record whether each Suspense fallback ever enters the DOM during the
// upcoming navigation.
const fallbackObserver = observeNodeAppearances(browser, [
'session-fallback',
'dynamic-fallback',
])
await fallbackObserver.observe()
await browser
.elementByCss(
'a[href="/partial-prefetching/session-data-ensure-static"]'
)
.click()
// Wait for the navigation to fully settle.
expect(
await browser.elementByCss('#session-data', { waitUntil: false }).text()
).toBe('session content')
expect(
await browser.elementByCss('#dynamic-data', { waitUntil: false }).text()
).toBe('dynamic content')
const appearanceCounts = await fallbackObserver.getResult()
expect(appearanceCounts).toEqual({
// 'session-fallback': 1, // FAILING: expected behavior, doesn't currently work
'session-fallback': 0,
'dynamic-fallback': 1,
})
})
// TODO(app-shells): for some reason we can't observe the fallback here
// even though all the stream unblocking logic seems to work as intended.
// NOTE: Deliberately doesn't use `it.failing` because it's too coarse-grained
// and we want to document existing behavior.
it('[FAILING] shows a Suspense fallback for link data on a client navigation (auto prefetch)', async () => {
const browser = await next.browser('/')
// Record whether each Suspense fallback ever enters the DOM during the
// upcoming navigation.
const fallbackObserver = observeNodeAppearances(browser, [
'session-fallback',
'link-fallback',
'dynamic-fallback',
])
await fallbackObserver.observe()
await browser
.elementByCss('a[href="/partial-prefetching/link-data?prefetch=auto"]')
.click()
// Wait for the navigation to fully settle.
expect(
await browser.elementByCss('#link-data', { waitUntil: false }).text()
).toBe('link content')
expect(
await browser.elementByCss('#dynamic-data', { waitUntil: false }).text()
).toBe('dynamic content')
const appearanceCounts = await fallbackObserver.getResult()
expect(appearanceCounts).toEqual({
'session-fallback': 0,
// 'link-fallback': 1, // FAILING: expected behavior, doesn't currently work
'link-fallback': 0,
'dynamic-fallback': 1,
})
})
})
})
......
import { unstable_navigation } from 'next/cache'
// NOTE: the page must export the following literally, we can't
// reexport them from here:
//
// export const prefetch = 'partial'
// export const instant: Instant = {
// level: 'experimental-error',
// unstable_samples: [{}],
// }
export default async function Page() {
return (
<main>
<p>
This page has an unguarded <code>navigation()</code> access. This is not
allowed in Partial Prefetching, regardless of{' '}
<code>{`ensureStatic`}</code>, because it blocks the shell.
</p>
<Navigation />
</main>
)
}
async function Navigation() {
await unstable_navigation()
return <div>Navigation data</div>
}
import { unstable_prefetch } from 'next/cache'
// NOTE: the page must export the following literally, we can't
// reexport them from here:
//
// export const prefetch = 'partial'
// export const instant: Instant = {
// level: 'experimental-error',
// unstable_samples: [{}],
// }
export default async function Page() {
return (
<main>
<p>
This page has an unguarded <code>prefetch()</code> access. This is not
allowed in Partial Prefetching, regardless of{' '}
<code>{`ensureStatic`}</code>, because it blocks the shell.
</p>
<Prefetch />
</main>
)
}
async function Prefetch() {
await unstable_prefetch()
return <div>Prefetch data</div>
}
import { cookies } from 'next/headers'
// NOTE: the page must export the following literally, we can't
// reexport them from here:
//
// export const prefetch = 'partial'
// export const instant: Instant = {
// level: 'experimental-error',
// unstable_samples: [{ cookies: [] }],
// }
export default async function Page() {
return (
<main>
<p>
This page has an unguarded session data access. This is not allowed if
<code>{`ensureStatic >= "shell"`}</code>.
</p>
<Cookies />
</main>
)
}
async function Cookies() {
await cookies()
return <div>Cookies data</div>
}
export async function generateStaticParams() {
return [{ slug: '123' }]
}
// NOTE: the page must export the following literally, we can't
// reexport them from here:
//
// export const prefetch = 'partial'
// export const instant: Instant = {
// level: 'experimental-error',
// unstable_samples: [{ params: { slug: '123' } }],
// }
type Params = { slug: string }
export default async function Page({ params }: { params: Promise<Params> }) {
return (
<main>
<p>
This page has an unguarded session data access. This is not allowed in
Partial Prefetching, regardless of <code>{`ensureStatic`}</code>,
because it blocks the shell.
</p>
<Slug params={params} />
</main>
)
}
async function Slug({ params }: { params: Promise<Params> }) {
const { slug } = await params
return <div>Slug: {slug}</div>
}
import type { Instant } from 'next'
import { default as Page } from '../../_base/navigation-without-suspense/page.base'
export const prefetch = 'partial'
export const unstable_ensureStatic = false
export const instant: Instant = {
level: 'experimental-error',
unstable_samples: [{}],
}
export default Page
import type { Instant } from 'next'
import { default as Page } from '../../_base/prefetch-without-suspense/page.base'
export const prefetch = 'partial'
export const unstable_ensureStatic = false
export const instant: Instant = {
level: 'experimental-error',
unstable_samples: [{}],
}
export default Page
import type { ReactNode } from 'react'
export const instant = false
export default function IgnoreStaticShellValidationLayout({
children,
}: {
children: ReactNode
}) {
return children
}
import type { Instant } from 'next'
import { default as Page } from '../../_base/session-data-without-suspense/page.base'
export const prefetch = 'partial'
export const unstable_ensureStatic = false
export const instant: Instant = {
level: 'experimental-error',
unstable_samples: [{ cookies: [] }],
}
export default Page
import type { Instant } from 'next'
import {
default as Page,
generateStaticParams,
} from '../../../_base/static-params-without-suspense/[slug]/page.base'
export const prefetch = 'partial'
export const unstable_ensureStatic = false
export const instant: Instant = {
level: 'experimental-error',
unstable_samples: [{ params: { slug: '123' } }],
}
export { generateStaticParams }
export default Page
import type { Instant } from 'next'
import { default as Page } from '../../_base/navigation-without-suspense/page.base'
export const prefetch = 'partial'
export const unstable_ensureStatic = 'prefetch'
export const instant: Instant = {
level: 'experimental-error',
unstable_samples: [{}],
}
export default Page
import type { Instant } from 'next'
import { default as Page } from '../../_base/prefetch-without-suspense/page.base'
export const prefetch = 'partial'
export const unstable_ensureStatic = 'prefetch'
export const instant: Instant = {
level: 'experimental-error',
unstable_samples: [{}],
}
export default Page
import type { ReactNode } from 'react'
export const instant = false
export default function IgnoreStaticShellValidationLayout({
children,
}: {
children: ReactNode
}) {
return children
}
import type { Instant } from 'next'
import { default as Page } from '../../_base/session-data-without-suspense/page.base'
export const prefetch = 'partial'
export const unstable_ensureStatic = 'prefetch'
export const instant: Instant = {
level: 'experimental-error',
unstable_samples: [{ cookies: [] }],
}
export default Page
import type { Instant } from 'next'
import {
default as Page,
generateStaticParams,
} from '../../../_base/static-params-without-suspense/[slug]/page.base'
export const prefetch = 'partial'
export const unstable_ensureStatic = 'prefetch'
export const instant: Instant = {
level: 'experimental-error',
unstable_samples: [{ params: { slug: '123' } }],
}
export { generateStaticParams }
export default Page
import type { Instant } from 'next'
import { default as Page } from '../../_base/navigation-without-suspense/page.base'
export const prefetch = 'partial'
export const unstable_ensureStatic = 'shell'
export const instant: Instant = {
level: 'experimental-error',
unstable_samples: [{}],
}
export default Page
import type { Instant } from 'next'
import { default as Page } from '../../_base/prefetch-without-suspense/page.base'
export const prefetch = 'partial'
export const unstable_ensureStatic = 'shell'
export const instant: Instant = {
level: 'experimental-error',
unstable_samples: [{}],
}
export default Page
import type { ReactNode } from 'react'
export const instant = false
export default function IgnoreStaticShellValidationLayout({
children,
}: {
children: ReactNode
}) {
return children
}
import type { Instant } from 'next'
import { default as Page } from '../../_base/session-data-without-suspense/page.base'
export const prefetch = 'partial'
export const unstable_ensureStatic = 'shell'
export const instant: Instant = {
level: 'experimental-error',
unstable_samples: [{ cookies: [] }],
}
export default Page
import type { Instant } from 'next'
import {
default as Page,
generateStaticParams,
} from '../../../_base/static-params-without-suspense/[slug]/page.base'
export const prefetch = 'partial'
export const unstable_ensureStatic = 'shell'
export const instant: Instant = {
level: 'experimental-error',
unstable_samples: [{ params: { slug: '123' } }],
}
export { generateStaticParams }
export default Page
import type { ReactNode } from 'react'
export const instant = false
export default function IgnoreStaticShellValidationLayout({ children }) {
export default function IgnoreStaticShellValidationLayout({
children,
}: {
children: ReactNode
}) {
return children
}
......@@ -64,6 +64,37 @@ export default async function Page() {
<DebugLinks href="/shells/valid-non-prerenderable-cache" />
</li>
</ul>
<h2>ensureStatic</h2>
<ul>
{[false, 'shell', 'prefetch'].map((ensureStaticConfig) => (
<li key={ensureStaticConfig + ''}>
<code>{`ensureStatic = ${ensureStaticConfig}`}</code>
<ul>
<li>
<DebugLinks
href={`/shells/ensure-static/${ensureStaticConfig}/session-data-without-suspense`}
/>
</li>
<li>
<DebugLinks
href={`/shells/ensure-static/${ensureStaticConfig}/static-params-without-suspense/123`}
/>
</li>
<li>
<DebugLinks
href={`/shells/ensure-static/${ensureStaticConfig}/prefetch-without-suspense`}
/>
</li>
<li>
<DebugLinks
href={`/shells/ensure-static/${ensureStaticConfig}/navigation-without-suspense`}
/>
</li>
</ul>
</li>
))}
</ul>
</main>
)
}
import type { ReactNode } from 'react'
export const instant = false
export default function IgnoreStaticShellValidationLayout({ children }) {
export default function IgnoreStaticShellValidationLayout({
children,
}: {
children: ReactNode
}) {
return children
}
import type { ReactNode } from 'react'
export const instant = false
export default function IgnoreStaticShellValidationLayout({ children }) {
export default function IgnoreStaticShellValidationLayout({
children,
}: {
children: ReactNode
}) {
return children
}
import type { ReactNode } from 'react'
export const instant = false
export default function IgnoreStaticShellValidationLayout({ children }) {
export default function IgnoreStaticShellValidationLayout({
children,
}: {
children: ReactNode
}) {
return children
}
'use cache'
import type { ReactNode } from 'react'
// A file-level `"use cache"` directive wraps every exported function in a cache
// boundary. `instant` is a statically known non-function value, so it stays a
// plain export and is read as route segment config.
export const instant = false
export default async function IgnoreStaticShellValidationLayout({ children }) {
export default async function IgnoreStaticShellValidationLayout({
children,
}: {
children: ReactNode
}) {
return children
}
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