fix: properly handle Unix socket paths in interceptors by vinialbano · Pull Request #722 · mswjs/interceptors

vinialbano · 2025-05-06T17:24:31Z

Fix Unix socket path handling in MSW Interceptors

Problem

The MSW Interceptors library had an issue with TCP requests bound to Unix sockets. When making requests to Unix socket paths (via the socketPath option), the interceptor was incorrectly trying to establish a TCP connection to localhost:80 rather than using the provided socket path. This prevented proper interception and mocking of requests to Unix sockets.

This issue is particularly important for:

Applications using Docker API (which often communicates through /var/run/docker.sock)
TestContainers and other containerization tools that leverage Unix sockets
Database connections that use Unix sockets (e.g., MySQL, PostgreSQL)
Custom IPC mechanisms based on Unix sockets

Solution

The solution involves a comprehensive approach to properly handle Unix socket paths throughout the request interceptor chain:

Modified URL creation for Unix sockets:
- Updated getUrlByRequestOptions.ts to create URLs with a special hostname "unix-socket-placeholder" for Unix socket requests
- This prevents the library from attempting TCP connections to localhost
Enhanced socket connection handling:
- Updated MockHttpSocket.ts to directly create socket connections using net.createConnection({ path: socketPath }) when a socket path is specified
- This bypasses the hostname/port mechanism for Unix socket connections
Improved agent configuration:
- Modified MockAgent and MockHttpsAgent classes to properly handle and preserve the socketPath property
- Added support in baseUrlFromConnectionOptions.ts to use the same special hostname for consistency
Code organization improvements:
- Refactored ClientRequest/index.ts to extract duplicate agent creation code into a helper method
- Ensured the socketPath property is properly preserved throughout the request handling chain
Comprehensive test coverage:
- Added regression tests verifying Unix socket connections work correctly
- Added unit tests for normalizeClientRequestArgs.ts to verify socketPath preservation
- Added tests for getUrlByRequestOptions.ts to verify special hostname URL creation

Testing

The fix has been thoroughly tested with:

Direct Unix socket connections to local test servers
GET and POST requests with various headers and body content
Error handling for non-existent sockets
Integration with the full interception pipeline

All tests are now passing, confirming that Unix socket connections are properly handled.

Related Issues

This fix addresses issues encountered when working with applications that leverage Unix sockets for communication, particularly in containerized environments or when interacting with system services.

vinialbano · 2025-05-20T21:04:26Z

Hi @kettanaito, were you able to take a look at this by any chance?
Or @msutkowski, @marcosvega91, @timdeschryver

mikicho · 2025-06-07T09:42:01Z

I'm wondering what the expected behavior is from this lib POV. Should we intercept them or automatically pass through?

vinialbano · 2025-06-07T16:16:40Z

I'm wondering what the expected behavior is from this lib POV. Should we intercept them or automatically pass through?

That's a great question @mikicho. Could this introduce any vulnerabilities if requests were intercepted? I see no harm in passing them through. I recognize some use cases for intercepting them, but they should probably be rarely explored, and I'm not sure if any security issues might arise.

kettanaito · 2025-06-08T16:10:17Z

Sorry, I didn't have the time to look into this. Will do my best to review this this month.

kettanaito

Thank you so much for working on this!

I think we should handle socketPath properly. That being said, I disagree with some of the directions taken by this solution. Please see my comments.

The parts I do like:

The normalize client args test;
The url-from-options test;
The fixes for the above seem good.

My main concern is that socketPath is a request option, not an agent option, and as such, drilling it through MockAgent is wrong. We should explore other ways to reference that option, like from within MockHttpSocket itself.

kettanaito · 2025-06-08T16:11:04Z

src/interceptors/ClientRequest/MockHttpSocket.ts

