The defineNetwork() API

[kettanaito]

MSW is a combination of two things: request interception algorithm and the handler resolution API to handle outgoing requests. Right now, the recommended way is to use it as a whole or implement custom resolution logic using the exposed utilities like handleRequest().

That might not be enough for some advanced cases. For once, handleRequest() is quite implementation detail heavy and doesn't feel like a public API. It would be great if MSW could be used as a function of network source:

declare function msw(network: NetworkProducer, handlers: Array<Handler>): Response | undefined

MSW has always been architectured around the concept of a request stream coming from somewhere and then getting handled by the user's handlers. I think it's time we exposed that as an actual public API.

Proposal

This proposal comes down to implementing network handling primitives that accept any source of network, either a request stream from a Service Worker or requests from page.route() in Playwright, and produce a response given a list of handlers.

import { defineNetwork, NetworkSource } from 'msw'
import { ServiceWorkerSource } from 'msw/browser'

const network = defineNetwork({
  sources: [
    // Request stream from the Service Worker.
    new ServiceWorkerSource(),

    // Request stream from `page.route()` in Playwright.
    new CustomPlaywrightSource(page)
  ],
  initialHandlers: [...]
})

class CustomPlaywrightSource extends NetworkSource {
  constructor(protected readonly page: Page) {
    page.route(/.+/, async (route, request) => {
      // ...implement the stream.
    })
  }
}

Important

Conceptually, the proposed defineNetwork() API replaces setupWorker and setupServer and introduces a single congruent way to create the network controller. setupWorker and setupServer function are left intact as they provide a better default experience.

defineNetwork()

The object returned from the defineNetwork() function allows you to control the network as you would with the similar control objects from setupWorker/setupServer:

const network = defineNetwork()

await network.enable() // Start mocking
network.use(...handlers) // Prepend overrides
network.resetHandlers() // Reset to `initialHandlers`
network.events.on('request:start', listener) // Observe the network
await network.disable() // Stop mocking

To facilitate for different network sources dictating how the request stream should be established and closed, the .enable() and .disable() methods are always asynchronous.

Example

Here's a contrived example of using the proposed API to integrate MSW into Playwright tests and utilize page.route() as the request interception algorithm:

import { buffer } from 'node:stream/consumers'
import { test as testBase } from '@playwright/test'
import { defineNetwork, NetworkSource, ResponseHandler } from 'msw'

testBase.extend({
  network: [
    async ({ page, baseURL }, use) => {
      const network = defineNetwork({
        sources: [new PlaywrightPageRouteSource(page, baseURL)],
      })
      await network.enable()
      await use(network)
      await network.disable()
    },
    {
      auto: true,
      scope: 'test',
    }
  ],
})

class PlaywrightPageRouteSource extends NetworkSource {
  constructor(page, baseUrl) {
    super()

    page.route(/.+/, (route, request) => {
      this.requestStream.push({
        // Convert to the Fetch API request.
        request: toFetchRequest(request),
        // Define a function that will handle mocked responses.
        responseHandler: this.createResponseHandler(route),
        resolutionContext: {
          baseUrl,
        }
      })
    })
  }

  private createResponseHandler(route): ResponseHandler {
    return async (response: Response | undefined) => {
      if (!response) {
        return route.continue()
      }

      route.fulfill({
        status: response.status,
        headers: Object.fromEntries(response.headers),
        body: response.body ? await buffer(response.body) : undefined
      })
    }
  }

  onUnhandledRequest(request) {
    // Bypass unhandled requests.
    return
  }
}

Prerequisites

• Export a unified Handler type that's maintained by us. Right now, it's clunky to create manual unions of RequestHandler | WebSocketHandler to correctly annotate "any" handler type.
• Deprecate handleRequest() and replace it with a nicer API.

Questions

• Network sources are, effectively, interceptors. Is it worth introducing a new concept? Can the proposed API revolve around interceptors: [...] instead?
  • Worth keeping in mind that the Interceptor class is an established pattern that doesn't behave as the proposed network source, in a way that it's not tightly integrated with MSW's internal request resolution logic. I think we should leave interceptors be interceptors and have a new concept of a "source" that hooks into the library.
  • One can also have NetworkSource.fromInterceptors(...interceptors) to map the interceptor events to the request/response stream expected by the network source. In fact, I would refactor the internals to be just that.
