Extends: undici.Dispatcher
A SOCKS5 proxy wrapper class that implements the Dispatcher API. It enables HTTP requests to be routed through a SOCKS5 proxy server, providing connection tunneling and authentication support.
", "signatures": [ { "textRaw": "`new Socks5ProxyAgent(proxyUrl[, options])`", "name": "Socks5ProxyAgent", "type": "ctor", "params": [ { "name": "proxyUrl" }, { "name": "options", "optional": true } ], "desc": "Arguments:
\nstring | URL (required) - The SOCKS5 proxy server URL. Must use socks5:// or socks:// protocol.Socks5ProxyAgent.Options (optional) - Additional configuration options.Returns: Socks5ProxyAgent
Extends: PoolOptions
IncomingHttpHeaders (optional) - Additional headers to send with proxy connections.string (optional) - SOCKS5 proxy username for authentication. Can also be provided in the proxy URL.string (optional) - SOCKS5 proxy password for authentication. Can also be provided in the proxy URL.Function (optional) - Custom connector function for the proxy connection.BuildOptions (optional) - TLS options for the proxy connection (when using SOCKS5 over TLS).BuildOptions (optional) - TLS options applied to the HTTPS connection to the target server through the SOCKS5 tunnel. Use this to configure ca, cert, key, rejectUnauthorized, servername, etc. for the target HTTPS endpoint.Examples:
\nimport { Socks5ProxyAgent } from 'undici'\n\nconst socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')\n// or with authentication\nconst socks5ProxyWithAuth = new Socks5ProxyAgent('socks5://user:pass@localhost:1080')\n// or with options\nconst socks5ProxyWithOptions = new Socks5ProxyAgent('socks5://localhost:1080', {\n username: 'user',\n password: 'pass',\n connections: 10\n})\nThis will instantiate the Socks5ProxyAgent. It will not do anything until registered as the dispatcher to use with requests.
\nimport { Socks5ProxyAgent } from 'undici'\n\nconst socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')\nimport { setGlobalDispatcher, request, Socks5ProxyAgent } from 'undici'\n\nconst socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')\nsetGlobalDispatcher(socks5Proxy)\n\nconst { statusCode, body } = await request('http://localhost:3000/foo')\n\nconsole.log('response received', statusCode) // response received 200\n\nfor await (const data of body) {\n console.log('data', data.toString('utf8')) // data foo\n}\nimport { Socks5ProxyAgent, request } from 'undici'\n\nconst socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')\n\nconst {\n statusCode,\n body\n} = await request('http://localhost:3000/foo', { dispatcher: socks5Proxy })\n\nconsole.log('response received', statusCode) // response received 200\n\nfor await (const data of body) {\n console.log('data', data.toString('utf8')) // data foo\n}\nimport { setGlobalDispatcher, request, Socks5ProxyAgent } from 'undici'\n\n// Authentication via URL\nconst socks5Proxy = new Socks5ProxyAgent('socks5://username:password@localhost:1080')\n\n// Or authentication via options\n// const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080', {\n// username: 'username',\n// password: 'password'\n// })\n\nsetGlobalDispatcher(socks5Proxy)\n\nconst { statusCode, body } = await request('http://localhost:3000/foo')\n\nconsole.log('response received', statusCode) // response received 200\n\nfor await (const data of body) {\n console.log('data', data.toString('utf8')) // data foo\n}\nSOCKS5 proxy supports both HTTP and HTTPS requests through tunneling:
\nimport { Socks5ProxyAgent, request } from 'undici'\n\nconst socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')\n\nconst response = await request('https://api.example.com/data', {\n dispatcher: socks5Proxy,\n method: 'GET'\n})\n\nconsole.log('Response status:', response.statusCode)\nconsole.log('Response data:', await response.body.json())\nimport { Socks5ProxyAgent, fetch } from 'undici'\n\nconst socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')\n\nconst response = await fetch('http://localhost:3000/api/users', {\n dispatcher: socks5Proxy,\n method: 'GET'\n})\n\nconsole.log('Response status:', response.status)\nconsole.log('Response data:', await response.text())\nSOCKS5ProxyWrapper automatically manages connection pooling for better performance:
\nimport { Socks5ProxyAgent, request } from 'undici'\n\nconst socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080', {\n connections: 10, // Allow up to 10 concurrent connections\n pipelining: 1 // Enable HTTP/1.1 pipelining\n})\n\n// Multiple requests will reuse connections through the SOCKS5 tunnel\nconst responses = await Promise.all([\n request('http://api.example.com/endpoint1', { dispatcher: socks5Proxy }),\n request('http://api.example.com/endpoint2', { dispatcher: socks5Proxy }),\n request('http://api.example.com/endpoint3', { dispatcher: socks5Proxy })\n])\n\nconsole.log('All requests completed through the same SOCKS5 proxy')\nCloses the SOCKS5 proxy wrapper and waits for all underlying pools and connections to close before resolving.
\nReturns: Promise<void>
import { Socks5ProxyAgent, setGlobalDispatcher } from 'undici'\n\nconst socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')\nsetGlobalDispatcher(socks5Proxy)\n\n// ... make requests\n\nawait socks5Proxy.close()\nDestroys the SOCKS5 proxy wrapper and all underlying connections immediately.
\nArguments:
\nError (optional) - The error that caused the destruction.Returns: Promise<void>
import { Socks5ProxyAgent } from 'undici'\n\nconst socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')\n\n// Force close all connections\nawait socks5Proxy.destroy()\nImplements Dispatcher.dispatch(options, handlers).
See Dispatcher.request(options [, callback]).
SOCKS5 proxy connections can be debugged using Node.js diagnostics:
\nNODE_DEBUG=undici:socks5 node script.js\nThis will output detailed information about the SOCKS5 handshake, authentication, and connection establishment.
", "displayName": "Debugging" }, { "textRaw": "SOCKS5 Protocol Support", "name": "socks5_protocol_support", "type": "module", "desc": "The Socks5ProxyAgent supports the following SOCKS5 features:
", "modules": [ { "textRaw": "Authentication Methods", "name": "authentication_methods", "type": "module", "desc": "0x00) - For public or internal proxies0x02) - RFC 1929 authentication0x01) - Standard IPv4 addresses0x03) - Domain names (recommended for flexibility)0x04) - IPv6 addresses (full support for standard and compressed notation)0x01) - Establish TCP connection (primary use case for HTTP)The wrapper handles various SOCKS5 error conditions:
\n