Commit 6adecd80 authored by Jimmy Lai's avatar Jimmy Lai

refactor chunk retry flow and harden coverage

parent 5e7c6112
/**
* Chunk load error handling with silent retry logic.
*
* This module provides retry orchestration for chunk/network loading failures.
* It tracks failures in-memory per {route, chunkKey} and implements a
* silent retry with jittered backoff.
* Shared retry timing utilities for chunk and RSC request retries.
*/
import { isChunkLoadError, isNetworkError } from './is-chunk-load-error'
/**
* Context for chunk error handling.
* Tracks where the error occurred and what kind of error it was.
*/
export interface ChunkErrorContext {
/** The current route/pathname */
route: string
/** Whether this error is blocking a user-visible operation (navigation, render) */
userVisible: boolean
/** Error message for generating chunk key */
message: string
/** URL of the failed chunk if extractable */
chunkUrl?: string
}
interface FailureState {
failCount: number
lastTs: number
retriedTs?: number
}
const RETRY_WINDOW_MS = 30_000 // Don't retry same chunk within 30s of a retry
const MAX_FAIL_COUNT_FOR_RETRY = 2 // After 2 failures, skip silent retry
const KEY_SEPARATOR = '\u0000'
const failureStates = new Map<string, FailureState>()
/**
* Simple hash function for generating chunk keys when URL isn't available.
*/
function simpleHash(str: string): string {
let hash = 0
for (let i = 0; i < str.length; i++) {
const char = str.charCodeAt(i)
hash = ((hash << 5) - hash + char) | 0
}
return Math.abs(hash).toString(36)
}
/**
* Extract chunk URL from error message if possible.
* ChunkLoadError messages typically contain the URL.
*/
function extractChunkUrl(error: Error): string | undefined {
const message = error.message
// Turbopack format: "Failed to load chunk <url> from <reason>: <cause>"
// The URL can be relative (/_next/...) or absolute (http://...)
const turbopackMatch = message.match(
/Failed to load chunk ([^\s]+\.(?:js|css))/
)
if (turbopackMatch) {
return turbopackMatch[1]
}
// Webpack format: "Loading chunk <id> failed. (error: <url>)"
// Match absolute URLs (http/https), protocol-relative URLs, and relative URLs
const webpackMatch = message.match(
/(?:https?:)?\/\/[^\s)]+|\/[^\s)]+\.(?:js|css)/
)
return webpackMatch?.[0]
}
/**
* Generate a unique key for this chunk error, used for deduplication.
*/
function getChunkKey(ctx: ChunkErrorContext): string {
return ctx.chunkUrl ?? simpleHash(ctx.message)
}
/**
* Get the in-memory key for tracking this chunk failure.
*/
function getStateKey(ctx: ChunkErrorContext): string {
return `${ctx.route}${KEY_SEPARATOR}${getChunkKey(ctx)}`
}
function readFailureState(ctx: ChunkErrorContext): FailureState | null {
return failureStates.get(getStateKey(ctx)) ?? null
}
function writeFailureState(ctx: ChunkErrorContext, state: FailureState): void {
failureStates.set(getStateKey(ctx), state)
}
/**
* Clear failure state for a route (called on successful navigation or explicit retry).
*/
export function clearFailureState(route: string): void {
const routePrefix = `${route}${KEY_SEPARATOR}`
for (const key of failureStates.keys()) {
if (key.startsWith(routePrefix)) {
failureStates.delete(key)
}
}
}
/**
* Increment the failure count for this chunk.
*/
function bumpFailCount(ctx: ChunkErrorContext): FailureState {
const existing = readFailureState(ctx)
const now = Date.now()
const state: FailureState = {
failCount: (existing?.failCount ?? 0) + 1,
lastTs: now,
retriedTs: existing?.retriedTs,
}
writeFailureState(ctx, state)
return state
}
/**
* Mark that a retry was attempted for this chunk.
*/
function markRetried(ctx: ChunkErrorContext): void {
const existing = readFailureState(ctx)
const now = Date.now()
const state: FailureState = {
failCount: existing?.failCount ?? 1,
lastTs: existing?.lastTs ?? now,
retriedTs: now,
}
writeFailureState(ctx, state)
}
/**
* Check if we should attempt a silent retry for this chunk error.
*/
export function shouldSilentRetry(ctx: ChunkErrorContext): boolean {
// Don't retry if offline
if (typeof navigator !== 'undefined' && !navigator.onLine) {
return false
}
const state = readFailureState(ctx)
const now = Date.now()
// If we already retried within the window, don't retry again
if (state?.retriedTs && now - state.retriedTs < RETRY_WINDOW_MS) {
return false
}
// Too many failures - skip silent retry to avoid annoying the user
if ((state?.failCount ?? 0) >= MAX_FAIL_COUNT_FOR_RETRY) {
return false
}
return true
}
/**
* Get the failure count for this chunk (for showing "hard refresh" hint).
*/
export function getFailCount(ctx: ChunkErrorContext): number {
return readFailureState(ctx)?.failCount ?? 0
}
const BASE_DELAY_MS = 200
const MAX_JITTER_MS = 400
const MAX_RTT_MS = 500
const MAX_TOTAL_DELAY_MS = 1500
/**
* Calculate retry delay with jitter based on RTT.
* Returns delay in milliseconds: 200 + random(0-400) + min(500, RTT)
* Returns delay in milliseconds: 200 + random(0-400) + min(500, RTT), capped.
*/
export function getRetryDelayMs(): number {
const baseDelay = 200
const jitter = Math.floor(Math.random() * 401) // 0-400ms
const jitter = Math.floor(Math.random() * (MAX_JITTER_MS + 1))
// Get RTT if available via Network Information API
let rtt = 0
if (typeof navigator !== 'undefined' && 'connection' in navigator) {
const connection = (navigator as any).connection
if (connection?.rtt) {
rtt = Math.min(500, connection.rtt) // Cap at 500ms
rtt = Math.min(MAX_RTT_MS, connection.rtt)
}
}
return Math.min(1500, baseDelay + jitter + rtt) // Cap total at 1500ms
return Math.min(MAX_TOTAL_DELAY_MS, BASE_DELAY_MS + jitter + rtt)
}
/**
......@@ -197,48 +31,3 @@ export function getRetryDelayMs(): number {
export function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms))
}
/**
* Create a ChunkErrorContext from an error.
*/
export function createChunkErrorContext(
error: Error,
route: string,
userVisible: boolean = true
): ChunkErrorContext | null {
if (!isChunkLoadError(error) && !isNetworkError(error)) {
return null
}
return {
route,
userVisible,
message: error.message,
chunkUrl: extractChunkUrl(error),
}
}
/**
* Handle a chunk load failure and determine if we should retry.
*
* Returns true if a silent retry should be attempted, false otherwise.
* This function updates the failure tracking state.
*/
export function handleChunkFailure(ctx: ChunkErrorContext): boolean {
// Don't count offline failures toward retry limit - they're expected
// and should be retried once connectivity is restored.
if (typeof navigator !== 'undefined' && !navigator.onLine) {
return false
}
// Record failure for online attempts
bumpFailCount(ctx)
// Check if we should try a silent retry
if (shouldSilentRetry(ctx)) {
markRetried(ctx)
return true
}
return false
}
......@@ -31,8 +31,6 @@ import {
} from '../app-router-headers'
import { isChunkOrNetworkError } from '../chunk-load-error/is-chunk-load-error'
import {
createChunkErrorContext,
handleChunkFailure,
getRetryDelayMs,
sleep,
} from '../chunk-load-error/chunk-load-error-handler'
......@@ -121,6 +119,7 @@ function doMpaNavigation(url: string): FetchServerResponseResult {
}
let isPageUnloading = false
const MAX_RSC_FETCH_RETRIES = 1
if (typeof window !== 'undefined') {
// Track when the page is unloading, e.g. due to reloading the page or
......@@ -144,6 +143,14 @@ if (typeof window !== 'undefined') {
export async function fetchServerResponse(
url: URL,
options: FetchServerResponseOptions
): Promise<FetchServerResponseResult> {
return fetchServerResponseWithRetry(url, options, 0)
}
async function fetchServerResponseWithRetry(
url: URL,
options: FetchServerResponseOptions,
retryCount: number
): Promise<FetchServerResponseResult> {
const { flightRouterState, nextUrl } = options
......@@ -299,42 +306,15 @@ export async function fetchServerResponse(
debugInfo: flightResponsePromise._debugInfo ?? null,
}
} catch (err) {
// Check if this is a chunk/network error that we can retry
if (
err instanceof Error &&
isChunkOrNetworkError(err) &&
!isPageUnloading
!isPageUnloading &&
retryCount < MAX_RSC_FETCH_RETRIES
) {
const ctx = createChunkErrorContext(
err,
originalUrl.pathname,
true // user-visible navigation
)
if (ctx) {
// handleChunkFailure updates failure tracking and returns whether to retry
const shouldRetry = handleChunkFailure(ctx)
if (shouldRetry) {
// Silent retry with jittered delay
const delay = getRetryDelayMs()
await sleep(delay)
try {
// Retry the fetch once (use originalUrl to ensure consistent error tracking)
return await fetchServerResponse(originalUrl, options)
} catch (retryErr) {
// Retry failed, fall through to MPA navigation
if (!isPageUnloading) {
console.error(
`Retry failed for RSC payload ${originalUrl}. Falling back to browser navigation.`,
retryErr
)
}
return originalUrl.toString()
}
}
}
// Retry once after a jittered delay for transient failures.
await sleep(getRetryDelayMs())
return fetchServerResponseWithRetry(originalUrl, options, retryCount + 1)
}
if (!isPageUnloading) {
......
......@@ -56,7 +56,6 @@ import {
writeHeadToBFCache,
} from '../segment-cache/bfcache'
import { DYNAMIC_STALETIME_MS } from './reducers/navigate-reducer'
import { clearFailureState } from '../chunk-load-error/chunk-load-error-handler'
// This is yet another tree type that is used to track pending promises that
// need to be fulfilled once the dynamic data is received. The terminal nodes of
......@@ -1365,9 +1364,6 @@ async function finishNavigationTask(
case NavigationTaskExitStatus.Done: {
// The task has completely finished. There's no missing data. Exit.
previousNavigationDidMismatch = false
// Clear failure state for the successfully navigated route
const primaryRequestResult = await primaryRequestPromise
clearFailureState(primaryRequestResult.url.pathname)
return
}
case NavigationTaskExitStatus.SoftRetry: {
......@@ -1377,8 +1373,6 @@ async function finishNavigationTask(
// happen in a row, fall back to a hard retry.
const isHardRetry = false
const primaryRequestResult = await primaryRequestPromise
// Clear failure state for the route we're retrying to give it another chance
clearFailureState(primaryRequestResult.url.pathname)
dispatchRetryDueToTreeMismatch(
isHardRetry,
primaryRequestResult.url,
......@@ -1401,8 +1395,6 @@ async function finishNavigationTask(
// doesn't exist yet.
const isHardRetry = true
const primaryRequestResult = await primaryRequestPromise
// Clear failure state for the route we're retrying to give it another chance
clearFailureState(primaryRequestResult.url.pathname)
dispatchRetryDueToTreeMismatch(
isHardRetry,
primaryRequestResult.url,
......
......@@ -3,7 +3,10 @@ import { BailoutToCSR } from './dynamic-bailout-to-csr'
import type { ComponentModule } from './types'
import { PreloadChunks } from './preload-chunks'
import { isChunkLoadError } from '../../../client/components/chunk-load-error/is-chunk-load-error'
import { getRetryDelayMs } from '../../../client/components/chunk-load-error/chunk-load-error-handler'
import {
getRetryDelayMs,
sleep,
} from '../../../client/components/chunk-load-error/chunk-load-error-handler'
// Normalize loader to return the module as form { default: Component } for `React.lazy`.
// Also for backward compatible since next/dynamic allows to resolve a component directly with loader
......@@ -32,30 +35,18 @@ function convertModule<P>(
* On first failure, retries once after a delay.
*/
function createRetryableLoader<T>(loader: () => Promise<T>): () => Promise<T> {
let hasRetried = false
return () =>
loader().catch((err) => {
// Only retry chunk load errors, and only once
if (
typeof window !== 'undefined' &&
isChunkLoadError(err) &&
!hasRetried
) {
hasRetried = true
// Retry after a short delay with jitter
return new Promise<T>((resolve, reject) => {
const delay = getRetryDelayMs()
setTimeout(() => {
loader().then(resolve, reject)
}, delay)
})
return async () => {
try {
return await loader()
} catch (err) {
if (typeof window !== 'undefined' && isChunkLoadError(err)) {
await sleep(getRetryDelayMs())
return loader()
}
// No retry - propagate error
throw err
})
}
}
}
const defaultOptions = {
......
......@@ -25,7 +25,10 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
import React from 'react'
import { LoadableContext } from './loadable-context.shared-runtime'
import { isChunkLoadError } from '../../client/components/chunk-load-error/is-chunk-load-error'
import { getRetryDelayMs } from '../../client/components/chunk-load-error/chunk-load-error-handler'
import {
getRetryDelayMs,
sleep,
} from '../../client/components/chunk-load-error/chunk-load-error-handler'
function resolve(obj: any) {
return obj && obj.default ? obj.default : obj
......@@ -35,8 +38,19 @@ const ALL_INITIALIZERS: any[] = []
const READY_INITIALIZERS: any[] = []
let initialized = false
function retryChunkLoadErrorOnce(loader: any) {
return loader().catch(async (err: any) => {
if (typeof window !== 'undefined' && isChunkLoadError(err)) {
await sleep(getRetryDelayMs())
return loader()
}
throw err
})
}
function load(loader: any) {
let promise = loader()
let promise = retryChunkLoadErrorOnce(loader)
let state: any = {
loading: true,
......@@ -169,14 +183,12 @@ class LoadableSubscription {
_timeout: any
_res: any
_state: any
_hasAutoRetried: boolean
constructor(loadFn: any, opts: any) {
this._loadFn = loadFn
this._opts = opts
this._callbacks = new Set()
this._delay = null
this._timeout = null
this._hasAutoRetried = false
this.retry()
}
......@@ -221,31 +233,9 @@ class LoadableSubscription {
this._update({})
this._clearTimeouts()
})
.catch((err: any) => {
// Auto-retry for chunk load errors (once)
// This handles transient network failures during dynamic imports
if (
typeof window !== 'undefined' &&
isChunkLoadError(err) &&
!this._hasAutoRetried
) {
this._hasAutoRetried = true
// Retry after a short delay with jitter
const delay = getRetryDelayMs()
setTimeout(() => {
this.retry()
}, delay)
// Mark state before retrying but ensure the promise chain rejects.
this._update({})
this._clearTimeouts()
throw err
}
// No more retries - propagate error
.catch((_err: any) => {
this._update({})
this._clearTimeouts()
throw err
})
this._update({})
}
......
......@@ -27,10 +27,12 @@ describe('chunk-load-failure', () => {
it('should report async chunk load failures', async () => {
let nextDynamicChunk = await getNextDynamicChunk()
let chunkRequestCount = 0
let pageError: Error | undefined
const browser = await next.browser('/dynamic', {
beforePageLoad(page) {
page.route(`**/${nextDynamicChunk}*`, async (route) => {
chunkRequestCount++
await route.abort('connectionreset')
})
page.on('pageerror', (error: Error) => {
......@@ -45,6 +47,8 @@ describe('chunk-load-failure', () => {
expect(await body.text()).toMatch(/This page couldn\u2019t load/)
})
// One initial request + one retry attempt.
expect(chunkRequestCount).toBe(2)
expect(pageError).toBeDefined()
expect(pageError.name).toBe('ChunkLoadError')
if (process.env.IS_TURBOPACK_TEST) {
......@@ -88,7 +92,8 @@ describe('chunk-load-failure', () => {
)
expect(await browser.eval('window.__TEST_NO_RELOAD')).toBe(true)
expect(rscRequestCount).toBeGreaterThanOrEqual(2)
// One initial request + one retry attempt.
expect(rscRequestCount).toBe(2)
})
it('should recover after a transient async chunk load failure', async () => {
......@@ -123,7 +128,8 @@ describe('chunk-load-failure', () => {
250
)
expect(chunkRequestCount).toBeGreaterThanOrEqual(2)
// One initial request + one retry attempt.
expect(chunkRequestCount).toBe(2)
expect(pageError).toBeUndefined()
})
......
......@@ -70,6 +70,12 @@ async function readFilesBuilder(
functions.map(async (fn) => {
let config = await next.readJSON(fn)
let fnDir = path.dirname(fn)
const filePathMapValues =
config && typeof config.filePathMap === 'object'
? Object.values(config.filePathMap).filter(
(value): value is string => typeof value === 'string'
)
: []
let files = [
...(
await glob('**/*', {
......@@ -79,7 +85,7 @@ async function readFilesBuilder(
ignore: ['.vc-config.json'],
})
).map((f) => path.join(fnDir, f)),
...Object.values(config.filePathMap),
...filePathMapValues,
] as string[]
files.sort()
return [
......
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