• Should NetworkSource expose side effect-based methods like this.requestStream.push() or actually expose a method that returns a mocked response, if any: this.handleRequest(): Response | undefined? I feel like the second would be more explicit and powerful.

[christoph-fricke]

I love the idea and the initiative to expose APIs for advanced cases. Nowadays I rarely use setupServer() (and setupWorker() even less) as intended. Most of the time, I combine MSW handlers with Playwright interception, or integrate MSW handlers into a HTTP server that does the interception.

Deprecate handleRequest() and replace it with a nicer API.

I usually use the exposed getResponse(handlers: Array<RequestHandler>, request: Request): Promise<Response | undefined> helper. Does it require an additional API? I feel like that one could already be sufficient. Might just need one or two small adjustments.

Export a unified Handler type that's maintained by us.

Yes please!!! With the release of WebSocketHandler it has become a annoying to interoperate between getResponse() and setupServer().listHandlers().

On a side-note: I sometimes use setupServer() without ever calling .listen() on it, just to have a handler collection. Basically type HandlerCollection = Pick<SetupServer, "use" | "resetHandlers" | "restoreHandlers"| "listHandlers">. When we talk about supporting advanced cases, I think it would be cool to extract and expose a HandlerCollection.

[kettanaito]

Thanks for your feedback, @christoph-fricke!

I usually use the exposed getResponse(handlers: Array, request: Request): Promise<Response | undefined> helper. Does it require an additional API?

