Skip to content

Support Unix domain sockets in the local Mockttp server - #233

Open
clivejefferies wants to merge 1 commit into
httptoolkit:mainfrom
clivejefferies:codex/unix-socket-listener
Open

clivejefferies wants to merge 1 commit into
httptoolkit:mainfrom
clivejefferies:codex/unix-socket-listener

Conversation

@clivejefferies

Copy link
Copy Markdown

Support Unix domain sockets in the local Mockttp server

Tools that embed Mockttp can already route traffic through a local relay.
Allowing the proxy to listen on a filesystem socket lets the relay reach it
using an app-owned directory and avoids opening a host TCP port. Our use case
is a debug-only Android emulator trace whose guest loopback relay carries
connections over ADB.

This adds a Node-only option to the existing local API.

const proxy = getLocal({ unixSocketPath: socketPath });
await proxy.start();
try {
    await proxy.forGet('/status').thenReply(204);
    // Connect with a Node HTTP client using { socketPath }.
} finally {
    await proxy.stop();
}

The caller supplies an absolute path in an existing directory. The listener
rejects an occupied path and removes its socket on shutdown. The existing TCP
startup behavior is preserved. Unix mode rejects a TCP port argument and
reports a clear error if the caller requests the TCP-specific port or URL.

Verification

  • The TypeScript source build passed.
  • Four focused tests covered HTTP over the socket, socket removal, collision
    ownership, invalid options, and default TCP startup.
  • A local HTTPS forwarding check passed over HTTP CONNECT. An invalid upstream
    certificate and an upstream hostname mismatch each failed before HTTP reached
    the origin.
  • An Android API 36 debug fixture reached a local HTTPS origin through the ADB
    relay and the compiled draft.

@CLAassistant

CLAassistant commented Nov 12, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@pimterry

Copy link
Copy Markdown
Member

This needs more thought I think. There's a lot of code in here (and probably in sub-dependencies) that assumes we have a TCP socket somewhere, and TCP address info available. We use the remote & local address and port for various things, like calculating client-relative addresses (getClientRelativeHostname), socket loop detection, metadata on various event types, probably more. And we use socket-only APIs like resetAndDestroy in a few places which will blow up when this is active.

Tests are failing here because of an issue with latest Node on main, that's unrelated. That's already fixed on main, but you'll need to rebase to get this passing. You'll find the rebase also adds some challenges though, as #223 adds another new way we use TCP ports to control traffic, so that may need some handling too.

@clivejefferies

Copy link
Copy Markdown
Author

This needs more thought I think. There's a lot of code in here (and probably in sub-dependencies) that assumes we have a TCP socket somewhere, and TCP address info available. We use the remote & local address and port for various things, like calculating client-relative addresses (getClientRelativeHostname), socket loop detection, metadata on various event types, probably more. And we use socket-only APIs like resetAndDestroy in a few places which will blow up when this is active.

Tests are failing here because of an issue with latest Node on main, that's unrelated. That's already fixed on main, but you'll need to rebase to get this passing. You'll find the rebase also adds some challenges though, as #223 adds another new way we use TCP ports to control traffic, so that may need some handling too.

Do you think there might be a simpler approach?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants