fix(proxyFetch): retry once on undici dispatcher failure before native fallback

[NomenAK]

What

Add a single retry with 25-75ms jittered backoff in proxyFetch.patchedFetch() when the undici dispatcher fails, before falling back to native fetch. Bypass the retry when the request body is a ReadableStream or Blob (non-replayable).

Why

On our fork we observed 19 [ProxyFetch] Undici dispatcher failed, falling back to native fetch warnings per hour. After tracing, most originated from a 17-connection concurrent burst at container boot (the same race that the ModelSync readiness-gate PR addresses). The undici dispatcher transient failure was real — a second attempt typically succeeded — but the existing code went straight to native fetch on the first error, producing noise and bypassing connection pooling benefits.

How

• patchedFetch() in the direct-connection branch now loops at most 2× when the error matches fetch failed, ECONNREFUSED, or UND_ERR_* codes. 25-75ms jitter between attempts to avoid synchronized retry storms from concurrent callers.
• Fatal version-mismatch errors from onRequestStart remain immediate throws — not retried.
• bodyIsStream guard: if options.body is a ReadableStream (has .getReader()) or Blob (has .stream()), maxAttempts=1 so the body isn't silently emptied on a retry.
• Warning message preserves the original phrase "Undici dispatcher failed, falling back to native fetch" verbatim (adds (after retry) as a parenthetical) so existing substring-based monitoring continues to fire.
• 3 tests in tests/unit/proxyfetch-undici-retry.test.ts: retry-succeeds, retry-also-fails-falls-to-native, no-retry-on-streamed-body. Uses a DI pattern (proxyFetch(url, opts, deps?: ProxyFetchDeps)) so tests can inject mocked undici/native fetches and assert exact call counts.

Notes

The DI signature change (deps? 3rd arg) is backward compatible — existing two-arg callers work unchanged. Happy to revise the jitter window or the error classifier if you have observed different transient patterns.

[gemini-code-assist]

Code Review

This pull request introduces a retry mechanism for undici fetch operations within proxyFetch.ts, including a guard to prevent retrying non-replayable request bodies such as ReadableStreams. It also implements a dependency injection pattern to facilitate unit testing, accompanied by a new test suite. Feedback focuses on enhancing type safety by utilizing existing type aliases and refining mock signatures in tests to avoid using 'as any'. Additionally, it is recommended to transition from string-based error checking to more robust error code validation for the retry logic.

[gemini-code-assist]

The type for undiciFetch is (...args: unknown[]) => Promise<Response>, which is not type-safe. You can use the FetchWithDispatcher type alias defined in this same file to make it more specific and improve type safety. This will also allow for better type inference and reduce the need for type assertions in patchedFetch.

Suggested change

	undiciFetch?: (...args: unknown[]) => Promise<Response>;
	undiciFetch?: FetchWithDispatcher;

[NomenAK]

Done in 6c73fa1 — ProxyFetchDeps.undiciFetch now uses the local FetchWithDispatcher type alias. That also let me drop the three as any casts on nativeFetch in the test file. Good catch.

[gemini-code-assist]

Relying on error message substrings for control flow can be brittle, as these messages might change in future library versions. It's more robust to check for specific error codes when they are available.

undici errors typically have a code property (e.g., UND_ERR_*), and system errors like ECONNREFUSED also expose a code. Checking for these codes directly will make the retry logic more resilient.

        // Only retry/fallback for connection/dispatcher errors, not HTTP errors
        const code = (dispatcherError as { code?: string })?.code;
        if (
          msg.includes("fetch failed") || // Keep for generic undici errors without a code
          code === "ECONNREFUSED" ||
          (code && code.startsWith("UND_ERR"))
        ) {

[NomenAK]

Done in 6c73fa1 — classifier now checks (err as { code?: string }).code first (ECONNREFUSED / UND_ERR* prefix) and falls back to the substring match for errors that lack a structured code. Kept the substring branch as a safety net since some undici versions throw plain Error("fetch failed") without a code — but agreed that code-based matching is more stable as the primary path.

[gemini-code-assist]

To improve type safety and avoid using as any, the mock functions mockUndici and mockNative should be defined with the full function signature they are mocking, even if the arguments are unused. This makes the tests more robust and easier to understand.

This principle applies to all tests in this file.

  const mockUndici = async (
    _input: RequestInfo | URL,
    _options?: RequestInit
  ): Promise<Response> => {
    undiciCalls++;
    throw makeUndiciError("fetch failed");
  };

  const mockNative = async (
    _input: RequestInfo | URL,
    _init?: RequestInit
  ): Promise<Response> => {
    nativeCalls++;
    return new Response("native-fallback-body", { status: 200 });
  };

  const res = await proxyFetch(
    "https://example.invalid/test",
    { method: "GET" },
    { undiciFetch: mockUndici, nativeFetch: mockNative }
  );

[NomenAK]

Done in 6c73fa1 — all 6 mocks (3 mockUndici, 3 mockNative) now use the full (input: RequestInfo | URL, init?: RequestInit) => Promise<Response> signature, and the as any casts at the three call sites are gone. Tests still pass.

[diegosouzapw]

Thanks @NomenAK! Your contribution has been integrated into release/v3.8.0 and will ship in the upcoming release.

The PR branch was synced with the latest release/v3.8.0 (no conflicts) and squash-merged. The undici-dispatcher retry-before-native-fallback path is a nice resilience improvement on proxyFetch.

Reviewed and merged via the /review-prs-cc workflow.