feat: pick dns cache commits to v4 (#5841)

PR Description
This PR ports the complete custom DNS lookup and httpclient
proxy/interceptor module design from 3.x to the next branch.
Key changes:

Implements createTransparentProxy utility for lazy, mm()-compatible
httpClient instantiation.
Refactors app.httpClient to use the proxy, enabling plugins to modify
config before real client creation.
Adds support for config.httpclient.interceptors (undici dispatcher
interceptors) and applies them in httpclient constructor.
Provides full unit tests for proxy and interceptor logic.
Ensures all changes are TypeScript, ESM, and monorepo compatible.
All tests pass except for known unrelated flaky cases.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Add middleware-style HTTP client interceptors via configuration to
modify outgoing requests.
* HTTP client now lazily initializes on first use (deferred
construction).
* Public utility for creating transparent/lazy proxies (with
configurable binding) is now exposed from the package entrypoint.

* **Tests**
* New test suites and app fixtures validating interceptor behavior,
proxy semantics, lazy initialization, and compatibility with mocking
utilities.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: MK (fengmk2) <fengmk2@gmail.com>

Author: Dipper30

packages/egg/src/index.ts

@@ -54,6 +54,9 @@ export type { LoggerLevel, EggLogger, EggLogger as Logger } from 'egg-logger';
 export * from './lib/core/httpclient.ts';
 export * from './lib/core/context_httpclient.ts';
 
+// export utils
+export { createTransparentProxy, type CreateTransparentProxyOptions } from './lib/core/utils.ts';
+
 /**
  * Start egg application with cluster mode
  * @since 1.0.0

packages/egg/src/lib/core/httpclient.ts

@@ -36,6 +36,13 @@ export class HttpClient extends RawHttpClient {
     };
     super(initOptions);
     this.#app = app;
+
+    // Apply custom interceptors via Dispatcher.compose() if configured.
+    // This enables tracer injection, custom headers, retry logic, etc.
+    if (config.interceptors?.length) {
+      const originalDispatcher = this.getDispatcher();
+      this.setDispatcher(originalDispatcher.compose(...config.interceptors));
+    }
   }
 
   async request<T = any>(

packages/egg/src/lib/core/utils.ts

@@ -73,3 +73,109 @@ export function safeParseURL(url: string): URL | null {
     return null;
   }
 }
+
+export interface CreateTransparentProxyOptions<T> {
+  /**
+   * Factory function to lazily create the real object.
+   * Called at most once, on first property access.
+   */
+  createReal: () => T;
+  /**
+   * Whether to bind functions from the real object to the real instance.
+   * Defaults to true.
+   */
+  bindFunctions?: boolean;
+}
+
+/**
+ * Create a Proxy that behaves like the real object, but remains transparent to
+ * monkeypatch libraries (e.g. defineProperty-based overrides like egg-mock's `mm()`).
+ *
+ * - Lazily creates the real object on first access.
+ * - Allows overriding properties on the proxy target (overlay) — e.g. via `Object.defineProperty`.
+ * - Delegates everything else to the real object.
+ *
+ * This is used to defer HttpClient construction so plugins can modify
+ * `config.httpclient.lookup` after the first access to `app.httpClient` but
+ * before any actual HTTP request is made.
+ */
+export function createTransparentProxy<T extends object>(options: CreateTransparentProxyOptions<T>): T {
+  const { createReal, bindFunctions = true } = options;
+  if (typeof createReal !== 'function') {
+    throw new TypeError('createReal must be a function');
+  }
+
+  let real: T | undefined;
+  let cachedError: unknown;
+  const boundFnCache = new WeakMap<Function, Function>();
+
+  const getReal = (): T => {
+    if (real) return real;
+    if (cachedError) throw cachedError;
+    try {
+      return (real = createReal());
+    } catch (err) {
+      cachedError = err;
+      throw err;
+    }
+  };
+
+  const hasOwn = (obj: object, prop: PropertyKey) => Reflect.getOwnPropertyDescriptor(obj, prop) !== undefined;
+
+  // The overlay target stores defineProperty-based overrides (e.g. from egg-mock's mm()).
+  // Mocks live here so mm.restore() can delete them and reveal the real object underneath.
+  const overlay = {} as T;
+
+  return new Proxy(overlay, {
+    get(target, prop, receiver) {
+      const r = getReal();
+      // Overlay (defineProperty-based overrides) takes precedence
+      if (hasOwn(target, prop)) {
+        return Reflect.get(target, prop, receiver);
+      }
+      const value = Reflect.get(r, prop);
+      if (bindFunctions && typeof value === 'function') {
+        let bound = boundFnCache.get(value);
+        if (!bound) {
+          bound = value.bind(r) as Function;
+          boundFnCache.set(value, bound);
+        }
+        return bound;
+      }
+      return value;
+    },
+
+    set(target, prop, value) {
+      const r = getReal();
+      if (hasOwn(target, prop)) {
+        return Reflect.set(target, prop, value);
+      }
+      return Reflect.set(r, prop, value);
+    },
+
+    has(target, prop) {
+      return Reflect.has(target, prop) || Reflect.has(getReal(), prop);
+    },
+
+    ownKeys(target) {
+      return [...new Set([...Reflect.ownKeys(getReal()), ...Reflect.ownKeys(target)])];
+    },
+
+    getOwnPropertyDescriptor(target, prop) {
+      return Reflect.getOwnPropertyDescriptor(target, prop) ?? Reflect.getOwnPropertyDescriptor(getReal(), prop);
+    },
+
+    deleteProperty(target, prop) {
+      if (hasOwn(target, prop)) return Reflect.deleteProperty(target, prop);
+      return Reflect.deleteProperty(getReal(), prop);
+    },
+
+    getPrototypeOf() {
+      return Reflect.getPrototypeOf(getReal());
+    },
+
+    defineProperty(target, prop, descriptor) {
+      return Reflect.defineProperty(target, prop, descriptor);
+    },
+  });
+}

