feat(runtime): add loadEntryTimeout option for the remote entry script timeout

Author: marksnode

.changeset/patient-remote-entry-timeout.md

@@ -0,0 +1,6 @@
+---
+'@module-federation/sdk': patch
+'@module-federation/runtime-core': patch
+---
+
+feat: `loadEntryTimeout` runtime option — how long a remote entry script may take to load before it fails with RUNTIME-008 (default 20000 ms, `Infinity` disables the timer); `createScript` / `loadScript` accept a `timeout` and a `createScript` hook return value still overrides it; when set, the option also bounds the fetch of a manifest entry

apps/website-new/docs/en/guide/runtime/runtime-api.mdx

@@ -41,6 +41,12 @@ const mf = createInstance({
 mf.loadRemote('sub1/util').then((m) => m.add(1, 2, 3));
 ```
 
+**Options**
+
+Besides `name`, `remotes`, `shared`, `plugins` and `shareStrategy`, the instance accepts:
+
+- `loadEntryTimeout` — how long (ms) a remote entry script may take to load before the load fails with `RUNTIME-008`. Defaults to `20000`; pass `Infinity` to wait indefinitely. A `createScript` hook that returns `timeout` still takes precedence. When set, the same limit bounds the fetch of a manifest entry (`mf-manifest.json`), which has no timeout by default.
+
 ## init <Badge type='warning'>Use with caution</Badge>
 
 Used to initialize or reuse a `ModuleFederation` runtime instance.

apps/website-new/docs/zh/guide/runtime/runtime-api.mdx

@@ -41,6 +41,12 @@ const mf = createInstance({
 mf.loadRemote('sub1/util').then((m) => m.add(1, 2, 3));
 ```
 
+**配置项**
+
+除了 `name`、`remotes`、`shared`、`plugins` 和 `shareStrategy`，实例还接受：
+
+- `loadEntryTimeout` — 远程入口脚本的加载超时时间（毫秒），超时后以 `RUNTIME-008` 报错。默认 `20000`；传 `Infinity` 表示不限时。`createScript` 钩子返回的 `timeout` 仍然优先。设置后，同一时限也会约束 manifest 入口（`mf-manifest.json`）的请求，默认情况下该请求没有超时。
+
 ## init <Badge type='warning'>谨慎使用</Badge>
 
 用于初始化或复用 `ModuleFederation` 运行时实例。

packages/runtime-core/__tests__/load.spec.ts

@@ -126,6 +126,53 @@ describe('getRemoteEntry - script load error discrimination', () => {
     );
   });
 
+  it('passes loadEntryTimeout to the entry script loader', async () => {
+    const entry = `${BASE}/success.js`;
+    const origin = new ModuleFederation({
+      name: 'test-host',
+      remotes: [],
+      loadEntryTimeout: 45000,
+    });
+    const remoteInfo = getRemoteInfo({ name: 'remote', entry });
+    const setTimeoutSpy = rs.spyOn(globalThis, 'setTimeout');
+
+    try {
+      await getRemoteEntry({ origin, remoteInfo });
+      expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 45000);
+      expect(setTimeoutSpy).not.toHaveBeenCalledWith(
+        expect.any(Function),
+        20000,
+      );
+    } finally {
+      setTimeoutSpy.mockRestore();
+    }
+  });
+
+  it('does not arm the entry timer when loadEntryTimeout is Infinity', async () => {
+    const entry = `${BASE}/success.js`;
+    const origin = new ModuleFederation({
+      name: 'test-host',
+      remotes: [],
+      loadEntryTimeout: Infinity,
+    });
+    const remoteInfo = getRemoteInfo({ name: 'remote', entry });
+    const setTimeoutSpy = rs.spyOn(globalThis, 'setTimeout');
+
+    try {
+      await getRemoteEntry({ origin, remoteInfo });
+      expect(setTimeoutSpy).not.toHaveBeenCalledWith(
+        expect.any(Function),
+        20000,
+      );
+      expect(setTimeoutSpy).not.toHaveBeenCalledWith(
+        expect.any(Function),
+        Infinity,
+      );
+    } finally {
+      setTimeoutSpy.mockRestore();
+    }
+  });
+
   it('module entry load failure can recover through loadEntryError with getEntryUrl', async () => {
     const entry = createDataUrlEntry(
       `throw new TypeError('Failed to fetch dynamically imported module: http://localhost:4999/remoteEntry.js');`,

packages/runtime-core/__tests__/snapshot.spec.ts

@@ -1,4 +1,4 @@
-import { assert, describe, it } from '@rstest/core';
+import { assert, describe, it, rs } from '@rstest/core';
 import { ModuleFederation } from '../src';
 import { getGlobalSnapshot, resetFederationGlobalInfo } from '../src/global';
 
@@ -46,4 +46,54 @@ describe('snapshot', () => {
       },
     });
   });
