feat(socks5): add SOCKS5 proxy support

docs/guides/http/proxy.mdx

@@ -4,7 +4,7 @@ sidebarTitle: Proxy HTTP requests using fetch()
 mode: center
 ---
 
-In Bun, `fetch` supports sending requests through an HTTP or HTTPS proxy. This is useful on corporate networks or when you need to ensure a request is sent through a specific IP address.
+In Bun, `fetch` supports sending requests through an HTTP, HTTPS, or SOCKS proxy. This is useful on corporate networks or when you need to ensure a request is sent through a specific IP address.
 
 ```ts proxy.ts icon="/icons/typescript.svg"
 await fetch("https://example.com", {
@@ -15,7 +15,17 @@ await fetch("https://example.com", {
 
 ---
 
-The `proxy` option can be a URL string or an object with `url` and optional `headers`. The URL can include the username and password if the proxy requires authentication. It can be `http://` or `https://`.
+The `proxy` option can be a URL string or an object with `url` and optional `headers`. The URL can include the username and password if the proxy requires authentication. It can be `http://`, `https://`, `socks5://`, or `socks5h://`.
+
+```ts socks-proxy.ts icon="/icons/typescript.svg"
+await fetch("https://example.com", {
+  proxy: "socks5h://username:password@127.0.0.1:1080",
+});
+```
+
+For SOCKS proxies, credentials are sent using SOCKS username/password authentication. With `socks5://`, Bun resolves the target hostname locally and sends the resolved IP address to the proxy. With `socks5h://`, Bun sends the hostname to the proxy and lets the proxy resolve DNS.
+
+Custom `proxy.headers` only apply to HTTP and HTTPS proxies.
 
 ---
 
@@ -35,7 +45,7 @@ await fetch("https://example.com", {
 });
 ```
 
-The `headers` property accepts a plain object or a `Headers` instance. These headers are sent directly to the proxy server in `CONNECT` requests (for HTTPS targets) or in the proxy request (for HTTP targets).
+The `headers` property accepts a plain object or a `Headers` instance. These headers are sent directly to HTTP and HTTPS proxy servers in `CONNECT` requests (for HTTPS targets) or in the proxy request (for HTTP targets).
 
 If you provide a `Proxy-Authorization` header, it will override any credentials specified in the proxy URL.
 
@@ -48,3 +58,7 @@ You can also set the `$HTTP_PROXY` or `$HTTPS_PROXY` environment variable to the
 ```sh terminal icon="terminal"
 HTTPS_PROXY=https://username:password@proxy.example.com:8080 bun run index.ts
 ```
+
+```sh terminal icon="terminal"
+HTTPS_PROXY=socks5h://username:password@127.0.0.1:1080 bun run index.ts
+```

docs/runtime/networking/fetch.mdx

@@ -59,6 +59,15 @@ const response = await fetch("http://example.com", {
 });
 ```
 
+The proxy URL can use `http://`, `https://`, `socks5://`, or `socks5h://`.
+SOCKS proxies support username/password credentials in the proxy URL. With `socks5://`, Bun resolves the target hostname locally and sends the resolved IP address to the proxy. With `socks5h://`, Bun sends the hostname to the proxy and lets the proxy resolve DNS:
+
+```ts
+const response = await fetch("https://example.com", {
+  proxy: "socks5h://username:password@127.0.0.1:1080",
+});
+```
+
 You can also use an object format to send custom headers to the proxy server:
 
 ```ts
@@ -73,7 +82,7 @@ const response = await fetch("http://example.com", {
 });
 ```
 
-The `headers` are sent directly to the proxy in `CONNECT` requests (for HTTPS targets) or in the proxy request (for HTTP targets). If you provide a `Proxy-Authorization` header, it overrides any credentials in the proxy URL.
+The `headers` are sent directly to HTTP and HTTPS proxies in `CONNECT` requests (for HTTPS targets) or in the proxy request (for HTTP targets). If you provide a `Proxy-Authorization` header, it overrides any credentials in the proxy URL. Custom proxy headers do not apply to SOCKS proxies.
 
 ### Custom headers
 

