fix(bundler): re-install web globals after a V8 snapshot restore

The snapshot prelude deleted Node's web globals (fetch/Headers/Request/
Response/FormData/WebSocket/.../Blob/File) at build time to keep the heap
serializable, but never restored them, so `globalThis.fetch` was a dead
stub after restore.

The prelude now gates the delete to the snapshot build
(EGG_BUNDLE_SNAPSHOT=build, so a plain `node worker.js` keeps native globals)
and defines `__installWebGlobalsLazy`, which EntryGenerator's deserialize
main calls after installing `__RUNTIME_REQUIRE` (now exposing `.resolve`).
It re-installs the globals as lazy accessors: the fetch family from the
app's undici (resolved directly, or via urllib under pnpm), Blob/File from
node:buffer. The accessor must not cache `undefined`, because undici reads
`globalThis.Headers` re-entrantly while its own require() is in flight.

Also fixes four build-serializability gaps found bringing a real app
(cnpmcore) snapshot up, all build-gated in the prelude:

- supply module/exports so the bundle's UMD external wrapper takes the
  require/externalRequire branch (`node --build-snapshot` runs the worker
  as a non-CommonJS main, so `typeof module === 'undefined'`).
- keep Blob/File (node:buffer-backed, serializable); deleting them only
  broke build-eval (e.g. undici webidl's MakeTypeAssertion(Blob)).
- replace deleted globals with marked, extendable stub classes so a fetch
  ponyfill doing `class Request extends globalThis.Request` builds without
  crashing; the restore installer replaces the marked stub with the real value.
- expose the hardcoded http constants in the lazy proxy's ownKeys /
  getOwnPropertyDescriptor so an ESM `import * as http; for (const m of
  http.METHODS)` works (turbopack interopEsm copies a static namespace).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: killagu

packages/typings/src/global.ts

@@ -9,10 +9,24 @@ declare global {
    * Synchronous require bound to the bundle output directory, installed by the
    * snapshot restore main function. The snapshot prelude / lazy mechanism uses it
    * to pull in modules through `require()` (Node 22+ can `require()` ESM) because a
-   * deserialized snapshot process has no dynamic `import()` callback.
+   * deserialized snapshot process has no dynamic `import()` callback. It also
+   * carries a `resolve` (the underlying `createRequire(...).resolve`) so the web
+   * globals re-installer can locate `undici` through the app dependency tree.
    */
   // eslint-disable-next-line no-var
-  var __RUNTIME_REQUIRE: ((id: string) => unknown) | undefined;
+  var __RUNTIME_REQUIRE:
+    | (((id: string) => unknown) & { resolve?: (id: string, options?: { paths?: string[] }) => string })
+    | undefined;
+  /**
+   * Re-install the web globals (`fetch`/`Headers`/`Request`/`Response`/`FormData`/
+   * `WebSocket`/`Blob`/`File`/...) that the snapshot prelude deletes at build time,
+   * as lazy accessors backed by `undici` (the fetch family) and `node:buffer`
+   * (`Blob`/`File`). Defined by the snapshot prelude and serialized into the blob;
+   * the snapshot restore main calls it once `__RUNTIME_REQUIRE` is installed, so an
+   * app that uses `globalThis.fetch` keeps working after a restore.
+   */
+  // eslint-disable-next-line no-var
+  var __installWebGlobalsLazy: (() => void) | undefined;
 }
 
 export {};

site/docs/advanced/snapshot.md

@@ -73,3 +73,16 @@ module.exports = AppBootHook;
 - `snapshotDidDeserialize()` runs after the process starts from the snapshot.
 
 Use these hooks for resources such as timers, sockets, process listeners, loggers, or other handles that must be recreated in a live runtime.
+
+## Web Globals After Restore (bundled snapshots)
+
+When you build a bundled snapshot (`egg-bin snapshot build`, which uses `@eggjs/egg-bundler`), Node's **undici-backed** web globals — `fetch`, `Headers`, `Request`, `Response`, `FormData`, `WebSocket`, `EventSource`, `MessageEvent`, `CloseEvent` — are deleted at build time. Touching any of them lazily initializes undici, whose llhttp `HTTPParser` / `WebAssembly` instance is a native binding that cannot be written into a V8 startup snapshot. `Blob` and `File` are **not** deleted: they are `node:buffer`-backed, serialize into a snapshot fine, and deleting them would only break a dependency that touches them at load time.
+
+The deleted globals are re-installed automatically when the snapshot is restored, as lazy accessors backed by the application's `undici` (resolved directly, or through `urllib` — egg's direct dependency — under pnpm layouts where undici is not hoisted). `Blob` / `File` survive the snapshot natively and the installer also re-installs them from `node:buffer` as a safety net (skipped when already present).
+
+Each one loads its real implementation on first access, so a restore stays fast when the app never touches them, and `globalThis.fetch(...)` (or a bare `fetch(...)`) and the related constructors all work normally after restore.
+
+Two things to keep in mind:
+
+- The bundle output must be run where `undici` is resolvable. An egg app always satisfies this through its `urllib` dependency; if your deployment strips dependencies, keep `urllib` (or `undici`) installed next to the bundle.
+- Reference web globals at call time, not at module top level. During a snapshot build the deleted globals are replaced with extendable stub classes, so a module that does `class MyRequest extends globalThis.Request` at load time builds without crashing — but a binding captured at build time (`const f = fetch`, or a class that `extends` a web global) freezes that stub into the blob and is not upgraded at restore. Call `fetch(...)` / `new Headers(...)` where you use them and the lazy accessors resolve the real implementation after restore.