+  describe('manifest fetch and loadEntryTimeout', () => {
+    const Remote1Entry =
+      'http://localhost:1111/resources/snapshot/remote1/federation-manifest.json';
+
+    const withFetchSpy = async (
+      loadEntryTimeout: number | undefined,
+      run: (seen: Array<RequestInit | undefined>) => Promise<void>,
+    ) => {
+      const originalFetch = global.fetch;
+      const seen: Array<RequestInit | undefined> = [];
+      global.fetch = ((url: RequestInfo | URL, init?: RequestInit) => {
+        seen.push(init);
+        return originalFetch(url, init);
+      }) as typeof fetch;
+      try {
+        const FM = new ModuleFederation({
+          name: '@snapshot/host-timeout',
+          remotes: [{ name: '@snapshot/remote1', entry: Remote1Entry }],
+          ...(loadEntryTimeout === undefined ? {} : { loadEntryTimeout }),
+        });
+        await FM.loadRemote<() => string>('@snapshot/remote1/say');
+        await run(seen);
+      } finally {
+        global.fetch = originalFetch;
+      }
+    };
+
+    it('bounds the manifest fetch with loadEntryTimeout', async () => {
+      const setTimeoutSpy = rs.spyOn(globalThis, 'setTimeout');
+      try {
+        await withFetchSpy(4321, async (seen) => {
+          expect(seen.length).toBeGreaterThan(0);
+          expect(seen[0]?.signal).toBeInstanceOf(AbortSignal);
+          expect(setTimeoutSpy).toHaveBeenCalledWith(
+            expect.any(Function),
+            4321,
+          );
+        });
+      } finally {
+        setTimeoutSpy.mockRestore();
+      }
+    });
+
+    it('leaves the manifest fetch unbounded without loadEntryTimeout', async () => {
+      await withFetchSpy(undefined, async (seen) => {
+        expect(seen.length).toBeGreaterThan(0);
+        expect(seen[0]?.signal).toBeUndefined();
+      });
+    });
+  });
 });

packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts

