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.

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.
• 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)).
  • 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)

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.

[kettanaito]

Test failures

 FAIL  test/node/msw-api/setup-remote-server/response.body.test.ts [ test/node/msw-api/setup-remote-server/response.body.test.ts ]
 Test Files  2 failed | 84 passed (86)
Error: listen EADDRINUSE: address already in use ::1:56957

This is caused by migrating to HTTP for the internal server. Since Vitest likely runs some of these tests in parallel, it attempts to call remote.listen(), which attempts to create multiple internal HTTP servers on the same port, which, naturally, fails.

This is a good precursor into figuring out whether the internal server port is fixed or random. I likely lean toward making it random and passing it along with remoteContext through remote.boundary() (but that will make the boundary required; or we can use a fallback port).

Solution

Solved by (1) spawning the internal server at a random port; (2) propagating the entire server URL through environment variable (getRemoteContext() + per-test app spawning). Boundary is not required.

[kettanaito]

Task: Ignore internal requests in life-cycle reporting

Internal MSW requests is a new thing with this pull request, such as a request to the remote HTTP server, or internal requests that forward life-cycle events. Those internal requests bubble to the life-cycle event emitting, and result in entries there.

Need to add some flag to ignore certain requests from the life-cycle API altogether. It may be an accept header once again.

✅ Solved by introducing a check for the msw/internal accept header value.

[kettanaito]

🐞 ECONNREFUSED on life-cycle event forwarding

Sometimes the following error is thrown while using the new API:

Error: connect ECONNREFUSED ::1:50004
    at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1555:16) {
  errno: -61,
  code: 'ECONNREFUSED',
  syscall: 'connect',
  address: '::1',
  port: 50004
}


stderr | Socket.<anonymous> (msw/test/node/msw-api/setup-remote-server/utils.ts:25:43)
msw/lib/node/index.js:556
        new Error(
        ^

Error: Failed to forward life-cycle event "request:match" for request "GET https://example.com/resource": unexpected error. There's likely additional information above.
    at ClientRequest.<anonymous> (msw/lib/node/index.js:556:9)

[pkg-pr-new]

Open in Stackblitz

npm i https://pkg.pr.new/msw@1617

commit: 3826cad

[kettanaito]

🐞 Life-cycle event forwarding order sensitivity

LCE are sensitive to order. But when forwarded, some events may arrive faster over HTTP, breaking that order:

 FAIL  test/node/msw-api/setup-remote-server/life-cycle-event-forwarding.node.test.ts > emits correct events for the request handled in the test process
AssertionError: expected [ …(4) ] to deeply equal [ …(4) ]

- Expected
+ Received

  Array [
    Array [
      "[request:start] GET https://example.com/resource ade0140740d15",
    ],
    Array [
-     "[request:match] GET https://example.com/resource ade0140740d15",
+     "[request:end] GET https://example.com/resource ade0140740d15",
    ],
    Array [
-     "[request:end] GET https://example.com/resource ade0140740d15",
+     "[request:match] GET https://example.com/resource ade0140740d15",
    ],
    Array [
      "[response:mocked] GET https://example.com/resource ade0140740d15 200 {\"mocked\":true}",
    ],
  ]

Need to solve this.