{"id":13453834,"url":"https://github.com/gajus/global-agent","last_synced_at":"2025-05-14T23:02:10.429Z","repository":{"id":41154816,"uuid":"183410611","full_name":"gajus/global-agent","owner":"gajus","description":"Global HTTP/HTTPS proxy agent configurable using environment variables.","archived":false,"fork":false,"pushed_at":"2024-08-06T11:22:04.000Z","size":109,"stargazers_count":379,"open_issues_count":26,"forks_count":45,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-05T06:01:43.392Z","etag":null,"topics":["global","http","https","nodejs","proxy"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gajus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"gajus","patreon":"gajus"}},"created_at":"2019-04-25T10:19:06.000Z","updated_at":"2025-04-28T16:00:03.000Z","dependencies_parsed_at":"2024-01-06T09:59:06.751Z","dependency_job_id":"78e6ffa0-27e7-4a67-8b31-f624f4a07a20","html_url":"https://github.com/gajus/global-agent","commit_stats":{"total_commits":105,"total_committers":11,"mean_commits":9.545454545454545,"dds":0.1333333333333333,"last_synced_commit":"abe65f5189ab2e6d32f6cf067b8741b3f0f846f3"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gajus%2Fglobal-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gajus%2Fglobal-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gajus%2Fglobal-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gajus%2Fglobal-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gajus","download_url":"https://codeload.github.com/gajus/global-agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243353,"owners_count":22038044,"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":["global","http","https","nodejs","proxy"],"created_at":"2024-07-31T08:00:48.240Z","updated_at":"2025-05-14T23:02:10.347Z","avatar_url":"https://github.com/gajus.png","language":"TypeScript","funding_links":["https://github.com/sponsors/gajus","https://patreon.com/gajus"],"categories":["Packages","Repository","包","TypeScript","目录"],"sub_categories":["HTTP"],"readme":"# global-agent\n\n[![Travis build status](http://img.shields.io/travis/gajus/global-agent/master.svg?style=flat-square)](https://travis-ci.org/gajus/global-agent)\n[![Coveralls](https://img.shields.io/coveralls/gajus/global-agent.svg?style=flat-square)](https://coveralls.io/github/gajus/global-agent)\n[![NPM version](http://img.shields.io/npm/v/global-agent.svg?style=flat-square)](https://www.npmjs.org/package/global-agent)\n[![Canonical Code Style](https://img.shields.io/badge/code%20style-canonical-blue.svg?style=flat-square)](https://github.com/gajus/canonical)\n[![Twitter Follow](https://img.shields.io/twitter/follow/kuizinas.svg?style=social\u0026label=Follow)](https://twitter.com/kuizinas)\n\nGlobal HTTP/HTTPS proxy configurable using environment variables.\n\n* [Usage](#usage)\n  * [Setup proxy using `global-agent/bootstrap`](#setup-proxy-using-global-agentbootstrap)\n  * [Setup proxy using `bootstrap` routine](#setup-proxy-using-bootstrap-routine)\n  * [Runtime configuration](#runtime-configuration)\n  * [Exclude URLs](#exclude-urls)\n  * [Enable logging](#enable-logging)\n* [API](#api)\n  * [`createGlobalProxyAgent`](#createglobalproxyagent)\n  * [Environment variables](#environment-variables)\n  * [`global.GLOBAL_AGENT`](#globalglobal_agent)\n* [Supported libraries](#supported-libraries)\n* [FAQ](#faq)\n  * [What is the reason `global-agent` overrides explicitly configured HTTP(S) agent?](#what-is-the-reason-global-agent-overrides-explicitly-configured-https-agent)\n  * [What is the reason `global-agent/bootstrap` does not use `HTTP_PROXY`?](#what-is-the-reason-global-agentbootstrap-does-not-use-http_proxy)\n  * [What is the difference from `global-tunnel` and `tunnel`?](#what-is-the-difference-from-global-tunnel-and-tunnel)\n\n## Usage\n\n### Setup proxy using `global-agent/bootstrap`\n\nTo configure HTTP proxy:\n\n1. Import `global-agent/bootstrap`.\n1. Export HTTP proxy address as `GLOBAL_AGENT_HTTP_PROXY` environment variable.\n\nCode:\n\n```js\nimport 'global-agent/bootstrap';\n\n// or:\n// import {bootstrap} from 'global-agent';\n// bootstrap();\n\n```\n\nBash:\n\n```bash\n$ export GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8080\n\n```\n\nAlternatively, you can preload module using Node.js `--require, -r` configuration, e.g.\n\n```bash\n$ export GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8080\n$ node -r 'global-agent/bootstrap' your-script.js\n\n```\n\n### Setup proxy using `bootstrap` routine\n\nInstead of importing a self-initialising script with side-effects as demonstrated in the [setup proxy using `global-agent/bootstrap`](#setup-proxy-using-global-agentbootstrap) documentation, you can import `bootstrap` routine and explicitly evaluate the bootstrap logic, e.g.\n\n```js\nimport {\n  bootstrap\n} from 'global-agent';\n\nbootstrap();\n\n```\n\nThis is useful if you need to conditionally bootstrap `global-agent`, e.g.\n\n```js\nimport {\n  bootstrap\n} from 'global-agent';\nimport globalTunnel from 'global-tunnel-ng';\n\nconst MAJOR_NODEJS_VERSION = parseInt(process.version.slice(1).split('.')[0], 10);\n\nif (MAJOR_NODEJS_VERSION \u003e= 10) {\n  // `global-agent` works with Node.js v10 and above.\n  bootstrap();\n} else {\n  // `global-tunnel-ng` works only with Node.js v10 and below.\n  globalTunnel.initialize();\n}\n\n```\n\n### Setup proxy using `createGlobalProxyAgent`\n\nIf you do not want to use `global.GLOBAL_AGENT` variable, then you can use `createGlobalProxyAgent` to instantiate a controlled instance of `global-agent`, e.g.\n\n```js\nimport {\n  createGlobalProxyAgent\n} from 'global-agent';\n\nconst globalProxyAgent = createGlobalProxyAgent();\n\n```\n\nUnlike `bootstrap` routine, `createGlobalProxyAgent` factory does not create `global.GLOBAL_AGENT` variable and does not guard against multiple initializations of `global-agent`. The result object of `createGlobalProxyAgent` is equivalent to `global.GLOBAL_AGENT`.\n\n### Runtime configuration\n\n`global-agent/bootstrap` script copies `process.env.GLOBAL_AGENT_HTTP_PROXY` value to `global.GLOBAL_AGENT.HTTP_PROXY` and continues to use the latter variable.\n\nYou can override the `global.GLOBAL_AGENT.HTTP_PROXY` value at runtime to change proxy behaviour, e.g.\n\n```js\nhttp.get('http://127.0.0.1:8000');\n\nglobal.GLOBAL_AGENT.HTTP_PROXY = 'http://127.0.0.1:8001';\n\nhttp.get('http://127.0.0.1:8000');\n\nglobal.GLOBAL_AGENT.HTTP_PROXY = 'http://127.0.0.1:8002';\n\n```\n\nThe first HTTP request is going to use http://127.0.0.1:8001 proxy and the second request is going to use http://127.0.0.1:8002.\n\nAll `global-agent` configuration is available under `global.GLOBAL_AGENT` namespace.\n\n### Exclude URLs\n\nThe `GLOBAL_AGENT_NO_PROXY` environment variable specifies a pattern of URLs that should be excluded from proxying. `GLOBAL_AGENT_NO_PROXY` value is a comma-separated list of domain names. Asterisks can be used as wildcards, e.g.\n\n```bash\nexport GLOBAL_AGENT_NO_PROXY='*.foo.com,baz.com'\n\n```\n\nsays to contact all machines with the 'foo.com' TLD and 'baz.com' domains directly.\n\n### Separate proxy for HTTPS\n\nThe environment variable `GLOBAL_AGENT_HTTPS_PROXY` can be set to specify a separate proxy for HTTPS requests. When this variable is not set `GLOBAL_AGENT_HTTP_PROXY` is used for both HTTP and HTTPS requests.\n\n### Enable logging\n\n`global-agent` is using [`roarr`](https://www.npmjs.com/package/roarr) logger to log HTTP requests and response (HTTP status code and headers), e.g.\n\n```json\n{\"context\":{\"program\":\"global-agent\",\"namespace\":\"Agent\",\"logLevel\":10,\"destination\":\"http://gajus.com\",\"proxy\":\"http://127.0.0.1:8076\"},\"message\":\"proxying request\",\"sequence\":1,\"time\":1556269669663,\"version\":\"1.0.0\"}\n{\"context\":{\"program\":\"global-agent\",\"namespace\":\"Agent\",\"logLevel\":10,\"headers\":{\"content-type\":\"text/plain\",\"content-length\":\"2\",\"date\":\"Fri, 26 Apr 2019 12:07:50 GMT\",\"connection\":\"close\"},\"requestId\":6,\"statusCode\":200},\"message\":\"proxying response\",\"sequence\":2,\"time\":1557133856955,\"version\":\"1.0.0\"}\n\n```\n\nExport `ROARR_LOG=true` environment variable to enable log printing to stdout.\n\nUse [`roarr-cli`](https://github.com/gajus/roarr-cli) program to pretty-print the logs.\n\n## API\n\n### `createGlobalProxyAgent`\n\n```js\n/**\n * @property environmentVariableNamespace Defines namespace of `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables. (Default: `GLOBAL_AGENT_`)\n * @property forceGlobalAgent Forces to use `global-agent` HTTP(S) agent even when request was explicitly constructed with another agent. (Default: `true`)\n * @property socketConnectionTimeout Destroys socket if connection is not established within the timeout. (Default: `60000`)\n */\ntype ProxyAgentConfigurationInputType = {|\n  +environmentVariableNamespace?: string,\n  +forceGlobalAgent?: boolean,\n  +socketConnectionTimeout?: number,\n|};\n\n(configurationInput: ProxyAgentConfigurationInputType) =\u003e ProxyAgentConfigurationType;\n\n```\n\n### Environment variables\n\n|Name|Description|Default|\n|---|---|---|\n|`GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE`|Defines namespace of `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables.|`GLOBAL_AGENT_`|\n|`GLOBAL_AGENT_FORCE_GLOBAL_AGENT`|Forces to use `global-agent` HTTP(S) agent even when request was explicitly constructed with another agent.|`true`|\n|`GLOBAL_AGENT_SOCKET_CONNECTION_TIMEOUT`|Destroys socket if connection is not established within the timeout.|`60000`|\n|`${NAMESPACE}HTTP_PROXY`|Sets the initial proxy controller HTTP_PROXY value.|N/A|\n|`${NAMESPACE}HTTPS_PROXY`|Sets the initial proxy controller HTTPS_PROXY value.|N/A|\n|`${NAMESPACE}NO_PROXY`|Sets the initial proxy controller NO_PROXY value.|N/A|\n\n### `global.GLOBAL_AGENT`\n\n`global.GLOBAL_AGENT` is initialized by `bootstrap` routine.\n\n`global.GLOBAL_AGENT` has the following properties:\n\n|Name|Description|Configurable|\n|---|---|---|\n|`HTTP_PROXY`|Yes|Sets HTTP proxy to use.|\n|`HTTPS_PROXY`|Yes|Sets a distinct proxy to use for HTTPS requests.|\n|`NO_PROXY`|Yes|Specifies a pattern of URLs that should be excluded from proxying. See [Exclude URLs](#exclude-urls).|\n\n## Supported libraries\n\n`global-agent` works with all libraries that internally use [`http.request`](https://nodejs.org/api/http.html#http_http_request_options_callback).\n\n`global-agent` has been tested to work with:\n\n* [`got`](https://www.npmjs.com/package/got)\n* [`axios`](https://www.npmjs.com/package/axios)\n* [`request`](https://www.npmjs.com/package/request)\n\n## FAQ\n\n### What is the reason `global-agent` overrides explicitly configured HTTP(S) agent?\n\nBy default, `global-agent` overrides [`agent` property](https://nodejs.org/api/http.html#http_http_request_options_callback) of any HTTP request, even if `agent` property was explicitly set when constructing a HTTP request. This behaviour allows to intercept requests of libraries that use a custom instance of an agent per default (e.g. Stripe SDK [uses an `http(s).globalAgent` instance pre-configured with `keepAlive: true`](https://github.com/stripe/stripe-node/blob/e542902dd8fbe591fe3c3ce07a7e89d1d60e4cf7/lib/StripeResource.js#L11-L12)).\n\nThis behaviour can be disabled with `GLOBAL_AGENT_FORCE_GLOBAL_AGENT=false` environment variable. When disabled, then `global-agent` will only set `agent` property when it is not already defined or if `agent` is an instance of `http(s).globalAgent`.\n\n### What is the reason `global-agent/bootstrap` does not use `HTTP_PROXY`?\n\nSome libraries (e.g. [`request`](https://npmjs.org/package/request)) change their behaviour when `HTTP_PROXY` environment variable is present. Using a namespaced environment variable prevents conflicting library behaviour.\n\nYou can override this behaviour by configuring `GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE` variable, e.g.\n\n```bash\n$ export GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE=\n\n```\n\nNow script initialized using `global-agent/bootstrap` will use `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables.\n\n### What is the difference from `global-tunnel` and `tunnel`?\n\n[`global-tunnel`](https://github.com/salesforce/global-tunnel) (including [`global-tunnel-ng`](https://github.com/np-maintain/global-tunnel) and [`tunnel`](https://npmjs.com/package/tunnel)) are designed to support legacy Node.js versions. They use various [workarounds](https://github.com/koichik/node-tunnel/blob/5fb2fb424788597146b7be6729006cad1cf9e9a8/lib/tunnel.js#L134-L144) and rely on [monkey-patching `http.request`, `http.get`, `https.request` and `https.get` methods](https://github.com/np-maintain/global-tunnel/blob/51413dcf0534252b5049ec213105c7063ccc6367/index.js#L302-L338).\n\nIn contrast, `global-agent` supports Node.js v10 and above, and does not implements workarounds for the older Node.js versions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgajus%2Fglobal-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgajus%2Fglobal-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgajus%2Fglobal-agent/lists"}