@@ -356,10 +356,32 @@ export class SnapshotHandler {
       let loadError: unknown;
       let recovered = false;
 
+      // `loadEntryTimeout` bounds the manifest fetch the same way it bounds the entry script:
+      // a stalled manifest response would otherwise hold `loadRemote` open indefinitely.
+      const timeout = this.HostInstance.options.loadEntryTimeout;
+      const controller =
+        typeof AbortController === 'function' &&
+        typeof timeout === 'number' &&
+        Number.isFinite(timeout) &&
+        timeout > 0
+          ? new AbortController()
+          : undefined;
+      const fetchInit: RequestInit = controller
+        ? { signal: controller.signal }
+        : {};
+      const timer = controller
+        ? setTimeout(() => controller.abort(), timeout)
+        : undefined;
+      const clearTimer = () => {
+        if (timer !== undefined) {
+          clearTimeout(timer);
+        }
+      };
+
       try {
         let res = await this.loaderHook.lifecycle.fetch.emit(
           manifestUrl,
-          {},
+          fetchInit,
           remoteInfo,
           resourceOptions
             ? {
@@ -370,11 +392,13 @@ export class SnapshotHandler {
             : undefined,
         );
         if (!res || !(res instanceof Response)) {
-          res = await fetch(manifestUrl, {});
+          res = await fetch(manifestUrl, fetchInit);
         }
         response = res;
         manifestJson = (await res.json()) as Manifest;
+        clearTimer();
       } catch (err) {
+        clearTimer();
         loadError = err;
         manifestJson =
           (await this.HostInstance.remoteHandler.hooks.lifecycle.errorLoadRemote.emit(

packages/runtime-core/src/type/config.ts

@@ -141,6 +141,12 @@ export interface Options {
   plugins: Array<ModuleFederationRuntimePlugin>;
   inBrowser: boolean;
   shareStrategy?: ShareStrategy;
+  /**
+   * How long (ms) a remote entry script may take to load before it is reported as RUNTIME-008.
+   * Defaults to 20000; `Infinity` disables the timer. A `createScript` hook returning `timeout` still wins.
+   * When set, it also bounds the fetch of a manifest entry (`mf-manifest.json`), which is otherwise unbounded.
+   */
+  loadEntryTimeout?: number;
 }
 
 export type UserOptions = Omit<

packages/runtime-core/src/utils/load.ts

@@ -165,6 +165,7 @@ async function loadEntryScript({
   loaderHook,
   getEntryUrl,
   resourceContext,
+  timeout,
 }: {
   name: string;
   globalName: string;
@@ -173,6 +174,7 @@ async function loadEntryScript({
   loaderHook: ModuleFederation['loaderHook'];
   getEntryUrl?: (url: string) => string;
   resourceContext?: ResourceLoadContext;
+  timeout?: number;
 }): Promise<RemoteEntryExports> {
   const { entryExports: remoteEntryExports } = getRemoteEntryExports(
     name,
@@ -187,6 +189,7 @@ async function loadEntryScript({
   const url = getEntryUrl ? getEntryUrl(entry) : entry;
   return loadScript(url, {
     attrs: {},
+    timeout,
     createScriptHook: (url, attrs) => {
       const res = loaderHook.lifecycle.createScript.emit({
         url,
@@ -244,12 +247,14 @@ async function loadEntryDom({
   loaderHook,
   getEntryUrl,
   resourceContext,
+  timeout,
 }: {
   remoteInfo: RemoteInfo;
   remoteEntryExports?: RemoteEntryExports;
   loaderHook: ModuleFederation['loaderHook'];
   getEntryUrl?: (url: string) => string;
   resourceContext?: ResourceLoadContext;
+  timeout?: number;
 }) {
   const { entry, entryGlobalName: globalName, name, type } = remoteInfo;
   if (isEsmRemoteType(type)) {
@@ -268,6 +273,7 @@ async function loadEntryDom({
     loaderHook,
     getEntryUrl,
     resourceContext,
+    timeout,
   });
 }
 
@@ -388,6 +394,7 @@ export async function getRemoteEntry(params: {
               loaderHook,
               getEntryUrl,
               resourceContext,
+              timeout: origin.options.loadEntryTimeout,
             })
           : loadEntryNode({ remoteInfo, loaderHook, resourceContext });
       })

packages/runtime-core/src/utils/preload.ts

@@ -233,6 +233,7 @@ function waitForScriptPreload({
         );
       },
       attrs,
+      timeout: host.options.loadEntryTimeout,
       createScriptHook: (hookUrl: string, hookAttrs: any) => {
         const res = host.loaderHook.lifecycle.createScript.emit({
           url: hookUrl,

packages/sdk/__tests__/dom.spec.ts

@@ -86,6 +86,36 @@ describe('createScript', () => {
       expect(setTimeout).toHaveBeenCalledWith(expect.any(Function), 20000);
     });
 
+    it('should use the timeout passed to createScript', () => {
+      const url = 'https://example.com/script.js';
+      const cb = jest.fn();
+      createScript({ url, cb, timeout: 45000 });
+
+      expect(setTimeout).toHaveBeenCalledWith(expect.any(Function), 45000);
+    });
+
+    it('should let the createScriptHook timeout override the passed timeout', () => {
+      const url = 'https://example.com/script.js';
+      const cb = jest.fn();
+      createScript({
+        url,
+        cb,
+        attrs: {},
+        timeout: 45000,
+        createScriptHook: () => ({ timeout: 5000 }),
+      });
+
+      expect(setTimeout).toHaveBeenCalledWith(expect.any(Function), 5000);
+    });
+
+    it('should not start a timer when the timeout is Infinity', () => {
+      const url = 'https://example.com/script.js';
+      const cb = jest.fn();
+      createScript({ url, cb, timeout: Infinity });
+
+      expect(setTimeout).not.toHaveBeenCalled();
+    });
+
     it('should use the timeout specified in the createScriptHook', () => {
       const url = 'https://example.com/script.js';
       const cb = jest.fn();