feat: add SOCKS proxy support to server-node SDK#1438
Conversation
Support SOCKS proxies via LDProxyOptions.scheme. Setting scheme to one of socks, socks4, socks4a, socks5, or socks5h routes both fetch and event-source traffic through a SOCKS proxy using socks-proxy-agent; a single agent handles both http and https targets. The proxy address is built as a URL so its username/password setters percent-encode the credentials, which socks-proxy-agent then decodes, so an auth password may safely contain characters such as ':'. TLS agent options are forwarded to the SOCKS agent for https targets. Adds end-to-end tests (polling, streaming, and username/password auth) backed by a minimal RFC 1928/1929 SOCKS5 test server.
|
Heads up on CI: the failing checks are all example-app smoke tests ( All SDK build/test checks relevant to this change pass, including |
|
Hey @bradbunce thanks for the contribution. I will need to speak with the team to see if we agree that this is a broad SDK feature that we want to pursue. UPDATE |
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
Reviewed by Cursor Bugbot for commit 597c672. Configure here.
| // A single SOCKS agent works for both http and https targets. Build the proxy address as a URL | ||
| // so its username/password setters percent-encode the credentials; socks-proxy-agent decodes | ||
| // them again, which means an `auth` password may safely contain characters such as ':'. | ||
| const proxyUrl = new URL(`${proxyOptions.scheme}://${proxyOptions.host}:${proxyOptions.port}`); |
There was a problem hiding this comment.
SOCKS proxy URL host parsing
Medium Severity
processSocksProxyOptions builds the proxy endpoint with a template string (scheme://host:port) instead of the same formatUrl / URL host handling used for HTTP proxies. IPv6 literals in proxyOptions.host (e.g. ::1) often produce an invalid URL or wrong host/port, and a missing port becomes the literal hostname suffix undefined rather than being omitted.
Reviewed by Cursor Bugbot for commit 597c672. Configure here.
2 participants
Requirements
Related issues
N/A — adds SOCKS proxy support to the Node server SDK for environments where outbound access is only available through a SOCKS proxy.
Describe the solution you've provided
Adds SOCKS proxy support to
@launchdarkly/node-server-sdk. SettingproxyOptions.schemeto one ofsocks,socks4,socks4a,socks5, orsocks5h(alongside the existingproxyOptions.host/proxyOptions.port) routes bothfetchand event-source (streaming) traffic through a SOCKS proxy, usingsocks-proxy-agent. A single agent handles bothhttpandhttpstargets.In
NodeRequests,processProxyOptionsnow branches to a newprocessSocksProxyOptionswhen the scheme is a SOCKS scheme; the existinghttps-proxy-agentpath is unchanged forhttp/httpsschemes. TLS agent options are forwarded to the SOCKS agent sohttpstargets are still validated.Credentials from
proxyOptions.auth("username:password", the same format as the HTTP proxy) are applied via aURLobject'susername/passwordsetters, which percent-encode them;socks-proxy-agentdecodes them again. This means a password may safely contain characters such as:(everything after the first colon inauthis treated as the password).Describe alternatives you've considered
https-proxy-agentpath —https-proxy-agentonly supports HTTP CONNECT proxies, not SOCKS.socks://user:pass@host:portstring — rejected in favor of theURLsetters, which handle percent-encoding (including:in the password) correctly without manualencodeURIComponentcalls.Additional context
New end-to-end tests cover polling, streaming, and username/password auth (including a colon in the password), backed by a minimal RFC 1928/1929 SOCKS5 test server (
__tests__/socksProxyServer.ts). The fullserver-nodetest suite passes and lint is clean. Validated locally on Node 20, including against a real Dante SOCKS5 proxy reaching live LaunchDarkly; relying on CI for the full supported-version matrix (hence the third box left unchecked).Note
Medium Risk
Changes the outbound networking stack for proxied SDK traffic (fetch and SSE), but the change is additive with HTTP proxies untouched and solid e2e coverage.
Overview
Adds SOCKS proxy routing for
@launchdarkly/node-server-sdkthrough the existingproxyOptionsconfig. Whenschemeissocks,socks4,socks4a,socks5, orsocks5h,NodeRequestsbuilds aSocksProxyAgent(newsocks-proxy-agentdependency) instead ofhttps-proxy-agent; HTTP/HTTPS proxy behavior is unchanged.Credentials still use
authasusername:password, with only the first:splitting user and password so passwords can contain colons; values are applied viaURLusername/password setters for correct encoding. The same agent is used for pollingfetchand streaming EventSource traffic.LDProxyOptionsJSDoc is updated to document SOCKS schemes. New integration tests use a minimal in-process SOCKS5 server (polling, streaming, and authenticated proxy).TESTING.mddocuments how to consume a local monorepo build and try SOCKS config before publish.Reviewed by Cursor Bugbot for commit 597c672. Bugbot is set up for automated code reviews on this repo. Configure here.