packages/egg/src/lib/egg.ts

@@ -34,7 +34,7 @@ import {
 } from './core/httpclient.ts';
 import { createLoggers } from './core/logger.ts';
 import { create as createMessenger, type IMessenger } from './core/messenger/index.ts';
-import { convertObject } from './core/utils.ts';
+import { convertObject, createTransparentProxy } from './core/utils.ts';
 import type { EggApplicationLoader } from './loader/index.ts';
 import type { EggAppConfig } from './types.ts';
 
@@ -377,12 +377,21 @@ export class EggApplicationCore extends EggCore {
 
   /**
    * HttpClient instance
+   *
+   * Returns a transparent proxy that defers actual HttpClient construction
+   * until a method/property is first accessed. This allows plugins to modify
+   * `config.httpclient.lookup` or other options during lifecycle hooks
+   * (e.g. `configWillLoad`, `didLoad`) even after `app.httpClient` is
+   * first referenced.
+   *
    * @see https://github.com/node-modules/urllib
    * @member {HttpClient}
    */
   get httpClient(): HttpClient {
     if (!this.#httpClient) {
-      this.#httpClient = this.createHttpClient();
+      this.#httpClient = createTransparentProxy<HttpClient>({
+        createReal: () => this.createHttpClient(),
+      });
     }
     return this.#httpClient;
   }

packages/egg/src/lib/types.ts

@@ -3,6 +3,7 @@ import type { Socket, LookupFunction } from 'node:net';
 import type { FileLoaderOptions, EggAppConfig as EggCoreAppConfig, EggAppInfo } from '@eggjs/core';
 import type { EggLoggerOptions, EggLoggersOptions } from 'egg-logger';
 import type { PartialDeep } from 'type-fest';
+import type { Dispatcher } from 'urllib';
 import type { RequestOptions as HttpClientRequestOptions } from 'urllib';
 
 import type { MetaMiddlewareOptions } from '../app/middleware/meta.ts';
@@ -67,6 +68,24 @@ export interface HttpClientConfig {
    */
   allowH2?: boolean;
   lookup?: LookupFunction;
+  /**
+   * Interceptors for request composition, applied via `Dispatcher.compose()`.
+   * Each interceptor receives a `dispatch` function and returns a new `dispatch` function.
+   *
+   * @example
+   * ```ts
+   * // config.default.ts
+   * config.httpclient = {
+   *   interceptors: [
+   *     (dispatch) => (opts, handler) => {
+   *       opts.headers = { ...opts.headers, 'x-trace-id': generateTraceId() };
+   *       return dispatch(opts, handler);
+   *     },
+   *   ],
+   * };
+   * ```
+   */
+  interceptors?: Dispatcher.DispatcherComposeInterceptor[];
 }
 
 /**

packages/egg/test/__snapshots__/index.test.ts.snap

@@ -89,6 +89,7 @@ exports[`should expose properties 1`] = `
   "Singleton": [Function],
   "SingletonProto": [Function],
   "Subscription": [Function],
+  "createTransparentProxy": [Function],
   "defineConfig": [Function],
   "defineConfigFactory": [Function],
   "definePluginFactory": [Function],

packages/egg/test/fixtures/apps/dnscache_httpclient/config/config.default.js

@@ -1,5 +1,12 @@
 'use strict';
 
+const os = require('os');
+const path = require('path');
+
+// Use unique log directory per vitest worker to avoid Windows file locking issues
+const workerId = process.env.VITEST_WORKER_ID || '0';
+const tempBase = path.join(os.tmpdir(), `egg-httpclient-test-${workerId}`);
+
 exports.httpclient = {
   lookup: function (hostname, options, callback) {
     const IP_REGEX = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
@@ -21,4 +28,10 @@ exports.httpclient = {
   },
 };
 
+exports.logger = {
+  dir: path.join(tempBase, 'logs', 'dnscache_httpclient'),
+};
+
+exports.rundir = path.join(tempBase, 'run');
+
 exports.keys = 'test key';

packages/egg/test/fixtures/apps/httpclient-interceptor/app/router.js

@@ -0,0 +1,7 @@
+'use strict';
+
+module.exports = (app) => {
+  app.get('/', async (ctx) => {
+    ctx.body = 'ok';
+  });
+};

packages/egg/test/fixtures/apps/httpclient-interceptor/config/config.default.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+
+let rpcIdCounter = 0;
+
+// Use unique log directory per vitest worker to avoid Windows file locking issues
+const workerId = process.env.VITEST_WORKER_ID || '0';
+const tempBase = path.join(os.tmpdir(), `egg-httpclient-test-${workerId}`);
+
+exports.httpclient = {
+  interceptors: [
+    // Tracer interceptor: injects trace headers into every request
+    (dispatch) => {
+      return (opts, handler) => {
+        opts.headers = opts.headers || {};
+        opts.headers['x-trace-id'] = 'trace-123';
+        rpcIdCounter++;
+        opts.headers['x-rpc-id'] = `rpc-${rpcIdCounter}`;
+        return dispatch(opts, handler);
+      };
+    },
+  ],
+};
+
+exports.logger = {
+  dir: path.join(tempBase, 'logs', 'httpclient-interceptor'),
+};
+
+exports.rundir = path.join(tempBase, 'run');
+
+exports.keys = 'test key';

packages/egg/test/fixtures/apps/httpclient-interceptor/package.json

@@ -0,0 +1,3 @@
+{
+  "name": "httpclient-interceptor-app"
+}