[turbopack] Retry chunk loading on failure (vercel#94918)

This is a trimmed down PR from
vercel#88107, it achieves the same thing
(with much of the same code). However, it is Turbopack-only. This is
because the Webpack portions of that PR required patching React - we can
return to this in a different PR or I guess people could use a plugin?
(https://github.com/mattlewis92/webpack-retry-chunk-load-plugin)

---------

Co-authored-by: Jimmy Lai <laijimmy0@gmail.com>

Author: sampoder

crates/next-core/src/next_client/context.rs

@@ -14,8 +14,8 @@ use turbopack_browser::{
 };
 use turbopack_core::{
     chunk::{
-        AssetSuffix, ChunkingConfig, ChunkingContext, ContentHashing, CrossOrigin, MangleType,
-        MinifyType, SourceMapSourceType, SourceMapsType, UnusedReferences, UrlBehavior,
+        AssetSuffix, ChunkLoadRetry, ChunkingConfig, ChunkingContext, ContentHashing, CrossOrigin,
+        MangleType, MinifyType, SourceMapSourceType, SourceMapsType, UnusedReferences, UrlBehavior,
         chunk_id_strategy::ModuleIdStrategy,
     },
     compile_time_info::{CompileTimeDefines, CompileTimeInfo, FreeVarReference, FreeVarReferences},
@@ -483,6 +483,14 @@ pub struct ClientChunkingContextOptions {
     pub style_groups_algorithm: StyleGroupsAlgorithm,
 }
 
+/// Next.js' chunk-load retry policy for the Turbopack browser runtime.
+/// Webpack does not currently support chunk-load retrying.
+const NEXT_CHUNK_LOAD_RETRY: ChunkLoadRetry = ChunkLoadRetry {
+    max_retry_attempts: 1,
+    base_delay_ms: 200,
+    max_jitter_ms: 400,
+};
+
 #[turbo_tasks::function]
 pub async fn get_client_chunking_context(
     options: ClientChunkingContextOptions,
@@ -543,6 +551,7 @@ pub async fn get_client_chunking_context(
     .asset_base_path(Some(asset_prefix))
     .current_chunk_method(CurrentChunkMethod::DocumentCurrentScript)
     .cross_origin(cross_origin_loading)
+    .chunk_load_retry(NEXT_CHUNK_LOAD_RETRY)
     .export_usage(*export_usage.await?)
     .unused_references(unused_references.to_resolved().await?)
     .module_id_strategy(module_id_strategy.to_resolved().await?)

test/production/chunk-load-failure/chunk-load-failure.test.ts

@@ -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) => {
@@ -48,15 +50,61 @@ describe('chunk-load-failure', () => {
     expect(pageError).toBeDefined()
     expect(pageError.name).toBe('ChunkLoadError')
     if (process.env.IS_TURBOPACK_TEST) {
+      // Turbopack retries a failed chunk load once before giving up: one initial
+      // request plus one retry.
+      expect(chunkRequestCount).toBe(2)
       expect(pageError.message).toStartWith(
         'Failed to load chunk /_next/' + nextDynamicChunk
       )
     } else {
+      // Webpack does not retry yet, so the failure surfaces on the first request.
+      expect(chunkRequestCount).toBe(1)
       expect(pageError.message).toMatch(/^Loading chunk \S+ failed./)
       expect(pageError.message).toContain('/_next/' + nextDynamicChunk)
     }
   })
 
+  // Turbopack-only: webpack does not retry chunk loads yet, so a transient
+  // failure there surfaces immediately as a ChunkLoadError.
+  /* eslint-disable jest/no-standalone-expect */
+  ;(process.env.IS_TURBOPACK_TEST ? it : it.skip)(
+    'should recover after a transient async chunk load failure',
+    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++
+            // Fail only the first attempt; let the retry through.
+            if (chunkRequestCount === 1) {
+              await route.abort('connectionreset')
+              return
+            }
+            await route.continue()
+          })
+          page.on('pageerror', (error: Error) => {
+            pageError = error
+          })
+        },
+      })
+
+      await retry(async () => {
+        const body = await browser.elementByCss('body')
+        expect(await body.text()).toContain(
+          'this is a lazy loaded async component'
+        )
+      })
+
+      // One initial request that failed + one retry that succeeded.
+      expect(chunkRequestCount).toBe(2)
+      expect(pageError).toBeUndefined()
+    }
+  )
+  /* eslint-enable jest/no-standalone-expect */
+
   it('should report aborted chunks when navigating away', async () => {
     let nextDynamicChunk = await getNextDynamicChunk()
 

turbopack/crates/turbopack-browser/src/chunking_context.rs

@@ -7,9 +7,9 @@ use turbo_tasks_hash::HashAlgorithm;
 use turbopack_core::{
     asset::{Asset, AssetContent},
     chunk::{
-        AssetSuffix, Chunk, ChunkGroupResult, ChunkItem, ChunkType, ChunkableModule,
-        ChunkingConfig, ChunkingConfigs, ChunkingContext, ContentHashing, CrossOrigin,
-        EntryChunkGroupResult, EvaluatableAsset, EvaluatableAssets, MinifyType,
+        AssetSuffix, Chunk, ChunkGroupResult, ChunkItem, ChunkLoadRetry, ChunkType,
+        ChunkableModule, ChunkingConfig, ChunkingConfigs, ChunkingContext, ContentHashing,
+        CrossOrigin, EntryChunkGroupResult, EvaluatableAsset, EvaluatableAssets, MinifyType,
         SourceMapSourceType, SourceMapsType, UnusedReferences, UrlBehavior,
         WorkerConfigurationOptions,
         availability_info::AvailabilityInfo,
@@ -230,6 +230,11 @@ impl BrowserChunkingContextBuilder {
         self
     }
 
+    pub fn chunk_load_retry(mut self, chunk_load_retry: ChunkLoadRetry) -> Self {
+        self.chunking_context.chunk_load_retry = chunk_load_retry;
+        self
+    }
+
     pub fn build(self) -> Vc<BrowserChunkingContext> {
         BrowserChunkingContext::cell(self.chunking_context)
     }
@@ -336,6 +341,8 @@ pub struct BrowserChunkingContext {
     hash_salt: ResolvedVc<RcStr>,
     /// The crossorigin mode for dynamically loaded chunks.
     cross_origin: CrossOrigin,
+    /// The retry policy for transient chunk load failures in the browser runtime.
+    chunk_load_retry: ChunkLoadRetry,
 }
 
 impl BrowserChunkingContext {
@@ -390,6 +397,7 @@ impl BrowserChunkingContext {
                 chunk_loading_global: Default::default(),
                 hash_salt: ResolvedVc::cell(RcStr::default()),
                 cross_origin: Default::default(),
+                chunk_load_retry: Default::default(),
             },
         }
     }
@@ -524,6 +532,11 @@ impl BrowserChunkingContext {
     pub fn cross_origin(&self) -> Vc<CrossOrigin> {
         self.cross_origin.cell()
     }
+
+    #[turbo_tasks::function]
+    pub fn chunk_load_retry(&self) -> Vc<ChunkLoadRetry> {
+        self.chunk_load_retry.cell()
+    }
 }
 
 #[turbo_tasks::value_impl]

turbopack/crates/turbopack-browser/src/ecmascript/evaluate/chunk.rs

@@ -192,6 +192,7 @@ impl EcmascriptBrowserEvaluateChunk {
                     source_maps,
                     this.chunking_context.chunk_loading_global(),
                     this.chunking_context.cross_origin(),
+                    this.chunking_context.chunk_load_retry(),
                     has_async_modules,
                 );
                 code.push_code(&*runtime_code.await?);

turbopack/crates/turbopack-core/src/chunk/mod.rs

@@ -98,6 +98,30 @@ impl TryFrom<Option<&str>> for CrossOrigin {
     }
 }
 
+#[turbo_tasks::value(shared)]
+#[derive(Debug, Clone, Copy, Hash, Serialize, Deserialize)]
+pub struct ChunkLoadRetry {
+    /// Number of retry attempts after the initial load fails. `0` disables retries.
+    pub max_retry_attempts: u32,
+    /// Base delay before a retry, in milliseconds.
+    pub base_delay_ms: u32,
+    /// Maximum random jitter added to the base delay, in milliseconds.
+    pub max_jitter_ms: u32,
+}
+
+impl Default for ChunkLoadRetry {
+    fn default() -> Self {
+        // Retry a transient failure once after a short jittered delay. Network
+        // blips (a brief connection reset, a short CDN hiccup) often succeed on
+        // a second try.
+        Self {
+            max_retry_attempts: 1,
+            base_delay_ms: 200,
+            max_jitter_ms: 400,
+        }
+    }
+}
+
 /// A module id, which can be a number or string
 #[turbo_tasks::value(shared, operation)]
 #[derive(Debug, Clone, Hash, Ord, PartialOrd, DeterministicHash, Serialize, ValueToString)]

turbopack/crates/turbopack-ecmascript-runtime/js/src/browser/runtime/base/runtime-base.ts

@@ -22,6 +22,9 @@ declare var TURBOPACK_NEXT_CHUNK_URLS: ChunkUrl[] | undefined
 declare var CHUNK_BASE_PATH: string
 declare var ASSET_SUFFIX: string
 declare var CROSS_ORIGIN: 'anonymous' | 'use-credentials' | null
+declare var CHUNK_LOAD_RETRY_MAX_ATTEMPTS: number
+declare var CHUNK_LOAD_RETRY_BASE_DELAY_MS: number
+declare var CHUNK_LOAD_RETRY_MAX_JITTER_MS: number
 
 interface TurbopackBrowserBaseContext<M> extends TurbopackBaseContext<M> {
   R: ResolvePathFromModule

turbopack/crates/turbopack-ecmascript-runtime/js/src/browser/runtime/dom/runtime-backend-dom.ts

@@ -20,6 +20,7 @@ function getAssetSuffixFromScriptSrc() {
 type ChunkResolver = {
   resolved: boolean
   loadingStarted: boolean
+  retryAttempts: number
   resolve: () => void
   reject: (error?: Error) => void
   promise: Promise<any>
@@ -88,6 +89,7 @@ const chunkResolvers: Map<ChunkUrl, ChunkResolver> = new Map()
       resolver = {
         resolved: false,
         loadingStarted: false,
+        retryAttempts: 0,
         promise,
         resolve: () => {
           resolver!.resolved = true
@@ -100,6 +102,72 @@ const chunkResolvers: Map<ChunkUrl, ChunkResolver> = new Map()
     return resolver
   }
 
+  /**
+   * Rejects a chunk resolver and drops it from the cache.
+   * We don't want to cache failed chunk loads: a later
+   * request for the same chunk should try again.
+   */
+  function rejectChunkResolver(
+    chunkUrl: ChunkUrl,
+    resolver: ChunkResolver,
+    error?: Error
+  ) {
+    if (chunkResolvers.get(chunkUrl) === resolver) {
+      chunkResolvers.delete(chunkUrl)
+    }
+    resolver.reject(error)
+  }
+
+  function getChunkLoadRetryDelayMs() {
+    const jitter = Math.floor(
+      Math.random() * (CHUNK_LOAD_RETRY_MAX_JITTER_MS + 1)
+    )
+    return CHUNK_LOAD_RETRY_BASE_DELAY_MS + jitter
+  }
+
+  function isRetryableChunkLoadError(error?: Error): boolean {
+    return (
+      error == null ||
+      (error instanceof DOMException && error.name === 'NetworkError')
+    )
+  }
+
+  /**
+   * Handles a failed chunk load: retries the load once after a short delay.
+   */
+  function onChunkLoadError(
+    sourceType: SourceType,
+    chunkUrl: ChunkUrl,
+    resolver: ChunkResolver,
+    error?: Error,
+    reload?: () => void
+  ) {
+    if (
+      !isRetryableChunkLoadError(error) ||
+      resolver.retryAttempts >= CHUNK_LOAD_RETRY_MAX_ATTEMPTS ||
+      chunkResolvers.get(chunkUrl) !== resolver
+    ) {
+      rejectChunkResolver(chunkUrl, resolver, error)
+      return
+    }
+
+    resolver.retryAttempts++
+    setTimeout(() => {
+      // if this chunk is being fetched multiple times, and one of those
+      // attempts succeeds. or, if this chunk has another resolver
+      // mapped to it - it's safe to skip retrying.
+      if (resolver.resolved || chunkResolvers.get(chunkUrl) !== resolver) {
+        return
+      }
+      if (reload) {
+        reload()
+      } else {
+        resolver.loadingStarted = false
+        doLoadChunk(sourceType, chunkUrl)
+      }
+    }, getChunkLoadRetryDelayMs())
+  }
+
   /**
    * Loads the given chunk, and returns a promise that resolves once the chunk
    * has been loaded.
@@ -134,7 +202,11 @@ const chunkResolvers: Map<ChunkUrl, ChunkResolver> = new Map()
         // ignore
       } else if (isJs(chunkUrl)) {
         self.TURBOPACK_NEXT_CHUNK_URLS!.push(chunkUrl)
-        importScripts(chunkUrl)
+        try {
+          importScripts(chunkUrl)
+        } catch (error) {
+          onChunkLoadError(sourceType, chunkUrl, resolver, error as Error)
+        }
       } else {
         throw new Error(
           `can't infer type of chunk from URL ${chunkUrl} in worker`
@@ -153,32 +225,45 @@ const chunkResolvers: Map<ChunkUrl, ChunkResolver> = new Map()
           // loaded instantly.
           resolver.resolve()
         } else {
-          const link = document.createElement('link')
-          link.rel = 'stylesheet'
-          link.crossOrigin = CROSS_ORIGIN
-          link.href = chunkUrl
-          link.onerror = () => {
-            resolver.reject()
-          }
-          link.onload = () => {
-            // CSS chunks do not register themselves, and as such must be marked as
-            // loaded instantly.
-            resolver.resolve()
+          const createLink = () => {
+            const link = document.createElement('link')
+            link.rel = 'stylesheet'
+            link.crossOrigin = CROSS_ORIGIN
+            link.href = chunkUrl
+            link.onerror = () => {
+              // Re-insert a fresh tag at the same position on retry to preserve
+              // cascade order.
+              const anchor = document.createComment('')
+              link.replaceWith(anchor)
+              onChunkLoadError(sourceType, chunkUrl, resolver, undefined, () =>
+                anchor.replaceWith(createLink())
+              )
+            }
+            link.onload = () => {
+              // CSS chunks do not register themselves, and as such must be marked as
+              // loaded instantly.
+              resolver.resolve()
+            }
+            return link
           }
           // Append to the `head` for webpack compatibility.
-          document.head.appendChild(link)
+          document.head.appendChild(createLink())
         }
       } else if (isJs(chunkUrl)) {
         const previousScripts = document.querySelectorAll(
           `script[src="${chunkUrl}"],script[src^="${chunkUrl}?"],script[src="${decodedChunkUrl}"],script[src^="${decodedChunkUrl}?"]`
         )
         if (previousScripts.length > 0) {
-          // There is this edge where the script already failed loading, but we
-          // can't detect that. The Promise will never resolve in this case.
           for (const script of Array.from(previousScripts)) {
-            script.addEventListener('error', () => {
-              resolver.reject()
-            })
+            script.addEventListener(
+              'error',
+              () => {
+                // Drop the failed tag so a retry can re-add it cleanly.
+                script.remove()
+                onChunkLoadError(sourceType, chunkUrl, resolver)
+              },
+              { once: true }
+            )
           }
         } else {
           const script = document.createElement('script')
@@ -188,7 +273,9 @@ const chunkResolvers: Map<ChunkUrl, ChunkResolver> = new Map()
           // which happens in `registerChunk`. Hence the absence of `resolve()` in
           // this branch.
           script.onerror = () => {
-            resolver.reject()
+            // Drop the failed tag so a retry can re-add it cleanly.
+            script.remove()
+            onChunkLoadError(sourceType, chunkUrl, resolver)
           }
           // Append to the `head` for webpack compatibility.
           document.head.appendChild(script)