{"id":23129812,"url":"https://github.com/detro/node-caronte-proxy","last_synced_at":"2025-08-17T06:32:49.884Z","repository":{"id":10457570,"uuid":"65804958","full_name":"detro/node-caronte-proxy","owner":"detro","description":"Simple HTTP(S) Proxy, suitable to test proxying during development","archived":false,"fork":false,"pushed_at":"2024-06-16T11:22:20.000Z","size":114,"stargazers_count":5,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-16T20:36:01.843Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/detro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-16T09:07:49.000Z","updated_at":"2023-04-03T11:30:18.000Z","dependencies_parsed_at":"2023-01-13T15:57:20.434Z","dependency_job_id":null,"html_url":"https://github.com/detro/node-caronte-proxy","commit_stats":null,"previous_names":["detro/node-simple-proxy"],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detro%2Fnode-caronte-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detro%2Fnode-caronte-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detro%2Fnode-caronte-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detro%2Fnode-caronte-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/detro","download_url":"https://codeload.github.com/detro/node-caronte-proxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230098721,"owners_count":18172741,"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":[],"created_at":"2024-12-17T10:10:58.866Z","updated_at":"2024-12-17T10:10:59.679Z","avatar_url":"https://github.com/detro.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Caronte Proxy (caronte-proxy)\n\n[![npm version](https://badge.fury.io/js/caronte-proxy.svg)](https://badge.fury.io/js/caronte-proxy)\n[![Build Status](https://travis-ci.org/detro/node-caronte-proxy.svg?branch=master)](https://travis-ci.org/detro/node-caronte-proxy)\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fdetro%2Fnode-caronte-proxy.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fdetro%2Fnode-caronte-proxy?ref=badge_shield)\n\n## What's this for?\n\nCaronte is my answer to the need of hosting a _feature-rich-enough_ HTTP Proxy in NodeJS.\n\nI have tons of NodeJS code that has to deal with Proxies, and such code needs testing.\nI started digging, and I found many libraries to build proxies (like the\nfamous [http-proxy](https://www.npmjs.com/package/http-proxy)), but no \"out of the box\"\nsolutions that fit my needs.\n\nSo I made one.\n\nThis is in no way something you want to use in _production_: this Proxy is built\nfor testing and I haven't spent a second checking memory consumption nor\nperformance. This Proxy is to provide you with a testing ground: so my focus\nis on adding typical commercial Proxy features, rather then being _production-ready_.\n\nSome features include:\n\n* Support for HTTP and HTTPS proxying\n* Support for HTTPS (it uses a self-signed certificate by default, but you can provide one)\n* Support for Proxy Basic HTTP Authentication\n\nEventually I'd like to add SOCKS support but it's not an urgent need of mine,\nso it can wait. Maybe **you** will build that!\n\n## Setup\n\n```javascript\nvar options = {};\nvar caronteProxy = require('caronte-proxy')(options, function (req, res, err) {\n  if (!err) {\n    console.log('A soul has approached Caronte with a coin for its journey...');\n  } else {\n    console.error('A soul has approached Caronte without a coin, so it\\'s going to remain in Limbo for ethernity...');\n  }\n});\n\ncaronteProxy.on('listening', function () {\n  console.log('Caronte is ready to carry new souls across the Acheronte...');\n});\n\ncaronteProxy.listen(6666);\n````\n\nAnd here is how the default options look like:\n```javascript\nconst defaultProxyOptions = {\n  key: fs.readFileSync(__dirname + '/lib/proxy.selfsigned.key'),    //\u003c TLS key to be used for HTTPS proxying (default: built-in self signed key)\n  cert: fs.readFileSync(__dirname + '/lib/proxy.selfsigned.cert'),  //\u003c TLS certificate to be used for HTTPS proxying (default: built-in self signed certificate)\n  httpAgent: false,       //\u003c http.Agent to use for HTTP traffic (default: 'false', i.e. no Agent, no socket reuse)\n  httpsAgent: false,      //\u003c https.Agent to use for HTTPS traffic (default: 'false', i.e. no Agent, no socket reuse)\n  auth: false             //\u003c Example value: { username: USERNAME, password: PASSWORD[, realm: USED_ONLY_IF_NOT_EMPTY]}\n};\n````\n\nAny of those properties can be overridden.\n\n### Agents and testing in NodeJS itself\n\nIf you are testing code that involves setting/manipulating the NodeJS Agents and Global Agents,\nit's important that the options `httpAgent` and `httpsAgent` are left to `false`:\nthis will ensure that the communication though the proxy will not directed to the\nNode default Global Agents, making your code very hard to test.\n\nIn other words, avoid _Agent inception_.\n\n## Debugging\nCaronte uses the NPM module [debug](https://www.npmjs.com/package/debug), so\ndebugging is trivial: just set the `ENV` variable `DEBUG` to `caronte:*`.\n\nSomething like:\n```bash\nDEBUG=caronte:* npm test\n```\n\nCheck out [debug](https://www.npmjs.com/package/debug) for more fine tuning. \n\n## _\"Caronte\"?_\nIn Greek mythology, _Charon_ or _Kharon_ (/ˈkɛərɒn/ or /ˈkɛərən/; Greek _Χάρων_; Italian **_Caronte_**)\nis the ferryman of [Hades](https://en.wikipedia.org/wiki/Hades) who carries\nsouls of the newly deceased across the rivers Styx and Acheron that divided\nthe world of the living from the world of the dead.\n\n**Credit for this awesome name goes to [Antonio Pironti](https://github.com/antoniopironti),\nfriend and currently colleague**.\n\n## Disclaimer\nThis project is heavily inspired by [cloudberry](https://github.com/monai/cloudberry),\nbut I forked away because I needed it to:\n\n* Run on more than just latest NodeJS\n* Avoid using the Global Agent, and instead create for every request a fresh connection\n* Support for HTTP Basic Authentication\n* Ability to override the HTTP(s) Agent used by the Proxy\n* Debug-ability\n\nIf you are after a Proxy written with latest NodeJS bells and wissle, you should check\n[cloudberry](https://github.com/monai/cloudberry) out.\n\n## License\n\n[Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) ([txt](https://www.apache.org/licenses/LICENSE-2.0.txt))\n\n\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fdetro%2Fnode-caronte-proxy.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fdetro%2Fnode-caronte-proxy?ref=badge_large)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdetro%2Fnode-caronte-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdetro%2Fnode-caronte-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdetro%2Fnode-caronte-proxy/lists"}