+
+    // For Unix socket paths, create a direct socket connection
+    if (this.connectionOptions.socketPath) {
+      socket = net.createConnection({ path: this.connectionOptions.socketPath })


this.createConnection() should already encapsulate net.createConnection(connectionOptions) within itself. Does it not?

kettanaito · 2025-06-08T16:11:56Z

src/interceptors/ClientRequest/agents.ts

    this.customAgent = options.customAgent
    this.onRequest = options.onRequest
    this.onResponse = options.onResponse
+    this.socketPath = options.socketPath


But is socketPath an actual property on http.Agent? If we are drilling this here for convenience, and the real agent doesn't in fact list socketPath, we should rethink the approach.

kettanaito · 2025-06-08T16:12:39Z

src/interceptors/ClientRequest/index.test.ts

+
+describe('Unix socket handling', () => {
+  // Skip these tests in environments that don't support Unix sockets
+  if (process.platform === 'win32') {


We don't run tests on Windows so this can be dropped altogether.

kettanaito · 2025-06-08T16:12:49Z

src/interceptors/ClientRequest/index.test.ts

  expect(res.headers['x-custom-header']).toEqual('Yes')
 })
+
+describe('Unix socket handling', () => {


If possible, please adhere to the flat test case structure. Thanks!

In fact, what you are solving warrants either a compliance or regression test. It would be great to put the new test case in the respective folder.

kettanaito · 2025-06-08T16:14:06Z

src/interceptors/ClientRequest/index.test.ts

+    }
+
+    // When
+    const agent = new agents.MockAgent(agentOptions)


This isn't a correct test. I appreciate the unit test approach here but we don't do that with Interceptors because our goal is to provide compliance with existing request clients.

This test has to be rewritten without using our internal classes at all. Just plain http.* usage as the client would use it.

kettanaito · 2025-06-08T16:15:51Z

src/interceptors/ClientRequest/index.ts

+      customAgent: options.agent,
+      onRequest,
+      onResponse,
+      ...(options.socketPath && { socketPath: options.socketPath }),


I believe this answers my previous concern about the socketPath being an agent option. It is not. Here, we are manually making it be one and that breaches the responsibility of the MockAgent class.

We should rethink this approach. Note that you should be able to get the original ClientRequest options from within the MockHttpSocket. Perhaps that would be a better solution.

kettanaito · 2025-06-08T16:16:34Z

src/interceptors/ClientRequest/utils/normalizeClientRequestArgs.ts

@@ -1,31 +1,31 @@
-import { urlToHttpOptions } from 'node:url'
+import { Logger } from '@open-draft/logger'


Do you have an import sorter plugin or similar? Please disable and revert formatting on this file.

kettanaito · 2025-06-08T16:17:15Z

src/interceptors/Socket/utils/baseUrlFromConnectionOptions.ts

@@ -1,4 +1,17 @@
 export function baseUrlFromConnectionOptions(options: any): URL {
+  // Handle Unix socket paths
+  if (options.socketPath) {


Because socketPath and request URL properties are mutually exclusive, right? One cannot provide both?

kettanaito · 2025-06-08T16:18:23Z

src/utils/getUrlByRequestOptions.ts

-export type ResolvedRequestOptions = RequestOptions & RequestSelf
+export type ResolvedRequestOptions = RequestOptions &
+  RequestSelf & {
+    socketPath?: string


So socketPath isn't annotated on RequestOptions by Node.js? That's a pity.

test/modules/http/regressions/http-unix-socket-path.test.ts

kettanaito · 2025-06-08T16:21:25Z

@mikicho, correct me if I'm wrong, but socketPath seems like another way to construct a request. As a result, it performs a regular request that must be intercepted and allowed to be mocked like any other request.

mikicho · 2025-06-08T16:37:24Z

@kettanaito I'm not familiar with this either. From what I understand, it is a Unix way to communicate between processes.
From a quick look, it seems like Node translates/overrides it to path, but I may be missing something.

mikicho · 2025-06-09T22:09:05Z

@kettanaito @vinialbano I think the root cause is that we create a custom agent and then override the path property, which determines the type of the request (pipe/tcp), with null. It should be the socket path in order to create a pipe connection.
When I disable it or send agent: false in the options, it works like a charm:

const request = http.get({
  socketPath,
  path: '/test-get',
  agent: false, // Disable the default agent
})

@kettanaito I believe this logic is outdated and no longer applicable to the socket-level interceptor we are currently using. After running a quick check, I noticed that all the tests still passed when I commented out these lines. We may want to remove it.

kettanaito · 2025-07-17T13:17:43Z

@mikicho, I think you are right regarding the default agent. Nice find!

kettanaito · 2025-07-17T13:22:37Z

Do we need any additional changes to support Unix socket paths after #731?

kettanaito · 2025-10-19T10:32:47Z

Update

I've moved the tests introduced in this pull request to #751, where they are passing without any additional changes. It looks like #731 has indeed fixed this issue.

Interestingly enough, we already had Unix socket tests at test/modules/http/compliance/http-unix-socket.test.ts and they were always passing. I wonder if this issue addresses something that the suggested tests does not cover. cc @vinialbano

kettanaito · 2025-10-19T10:37:14Z

Since the tests are passing, I'm consider this issue non-reproducible. If it still happens, please open a pull request with a failing test to confirm that. Thanks!

kettanaito · 2025-10-19T10:40:08Z

Released: v0.40.0 🎉

This has been released in v0.40.0!

📄 Release notes
📦 npm package

Make sure to always update to the latest version (npm i @mswjs/interceptors@latest) to get the newest features and bug fixes.

Predictable release automation by @ossjs/release.

fix: properly handle Unix socket paths in interceptors

cd07a9d

vinialbano mentioned this pull request May 6, 2025

nock@14 breaks testcontainers nock/nock#2839

Closed

2 tasks

mikicho requested a review from kettanaito May 6, 2025 19:52

kettanaito requested changes Jun 8, 2025

View reviewed changes

mikicho mentioned this pull request Jun 11, 2025

fix(ClientRequest): remove the fallback Agent if the request option agent is undefined #731

Merged

Merge branch 'main' into fix-unix-socket-handling

3997199

kettanaito mentioned this pull request Oct 19, 2025

test: add http unix socket test cases #751

Merged

kettanaito closed this in #751 Oct 19, 2025

georgewaters mentioned this pull request Dec 30, 2025

Intermittent EPIPE errors with high-concurrency Unix socket requests #760

Open

		@@ -1,31 +1,31 @@
		import { urlToHttpOptions } from 'node:url'
		import { Logger } from '@open-draft/logger'

Uh oh!

Conversation

vinialbano commented May 6, 2025 • edited by kettanaito Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Fix Unix socket path handling in MSW Interceptors

Problem

Solution

Testing

Related Issues

Uh oh!

vinialbano commented May 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mikicho commented Jun 7, 2025

Uh oh!

vinialbano commented Jun 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kettanaito commented Jun 8, 2025

Uh oh!

kettanaito left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kettanaito commented Jun 8, 2025

Uh oh!

mikicho commented Jun 8, 2025

Uh oh!

mikicho commented Jun 9, 2025

Uh oh!

kettanaito commented Jul 17, 2025

Uh oh!

kettanaito commented Jul 17, 2025

Uh oh!

kettanaito commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Update

Uh oh!

kettanaito commented Oct 19, 2025

Uh oh!

kettanaito commented Oct 19, 2025

Released: v0.40.0 🎉

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vinialbano commented May 6, 2025 •

edited by kettanaito

Loading

vinialbano commented May 20, 2025 •

edited

Loading

vinialbano commented Jun 7, 2025 •

edited

Loading

kettanaito commented Oct 19, 2025 •

edited

Loading