Unverified Commit a362fd27 authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

instant(): fix cookie handling for fresh page loads (#90613)

Previously, instant() used page.evaluate() to set the cookie via
document.cookie, which required a page to already be loaded. This meant
the cookie wasn't present on the very first navigation.

Switch to Playwright's browser context cookie API so the cookie is set
before any page loads. If the page is already loaded, the base URL is
inferred automatically. Otherwise, a new baseURL option allows setting
the cookie before the first navigation.
parent 9ce8d136
/** /**
* Minimal interface for Playwright's Page. We use a structural type rather than * Minimal interfaces for Playwright's Page and BrowserContext. We use
* importing from a specific Playwright package so this works with any version * structural types rather than importing from a specific Playwright package
* of playwright, playwright-core, or @playwright/test. * so this works with any version of playwright, playwright-core, or
* @playwright/test.
*/ */
interface PlaywrightBrowserContext {
addCookies(
cookies: Array<{
name: string
value: string
url?: string
domain?: string
path?: string
}>
): Promise<void>
clearCookies(options?: { name?: string }): Promise<void>
}
interface PlaywrightPage { interface PlaywrightPage {
evaluate<R, Arg>(pageFunction: (arg: Arg) => R, arg: Arg): Promise<R> url(): string
context(): PlaywrightBrowserContext
} }
const INSTANT_COOKIE = 'next-instant-navigation-testing' const INSTANT_COOKIE = 'next-instant-navigation-testing'
...@@ -17,17 +32,31 @@ const INSTANT_COOKIE = 'next-instant-navigation-testing' ...@@ -17,17 +32,31 @@ const INSTANT_COOKIE = 'next-instant-navigation-testing'
* Uses the cookie-based protocol: setting the cookie acquires the * Uses the cookie-based protocol: setting the cookie acquires the
* navigation lock (via CookieStore change event), and clearing it * navigation lock (via CookieStore change event), and clearing it
* releases the lock. * releases the lock.
*
* If the page is already loaded, the URL is inferred
* automatically. For a fresh page (before any navigation), pass
* `baseURL` so the cookie can be scoped to the correct domain:
*
* await instant(page, async () => {
* await page.goto(url)
* // ...
* }, { baseURL: 'http://localhost:3000' })
*/ */
export async function instant<T>( export async function instant<T>(
page: PlaywrightPage, page: PlaywrightPage,
fn: () => Promise<T> fn: () => Promise<T>,
options?: { baseURL?: string }
): Promise<T> { ): Promise<T> {
// Acquire the lock by setting the cookie from within the page context. // Acquire the lock by setting the cookie via the browser context. This
// This triggers the CookieStore change event in navigation-testing-lock.ts, // ensures the cookie is present even on the very first navigation.
// which acquires the in-memory navigation lock. // The cookie triggers the CookieStore change event in
await page.evaluate((name) => { // navigation-testing-lock.ts, which acquires the in-memory navigation lock.
document.cookie = name + '=1; path=/' const { hostname } = new URL(resolveURL(page, options))
}, INSTANT_COOKIE) await page
.context()
.addCookies([
{ name: INSTANT_COOKIE, value: '1', domain: hostname, path: '/' },
])
try { try {
return await fn() return await fn()
} finally { } finally {
...@@ -35,8 +64,57 @@ export async function instant<T>( ...@@ -35,8 +64,57 @@ export async function instant<T>(
// triggers the CookieStore change event which resolves the in-memory // triggers the CookieStore change event which resolves the in-memory
// lock. For MPA navigations (reload, plain anchor), the listener in // lock. For MPA navigations (reload, plain anchor), the listener in
// app-bootstrap.ts triggers a page reload to fetch dynamic data. // app-bootstrap.ts triggers a page reload to fetch dynamic data.
await page.evaluate((name) => { await page.context().clearCookies({ name: INSTANT_COOKIE })
document.cookie = name + '=; path=/; max-age=0'
}, INSTANT_COOKIE)
} }
} }
/**
* Resolves the URL to scope the instant navigation cookie to. Prefers
* an explicit `baseURL` option, then falls back to the page's current URL.
* Throws a descriptive error if neither is available (e.g. fresh page
* before any navigation).
*/
function resolveURL(
page: PlaywrightPage,
options?: { baseURL?: string }
): string {
const url = options?.baseURL ?? page.url()
if (url && url !== 'about:blank') {
return url
}
const error = new Error(
`Could not infer the base URL of the application.
instant() needs to know the base URL so it can configure the
browser before the first page load. If the page is already
loaded, the base URL is detected automatically.
Otherwise, you can fix this in one of two ways:
1. Pass a baseURL option:
await instant(page, async () => {
await page.goto('http://localhost:3000')
// ...
}, { baseURL: 'http://localhost:3000' })
Tip: If you use baseURL in your Playwright config, you can
get it from the test fixture:
test('my test', async ({ page, baseURL }) => {
await instant(page, async () => {
// ...
}, { baseURL })
})
2. Navigate to a page before calling instant():
await page.goto('http://localhost:3000')
await instant(page, async () => {
// ...
})`
)
// Remove resolveURL and instant from the stack trace so the error
// points at the caller's code.
Error.captureStackTrace(error, instant)
throw error
}
...@@ -63,6 +63,7 @@ import { ...@@ -63,6 +63,7 @@ import {
} from '../../lib/constants' } from '../../lib/constants'
import type { CacheControl } from '../../server/lib/cache-control' import type { CacheControl } from '../../server/lib/cache-control'
import { ENCODED_TAGS } from '../../server/stream-utils/encoded-tags' import { ENCODED_TAGS } from '../../server/stream-utils/encoded-tags'
import { createInstantTestScriptInsertionTransformStream } from '../../server/stream-utils/node-web-streams-helper'
import { sendRenderResult } from '../../server/send-payload' import { sendRenderResult } from '../../server/send-payload'
import { NoFallbackError } from '../../shared/lib/no-fallback-error.external' import { NoFallbackError } from '../../shared/lib/no-fallback-error.external'
import { parseMaxPostponedStateSize } from '../../shared/lib/size-limit' import { parseMaxPostponedStateSize } from '../../shared/lib/size-limit'
...@@ -1456,6 +1457,21 @@ export async function handler( ...@@ -1456,6 +1457,21 @@ export async function handler(
// This is a request for HTML data. // This is a request for HTML data.
const body = cachedData.html const body = cachedData.html
// When serving a static shell for instant navigation testing, inject
// self.__next_instant_test=1 as the first thing inside <head> so the
// client can detect the static shell. This must be before any async
// bootstrap scripts — otherwise a cached async script can execute
// before the global is set.
//
// TODO: Currently the client skips hydration entirely during
// instant navigation testing. Ideally we would still hydrate but
// without the dynamic data — the static shell is valid HTML that
// could be hydrated. This is just an implementation gap; the
// page gets reloaded when the instant scope ends anyway.
if (isInstantNavigationTest && isDebugStaticShell) {
body.pipeThrough(createInstantTestScriptInsertionTransformStream())
}
// If there's no postponed state, we should just serve the HTML. This // If there's no postponed state, we should just serve the HTML. This
// should also be the case for a resume request because it's completed // should also be the case for a resume request because it's completed
// as a server render (rather than a static render). // as a server render (rather than a static render).
...@@ -1490,25 +1506,22 @@ export async function handler( ...@@ -1490,25 +1506,22 @@ export async function handler(
// HTML will be the static shell so all the Dynamic API's will be used // HTML will be the static shell so all the Dynamic API's will be used
// during static generation. // during static generation.
if (isDebugStaticShell || isDebugDynamicAccesses) { if (isDebugStaticShell || isDebugDynamicAccesses) {
// Since we're not resuming the render, we need to at least add the if (!isInstantNavigationTest) {
// closing body and html tags to create valid HTML. // Since we're not resuming the render, we need to at least add the
body.push( // closing body and html tags to create valid HTML.
new ReadableStream({ body.push(
start(controller) { new ReadableStream({
if (isInstantNavigationTest) { start(controller) {
// Inject a global so the client can detect that this response controller.enqueue(ENCODED_TAGS.CLOSED.BODY_AND_HTML)
// is a partial static shell, independent of document.cookie controller.close()
// (which may be empty on the new page in some browsers). },
const encoder = new TextEncoder() })
controller.enqueue( )
encoder.encode('<script>self.__next_instant_test=1</script>') }
) // When in instant navigation testing mode, we intentionally omit
} // the closing </body></html> tags so the client interprets the
controller.enqueue(ENCODED_TAGS.CLOSED.BODY_AND_HTML) // response as a partial stream rather than a complete document
controller.close() // with incoherent content.
},
})
)
return sendRenderResult({ return sendRenderResult({
req, req,
......
...@@ -2677,8 +2677,10 @@ async function renderToStream( ...@@ -2677,8 +2677,10 @@ async function renderToStream(
// In development mode, set the request ID as a global variable, before the // In development mode, set the request ID as a global variable, before the
// bootstrap script is executed, which depends on it during hydration. // bootstrap script is executed, which depends on it during hydration.
// For MPA navigations (page reload, direct URL entry), the request ID
// header is not present, so we generate a random one.
const bootstrapScriptContent = process.env.__NEXT_DEV_SERVER const bootstrapScriptContent = process.env.__NEXT_DEV_SERVER
? `self.__next_r=${JSON.stringify(requestId)}` ? `self.__next_r=${JSON.stringify(requestId ?? crypto.randomUUID())}`
: undefined : undefined
// Create the "render route (app)" span manually so we can keep it open during streaming. // Create the "render route (app)" span manually so we can keep it open during streaming.
......
...@@ -250,6 +250,17 @@ export default class RenderResult< ...@@ -250,6 +250,17 @@ export default class RenderResult<
} }
} }
/**
* Pipes the response through a transform stream. This converts the response
* to a single readable stream (chaining if needed) and pipes it through the
* provided transform.
*
* @param transform The transform stream to pipe through
*/
public pipeThrough(transform: TransformStream<Uint8Array, Uint8Array>): void {
this.response = this.readable.pipeThrough(transform)
}
/** /**
* Unshifts a new stream to the response. This will convert the response to an * Unshifts a new stream to the response. This will convert the response to an
* array of streams if it is not already one and will add the new stream to * array of streams if it is not already one and will add the new stream to
......
...@@ -3,6 +3,8 @@ export const ENCODED_TAGS = { ...@@ -3,6 +3,8 @@ export const ENCODED_TAGS = {
OPENING: { OPENING: {
// <html // <html
HTML: new Uint8Array([60, 104, 116, 109, 108]), HTML: new Uint8Array([60, 104, 116, 109, 108]),
// <head
HEAD: new Uint8Array([60, 104, 101, 97, 100]),
// <body // <body
BODY: new Uint8Array([60, 98, 111, 100, 121]), BODY: new Uint8Array([60, 98, 111, 100, 121]),
}, },
......
...@@ -518,6 +518,66 @@ function createClientResumeScriptInsertionTransformStream(): TransformStream< ...@@ -518,6 +518,66 @@ function createClientResumeScriptInsertionTransformStream(): TransformStream<
}) })
} }
/**
* Creates a transform stream that injects an inline script as the first
* element inside <head>. Used during instant navigation testing to set
* self.__next_instant_test before any async bootstrap scripts execute.
*/
export function createInstantTestScriptInsertionTransformStream(): TransformStream<
Uint8Array,
Uint8Array
> {
const INSTANT_TEST_SCRIPT = '<script>self.__next_instant_test=1</script>'
let didAlreadyInsert = false
return new TransformStream({
transform(chunk, controller) {
if (didAlreadyInsert) {
// Already inserted the script into the head. Pass through.
controller.enqueue(chunk)
return
}
// Find the opening <head tag (may have attributes like <head class="...">)
const headOpenIndex = indexOfUint8Array(chunk, ENCODED_TAGS.OPENING.HEAD)
if (headOpenIndex === -1) {
controller.enqueue(chunk)
return
}
// Find the closing > of the <head ...> tag
const headCloseAngle = chunk.indexOf(
62, // '>'
headOpenIndex + ENCODED_TAGS.OPENING.HEAD.length
)
if (headCloseAngle === -1) {
controller.enqueue(chunk)
return
}
const encodedInsertion = encoder.encode(INSTANT_TEST_SCRIPT)
const insertionPoint = headCloseAngle + 1
// e.g.
// chunk = <!DOCTYPE html><html><head><meta charset="utf-8">...
// insertion = <script>self.__next_instant_test=1</script>
// output = <!DOCTYPE html><html><head> [ <script>...</script> ] <meta charset="utf-8">...
const insertedHeadContent = new Uint8Array(
chunk.length + encodedInsertion.length
)
insertedHeadContent.set(chunk.slice(0, insertionPoint))
insertedHeadContent.set(encodedInsertion, insertionPoint)
insertedHeadContent.set(
chunk.slice(insertionPoint),
insertionPoint + encodedInsertion.length
)
controller.enqueue(insertedHeadContent)
didAlreadyInsert = true
},
})
}
// Suffix after main body content - scripts before </body>, // Suffix after main body content - scripts before </body>,
// but wait for the major chunks to be enqueued. // but wait for the major chunks to be enqueued.
function createDeferredSuffixStream( function createDeferredSuffixStream(
......
...@@ -529,4 +529,136 @@ describe('instant-navigation-testing-api', () => { ...@@ -529,4 +529,136 @@ describe('instant-navigation-testing-api', () => {
'Dynamic content loaded' 'Dynamic content loaded'
) )
}) })
it('throws descriptive error on fresh page without baseURL', async () => {
const page = await openPage('/')
const freshPage = await page.context().newPage()
try {
let caughtError: Error | undefined
try {
await instant(freshPage, async () => {})
} catch (e) {
caughtError = e as Error
}
// Snapshot the error message
expect(caughtError!.message).toMatchInlineSnapshot(`
"Could not infer the base URL of the application.
instant() needs to know the base URL so it can configure the
browser before the first page load. If the page is already
loaded, the base URL is detected automatically.
Otherwise, you can fix this in one of two ways:
1. Pass a baseURL option:
await instant(page, async () => {
await page.goto('http://localhost:3000')
// ...
}, { baseURL: 'http://localhost:3000' })
Tip: If you use baseURL in your Playwright config, you can
get it from the test fixture:
test('my test', async ({ page, baseURL }) => {
await instant(page, async () => {
// ...
}, { baseURL })
})
2. Navigate to a page before calling instant():
await page.goto('http://localhost:3000')
await instant(page, async () => {
// ...
})"
`)
// Verify the stack trace points at the caller, not at the
// internals of the instant() helper.
const firstFrame = caughtError!
.stack!.split('\n')
.find((line) => line.trimStart().startsWith('at '))
expect(firstFrame).not.toContain('resolveURL')
expect(firstFrame).not.toContain('at instant ')
} finally {
await freshPage.close()
}
})
it('sets cookie before first navigation when using baseURL', async () => {
const page = await openPage('/')
const freshPage = await page.context().newPage()
try {
await instant(
freshPage,
async () => {
// Navigate to a page for the first time within the instant scope.
// The cookie was set via addCookies before this navigation, so
// the server sees it on the initial request and blocks dynamic data.
await freshPage.goto(next.url + '/target-page')
// The loading shell appears immediately
const loadingShell = freshPage.locator(
'[data-testid="loading-shell"]'
)
await loadingShell.waitFor({ state: 'visible' })
expect(await loadingShell.textContent()).toContain(
'Loading target page...'
)
// Dynamic content has not streamed in yet
const dynamicContent = freshPage.locator(
'[data-testid="dynamic-content"]'
)
expect(await dynamicContent.count()).toBe(0)
},
{ baseURL: next.url }
)
// After exiting the instant scope, dynamic content streams in
const dynamicContent = freshPage.locator(
'[data-testid="dynamic-content"]'
)
await dynamicContent.waitFor({ state: 'visible' })
expect(await dynamicContent.textContent()).toContain(
'Dynamic content loaded'
)
} finally {
await freshPage.close()
}
})
it('clears cookie after instant scope exits', async () => {
const page = await openPage('/')
await instant(page, async () => {
await page.reload()
const homeTitle = page.locator('[data-testid="home-title"]')
await homeTitle.waitFor({ state: 'visible' })
})
// The instant cookie should be cleaned up
const cookies = await page.context().cookies()
const instantCookie = cookies.find(
(c) => c.name === 'next-instant-navigation-testing'
)
expect(instantCookie).toBeUndefined()
})
it('clears cookie even when callback throws', async () => {
const page = await openPage('/')
await expect(
instant(page, async () => {
throw new Error('test error')
})
).rejects.toThrow('test error')
// The instant cookie should still be cleaned up
const cookies = await page.context().cookies()
const instantCookie = cookies.find(
(c) => c.name === 'next-instant-navigation-testing'
)
expect(instantCookie).toBeUndefined()
})
}) })
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