{ "type": "module", "source": "doc/api/api-socks5proxyagent.md", "modules": [ { "textRaw": "Socks5ProxyAgent", "name": "socks5proxyagent", "introduced_in": "v7.23.0", "type": "module", "stability": 1, "stabilityText": "Experimental", "desc": "

A [Dispatcher][] implementation that routes requests through a SOCKS5\nproxy server. It tunnels both HTTP and HTTPS traffic over the proxy, supports\noptional username/password authentication, and pools connections per origin so\nthat subsequent requests to the same host reuse the established tunnel.

\n

DNS resolution is delegated to the proxy: target host names are sent to the\nproxy as domain names rather than being resolved locally. For HTTPS targets the\nTLS session is negotiated end-to-end through the tunnel, so the proxy only sees\nencrypted bytes.

\n

Import it from 'undici':

\n
import { Socks5ProxyAgent } from 'undici'\n
\n

Constructing the agent emits a one-time ExperimentalWarning, reflecting the\nexperimental status of SOCKS5 support.

", "classes": [ { "textRaw": "Class: `Socks5ProxyAgent`", "name": "Socks5ProxyAgent", "type": "class", "meta": { "added": [ "v7.23.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "desc": "\n

Routes dispatched requests through a SOCKS5 proxy. Register an instance as the\nglobal dispatcher with [setGlobalDispatcher()][], or pass it per request via\nthe dispatcher option.

", "signatures": [ { "textRaw": "`new Socks5ProxyAgent(proxyUrl[, options])`", "name": "Socks5ProxyAgent", "type": "ctor", "meta": { "added": [ "v7.23.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "params": [ { "textRaw": "`proxyUrl` {string|URL} The SOCKS5 proxy server URL. Must use the `socks5:` or `socks:` protocol. Credentials may be embedded in the URL userinfo (for example `socks5://user:pass@host:1080`).", "name": "proxyUrl", "type": "string|URL", "desc": "The SOCKS5 proxy server URL. Must use the `socks5:` or `socks:` protocol. Credentials may be embedded in the URL userinfo (for example `socks5://user:pass@host:1080`)." }, { "textRaw": "`options` {Object} (optional) Extends {PoolOptions}; the pool options are applied to the per-origin pools created behind the tunnel.", "name": "options", "type": "Object", "desc": "(optional) Extends {PoolOptions}; the pool options are applied to the per-origin pools created behind the tunnel.", "options": [ { "textRaw": "`headers` {Object} Additional headers to send with the proxy connection. **Default:** `{}`.", "name": "headers", "type": "Object", "default": "`{}`", "desc": "Additional headers to send with the proxy connection." }, { "textRaw": "`username` {string} Username for SOCKS5 authentication. Takes precedence over a username embedded in `proxyUrl`. **Default:** the URL username, if any.", "name": "username", "type": "string", "default": "the URL username, if any", "desc": "Username for SOCKS5 authentication. Takes precedence over a username embedded in `proxyUrl`." }, { "textRaw": "`password` {string} Password for SOCKS5 authentication. Takes precedence over a password embedded in `proxyUrl`. **Default:** the URL password, if any.", "name": "password", "type": "string", "default": "the URL password, if any", "desc": "Password for SOCKS5 authentication. Takes precedence over a password embedded in `proxyUrl`." }, { "textRaw": "`connect` {Function} Custom connector used to open the socket to the proxy. **Default:** a connector built from `proxyTls`.", "name": "connect", "type": "Function", "default": "a connector built from `proxyTls`", "desc": "Custom connector used to open the socket to the proxy." }, { "textRaw": "`proxyTls` {BuildOptions} TLS options for the connection to the proxy itself (SOCKS5 over TLS). When set, the proxy connection is established over TLS and `servername` defaults to the proxy host name.", "name": "proxyTls", "type": "BuildOptions", "desc": "TLS options for the connection to the proxy itself (SOCKS5 over TLS). When set, the proxy connection is established over TLS and `servername` defaults to the proxy host name." }, { "textRaw": "`requestTls` {BuildOptions} TLS options applied to the end-to-end connection to an HTTPS target through the tunnel, such as `ca`, `cert`, `key`, `rejectUnauthorized`, and `servername`. `servername` defaults to the target host name.", "name": "requestTls", "type": "BuildOptions", "desc": "TLS options applied to the end-to-end connection to an HTTPS target through the tunnel, such as `ca`, `cert`, `key`, `rejectUnauthorized`, and `servername`. `servername` defaults to the target host name." } ], "optional": true } ], "desc": "

Throws an InvalidArgumentError if proxyUrl is missing or does not use the\nsocks5: or socks: protocol.

\n
import { Socks5ProxyAgent } from 'undici'\n\n// Without authentication.\nconst agent = new Socks5ProxyAgent('socks5://localhost:1080')\n\n// With credentials in the URL.\nconst authAgent = new Socks5ProxyAgent('socks5://user:pass@localhost:1080')\n\n// With credentials and pool options.\nconst configuredAgent = new Socks5ProxyAgent('socks5://localhost:1080', {\n  username: 'user',\n  password: 'pass',\n  connections: 10\n})\n
\n

Using the agent as the global dispatcher:

\n
import { setGlobalDispatcher, request, Socks5ProxyAgent } from 'undici'\n\nconst agent = new Socks5ProxyAgent('socks5://localhost:1080')\nsetGlobalDispatcher(agent)\n\nconst { statusCode, body } = await request('http://localhost:3000/foo')\nconsole.log('response received', statusCode)\n\nfor await (const data of body) {\n  console.log('data', data.toString('utf8'))\n}\n
\n

Using the agent per request:

\n
import { request, Socks5ProxyAgent } from 'undici'\n\nconst agent = new Socks5ProxyAgent('socks5://localhost:1080')\n\nconst { statusCode, body } = await request('http://localhost:3000/foo', {\n  dispatcher: agent\n})\n\nconsole.log('response received', statusCode)\n
\n

HTTPS targets are tunnelled and encrypted end-to-end:

\n
import { request, Socks5ProxyAgent } from 'undici'\n\nconst agent = new Socks5ProxyAgent('socks5://localhost:1080')\n\nconst { statusCode, body } = await request('https://api.example.com/data', {\n  dispatcher: agent\n})\n\nconsole.log('Response status:', statusCode)\nconsole.log('Response data:', await body.json())\n
" } ], "methods": [ { "textRaw": "`socks5ProxyAgent.close()`", "name": "close", "type": "method", "meta": { "added": [ "v7.23.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "params": [], "return": { "textRaw": "Returns: {Promise} Resolves once every per-origin pool has been closed.", "name": "return", "type": "Promise", "desc": "Resolves once every per-origin pool has been closed." } } ], "desc": "

Gracefully closes the agent, waiting for all underlying pools and their\nconnections to drain and close before resolving.

\n
import { setGlobalDispatcher, Socks5ProxyAgent } from 'undici'\n\nconst agent = new Socks5ProxyAgent('socks5://localhost:1080')\nsetGlobalDispatcher(agent)\n\n// ... make requests ...\n\nawait agent.close()\n
" }, { "textRaw": "`socks5ProxyAgent.destroy([err])`", "name": "destroy", "type": "method", "meta": { "added": [ "v7.23.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "params": [ { "textRaw": "`err` {Error} (optional) The error to reject in-flight requests with.", "name": "err", "type": "Error", "desc": "(optional) The error to reject in-flight requests with.", "optional": true } ], "return": { "textRaw": "Returns: {Promise} Resolves once every per-origin pool has been destroyed.", "name": "return", "type": "Promise", "desc": "Resolves once every per-origin pool has been destroyed." } } ], "desc": "

