{"id":13583047,"url":"https://github.com/apify/proxy-chain","last_synced_at":"2025-11-03T16:25:34.680Z","repository":{"id":37075789,"uuid":"109683841","full_name":"apify/proxy-chain","owner":"apify","description":"Node.js implementation of a proxy server (think Squid) with support for SSL, authentication and upstream proxy chaining.","archived":false,"fork":false,"pushed_at":"2025-04-28T08:59:10.000Z","size":672,"stargazers_count":909,"open_issues_count":20,"forks_count":147,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-05-08T05:44:24.937Z","etag":null,"topics":["headless-chrome","javascript-library","proxy-server","proxychains"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/proxy-chain","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apify.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-11-06T10:59:24.000Z","updated_at":"2025-05-05T03:20:08.000Z","dependencies_parsed_at":"2024-04-29T13:42:07.822Z","dependency_job_id":"a4de73ac-ca9b-483d-86c6-d2092d7fe29d","html_url":"https://github.com/apify/proxy-chain","commit_stats":{"total_commits":366,"total_committers":25,"mean_commits":14.64,"dds":"0.39617486338797814","last_synced_commit":"67f961d5881f23dacba01e51872eef76c94375ab"},"previous_names":["apifytech/proxy-chain"],"tags_count":155,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fproxy-chain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fproxy-chain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fproxy-chain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fproxy-chain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apify","download_url":"https://codeload.github.com/apify/proxy-chain/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253528884,"owners_count":21922625,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["headless-chrome","javascript-library","proxy-server","proxychains"],"created_at":"2024-08-01T15:03:13.206Z","updated_at":"2025-11-03T16:25:34.623Z","avatar_url":"https://github.com/apify.png","language":"JavaScript","readme":"# Programmable HTTP proxy server for Node.js\n\n[![npm version](https://badge.fury.io/js/proxy-chain.svg)](http://badge.fury.io/js/proxy-chain)\n\nA programmable proxy server (think Squid) with support for SSL/TLS, authentication, upstream proxy chaining, SOCKS4/5 protocol,\ncustom HTTP responses, and traffic statistics.\nThe authentication and proxy chaining configuration is defined in code and can be fully dynamic, giving you a high level of customization for your use case.\n\nFor example, the proxy-chain package is useful if you need to use headless Chrome web browser and proxies with authentication,\nbecause Chrome doesn't support proxy URLs with password, such as `http://username:password@proxy.example.com:8080`.\nWith this package, you can set up a local proxy server without any password\nthat will forward requests to the upstream proxy with password.\nFor details, read [How to make headless Chrome and Puppeteer use a proxy server with authentication](https://blog.apify.com/how-to-make-headless-chrome-and-puppeteer-use-a-proxy-server-with-authentication-249a21a79212/).\n\nThe proxy-chain package is developed by [Apify](https://apify.com/), the full-stack web scraping and data extraction platform, to support their [Apify Proxy](https://apify.com/proxy) product,\nwhich provides an easy access to a large pool of datacenter and residential IP addresses all around the world. The proxy-chain package is also used by [Crawlee](https://crawlee.dev/),\nthe world's most popular web craling library for Node.js.\n\nThe proxy-chain package currently supports HTTP/SOCKS forwarding and HTTP CONNECT tunneling to forward arbitrary protocols such as HTTPS or FTP ([learn more](https://blog.apify.com/tunneling-arbitrary-protocols-over-http-proxy-with-static-ip-address-b3a2222191ff)). The HTTP CONNECT tunneling also supports the SOCKS protocol. Also, proxy-chain only supports the Basic [Proxy-Authorization](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Proxy-Authorization).\n\n## Run a simple HTTP/HTTPS proxy server\n\n```javascript\nconst ProxyChain = require('proxy-chain');\n\nconst server = new ProxyChain.Server({ port: 8000 });\n\nserver.listen(() =\u003e {\n    console.log(`Proxy server is listening on port ${server.port}`);\n});\n```\n\n## Run a HTTP/HTTPS proxy server with credentials and upstream proxy\n\n```javascript\nconst ProxyChain = require('proxy-chain');\n\nconst server = new ProxyChain.Server({\n    // Port where the server will listen. By default 8000.\n    port: 8000,\n\n    // Optional host where the proxy server will listen.\n    // If not specified, the sever listens on an unspecified IP address (0.0.0.0 in IPv4, :: in IPv6)\n    // You can use this option to limit the access to the proxy server.\n    host: 'localhost',\n\n    // Enables verbose logging\n    verbose: true,\n\n    // Custom user-defined function to authenticate incoming proxy requests,\n    // and optionally provide the URL to chained upstream proxy.\n    // The function must return an object (or promise resolving to the object) with the following signature:\n    // { requestAuthentication: boolean, upstreamProxyUrl: string, failMsg?: string, customTag?: unknown }\n    // If the function is not defined or is null, the server runs in simple mode.\n    // Note that the function takes a single argument with the following properties:\n    // * request      - An instance of http.IncomingMessage class with information about the client request\n    //                  (which is either HTTP CONNECT for SSL protocol, or other HTTP request)\n    // * username     - Username parsed from the Proxy-Authorization header. Might be empty string.\n    // * password     - Password parsed from the Proxy-Authorization header. Might be empty string.\n    // * hostname     - Hostname of the target server\n    // * port         - Port of the target server\n    // * isHttp       - If true, this is a HTTP request, otherwise it's a HTTP CONNECT tunnel for SSL\n    //                  or other protocols\n    // * connectionId - Unique ID of the HTTP connection. It can be used to obtain traffic statistics.\n    prepareRequestFunction: ({ request, username, password, hostname, port, isHttp, connectionId }) =\u003e {\n        return {\n            // If set to true, the client is sent HTTP 407 resposne with the Proxy-Authenticate header set,\n            // requiring Basic authentication. Here you can verify user credentials.\n            requestAuthentication: username !== 'bob' || password !== 'TopSecret',\n\n            // Sets up an upstream HTTP/HTTPS/SOCKS proxy to which all the requests are forwarded.\n            // If null, the proxy works in direct mode, i.e. the connection is forwarded directly\n            // to the target server. This field is ignored if \"requestAuthentication\" is true.\n            // The username and password must be URI-encoded.\n            upstreamProxyUrl: `http://username:password@proxy.example.com:3128`,\n            // Or use SOCKS4/5 proxy, e.g.\n            // upstreamProxyUrl: `socks://username:password@proxy.example.com:1080`,\n\n            // Applies to HTTPS upstream proxy. If set to true, requests made to the proxy will\n            // ignore certificate errors. Useful when upstream proxy uses self-signed certificate. By default \"false\".\n            ignoreUpstreamProxyCertificate: true\n\n            // If \"requestAuthentication\" is true, you can use the following property\n            // to define a custom error message to return to the client instead of the default \"Proxy credentials required\"\n            failMsg: 'Bad username or password, please try again.',\n\n            // Optional custom tag that will be passed back via\n            // `tunnelConnectResponded` or `tunnelConnectFailed` events\n            // Can be used to pass information between proxy-chain\n            // and any external code or application using it\n            customTag: { userId: '123' },\n        };\n    },\n});\n\nserver.listen(() =\u003e {\n  console.log(`Proxy server is listening on port ${server.port}`);\n});\n\n// Emitted when HTTP connection is closed\nserver.on('connectionClosed', ({ connectionId, stats }) =\u003e {\n  console.log(`Connection ${connectionId} closed`);\n  console.dir(stats);\n});\n\n// Emitted when HTTP request fails\nserver.on('requestFailed', ({ request, error }) =\u003e {\n  console.log(`Request ${request.url} failed`);\n  console.error(error);\n});\n```\n\n## SOCKS support\nSOCKS protocol is supported for versions 4 and 5, specifically: `['socks', 'socks4', 'socks4a', 'socks5', 'socks5h']`, where `socks` will default to version 5.\n\nYou can use an `upstreamProxyUrl` like `socks://username:password@proxy.example.com:1080`.\n\n## Error status codes\n\nThe `502 Bad Gateway` HTTP status code is not comprehensive enough. Therefore, the server may respond with `590-599` instead:\n\n### `590 Non Successful`\n\nUpstream responded with non-200 status code.\n\n### `591 RESERVED`\n\n*This status code is reserved for further use.*\n\n### `592 Status Code Out Of Range`\n\nUpstream respondend with status code different than 100-999.\n\n### `593 Not Found`\n\nDNS lookup failed - [`EAI_NODATA`](https://github.com/libuv/libuv/blob/cdbba74d7a756587a696fb3545051f9a525b85ac/include/uv.h#L82) or [`EAI_NONAME`](https://github.com/libuv/libuv/blob/cdbba74d7a756587a696fb3545051f9a525b85ac/include/uv.h#L83).\n\n### `594 Connection Refused`\n\nUpstream refused connection.\n\n### `595 Connection Reset`\n\nConnection reset due to loss of connection or timeout.\n\n### `596 Broken Pipe`\n\nTrying to write on a closed socket.\n\n### `597 Auth Failed`\n\nIncorrect upstream credentials.\n\n### `598 RESERVED`\n\n*This status code is reserved for further use.*\n\n### `599 Upstream Error`\n\nGeneric upstream error.\n\n---\n\n`590` and `592` indicate an issue on the upstream side. \\\n`593` indicates an incorrect `proxy-chain` configuration.\\\n`594`, `595` and `596` may occur due to connection loss.\\\n`597` indicates incorrect upstream credentials.\\\n`599` is a generic error, where the above is not applicable.\n\n## Custom error responses\n\nTo return a custom HTTP response to indicate an error to the client,\nyou can throw the `RequestError` from inside of the `prepareRequestFunction` function.\nThe class constructor has the following parameters: `RequestError(body, statusCode, headers)`.\nBy default, the response will have `Content-Type: text/plain; charset=utf-8`.\n\n```javascript\nconst ProxyChain = require('proxy-chain');\n\nconst server = new ProxyChain.Server({\n    prepareRequestFunction: ({ request, username, password, hostname, port, isHttp, connectionId }) =\u003e {\n        if (username !== 'bob') {\n           throw new ProxyChain.RequestError('Only Bob can use this proxy!', 400);\n        }\n    },\n});\n```\n\n## Measuring traffic statistics\n\nTo get traffic statistics for a certain HTTP connection, you can use:\n```javascript\nconst stats = server.getConnectionStats(connectionId);\nconsole.dir(stats);\n```\n\nThe resulting object looks like:\n```javascript\n{\n    // Number of bytes sent to client\n    srcTxBytes: Number,\n    // Number of bytes received from client\n    srcRxBytes: Number,\n    // Number of bytes sent to target server (proxy or website)\n    trgTxBytes: Number,\n    // Number of bytes received from target server (proxy or website)\n    trgRxBytes: Number,\n}\n```\n\nIf the underlying sockets were closed, the corresponding values will be `null`,\nrather than `0`.\n\n## Custom responses\n\nCustom responses allow you to override the response to a HTTP requests to the proxy, without contacting any target host.\nFor example, this is useful if you want to provide a HTTP proxy-style interface\nto an external API or respond with some custom page to certain requests.\nNote that this feature is only available for HTTP connections. That's because HTTPS\nconnections cannot be intercepted without access to the target host's private key.\n\nTo provide a custom response, the result of the `prepareRequestFunction` function must\ndefine the `customResponseFunction` property, which contains a function that generates the custom response.\nThe function is passed no parameters and it must return an object (or a promise resolving to an object)\nwith the following properties:\n\n```javascript\n{\n  // Optional HTTP status code of the response. By default it is 200.\n  statusCode: 200,\n\n  // Optional HTTP headers of the response\n  headers: {\n    'X-My-Header': 'bla bla',\n  }\n\n  // Optional string with the body of the HTTP response\n  body: 'My custom response',\n\n  // Optional encoding of the body. If not provided, defaults to 'UTF-8'\n  encoding: 'UTF-8',\n}\n```\n\nHere is a simple example:\n\n```javascript\nconst ProxyChain = require('proxy-chain');\n\nconst server = new ProxyChain.Server({\n    port: 8000,\n    prepareRequestFunction: ({ request, username, password, hostname, port, isHttp }) =\u003e {\n        return {\n            customResponseFunction: () =\u003e {\n                return {\n                    statusCode: 200,\n                    body: `My custom response to ${request.url}`,\n                };\n            },\n        };\n    },\n});\n\nserver.listen(() =\u003e {\n  console.log(`Proxy server is listening on port ${server.port}`);\n});\n```\n\n## Routing CONNECT to another HTTP server\n\nWhile `customResponseFunction` enables custom handling methods such as `GET` and `POST`, many HTTP clients rely on `CONNECT` tunnels.\nIt's possible to route those requests differently using the `customConnectServer` option. It accepts an instance of Node.js HTTP server.\n\n```javascript\nconst http = require('http');\nconst ProxyChain = require('proxy-chain');\n\nconst exampleServer = http.createServer((request, response) =\u003e {\n    response.end('Hello from a custom server!');\n});\n\nconst server = new ProxyChain.Server({\n    port: 8000,\n    prepareRequestFunction: ({ request, username, password, hostname, port, isHttp }) =\u003e {\n        if (request.url.toLowerCase() === 'example.com:80') {\n            return {\n                customConnectServer: exampleServer,\n            };\n        }\n\n        return {};\n    },\n});\n\nserver.listen(() =\u003e {\n  console.log(`Proxy server is listening on port ${server.port}`);\n});\n```\n\nIn the example above, all CONNECT tunnels to `example.com` are overridden.\nThis is an unsecure server, so it accepts only `http:` requests.\n\nIn order to intercept `https:` requests, `https.createServer` should be used instead, along with a self signed certificate.\n\n```javascript\nconst https = require('https');\nconst fs = require('fs');\nconst key = fs.readFileSync('./test/ssl.key');\nconst cert = fs.readFileSync('./test/ssl.crt');\n\nconst exampleServer = https.createServer({\n    key,\n    cert,\n}, (request, response) =\u003e {\n    response.end('Hello from a custom server!');\n});\n```\n\n## Closing the server\n\nTo shut down the proxy server, call the `close([destroyConnections], [callback])` function. For example:\n\n```javascript\nserver.close(true, () =\u003e {\n  console.log('Proxy server was closed.');\n});\n```\n\nThe `closeConnections` parameter indicates whether pending proxy connections should be forcibly closed.\nIf it's `false`, the function will wait until all connections are closed, which can take a long time.\nIf the `callback` parameter is omitted, the function returns a promise.\n\n\n## Accessing the CONNECT response headers for proxy tunneling\n\nSome upstream proxy providers might include valuable debugging information in the CONNECT response\nheaders when establishing the proxy tunnel, for they may not modify future data in the tunneled\nconnection.\n\nThe proxy server would emit a `tunnelConnectResponded` event for exposing such information, where\nthe parameter types of the event callback are described in [Node.js's documentation][1]. Example:\n\n[1]: https://nodejs.org/api/http.html#http_event_connect\n\n```javascript\nserver.on('tunnelConnectResponded', ({ proxyChainId, response, socket, head, customTag }) =\u003e {\n    console.log(`CONNECT response headers received: ${response.headers}`);\n});\n```\n\nAlternatively a [helper function](##helper-functions) may be used:\n\n```javascript\nlistenConnectAnonymizedProxy(anonymizedProxyUrl, ({ response, socket, head }) =\u003e {\n    console.log(`CONNECT response headers received: ${response.headers}`);\n});\n```\n\nYou can also listen to CONNECT requests that receive response with status code different from 200.\nThe proxy server would emit a `tunnelConnectFailed` event.\n\n```javascript\nserver.on('tunnelConnectFailed', ({ proxyChainId, response, socket, head, customTag }) =\u003e {\n    console.log(`CONNECT response failed with status code: ${response.statusCode}`);\n});\n```\n\n## Helper functions\n\nThe package also provides several utility functions.\n\n\n### `anonymizeProxy({ url, port }, callback)`\n\nParses and validates a HTTP/HTTPS proxy URL. If the proxy requires authentication,\nthen the function starts an open local proxy server that forwards to the proxy.\nThe port (on which the local proxy server will start) can be set via the `port` property of the first argument, if not provided, it will be chosen randomly.\n\nFor HTTPS proxy with self-signed certificate, set `ignoreProxyCertificate` property of the first argument to `true` to ignore certificate errors in\nproxy requests.\n\nThe function takes an optional callback that receives the anonymous proxy URL.\nIf no callback is supplied, the function returns a promise that resolves to a String with\nanonymous proxy URL or the original URL if it was already anonymous.\n\nThe following example shows how you can use a proxy with authentication\nfrom headless Chrome and [Puppeteer](https://github.com/GoogleChrome/puppeteer).\nFor details, read this [blog post](https://blog.apify.com/how-to-make-headless-chrome-and-puppeteer-use-a-proxy-server-with-authentication-249a21a79212).\n\n```javascript\nconst puppeteer = require('puppeteer');\nconst proxyChain = require('proxy-chain');\n\n(async() =\u003e {\n    const oldProxyUrl = 'http://bob:password123@proxy.example.com:8000';\n    const newProxyUrl = await proxyChain.anonymizeProxy(oldProxyUrl);\n\n    // Prints something like \"http://127.0.0.1:45678\"\n    console.log(newProxyUrl);\n\n    const browser = await puppeteer.launch({\n        args: [`--proxy-server=${newProxyUrl}`],\n    });\n\n    // Do your magic here...\n    const page = await browser.newPage();\n    await page.goto('https://www.example.com');\n    await page.screenshot({ path: 'example.png' });\n    await browser.close();\n\n    // Clean up\n    await proxyChain.closeAnonymizedProxy(newProxyUrl, true);\n})();\n```\n\n### `closeAnonymizedProxy(anonymizedProxyUrl, closeConnections, callback)`\n\nCloses anonymous proxy previously started by `anonymizeProxy()`.\nIf proxy was not found or was already closed, the function has no effect\nand its result is `false`. Otherwise the result is `true`.\n\nThe `closeConnections` parameter indicates whether pending proxy connections are forcibly closed.\nIf it's `false`, the function will wait until all connections are closed, which can take a long time.\n\nThe function takes an optional callback that receives the result Boolean from the function.\nIf callback is not provided, the function returns a promise instead.\n\n### `createTunnel(proxyUrl, targetHost, options, callback)`\n\nCreates a TCP tunnel to `targetHost` that goes through a HTTP/HTTPS proxy server\nspecified by the `proxyUrl` parameter.\n\nThe optional `options` parameter is an object with the following properties:\n- `port: Number` - Enables specifying the local port to listen at. By default `0`,\n   which means a random port will be selected.\n- `hostname: String` - Local hostname to listen at. By default `localhost`.\n- `ignoreProxyCertificate` - For HTTPS proxy, ignore certificate errors in proxy requests. Useful for proxy with self-signed certificate. By default `false`.\n- `verbose: Boolean` - If `true`, the functions logs a lot. By default `false`.\n\nThe result of the function is a local endpoint in a form of `hostname:port`.\nAll TCP connections made to the local endpoint will be tunneled through the proxy to the target host and port.\nFor example, this is useful if you want to access a certain service from a specific IP address.\n\nThe tunnel should be eventually closed by calling the `closeTunnel()` function.\n\nThe `createTunnel()` function accepts an optional Node.js-style callback that receives the path to the local endpoint.\nIf no callback is supplied, the function returns a promise that resolves to a String with\nthe path to the local endpoint.\n\nFor more information, read this [blog post](https://blog.apify.com/tunneling-arbitrary-protocols-over-http-proxy-with-static-ip-address-b3a2222191ff).\n\nExample:\n\n```javascript\nconst host = await createTunnel('http://bob:pass123@proxy.example.com:8000', 'service.example.com:356');\n// Prints something like \"localhost:56836\"\nconsole.log(host);\n```\n\n### `closeTunnel(tunnelString, closeConnections, callback)`\n\nCloses tunnel previously started by `createTunnel()`.\nThe result value is `false` if the tunnel was not found or was already closed, otherwise it is `true`.\n\nThe `closeConnections` parameter indicates whether pending connections are forcibly closed.\nIf it's `false`, the function will wait until all connections are closed, which can take a long time.\n\nThe function takes an optional callback that receives the result of the function.\nIf the callback is not provided, the function returns a promise instead.\n\n### `listenConnectAnonymizedProxy(anonymizedProxyUrl, tunnelConnectRespondedCallback)`\n\nAllows to configure a callback on the anonymized proxy URL for the CONNECT response headers. See the\nabove section [Accessing the CONNECT response headers for proxy tunneling](#accessing-the-connect-response-headers-for-proxy-tunneling)\nfor details.\n\n### `redactUrl(url, passwordReplacement)`\n\nTakes a URL and hides the password from it. For example:\n\n```javascript\n// Prints 'http://bob:\u003credacted\u003e@example.com'\nconsole.log(redactUrl('http://bob:pass123@example.com'));\n```\n","funding_links":[],"categories":["JavaScript","others"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapify%2Fproxy-chain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapify%2Fproxy-chain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapify%2Fproxy-chain/lists"}