Good point. I sort of forgot about getResponse()! Yeah, you should be using that and what I may include in this proposal is still refactoring handlRequest` for even more advanced use cases (and also for internal usage to be a bit nicer).

I think it would be cool to extract and expose a HandlerCollection.

I think we have this already in the HandlersController interface. Right now it's a abstract interface you have to implement. We implement it in different ways:

msw/src/core/SetupApi.ts

Lines 11 to 17 in 379f825

	export abstract class HandlersController {
	abstract prepend(
	runtimeHandlers: Array<RequestHandler | WebSocketHandler>,
	): void
	abstract reset(nextHandles: Array<RequestHandler | WebSocketHandler>): void
	abstract currentHandlers(): Array<RequestHandler | WebSocketHandler>
	}

msw/src/core/SetupApi.ts

Lines 19 to 42 in 379f825

	export class InMemoryHandlersController implements HandlersController {
	private handlers: Array<RequestHandler | WebSocketHandler>
	constructor(
	private initialHandlers: Array<RequestHandler | WebSocketHandler>,
	) {
	this.handlers = [...initialHandlers]
	}
	public prepend(
	runtimeHandles: Array<RequestHandler | WebSocketHandler>,
	): void {
	this.handlers.unshift(...runtimeHandles)
	}
	public reset(nextHandlers: Array<RequestHandler | WebSocketHandler>): void {
	this.handlers =
	nextHandlers.length > 0 ? [...nextHandlers] : [...this.initialHandlers]
	}
	public currentHandlers(): Array<RequestHandler | WebSocketHandler> {
	return this.handlers
	}
	}

msw/src/node/SetupServerApi.ts

Lines 23 to 49 in 379f825

	class AsyncHandlersController implements HandlersController {
	private rootContext: RequestHandlersContext
	constructor(initialHandlers: Array<RequestHandler | WebSocketHandler>) {
	this.rootContext = { initialHandlers, handlers: [] }
	}
	get context(): RequestHandlersContext {
	return store.getStore() || this.rootContext
	}
	public prepend(runtimeHandlers: Array<RequestHandler | WebSocketHandler>) {
	this.context.handlers.unshift(...runtimeHandlers)
	}
	public reset(nextHandlers: Array<RequestHandler | WebSocketHandler>) {
	const context = this.context
	context.handlers = []
	context.initialHandlers =
	nextHandlers.length > 0 ? nextHandlers : context.initialHandlers
	}
	public currentHandlers(): Array<RequestHandler | WebSocketHandler> {
	const { initialHandlers, handlers } = this.context
	return handlers.concat(initialHandlers)
	}
	}

This is because different APIs can store and manage handlers differently (e.g. setupServer() relies on AsyncLocalStorage while setupBrowser() stores them in-memory.

With that in mind, it's hard to expose just one handler-managing interface to you. I'd say for that case, it's okay to use setup* APIs and not instantiate them.

[christoph-fricke]

Should NetworkSource expose side effect-based methods like this.requestStream.push() or actually expose a method that returns a mocked response, if any: this.handleRequest(): Response | undefined? I feel like the second would be more explicit and powerful.

Thinking about this a bit, I start to wonder about the usefulness of defineNetwork(). I agree that the second part of your question might be the more powerful answer. It also feels more intuitive.
But I also think that there are a lot interchanged control and responsibilities between defineNetwork and a NetworkSource. Is the complexity really needed or can everything be achieved just as well with getReponse()?

In my head I am mostly focusing on the Playwright example. One thing that can really help here is a HandlerCollection that I mentioned in my other comment. With this, the Playwright example can also be written like the following. I feel like it has a clearer separation between request interception and handler resolution.

import {
  test as testBase,
  type Page,
  type Request as PWRequest,
  type Route,
} from "@playwright/test";
import { getResponse, type RequestHandler } from "msw";
import type { SetupServer } from "msw/node";

// Imagine such API exposed by MSW. Of course it should be more refined and nuanced, e.g. be Iterable etc...
type HandlerCollection = Pick<
  SetupServer,
  "use" | "resetHandlers" | "restoreHandlers" | "listHandlers"
>;

export const test = testBase.extend<{ handlers: HandlerCollection }>({
  handlers: [
    async ({ page }, use) => {
      const collection = new HandlerCollection(initialHandlers);
      const cleanup = await setupRequestInterception(page, collection);
      await use(collection);
      await cleanup();
    },
    {
      auto: true,
      scope: "test",
    },
  ],
});

async function setupRequestInterception(
  page: Page,
  collection: HandlerCollection,
): Promise<() => Promise<void>> {
  async function handler(route: Route, request: PWRequest) {
    const nativeRequest = new Request(request.url(), {
      method: request.method(),
      headers: new Headers(await request.allHeaders()),
      body: request.postDataBuffer(),
    });

    const response = await getResponse(
      collection.listHandlers() as RequestHandler[], // Conflict with WebSocketHandler...
      nativeRequest,
    );

    return !response
      ? route.continue()
      : route.fulfill({
          status: response.status,
          headers: Object.fromEntries(response.headers),
          body: Buffer.from(await response.arrayBuffer()),
        });
  }

  await page.route(/.+/, handler);
  return () => page.unroute(/.+/);
}

[kettanaito]

Is the complexity really needed or can everything be achieved just as well with getReponse()?

getResponse() is not a substitute for defineNetwork(). They follow different goals:

• getResponse() gives you a response given a request within the defined request handlers. It's primarily a response resolution algo.
• defineNetwork() allows you to outside the interception itself. See the Playwright example I listed in the proposal. With defineNetwork(), you can say "I want Playwright to be the source of network", that's the important part that we currently don't support in any developer-friendly way.

My goal with this proposal is to make things simpler. So if you feel like it's introducing complexity, I'd love to learn more about your perspective. If we have defineNetwork(), I may consider deprecating setupServer() and setupWorker() in the future because they might become obsolete.

With this, the Playwright example can also be written like the following.

Notice that your rewritten example is bound more to Playwright than it should be. setupRequestInterception is pretty much ephemeral, and if you decide to, say, use an HAR as the source of network, you have to implement that request/response pulling logic yourself. That's what I want to solve with the proposal—introduce a clear API to define custom network sources. Then, adjust the existing APIs to request handling becomes a function of request (which it kinda is but with oddities, like emitter).

[kettanaito]

Network source API encompasses multiple DX requirements at the same time. For example, it facilitates the definition of custom interceptors (or network sources) as opposed to how difficult it is to do that now (requires you to define a subclass of SetupApi).

[kettanaito]

I want MSW to feel like you're choosing two things: where the requests come from and how to handle them. Right now, you are in a good place with the latter. The request handler API is great for defining your network behavior. But the source of network is abstracted quite heavily from you. I think that shouldn't be the case.

You should be able to use pre-defined network sources, like the ServiceWorker source or Node.js Interceptors, but also empowered to define your own. I want first-class APIs for that. This has always been the implementation model behind MSW, and now I want to expose some of that power to the users, wrapped in nice API.

It can help us internally, too. For example, cross-process interception (#1617) can become not a special request handler but instead a special network source. That would make much more sense.