Forcibly destroys the agent and all underlying connections immediately, without\nwaiting for in-flight requests to complete.

\n
import { Socks5ProxyAgent } from 'undici'\n\nconst agent = new Socks5ProxyAgent('socks5://localhost:1080')\n\nawait agent.destroy()\n
" }, { "textRaw": "`socks5ProxyAgent.dispatch(options, handlers)`", "name": "dispatch", "type": "method", "meta": { "added": [ "v7.23.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "params": [ { "textRaw": "`options` {DispatchOptions}", "name": "options", "type": "DispatchOptions" }, { "textRaw": "`handlers` {DispatchHandler}", "name": "handlers", "type": "DispatchHandler" } ], "return": { "textRaw": "Returns: {boolean} `false` if the dispatcher is busy and the request should be retried later, otherwise `true`.", "name": "return", "type": "boolean", "desc": "`false` if the dispatcher is busy and the request should be retried later, otherwise `true`." } } ], "desc": "

Routes a request through the SOCKS5 tunnel. The agent maintains a [Pool][] per\ntarget origin; the first request to a given origin establishes the tunnel and\nupgrades to TLS when the target is HTTPS, and later requests reuse the pool.

\n

This is the lower-level entry point implementing\nDispatcher.dispatch(options, handlers). Prefer\n[socks5ProxyAgent.request()][] for most use cases.

" }, { "textRaw": "`socks5ProxyAgent.request(options[, callback])`", "name": "request", "type": "method", "meta": { "added": [ "v7.23.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "signatures": [ { "params": [ { "textRaw": "`options` {DispatchOptions}", "name": "options", "type": "DispatchOptions" }, { "textRaw": "`callback` {Function} (optional)", "name": "callback", "type": "Function", "desc": "(optional)", "optional": true } ], "return": { "textRaw": "Returns: {Promise|void} A promise resolving to the response when `callback` is omitted.", "name": "return", "type": "Promise|void", "desc": "A promise resolving to the response when `callback` is omitted." } } ], "desc": "

Performs a request through the SOCKS5 proxy. Inherited from\n[Dispatcher.request(options[, callback])][]; see that method for the full set\nof options and the shape of the resolved response.

\n
import { fetch, Socks5ProxyAgent } from 'undici'\n\nconst agent = new Socks5ProxyAgent('socks5://localhost:1080')\n\nconst response = await fetch('http://localhost:3000/api/users', {\n  dispatcher: agent\n})\n\nconsole.log('Response status:', response.status)\nconsole.log('Response data:', await response.text())\n
" } ] } ], "modules": [ { "textRaw": "Debugging", "name": "debugging", "type": "module", "desc": "

SOCKS5 proxy activity can be traced with the undici:socks5-proxy debug scope:

\n
NODE_DEBUG=undici:socks5-proxy node script.js\n
\n

This logs the SOCKS5 handshake, authentication, and tunnel establishment steps.

\n

[Dispatcher.request(options[, callback])]: Dispatcher.md#dispatcherrequestoptions-callback\n[Dispatcher]: Dispatcher.md#class-dispatcher\n[Pool]: Pool.md#class-pool\n[setGlobalDispatcher()]: Dispatcher.md#setglobaldispatcherdispatcher\n[socks5ProxyAgent.request()]: #socks5proxyagentrequestoptions-callback

", "displayName": "Debugging" } ] } ] }