feat: support cross-process interception via setupRemoteServer

[kettanaito]

This is an experimental feature. It's unlikely to ship before 2.0.

Intention

Introduce an API that allows one process to modify the traffic of another process. The most apparent application for this is testing server-side behaviors of a JavaScript application:

// app.js
forwardNetworkToRemote()

export const loader = async () => {
  const res = await fetch('https://example.com/resource')
}

// app.test.js
it('fetches the user server-side', async () => {
  let a = listenToRemoteNetwork(targetProcess)
  modifyNetwork(a)
  // ...render
  // ...assert
})

This is an example API. For the exact proposed API, keep reading.

This API is designed exclusively for use cases when the request-issuing process and the request-resolving process (i.e. where you run MSW) are two different processes.

Important

While the feature itself is unopinionated in how it's used, in practice it implies that you either have a fixed list of handlers OR you provide test-app isolation by spawning an app instance per test case. That is so handler overrides in one test don't affect the remote network for other tests. The app becomes a shared state here with no means to distinguish who is the consumer (test -> client -> server chain loses any identifiers).

Proposed API

With consideration to the existing MSW user experience, I suggest we add a setupRemoteServer() API that implements the SetupApi interface and has a similar API to setupServer. The main user-facing distinction here is that setupRemoteServer is affecting a remote process, as indicated by the name.

import { http } from 'msw'
import { setupRemoteServer } from 'msw/node'

const remote = setupRemoteServer(...initialHandlers)

// Notice: async!
beforeAll(async () => await remote.listen())
afterEach(() => remote.resetHandlers())
afterAll(async () => await remote.close())

The .listen() and .close() methods of the remote server become async since they now establish and terminate an internal server instance respectively.

Similar to the setupServer integration, it would be recommended to call setupRemoteServer once as a part of your global testing setup. Closing the WebSocket server after each test suite will have performance implications since each next test suite would wait while remote.listen() spawns that server again.

You can then operate with the remote server as you would with a regular setupServer, keeping in mind that it doesn't affect the current process (your test) but instead, any remote process that runs setupServer (your app).

it('handles user errors', () => {
  // Appending and removing request handlers is sync
  // because they are stored in the current (test) process.
  remote.use(
    http.get('/user', () => {
      return new Response(null, { status: 500 })
    })
  )

  // ...interact and assert your app.
})

By fully extending the SetupApi, the setupRemoteServer API provides the user with full network-managing capabilities. This includes defining initial and runtime request handlers, as well as observing the outgoing traffic of a remote process using the Life-cycle API (remote.events.on(event, listener)). I think this is a nice familiarity that also provides the user with more power when it comes to controlling the network.

Implementation

I've considered multiple ways of implementing this feature. Listing them below.

(Chosen) WebSocket server

The setupRemoteServer API can establish an internal WebSocket server that can route the outgoing traffic from any server-side MSW instance anywhere and deliver it to the remote server to potentially resolve.

Technically, the WebSocket server acts as a resolution point (i.e. your handlers) while the remote MSW process acts as a request supplier (similar to how the Service Worker acts in the browser).

Very roughly, this implies that the regular setupServer instances now have a fixed request handler that tries to check if any outgoing request is potentially handled by an existing remote WebSocket server:

// setupServer.js
await handleRequest(
  request,
  requestId,
  [
    // A very basic idea on how a "remote" request handler works.
    http.all('*', async ({ request }) => {
      wsServer.emit('request', serializeRequest(request))
      await wsServer.on('response', (serializedResponse) => {
        return deserializeResponse(serializedResponse)
      })
    }),
    ...this.currentHandlers,
  ]
)

Unlike request handler (i.e. function) serialization, it is perfectly fine to serialize Request and Response instances and transfer them over any message channel, like a WebSocket transport.

If no WebSocket server was found or establishing a connection with it fails within a sensible timeout period (~500ms), the setupServer instance of the app continues to operate as normal.

Alternatively, we can skip the WebSocket server lookup altogether and make it opt-in via some remote: true option on the app's side.

IPC

The test process and the app process can utilize IPC (interprocess communication) to implement a messaging protocol. Using that protocol, the app can signal back any outgoing requests and the test can try resolving them against the request handlers you defined immediately in the test.

This approach is similar to the WebSocket approach above with the exception that it relies on IPC instead of a standalone running server. With that, it also gains its biggest disadvantage: the app process must be a child process of the test process. This is not easy to guarantee. Depending on the framework's internal implementation, the user may not achieve this parent/child relationship, and the IPC implementation will not work.

Given such a demanding requirement, I've decided not to use this implementation.

Limitations

• useRemoteServer() affects the network resolution for the entire app. This means that you cannot have multiple tests that override request handlers for the same app at the same time. I think this is more than reasonable since you know you're running 1 app instance that can only behave in a single way at a single point in time. Still, I expect users to be confused when they parallelize their E2E tests and suddenly see some network behaviors leaking across the test cases.

Concerns

• Can we rely on a fixed local port to always be available?
• Is it safe to introduce a WebSocket server that will be, effectively, routing HTTP messages over the local network (during tests only)?
  • Yes. If someone can intercept that WebSocket communication, they are already in your machine and can do things far worse than that.
