feat: use the network source architecture (defineNetwork)

[kettanaito]

• Drafted in The `defineNetwork()` API #2488
• Ported from feat: support cross-process interception via setupRemoteServer #1617
• Related to Support for Cloudflare Workers runtime #2637
• Closes chore: migrate to rettime #2558
• Closes instanceof filtering with multiple msw versions #2632

Changes

• Rewrites the way the SetupApi behaves by introducing: network frames, sources, controllers, and defineNetwork.
• Handlers are now stored in a kind-based map. This should improve the performance during handler lookup since it becomes O(1).
• Fixes an issue where a WebSocket connection would be logged in the console even when there are no matching event handlers for it.
• Handlers filtering no longer uses instanceof check. Instead, the kind property of the handler is used.

Usage

The introduces APIs are meant to be used from the explicit msw/future export path. The path itself isn't documented as the APIs are considered experimental until the next major release.

Roadmap

• Ensure the changes are backward-compatible
  • I removed HandlersKind and just inlined them in the handler classes.
  • I removed __kind private field from handler classes and made kind public. This is a safe change as nobody should be using these fields.
• Passing handlers as both handlers and the constructor argument for the handlers controller seems odd. Choose just one?
  • Merged two into a single handlers option. After all, handlers are only needed as the input to the controller.
• Consider higher-level utilities to create things like custom setupServer. The defineNetwork API is rather low-level. Export NetowrkOptions to the user can just override some of them?

import { defineNetwork } from 'msw'
import { defaultNetwork } from 'msw/node'

// Create a custom "setup*" wrapper.
function setupCustomApi(...handlers) {
  return defineNetwork({
    ...defaultNetwork,
    ...customizations,
    handlers,
  })
}

// Use it as you normally would use "setup*" APIs.
const network = setupCustomApi(...handlers)
await network.enable()

• Export createSetupServerCommonApi or its alternative. That's a crucial part of extending the default behaviors.
  • I'll hold on regarding this. Let the userland decide what utilities are missing. The common SetuApi isn't that difficult to implement by hand.
• Fix the issue where onUnhandledFrame couldn't affect the request resolution because it's called after frame.resolve() is finished.
• Add a test for onUnhandledRequest: 'error' to ensure that the request is errored (not bypassed). There's currently a bug since onUnhandledFrame is called after frame.resolve(), which always calls passthrough() before the unhandled frame callback.
• Add a test for multiple WebSocket handlers that match the same URL. Make the first throw an error intentionally. Make sure that the next two still fire off. I suspect due to the algo change in WebSocketNetworkFrame, that won't happen (exception in one handler will short-circuit the entire loop).
  • ⚠️ The handler lookup must short-circuit. This is how HTTP behaves, this is how WebSocket should behave to remain predictable.
• Unit tests for the introduced functionality.
• Check if unhandled frame logic and exception try/catch in WebSocketInterceptor aren't fighting each other. I suspect since we catch exceptions, they never surface to the interceptor and it never properly translates them to socket error + closure.
• Consider a new API to replace server.boundary() to establish ASL boundaries for Node.js tests. The NetworkApi must remain the same across environments. Environment-specific APIs must come from the environment entrypoints (msw/node) and applied explicitly.
  • Consider AsyncHandlersController.boundary() instead of the boundary() method in setup-server.ts.
• (Potentially unneeded) Introduce readyState to NetworkApi so implementers don't have to introduce it themselves (e.g. remove isStarted from setup-worker.ts and use a network.readyState check).
• ⚠️ Solve the optional asynchronicity in .enable() leaking from the network sources. Not awaiting network.disable() in server.stop() feels weird.
• Write unit tests for colorless enable/disable in defineNetwork.
• ⚠️ SetupWorkerApi was exported as a class before, now it's only a type. Re-implement that class similar to how we re-implement SetupServerApi for backwards compatibility.

[coderabbitai]

♻️ Duplicate comments (1)

src/browser/sources/service-worker-source.ts (1)

400-428: ⚠️ Potential issue | 🟡 Minor

errorWith() silently ignores non-Error, non-Response throwables.

If reason is neither a Response nor an Error (e.g., a thrown string, number, or plain object), the method returns without resolving the request. This could leave the request hanging indefinitely.

