fetch-socks

Socks proxy for Node builtin (also undici) fetch.

1npm install fetch-socks

Usage Examples

Fetch http://example.com through socks5://[::1]:1080.

1import { socksDispatcher } from "fetch-socks";
2
3const dispatcher = socksDispatcher({
4    type: 5,
5    host: "::1",
6    port: 1080,
7
8    //userId: "username",
9    //password: "password",
10});
11
12const response = await fetch("http://example.com", { dispatcher });
13console.log(response.status);
14console.log(await response.text());

Set the proxy globally.

1import { socksDispatcher } from "fetch-socks";
2
3const dispatcher = socksDispatcher({ /* ... */});
4
5global[Symbol.for("undici.globalDispatcher.1")] = dispatcher;

TypeScript example, fetch through proxy chain with two SOCKS proxies.

1import { fetch } from "undici";
2import { socksDispatcher, SocksProxies } from "fetch-socks";
3
4const proxyConfig: SocksProxies = [{
5    type: 5,
6    host: "::1",
7    port: 1080,
8}, {
9    type: 5,
10    host: "127.0.0.1",
11    port: 1081,
12}];
13
14const dispatcher = socksDispatcher(proxyConfig, {
15    connect: {
16        // set some TLS options
17        rejectUnauthorized: false,
18    },
19});
20
21const response = await fetch("https://example.com", { dispatcher });

create a socks connection over HTTP tunnel with socksConnector.

1import { Client, Agent } from "undici";
2import { socksConnector } from "fetch-socks";
3
4const socksConnect = socksConnector({
5    type: 5,
6    host: "::1",
7    port: 1080,
8});
9
10async function connect(options, callback) {
11    // First establish a connection to the HTTP proxy server (localhost:80).
12    const client = new Client("http://localhost:80");
13    const { socket, statusCode } = await client.connect({
14        // Tell the server to connect to the next ([::1]:1080)
15        path: "[::1]:1080",
16    });
17    if (statusCode !== 200) {
18        callback(new Error("Proxy response !== 200 when HTTP Tunneling"));
19    } else {
20        // Perform socks handshake on the connection.
21        socksConnect({ ...options, httpSocket: socket }, callback);
22    }
23}
24
25const dispatcher = new Agent({ connect });
26const response = await fetch("https://example.com", { dispatcher });

API

socksConnector(proxies, connectOptions?)

Create an Undici connector which establish the connection through socks proxies.

• proxies The proxy server to use or the list of proxy servers to chain. If you pass an empty array it will connect directly.
• connectOptions (optional) The options used to perform directly connect or TLS upgrade, see here

socksDispatcher(proxies, options?)

Create a Undici Agent with socks connector.

• proxies Same as socksConnector's.
• options (optional) Agent options. The connect property will be used to create socks connector.

1import { socksConnector, socksDispatcher } from "fetch-socks";
2import { Agent } from "undici";
3
4const proxy = { type: 5, host: "::1", port: 1080 };
5const connect = { /* ... */ };
6const agentOptions = { /* ... */ };
7
8socksDispatcher(proxy, { ...agentOptions, connect });
9
10// Is equivalent to
11new Agent({ ...agentOptions, connect: socksConnector(proxy, connect) });