• Is it clear that setupRemoteServer only affects the server-side network behavior of any running application process with the server-side MSW integration? To affect the client-side network behavior from a test you have to 1) have setupWorker integration in the app; 2) set a global window.worker instance; 3) use window.worker.use() to add runtime request handlers. This stays as it is right now, no changes here.

---

• Remix example repo

The API is TBD and is subjected to change.

Roadmap

• Ensure the sync server connection is awaited before the first request handler runs.
• Introduce serialize/deserialize utilities for requests and responses (used both in the worker and in the WS sync layer now).
• Fix listeners' memory leaks on hot updates (clean up listeners).
• Make the WS events map type-safe
• Rely on the internal request header when bypassing Socket IO connection requests in the rest.all() handler.
• Handle socket timeout and errors when awaiting for the response in setupServer.
  • CPRI doesn't use websockets anymore.
• Support ReadableStream from the remote request handler (may consider transferring ReadableStream over the WS messages instead of ArrayBuffer, if that's allowed).
  • This may not be needed, in the end, but if we can pull off ReadableStream transfer over WebSockets that would be great.
• Support all Life-cycle events.
• Support setting a custom WebSocket server port number through environment variables.
• Make the remotePort and port an implementation detail of setupRemoteServer and setupServer({ remote: true }). The developer mustn't care about those.
• Do not spread the list of user-defined request handlers to prepend the fixed remote server handler (spreading of large lists may have performance implications).
  • Not an issue until proven otherwise; have no wish to optimize prematurely.
• Solve the test/app catch 22 by attaching a self-replicating one-time handlers only for the first-time requests (those fetched when the testing framework pings your app).
• Fix: failing use() test (may have something to do with the handlers management refactoring as a part of the server.boundary()).
• Support differentiating between requests done in different Playwright workers (see this).
• Add more tests, specifically for different response body types. Also life-cycle events tests for setupServer (that it doesn't emit them for internal requests).
• Consider adding setupWorker support (see feat: support cross-process interception via setupRemoteServer #1617 (comment)).
  • Out of scope. This is likely too much for the initial scope. May consider iterating on it to bring remote interception to the browser in the future.
• Consider dropping socket.io in favor of ws if we don't need anything socketio-specific
• Silent WebSocket connection errors if the remote mode is enabled but the WebSocket server is not running/fails to connect. Print a warning and continue in regular mode.
• Don't send life-cycle events for the WebSocket connection HTTP request to the WebSocket server (forwardLifeCycleEvents()).
• Support ListenOptions on setupRemoteServer(), like onUnhandledRequest.
• Fix the spyOnLifeCycleEvents test utility importing vitest when it can also be run in the browser.
• Fix forwarded LCE order sensitivity feat: support cross-process interception via setupRemoteServer #1617 (comment)
• Protect the internal HTTP connection form malicious actors (feat: support cross-process interception via setupRemoteServer #1617 (review)).
• Implement the RemoteInterceptor. Then, use it in MSW via InterceptorNetworkSource.
• ⚠️ Clean up the code. /new has to be merged with /core.

Blockers

• Types are not installed socketio/socket.io#4621 (type definitions for socket.io-parser are broken for the CJS build).
• Modern Remix requires sourcemaps. I added those for Interceptors but adding them to MSW breaks due to tsup: Incorrect JSON in "sourcesContent" with the "sourcemap" option egoist/tsup#1073
  • Fixed in fix: publish source and include sourcemaps #1958
• Support different tests provisioning overrides for the same running app (feat: support cross-process interception via setupRemoteServer #1617 (comment)).
• Implement life cycle events forwarding to remote.

[jonlambert]

Hey @kettanaito! Sorry to ask the age-old annoying question...

This would be suuuuch a game changer for our team. Are there any plans to merge this functionality? I can see it was added to the 3.0 milestone but can't see it in the list!

[kettanaito]

Hi @jonlambert. No worries. This is going to be a gamechanger for all teams, I can imagine!

This pull request as-is is likely dead weight. It was foundational in figuring out the defineNetwork architecture that I have since surgically extracted and merged into main (see #2650).

Instead of continuing with this branch, I've opened another feature branch that rebuilds this on top of the new architecture. There are a couple of decisions that were not addressed with this feature that I'm still working on:

• Who should decide the remote port between the two parties?
• Is there a room for the port to be implicitly set? How?
• Still (laughably) unsure which side should establish the connection and which one should connect. Ended up on the app being responsible for the connection (app is always Node.js) and anything else is the client (which potentially opens setupWorker() to be compatible with this API as well).

And a few dozens smaller decisions sprinkled all around.

Availability

The biggest blocker right now is my availability. I have a ton of work at Epic Web, I have a few pull request I really need to finish. Realistically, this is coming in 3.0, which might release sometime later this year if all goes smoothly.

What you can do to help

If this feature would be beneficial to your team, consider sponsoring my work on it! That would allow me to dedicate proper time to the cross-process interception and finish it for everybody, with your company as a proud patron (I will make sure everyone knows who made this possible). I'd then release this under an experimental version so you can start using it without having to wait for 3.0. Reach out to me on Discord or Twitter if this is something you would be interested in. Thank you!