🛡️ Proposed fix to handle arbitrary throwables

   public errorWith(reason?: unknown): void {
     if (reason instanceof Response) {
       return this.respondWith(reason)
     }

     if (reason instanceof Error) {
       devUtils.warn(
         `Uncaught exception in the request handler for "%s %s". This exception has been gracefully handled as a 500 response, however, it's strongly recommended to resolve this error, as it indicates a mistake in your code. If you wish to mock an error response, please see this guide: https://mswjs.io/docs/http/mocking-responses/error-responses`,
         this.data.request.method,
         this.data.request.url,
       )

       this.respondWith(
         HttpResponse.json(
           {
             name: reason.name,
             message: reason.message,
             stack: reason.stack,
           },
           {
             status: 500,
             statusText: 'Request Handler Error',
           },
         ),
       )
+      return
+    }
+
+    if (reason !== undefined) {
+      devUtils.warn(
+        `Uncaught non-Error value thrown in the request handler for "%s %s": %o. This has been gracefully handled as a 500 response.`,
+        this.data.request.method,
+        this.data.request.url,
+        reason,
+      )
+
+      this.respondWith(
+        HttpResponse.json(
+          {
+            name: 'UnknownError',
+            message: String(reason),
+          },
+          {
+            status: 500,
+            statusText: 'Request Handler Error',
+          },
+        ),
+      )
     }
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/browser/sources/service-worker-source.ts` around lines 400 - 428, The
errorWith method currently returns silently for throwables that are neither
Response nor Error, leaving requests unresolved; update errorWith (the method)
to handle arbitrary throwables by adding an else branch that logs a warning via
devUtils.warn (including this.data.request.method and this.data.request.url) and
calls this.respondWith(HttpResponse.json(...)) returning a 500 response;
construct the JSON body with a fallback name like "NonErrorThrown" (or use
typeof reason), a message created by String(reason) or JSON.stringify when safe,
and omit or set stack to undefined, so all thrown values resolve the request
instead of hanging.

🧹 Nitpick comments (1)

src/browser/setup-worker.ts (1)

107-109: Consider stronger typing for the WebSocketInterceptor cast.

The as any cast obscures type incompatibilities. If InterceptorSource expects a specific interceptor interface, consider updating the type definition or using a more precise cast to maintain type safety.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/browser/setup-worker.ts` around lines 107 - 109, The current use of "as
any" on new WebSocketInterceptor() hides type mismatches for
InterceptorSource.interceptors; replace the any cast with the concrete
interceptor interface expected by InterceptorSource (or make InterceptorSource
generic) so the compiler enforces compatibility—either update
WebSocketInterceptor to implement the required interface (methods/properties) or
update the InterceptorSource type signature to accept the WebSocketInterceptor
type, and then remove the "as any" cast from the interceptors array where new
WebSocketInterceptor() is passed.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@src/browser/sources/service-worker-source.ts`:
- Around line 400-428: The errorWith method currently returns silently for
throwables that are neither Response nor Error, leaving requests unresolved;
update errorWith (the method) to handle arbitrary throwables by adding an else
branch that logs a warning via devUtils.warn (including this.data.request.method
and this.data.request.url) and calls this.respondWith(HttpResponse.json(...))
returning a 500 response; construct the JSON body with a fallback name like
"NonErrorThrown" (or use typeof reason), a message created by String(reason) or
JSON.stringify when safe, and omit or set stack to undefined, so all thrown
values resolve the request instead of hanging.

---

Nitpick comments:
In `@src/browser/setup-worker.ts`:
- Around line 107-109: The current use of "as any" on new WebSocketInterceptor()
hides type mismatches for InterceptorSource.interceptors; replace the any cast
with the concrete interceptor interface expected by InterceptorSource (or make
InterceptorSource generic) so the compiler enforces compatibility—either update
WebSocketInterceptor to implement the required interface (methods/properties) or
update the InterceptorSource type signature to accept the WebSocketInterceptor
type, and then remove the "as any" cast from the interceptors array where new
WebSocketInterceptor() is passed.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: e56feca9-0dcd-4ef4-9fa9-0e963bc2ce5c

📥 Commits

Reviewing files that changed from the base of the PR and between a41926b and 8d34dc7.

📒 Files selected for processing (3)

• src/browser/setup-worker.ts
• src/browser/sources/service-worker-source.ts
• test/browser/msw-api/setup-worker/life-cycle-events/on.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• test/browser/msw-api/setup-worker/life-cycle-events/on.test.ts

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/core/experimental/define-network.test.ts (1)

28-28: Floating promises in async assertions could cause test runner warnings.

The toBeInstanceOf(Promise) assertions verify the return type but leave the returned Promises unhandled. While these empty async functions won't reject, some test runners flag unhandled promises. Consider awaiting or explicitly ignoring them for cleaner test output.

💡 Example fix for one case

-    expect(network.enable()).toBeInstanceOf(Promise)
+    const result = network.enable()
+    expect(result).toBeInstanceOf(Promise)
+    await result

Also applies to: 40-40, 73-73, 87-87

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/core/experimental/define-network.test.ts` at line 28, Tests currently
assert return types with expect(network.enable()).toBeInstanceOf(Promise) (and
similarly for network.disable(), network.onRequest(), network.offRequest()),
leaving Promises unawaited and creating floating promises; change each assertion
to either await the call (e.g., await network.enable() then assert expected
side-effects) or use Jest's promise helpers (await
expect(network.enable()).resolves.toBeDefined() or similar) so the returned
Promise is handled and no unhandled/floating promise warnings occur.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/core/experimental/define-network.test.ts`:
- Line 16: Fix the typo in the test names in
src/core/experimental/define-network.test.ts: change the string "returns an
async enable if any the sources are async" to "returns an async enable if any of
the sources are async" (update both occurrences, including the one referenced
around the second occurrence) so the test descriptions read correctly; locate
the tests by the current description in the it(...) calls in the file.

---

Nitpick comments:
In `@src/core/experimental/define-network.test.ts`:
- Line 28: Tests currently assert return types with
expect(network.enable()).toBeInstanceOf(Promise) (and similarly for
network.disable(), network.onRequest(), network.offRequest()), leaving Promises
unawaited and creating floating promises; change each assertion to either await
the call (e.g., await network.enable() then assert expected side-effects) or use
Jest's promise helpers (await expect(network.enable()).resolves.toBeDefined() or
similar) so the returned Promise is handled and no unhandled/floating promise
warnings occur.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 6bf9d467-fa56-4297-b0e0-4816c7bb266a

📥 Commits

Reviewing files that changed from the base of the PR and between 8d34dc7 and 9b2a005.

📒 Files selected for processing (4)

• src/browser/glossary.ts
• src/browser/index.ts
• src/browser/setup-worker.ts
• src/core/experimental/define-network.test.ts

✅ Files skipped from review due to trivial changes (2)

• src/browser/glossary.ts
• src/browser/index.ts

[kettanaito]

Released: v2.13.0 🎉

This has been released in v2.13.0.

• 📄 Release notes
• 📦 View on npm

Get these changes by running the following command:

npm i msw@latest

---

Predictable release automation by Release.