feat(fetch): add proxy object format with headers support (#25090)

## Summary

- Extends `fetch()` proxy option to accept an object format: `proxy: {
url: string, headers?: Headers }`
- Allows sending custom headers to the proxy server (useful for proxy
authentication, custom routing headers, etc.)
- Headers are sent in CONNECT requests (for HTTPS targets) and direct
proxy requests (for HTTP targets)
- User-provided `Proxy-Authorization` header overrides auto-generated
credentials from URL

## Usage

```typescript
// Old format (still works)
fetch(url, { proxy: "http://proxy.example.com:8080" });

// New object format with headers
fetch(url, {
  proxy: {
    url: "http://proxy.example.com:8080",
    headers: {
      "Proxy-Authorization": "Bearer token",
      "X-Custom-Proxy-Header": "value"
    }
  }
});
```

## Test plan

- [x] Test proxy object with url string works same as string proxy
- [x] Test proxy object with headers sends headers to proxy (HTTP
target)
- [x] Test proxy object with headers sends headers in CONNECT request
(HTTPS target)
- [x] Test proxy object with Headers instance
- [x] Test proxy object with empty headers
- [x] Test proxy object with undefined headers
- [x] Test user-provided Proxy-Authorization overrides URL credentials
- [x] All existing proxy tests pass (25 total)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>

docs/guides/http/proxy.mdx

@@ -9,18 +9,42 @@ In Bun, `fetch` supports sending requests through an HTTP or HTTPS proxy. This i
 ```ts proxy.ts icon="/icons/typescript.svg"
 await fetch("https://example.com", {
   // The URL of the proxy server
-  proxy: "https://usertitle:password@proxy.example.com:8080",
+  proxy: "https://username:password@proxy.example.com:8080",
 });
 ```
 
 ---
 
-The `proxy` option is a URL string that specifies the proxy server. It 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://` or `https://`.
 
 ---
 
+## Custom proxy headers
+
+To send custom headers to the proxy server (useful for proxy authentication tokens, custom routing, etc.), use the object format:
+
+```ts proxy-headers.ts icon="/icons/typescript.svg"
+await fetch("https://example.com", {
+  proxy: {
+    url: "https://proxy.example.com:8080",
+    headers: {
+      "Proxy-Authorization": "Bearer my-token",
+      "X-Proxy-Region": "us-east-1",
+    },
+  },
+});
+```
+
+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).
+
+If you provide a `Proxy-Authorization` header, it will override any credentials specified in the proxy URL.
+
+---
+
+## Environment variables
+
 You can also set the `$HTTP_PROXY` or `$HTTPS_PROXY` environment variable to the proxy URL. This is useful when you want to use the same proxy for all requests.
 
 ```sh terminal icon="terminal"
-HTTPS_PROXY=https://usertitle:password@proxy.example.com:8080 bun run index.ts
+HTTPS_PROXY=https://username:password@proxy.example.com:8080 bun run index.ts
 ```

docs/runtime/networking/fetch.mdx

@@ -51,7 +51,7 @@ const response = await fetch("http://example.com", {
 
 ### Proxying requests
 
-To proxy a request, pass an object with the `proxy` property set to a URL.
+To proxy a request, pass an object with the `proxy` property set to a URL string:
 
 ```ts
 const response = await fetch("http://example.com", {
@@ -59,6 +59,22 @@ const response = await fetch("http://example.com", {
 });
 ```
 
+You can also use an object format to send custom headers to the proxy server:
+
+```ts
+const response = await fetch("http://example.com", {
+  proxy: {
+    url: "http://proxy.com",
+    headers: {
+      "Proxy-Authorization": "Bearer my-token",
+      "X-Custom-Proxy-Header": "value",
+    },
+  },
+});
+```
+
+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.
+
 ### Custom headers
 
 To set custom headers, pass an object with the `headers` property set to an object.