packages/bun-types/bun.d.ts

@@ -4219,9 +4219,14 @@ declare module "bun" {
 
   type WebSocketOptionsProxy = {
     /**
-     * HTTP proxy to use for the WebSocket connection.
+     * Proxy to use for the WebSocket connection.
      *
      * Can be a string URL or an object with `url` and optional `headers`.
+     * Supported proxy URL schemes are `http:`, `https:`, `socks5:`, and
+     * `socks5h:`. SOCKS proxies support username/password credentials in the
+     * proxy URL. `socks5:` resolves target hostnames locally; `socks5h:`
+     * lets the proxy resolve target hostnames. `proxy.headers` only applies
+     * to HTTP(S) proxies.
      *
      * @example
      * ```ts
@@ -4250,7 +4255,7 @@ declare module "bun" {
       | string
       | {
           /**
-           * The proxy URL (http:// or https://)
+           * The proxy URL (`http://`, `https://`, `socks5://`, or `socks5h://`)
            */
           url: string;
           /**

packages/bun-types/globals.d.ts

@@ -1937,6 +1937,10 @@ interface BunFetchRequestInit extends RequestInit {
    * This is a custom property that is not part of the Fetch API specification.
    *
    * Can be a string URL or an object with `url` and optional `headers`.
+   * Supported proxy URL schemes are `http:`, `https:`, `socks5:`, and `socks5h:`.
+   * SOCKS proxies support username/password credentials in the proxy URL.
+   * `socks5:` resolves target hostnames locally; `socks5h:` lets the proxy
+   * resolve target hostnames. `proxy.headers` only applies to HTTP(S) proxies.
    *
    * @example
    * ```js

src/http/AsyncHTTP.zig

@@ -173,7 +173,7 @@ pub fn init(
         .result_callback = callback,
         .http_proxy = options.http_proxy,
         .signals = options.signals orelse .{},
-        .async_http_id = if (options.signals != null and options.signals.?.aborted != null) bun.http.async_http_id_monotonic.fetchAdd(1, .monotonic) else 0,
+        .async_http_id = if (options.signals != null and options.signals.?.aborted != null) bun.http.nextAsyncHTTPID() else 0,
     };
 
     this.client = .{
@@ -213,7 +213,9 @@ pub fn init(
     }
 
     if (options.http_proxy) |proxy| {
-        if (proxy.username.len > 0) {
+        const is_socks = strings.eqlComptime(proxy.protocol, "socks5") or strings.eqlComptime(proxy.protocol, "socks5h");
+        this.client.flags.disable_keepalive = this.client.flags.disable_keepalive or this.url.isHTTPS() or is_socks;
+        if (!is_socks and proxy.username.len > 0) {
             // Use stack fallback allocator - stack for small credentials, heap for large ones
             var username_sfb = std.heap.stackFallback(4096, allocator);
             const username_alloc = username_sfb.get();
@@ -283,14 +285,16 @@ pub fn initSync(
 }
 
 fn reset(this: *AsyncHTTP) !void {
+    const disable_keepalive = this.client.flags.disable_keepalive;
     const aborted = this.client.aborted;
     this.client = try HTTPClient.init(this.allocator, this.method, this.client.url, this.client.header_entries, this.client.header_buf, aborted);
     this.client.http_proxy = this.http_proxy;
 
     if (this.http_proxy) |proxy| {
+        const is_socks = strings.eqlComptime(proxy.protocol, "socks5") or strings.eqlComptime(proxy.protocol, "socks5h");
         //TODO: need to understand how is possible to reuse Proxy with TSL, so disable keepalive if url is HTTPS
-        this.client.flags.disable_keepalive = this.url.isHTTPS();
-        if (proxy.username.len > 0) {
+        this.client.flags.disable_keepalive = disable_keepalive or this.url.isHTTPS() or is_socks;
+        if (!is_socks and proxy.username.len > 0) {
             // Use stack fallback allocator - stack for small credentials, heap for large ones
             var username_sfb = std.heap.stackFallback(4096, this.allocator);
             const username_alloc = username_sfb.get();
@@ -475,6 +479,7 @@ const MutableString = bun.MutableString;
 const assert = bun.assert;
 const jsc = bun.jsc;
 const picohttp = bun.picohttp;
+const strings = bun.strings;
 const Channel = bun.threading.Channel;
 const SSLConfig = bun.api.server.ServerConfig.SSLConfig;
 

src/http/HTTPThread.zig

@@ -273,7 +273,10 @@ pub fn connect(this: *@This(), client: *HTTPClient, comptime is_ssl: bool) !?New
                 client.setCustomSslCtx(entry.ctx);
                 // Keepalive is now supported for custom SSL contexts
                 if (client.http_proxy) |url| {
-                    return try entry.ctx.connect(client, url.hostname, url.getPortAuto());
+                    if (!(url.protocol.len == 0 or strings.eqlComptime(url.protocol, "https") or strings.eqlComptime(url.protocol, "http") or strings.eqlComptime(url.protocol, "socks5") or strings.eqlComptime(url.protocol, "socks5h"))) {
+                        return error.UnsupportedProxyProtocol;
+                    }
+                    return try entry.ctx.connect(client, url.hostname, proxyPort(url));
                 } else {
                     return try entry.ctx.connect(client, client.url.hostname, client.url.getPortAuto());
                 }
@@ -312,8 +315,8 @@ pub fn connect(this: *@This(), client: *HTTPClient, comptime is_ssl: bool) !?New
             client.setCustomSslCtx(custom_context);
             // Keepalive is now supported for custom SSL contexts
             if (client.http_proxy) |url| {
-                if (url.protocol.len == 0 or strings.eqlComptime(url.protocol, "https") or strings.eqlComptime(url.protocol, "http")) {
-                    return try custom_context.connect(client, url.hostname, url.getPortAuto());
+                if (url.protocol.len == 0 or strings.eqlComptime(url.protocol, "https") or strings.eqlComptime(url.protocol, "http") or strings.eqlComptime(url.protocol, "socks5") or strings.eqlComptime(url.protocol, "socks5h")) {
+                    return try custom_context.connect(client, url.hostname, proxyPort(url));
                 }
                 return error.UnsupportedProxyProtocol;
             }
@@ -323,8 +326,8 @@ pub fn connect(this: *@This(), client: *HTTPClient, comptime is_ssl: bool) !?New
     if (client.http_proxy) |url| {
         if (url.href.len > 0) {
             // https://github.com/oven-sh/bun/issues/11343
-            if (url.protocol.len == 0 or strings.eqlComptime(url.protocol, "https") or strings.eqlComptime(url.protocol, "http")) {
-                return try this.context(is_ssl).connect(client, url.hostname, url.getPortAuto());
+            if (url.protocol.len == 0 or strings.eqlComptime(url.protocol, "https") or strings.eqlComptime(url.protocol, "http") or strings.eqlComptime(url.protocol, "socks5") or strings.eqlComptime(url.protocol, "socks5h")) {
+                return try this.context(is_ssl).connect(client, url.hostname, proxyPort(url));
             }
             return error.UnsupportedProxyProtocol;
         }
@@ -525,6 +528,7 @@ fn drainEvents(this: *@This()) void {
     this.drainQueuedWrites();
     this.drainQueuedShutdowns();
     bun.http.H3.PendingConnect.drainResolved();
+    bun.http.SocksDNSPending.drainResolved();
 
     for (this.queued_threadlocal_proxy_derefs.items) |http| {
         http.deref();
@@ -729,6 +733,14 @@ pub fn schedule(this: *@This(), batch: Batch) void {
 
 pub const Queue = UnboundedQueue(AsyncHTTP, .next);
 
+fn proxyPort(url: bun.URL) u16 {
+    if (strings.eqlComptime(url.protocol, "socks5") or strings.eqlComptime(url.protocol, "socks5h")) {
+        if (url.getPort()) |_| return url.getPortAuto();
+        return 1080;
+    }
+    return url.getPortAuto();
+}
+
 const log = Output.scoped(.HTTPThread, .visible);
 
 const stringZ = [:0]const u8;