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. * Shared retry timing utilities for chunk and RSC request retries.
*
* 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.
*/ */
const BASE_DELAY_MS = 200
import { isChunkLoadError, isNetworkError } from './is-chunk-load-error' const MAX_JITTER_MS = 400
const MAX_RTT_MS = 500
/** const MAX_TOTAL_DELAY_MS = 1500
* 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
}
/** /**
* Calculate retry delay with jitter based on RTT. * 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 { export function getRetryDelayMs(): number {
const baseDelay = 200 const jitter = Math.floor(Math.random() * (MAX_JITTER_MS + 1))
const jitter = Math.floor(Math.random() * 401) // 0-400ms
// Get RTT if available via Network Information API // Get RTT if available via Network Information API
let rtt = 0 let rtt = 0
if (typeof navigator !== 'undefined' && 'connection' in navigator) { if (typeof navigator !== 'undefined' && 'connection' in navigator) {
const connection = (navigator as any).connection const connection = (navigator as any).connection
if (connection?.rtt) { 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 { ...@@ -197,48 +31,3 @@ export function getRetryDelayMs(): number {
export function sleep(ms: number): Promise<void> { export function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms)) 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 { ...@@ -31,8 +31,6 @@ import {
} from '../app-router-headers' } from '../app-router-headers'
import { isChunkOrNetworkError } from '../chunk-load-error/is-chunk-load-error' import { isChunkOrNetworkError } from '../chunk-load-error/is-chunk-load-error'
import { import {
createChunkErrorContext,
handleChunkFailure,
getRetryDelayMs, getRetryDelayMs,
sleep, sleep,
} from '../chunk-load-error/chunk-load-error-handler' } from '../chunk-load-error/chunk-load-error-handler'
...@@ -121,6 +119,7 @@ function doMpaNavigation(url: string): FetchServerResponseResult { ...@@ -121,6 +119,7 @@ function doMpaNavigation(url: string): FetchServerResponseResult {
} }
let isPageUnloading = false let isPageUnloading = false
const MAX_RSC_FETCH_RETRIES = 1
if (typeof window !== 'undefined') { if (typeof window !== 'undefined') {
// Track when the page is unloading, e.g. due to reloading the page or // Track when the page is unloading, e.g. due to reloading the page or
...@@ -144,6 +143,14 @@ if (typeof window !== 'undefined') { ...@@ -144,6 +143,14 @@ if (typeof window !== 'undefined') {
export async function fetchServerResponse( export async function fetchServerResponse(
url: URL, url: URL,
options: FetchServerResponseOptions options: FetchServerResponseOptions
): Promise<FetchServerResponseResult> {
return fetchServerResponseWithRetry(url, options, 0)
}
async function fetchServerResponseWithRetry(
url: URL,
options: FetchServerResponseOptions,
retryCount: number
): Promise<FetchServerResponseResult> { ): Promise<FetchServerResponseResult> {
const { flightRouterState, nextUrl } = options const { flightRouterState, nextUrl } = options
...@@ -299,42 +306,15 @@ export async function fetchServerResponse( ...@@ -299,42 +306,15 @@ export async function fetchServerResponse(
debugInfo: flightResponsePromise._debugInfo ?? null, debugInfo: flightResponsePromise._debugInfo ?? null,
} }
} catch (err) { } catch (err) {
// Check if this is a chunk/network error that we can retry
if ( if (
err instanceof Error && err instanceof Error &&
isChunkOrNetworkError(err) && isChunkOrNetworkError(err) &&
!isPageUnloading !isPageUnloading &&
retryCount < MAX_RSC_FETCH_RETRIES
) { ) {
const ctx = createChunkErrorContext( // Retry once after a jittered delay for transient failures.
err, await sleep(getRetryDelayMs())
originalUrl.pathname, return fetchServerResponseWithRetry(originalUrl, options, retryCount + 1)
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()
}
}
}
} }
if (!isPageUnloading) { if (!isPageUnloading) {
......
...@@ -56,7 +56,6 @@ import { ...@@ -56,7 +56,6 @@ import {
writeHeadToBFCache, writeHeadToBFCache,
} from '../segment-cache/bfcache' } from '../segment-cache/bfcache'
import { DYNAMIC_STALETIME_MS } from './reducers/navigate-reducer' 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 // 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 // need to be fulfilled once the dynamic data is received. The terminal nodes of
...@@ -1365,9 +1364,6 @@ async function finishNavigationTask( ...@@ -1365,9 +1364,6 @@ async function finishNavigationTask(
case NavigationTaskExitStatus.Done: { case NavigationTaskExitStatus.Done: {
// The task has completely finished. There's no missing data. Exit. // The task has completely finished. There's no missing data. Exit.
previousNavigationDidMismatch = false previousNavigationDidMismatch = false
// Clear failure state for the successfully navigated route
const primaryRequestResult = await primaryRequestPromise
clearFailureState(primaryRequestResult.url.pathname)
return return
} }
case NavigationTaskExitStatus.SoftRetry: { case NavigationTaskExitStatus.SoftRetry: {
...@@ -1377,8 +1373,6 @@ async function finishNavigationTask( ...@@ -1377,8 +1373,6 @@ async function finishNavigationTask(
// happen in a row, fall back to a hard retry. // happen in a row, fall back to a hard retry.
const isHardRetry = false const isHardRetry = false
const primaryRequestResult = await primaryRequestPromise const primaryRequestResult = await primaryRequestPromise
// Clear failure state for the route we're retrying to give it another chance
clearFailureState(primaryRequestResult.url.pathname)
dispatchRetryDueToTreeMismatch( dispatchRetryDueToTreeMismatch(
isHardRetry, isHardRetry,
primaryRequestResult.url, primaryRequestResult.url,
...@@ -1401,8 +1395,6 @@ async function finishNavigationTask( ...@@ -1401,8 +1395,6 @@ async function finishNavigationTask(
// doesn't exist yet. // doesn't exist yet.
const isHardRetry = true const isHardRetry = true
const primaryRequestResult = await primaryRequestPromise const primaryRequestResult = await primaryRequestPromise
// Clear failure state for the route we're retrying to give it another chance
clearFailureState(primaryRequestResult.url.pathname)
dispatchRetryDueToTreeMismatch( dispatchRetryDueToTreeMismatch(
isHardRetry, isHardRetry,
primaryRequestResult.url, primaryRequestResult.url,
......
...@@ -3,7 +3,10 @@ import { BailoutToCSR } from './dynamic-bailout-to-csr' ...@@ -3,7 +3,10 @@ import { BailoutToCSR } from './dynamic-bailout-to-csr'
import type { ComponentModule } from './types' import type { ComponentModule } from './types'
import { PreloadChunks } from './preload-chunks' import { PreloadChunks } from './preload-chunks'
import { isChunkLoadError } from '../../../client/components/chunk-load-error/is-chunk-load-error' 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`. // 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 // Also for backward compatible since next/dynamic allows to resolve a component directly with loader
...@@ -32,30 +35,18 @@ function convertModule<P>( ...@@ -32,30 +35,18 @@ function convertModule<P>(
* On first failure, retries once after a delay. * On first failure, retries once after a delay.
*/ */
function createRetryableLoader<T>(loader: () => Promise<T>): () => Promise<T> { function createRetryableLoader<T>(loader: () => Promise<T>): () => Promise<T> {
let hasRetried = false return async () => {
try {
return () => return await loader()
loader().catch((err) => { } catch (err) {
// Only retry chunk load errors, and only once if (typeof window !== 'undefined' && isChunkLoadError(err)) {
if ( await sleep(getRetryDelayMs())
typeof window !== 'undefined' && return loader()
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)
})
} }
// No retry - propagate error
throw err throw err
}) }
}
} }
const defaultOptions = { const defaultOptions = {
......
...@@ -25,7 +25,10 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE ...@@ -25,7 +25,10 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
import React from 'react' import React from 'react'
import { LoadableContext } from './loadable-context.shared-runtime' import { LoadableContext } from './loadable-context.shared-runtime'
import { isChunkLoadError } from '../../client/components/chunk-load-error/is-chunk-load-error' 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) { function resolve(obj: any) {
return obj && obj.default ? obj.default : obj return obj && obj.default ? obj.default : obj
...@@ -35,8 +38,19 @@ const ALL_INITIALIZERS: any[] = [] ...@@ -35,8 +38,19 @@ const ALL_INITIALIZERS: any[] = []
const READY_INITIALIZERS: any[] = [] const READY_INITIALIZERS: any[] = []
let initialized = false 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) { function load(loader: any) {
let promise = loader() let promise = retryChunkLoadErrorOnce(loader)
let state: any = { let state: any = {
loading: true, loading: true,
...@@ -169,14 +183,12 @@ class LoadableSubscription { ...@@ -169,14 +183,12 @@ class LoadableSubscription {
_timeout: any _timeout: any
_res: any _res: any
_state: any _state: any
_hasAutoRetried: boolean
constructor(loadFn: any, opts: any) { constructor(loadFn: any, opts: any) {
this._loadFn = loadFn this._loadFn = loadFn
this._opts = opts this._opts = opts
this._callbacks = new Set() this._callbacks = new Set()
this._delay = null this._delay = null
this._timeout = null this._timeout = null
this._hasAutoRetried = false
this.retry() this.retry()
} }
...@@ -221,31 +233,9 @@ class LoadableSubscription { ...@@ -221,31 +233,9 @@ class LoadableSubscription {
this._update({}) this._update({})
this._clearTimeouts() this._clearTimeouts()
}) })
.catch((err: any) => { .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
this._update({}) this._update({})
this._clearTimeouts() this._clearTimeouts()
throw err
}) })
this._update({}) this._update({})
} }
......
...@@ -27,10 +27,12 @@ describe('chunk-load-failure', () => { ...@@ -27,10 +27,12 @@ describe('chunk-load-failure', () => {
it('should report async chunk load failures', async () => { it('should report async chunk load failures', async () => {
let nextDynamicChunk = await getNextDynamicChunk() let nextDynamicChunk = await getNextDynamicChunk()
let chunkRequestCount = 0
let pageError: Error | undefined let pageError: Error | undefined
const browser = await next.browser('/dynamic', { const browser = await next.browser('/dynamic', {
beforePageLoad(page) { beforePageLoad(page) {
page.route(`**/${nextDynamicChunk}*`, async (route) => { page.route(`**/${nextDynamicChunk}*`, async (route) => {
chunkRequestCount++
await route.abort('connectionreset') await route.abort('connectionreset')
}) })
page.on('pageerror', (error: Error) => { page.on('pageerror', (error: Error) => {
...@@ -45,6 +47,8 @@ describe('chunk-load-failure', () => { ...@@ -45,6 +47,8 @@ describe('chunk-load-failure', () => {
expect(await body.text()).toMatch(/This page couldn\u2019t load/) 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).toBeDefined()
expect(pageError.name).toBe('ChunkLoadError') expect(pageError.name).toBe('ChunkLoadError')
if (process.env.IS_TURBOPACK_TEST) { if (process.env.IS_TURBOPACK_TEST) {
...@@ -88,7 +92,8 @@ describe('chunk-load-failure', () => { ...@@ -88,7 +92,8 @@ describe('chunk-load-failure', () => {
) )
expect(await browser.eval('window.__TEST_NO_RELOAD')).toBe(true) 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 () => { it('should recover after a transient async chunk load failure', async () => {
...@@ -123,7 +128,8 @@ describe('chunk-load-failure', () => { ...@@ -123,7 +128,8 @@ describe('chunk-load-failure', () => {
250 250
) )
expect(chunkRequestCount).toBeGreaterThanOrEqual(2) // One initial request + one retry attempt.
expect(chunkRequestCount).toBe(2)
expect(pageError).toBeUndefined() expect(pageError).toBeUndefined()
}) })
......
...@@ -70,6 +70,12 @@ async function readFilesBuilder( ...@@ -70,6 +70,12 @@ async function readFilesBuilder(
functions.map(async (fn) => { functions.map(async (fn) => {
let config = await next.readJSON(fn) let config = await next.readJSON(fn)
let fnDir = path.dirname(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 = [ let files = [
...( ...(
await glob('**/*', { await glob('**/*', {
...@@ -79,7 +85,7 @@ async function readFilesBuilder( ...@@ -79,7 +85,7 @@ async function readFilesBuilder(
ignore: ['.vc-config.json'], ignore: ['.vc-config.json'],
}) })
).map((f) => path.join(fnDir, f)), ).map((f) => path.join(fnDir, f)),
...Object.values(config.filePathMap), ...filePathMapValues,
] as string[] ] as string[]
files.sort() files.sort()
return [ 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