site/docs/zh-CN/advanced/snapshot.md

@@ -73,3 +73,16 @@ module.exports = AppBootHook;
 - `snapshotDidDeserialize()` 会在进程从快照启动后执行。
 
 这两个钩子适合处理 timer、socket、process listener、logger 等需要在真实运行期重新建立的资源。
+
+## 恢复后的 Web 全局对象（打包快照）
+
+当你构建打包快照时（`egg-bin snapshot build`，底层使用 `@eggjs/egg-bundler`），Node 中 **由 undici 支持**的 Web 全局对象——`fetch`、`Headers`、`Request`、`Response`、`FormData`、`WebSocket`、`EventSource`、`MessageEvent`、`CloseEvent`——会在构建阶段被删除。因为一旦触碰它们就会惰性初始化 undici，而其 llhttp `HTTPParser` / `WebAssembly` 实例属于原生绑定，无法写入 V8 启动快照。`Blob` 和 `File` **不会**被删除：它们由 `node:buffer` 支持，可以正常序列化到快照中，删除它们只会破坏在加载期触碰它们的依赖。
+
+被删除的全局对象会在恢复快照时自动重新安装为惰性访问器，由应用的 `undici` 提供（直接解析；在 pnpm 等 undici 未被提升的目录布局下，则通过 egg 的直接依赖 `urllib` 解析）。`Blob` / `File` 本身就能存活于快照中，安装器也会从 `node:buffer` 把它们作为安全网重新安装（若已存在则跳过）。
+
+每个全局对象都在首次访问时才加载真实实现，因此当应用从不使用它们时恢复依然很快；而 `globalThis.fetch(...)`（或直接 `fetch(...)`）以及相关构造函数在恢复后都能正常工作。
+
+需要注意两点：
+
+- 打包产物必须运行在能解析到 `undici` 的环境中。egg 应用通过 `urllib` 依赖天然满足这一点；如果你的部署裁剪了依赖，请保留 `urllib`（或 `undici`）安装在产物旁边。
+- 请在调用处引用 Web 全局对象，而不是在模块顶层捕获。快照构建期间，被删除的全局对象会被替换为可继承的桩类，因此在模块加载时写 `class MyRequest extends globalThis.Request` 不会再崩溃；但在构建期捕获的绑定（`const f = fetch`，或 `extends` 某个 Web 全局的类）会把该桩固化进 blob，恢复后不会被升级。请在使用处直接调用 `fetch(...)` / `new Headers(...)`，惰性访问器会在恢复后解析出真实实现。

tools/egg-bundler/src/lib/EntryGenerator.ts

@@ -367,6 +367,14 @@ if (process.env.EGG_BUNDLE_SNAPSHOT === 'build') {
     }
     await app.triggerSnapshotWillSerialize();
 
+    // The snapshot prelude set globalThis.module/exports so the bundle's UMD external
+    // wrapper takes the require branch under \`--build-snapshot\`. Loading is complete
+    // now (every bundled module — and thus every external factory — has evaluated),
+    // so remove them before V8 serializes the heap; otherwise a global \`module\` would
+    // be baked into the blob and could confuse libraries that sniff it after restore.
+    try { delete (globalThis as Record<string, unknown>).module; } catch {}
+    try { delete (globalThis as Record<string, unknown>).exports; } catch {}
+
     v8.startupSnapshot.setDeserializeMainFunction(() => {
       // ── snapshot restore main ──────────────────────────────────────────
       // V8 runs this callback synchronously right after deserialization, before
@@ -392,9 +400,20 @@ if (process.env.EGG_BUNDLE_SNAPSHOT === 'build') {
             ? process.getBuiltinModule('node:module')
             : (0, eval)('require')('node:module');
         const __req = createRequire(__outputDir + '/');
-        globalThis.__RUNTIME_REQUIRE = (id: string) => __req(id);
+        const __runtimeRequire: any = (id: string) => __req(id);
+        // Expose resolve so the web-globals re-installer can locate undici through
+        // the app dependency tree (e.g. via urllib under pnpm).
+        __runtimeRequire.resolve = (id: string, options?: any) => __req.resolve(id, options);
+        globalThis.__RUNTIME_REQUIRE = __runtimeRequire;
         globalThis.__EGG_MODULE_IMPORTER__ = async (fp: string) => __req(fp);
 
+        // Re-install the web globals (fetch/Headers/Request/Response/FormData/
+        // WebSocket/Blob/File/...) the snapshot prelude deleted at build time, so an
+        // app that uses globalThis.fetch keeps working after a restore. They become
+        // lazy accessors backed by undici (the fetch family) and node:buffer
+        // (Blob/File), loaded on first use through __RUNTIME_REQUIRE.
+        globalThis.__installWebGlobalsLazy?.();
+
         (async () => {
           if (app.agent) {
             await app.agent.triggerSnapshotDidDeserialize();