feat: replace string matching with error code propagation for prebundle detection

Eliminates the fragile dependency on Vite's internal error message text
("new version of the pre-bundle") by propagating the structured error
code through the HTTP boundary between server-middleware and worker-entry.

Vite's throwOutdatedRequest sets error.code = 'ERR_OUTDATED_OPTIMIZED_DEP'
(packages/vite/src/shared/constants.ts), but this code was being dropped
when server-middleware serialized only error.message. Now:

1. server-middleware.ts — includes error.code in the JSON error response
2. worker-entry.ts fetchModuleWithRetry — parses and propagates the code
   from the JSON body onto the thrown Error, including through the final
   "all attempts exhausted" wrapper error
3. isPrebundleVersionMismatch — checks error.code instead of string matching

The error code 'ERR_OUTDATED_OPTIMIZED_DEP' is defined as a constant in
our code (not imported from Vite), is stable since Vite 2.9, and is used
by Vite's own transform middleware — changing it would break Vite itself.

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

Author: kdaviduik

packages/mini-oxygen/src/vite/server-middleware.ts

@@ -201,7 +201,12 @@ export function setupOxygenMiddleware(
           .catch((error) => {
             console.error('Error during module fetch:', error);
             res.writeHead(500, {'Content-Type': 'application/json'});
-            res.end(JSON.stringify({error: String(error?.message ?? error)}));
+            res.end(
+              JSON.stringify({
+                error: String(error?.message ?? error),
+                ...(error?.code && {code: error.code}),
+              }),
+            );
           });
       } else {
         res.writeHead(400, {'Content-Type': 'text/plain'});

packages/mini-oxygen/src/vite/worker-entry.test.ts

@@ -20,33 +20,28 @@ import {
 // isPrebundleVersionMismatch
 // ---------------------------------------------------------------------------
 describe('isPrebundleVersionMismatch', () => {
-  it('detects the Vite prebundle invalidation message', () => {
-    const error = new Error(
-      'There is a new version of the pre-bundle for "react"',
-    );
+  it('detects errors with the Vite outdated dep error code', () => {
+    const error = new Error('anything') as any;
+    error.code = 'ERR_OUTDATED_OPTIMIZED_DEP';
     expect(isPrebundleVersionMismatch(error)).toBe(true);
   });
 
-  it('returns false for unrelated errors', () => {
+  it('returns false for errors without the code', () => {
     expect(isPrebundleVersionMismatch(new Error('Module not found'))).toBe(
       false,
     );
     expect(isPrebundleVersionMismatch(new Error('syntax error'))).toBe(false);
   });
 
-  it('falls back to error.stack when message is nullish', () => {
-    // The function uses `??` (nullish coalescing) — only null/undefined
-    // triggers the stack fallback, not empty string.
-    const error = {
-      message: undefined,
-      stack: 'Error: new version of the pre-bundle detected\n  at foo.ts:1',
-    } as unknown as Error;
-    expect(isPrebundleVersionMismatch(error)).toBe(true);
+  it('returns false for errors with a different code', () => {
+    const error = new Error('some error') as any;
+    error.code = 'ERR_SOMETHING_ELSE';
+    expect(isPrebundleVersionMismatch(error)).toBe(false);
   });
 
-  it('handles fully nullish error properties gracefully', () => {
-    const error = {message: undefined, stack: undefined} as unknown as Error;
-    expect(isPrebundleVersionMismatch(error)).toBe(false);
+  it('handles nullish error gracefully', () => {
+    expect(isPrebundleVersionMismatch(null as any)).toBe(false);
+    expect(isPrebundleVersionMismatch(undefined as any)).toBe(false);
   });
 });
 
@@ -211,6 +206,46 @@ describe('fetchModuleWithRetry', () => {
     ).rejects.toThrow(/connection refused/);
   });
 
+  it('propagates error code from JSON error response', async () => {
+    const errorBody = JSON.stringify({
+      error: 'There is a new version of the pre-bundle for "react"',
+      code: 'ERR_OUTDATED_OPTIMIZED_DEP',
+    });
+    mockFetch.mockResolvedValueOnce(
+      new Response(errorBody, {
+        status: 500,
+        headers: {'Content-Type': 'application/json'},
+      }),
+    );
+    // All attempts fail with the same error
+    mockFetch.mockResolvedValueOnce(new Response(errorBody, {status: 500}));
+    mockFetch.mockResolvedValueOnce(new Response(errorBody, {status: 500}));
+
+    try {
+      await fetchModuleWithRetry(
+        new URL('http://localhost:5173/__vite_fetch_module?id=test'),
+      );
+      expect.unreachable('should have thrown');
+    } catch (error: any) {
+      expect(error.code).toBe('ERR_OUTDATED_OPTIMIZED_DEP');
+    }
+  });
+
+  it('handles non-JSON error bodies without propagating code', async () => {
+    mockFetch.mockResolvedValueOnce(textResponse('plain text error', 500));
+    mockFetch.mockResolvedValueOnce(textResponse('plain text error', 500));
+    mockFetch.mockResolvedValueOnce(textResponse('plain text error', 500));
+
+    try {
+      await fetchModuleWithRetry(
+        new URL('http://localhost:5173/__vite_fetch_module?id=test'),
+      );
+      expect.unreachable('should have thrown');
+    } catch (error: any) {
+      expect(error.code).toBeUndefined();
+    }
+  });
+
   it('delegates to fetchWithTimeout which wires AbortSignal', async () => {
     mockFetch.mockResolvedValueOnce(jsonResponse({code: 'ok'}));
 

packages/mini-oxygen/src/vite/worker-entry.ts

@@ -33,6 +33,12 @@ export interface ViteEnv {
 
 const O2_PREFIX = '[o2:runtime]';
 
+// Vite's dep optimizer sets this code on errors thrown when a prebundled
+// dependency is invalidated mid-request. Defined in Vite's source at
+// packages/vite/src/shared/constants.ts — not part of Vite's public API,
+// but stable since Vite 2.9 and used by Vite's own transform middleware.
+const VITE_ERR_OUTDATED_OPTIMIZED_DEP = 'ERR_OUTDATED_OPTIMIZED_DEP';
+
 const MODULE_FETCH_MAX_ATTEMPTS = 3;
 const MODULE_FETCH_BASE_DELAY_MS = 200;
 const MODULE_FETCH_TIMEOUT_MS = 10_000;
@@ -88,6 +94,16 @@ export async function fetchModuleWithRetry(url: URL) {
         `${O2_PREFIX} Module fetch failed (${res.status}): ${body}`,
       );
 
+      // Propagate error code from the server response (e.g.,
+      // Vite's ERR_OUTDATED_OPTIMIZED_DEP) so callers can identify
+      // specific error types without string matching on the message.
+      try {
+        const parsed = JSON.parse(body);
+        if (parsed?.code) (error as any).code = parsed.code;
+      } catch {
+        // Body wasn't JSON — no code to propagate
+      }
+
       // Client errors (4xx) are deterministic — retrying won't help
       if (res.status < 500) throw error;
 
@@ -106,10 +122,17 @@ export async function fetchModuleWithRetry(url: URL) {
     }
   }
 
-  throw new Error(
+  const finalError = new Error(
     `${O2_PREFIX} Module fetch failed after ${MODULE_FETCH_MAX_ATTEMPTS} attempts: ` +
       (lastError?.message ?? 'unknown error'),
   );
+
+  // Preserve error code from the last attempt so callers can identify
+  // specific error types (e.g., prebundle invalidation) after retries.
+  const lastErrorCode = (lastError as any)?.code;
+  if (lastErrorCode) (finalError as any).code = lastErrorCode;
+
+  throw finalError;
 }
 
 export default {
@@ -314,16 +337,13 @@ function resetRuntime() {
 }
 
 /**
- * Detects Vite's dep optimizer prebundle invalidation error.
- * This string comes from Vite's optimizer — see:
- * https://github.com/vitejs/vite/blob/v6.4.1/packages/vite/src/node/plugins/optimizedDeps.ts
- * (throwOutdatedRequest function).
- * If Vite changes this message, the recovery path silently stops working
- * and falls back to returning a 503 error page (same as before this fix).
- * Verify this string still exists after Vite upgrades.
+ * Detects Vite's dep optimizer prebundle invalidation error by checking
+ * the error code propagated from the server middleware. Vite's
+ * `throwOutdatedRequest` sets `error.code = 'ERR_OUTDATED_OPTIMIZED_DEP'`
+ * (see packages/vite/src/node/plugins/optimizedDeps.ts), and our
+ * server-middleware preserves it in the JSON error response.
  * @internal Exported for unit testing — not part of the public API.
  */
 export function isPrebundleVersionMismatch(error: Error): boolean {
-  const message = error?.message ?? error?.stack ?? '';
-  return message.includes('new version of the pre-bundle');
+  return (error as any)?.code === VITE_ERR_OUTDATED_OPTIMIZED_DEP;
 }