3.0.0 • Published 3 years ago

global-agent v3.0.0

Weekly downloads
767,334
License
BSD-3-Clause
Repository
github
Last release
3 years ago

global-agent

GitSpo Mentions Travis build status Coveralls NPM version Canonical Code Style Twitter Follow

Global HTTP/HTTPS proxy configurable using environment variables.

Usage

Setup proxy using global-agent/bootstrap

To configure HTTP proxy:

  1. Import global-agent/bootstrap.
  2. Export HTTP proxy address as GLOBAL_AGENT_HTTP_PROXY environment variable.

Code:

import 'global-agent/bootstrap';

// or:
// import {bootstrap} from 'global-agent';
// bootstrap();

Bash:

$ export GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8080

Alternatively, you can preload module using Node.js --require, -r configuration, e.g.

$ export GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8080
$ node -r 'global-agent/bootstrap' your-script.js

Setup proxy using bootstrap routine

Instead of importing a self-initialising script with side-effects as demonstrated in the setup proxy using global-agent/bootstrap documentation, you can import bootstrap routine and explicitly evaluate the bootstrap logic, e.g.

import {
  bootstrap
} from 'global-agent';

bootstrap();

This is useful if you need to conditionally bootstrap global-agent, e.g.

import {
  bootstrap
} from 'global-agent';
import globalTunnel from 'global-tunnel-ng';

const MAJOR_NODEJS_VERSION = parseInt(process.version.slice(1).split('.')[0], 10);

if (MAJOR_NODEJS_VERSION >= 10) {
  // `global-agent` works with Node.js v10 and above.
  bootstrap();
} else {
  // `global-tunnel-ng` works only with Node.js v10 and below.
  globalTunnel.initialize();
}

Setup proxy using createGlobalProxyAgent

If 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.

import {
  createGlobalProxyAgent
} from 'global-agent';

const globalProxyAgent = createGlobalProxyAgent();

Unlike 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.

Runtime configuration

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.

You can override the global.GLOBAL_AGENT.HTTP_PROXY value at runtime to change proxy behaviour, e.g.

http.get('http://127.0.0.1:8000');

global.GLOBAL_AGENT.HTTP_PROXY = 'http://127.0.0.1:8001';

http.get('http://127.0.0.1:8000');

global.GLOBAL_AGENT.HTTP_PROXY = 'http://127.0.0.1:8002';

The first HTTP request is going to use http://127.0.0.1:8001 proxy and the secord request is going to use http://127.0.0.1:8002.

All global-agent configuration is available under global.GLOBAL_AGENT namespace.

Exclude URLs

The 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.

export GLOBAL_AGENT_NO_PROXY='*.foo.com,baz.com'

says to contact all machines with the 'foo.com' TLD and 'baz.com' domains directly.

Separate proxy for HTTPS

The 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.

Enable logging

global-agent is using roarr logger to log HTTP requests and response (HTTP status code and headers), e.g.

{"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"}
{"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"}

Export ROARR_LOG=true environment variable to enable log printing to stdout.

Use roarr-cli program to pretty-print the logs.

API

createGlobalProxyAgent

/**
 * @property environmentVariableNamespace Defines namespace of `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables. (Default: `GLOBAL_AGENT_`)
 * @property forceGlobalAgent Forces to use `global-agent` HTTP(S) agent even when request was explicitly constructed with another agent. (Default: `true`)
 * @property socketConnectionTimeout Destroys socket if connection is not established within the timeout. (Default: `60000`)
 */
type ProxyAgentConfigurationInputType = {|
  +environmentVariableNamespace?: string,
  +forceGlobalAgent?: boolean,
  +socketConnectionTimeout?: number,
|};

(configurationInput: ProxyAgentConfigurationInputType) => ProxyAgentConfigurationType;

Environment variables

NameDescriptionDefault
GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACEDefines namespace of HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables.GLOBAL_AGENT_
GLOBAL_AGENT_FORCE_GLOBAL_AGENTForces to use global-agent HTTP(S) agent even when request was explicitly constructed with another agent.true
GLOBAL_AGENT_SOCKET_CONNECTION_TIMEOUTDestroys socket if connection is not established within the timeout.60000
${NAMESPACE}_HTTP_PROXYSets the initial proxy controller HTTP_PROXY value.N/A
${NAMESPACE}_HTTPS_PROXYSets the initial proxy controller HTTPS_PROXY value.N/A
${NAMESPACE}_NO_PROXYSets the initial proxy controller NO_PROXY value.N/A

global.GLOBAL_AGENT

global.GLOBAL_AGENT is initialized by bootstrap routine.

global.GLOBAL_AGENT has the following properties:

NameDescriptionConfigurable
HTTP_PROXYYesSets HTTP proxy to use.
HTTPS_PROXYYesSets a distinct proxy to use for HTTPS requests.
NO_PROXYYesSpecifies a pattern of URLs that should be excluded from proxying. See Exclude URLs.

Supported libraries

global-agent works with all libraries that internally use http.request.

global-agent has been tested to work with:

FAQ

What is the reason global-agent overrides explicitly configured HTTP(S) agent?

By default, global-agent overrides agent property 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).

This 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.

What is the reason global-agent/bootstrap does not use HTTP_PROXY?

Some libraries (e.g. request) change their behaviour when HTTP_PROXY environment variable is present. Using a namespaced environment variable prevents conflicting library behaviour.

You can override this behaviour by configuring GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE variable, e.g.

$ export GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE=

Now script initialized using global-agent/bootstrap will use HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables.

What is the difference from global-tunnel and tunnel?

global-tunnel (including global-tunnel-ng and tunnel) are designed to support legacy Node.js versions. They use various workarounds and rely on monkey-patching http.request, http.get, https.request and https.get methods.

In contrast, global-agent supports Node.js v10 and above, and does not implements workarounds for the older Node.js versions.

balena-cliblitz@backstage/cli@budibase/server@budibase/workerverdaccio-keycloak-oauth-ui@lydev/get@njmaeff/node-gen-cli@snyk/snyk-dev@h2security/cdxgenrepotestone-index@dgrammatiko/karma-sauce-launcherrenovatesnyk@everything-registry/sub-chunk-1770yo-slimng-open-api-swagger-genng-renovateng-swagger-genng-swagger-gen-epsng-swagger-gen-extng-swagger-gen-smmudslidemichaelhostmyproximus-tsmyrenobatebotmyrenovatebotmagicspacenodeptmediac@triply/triplydbaide-node-helpers@worldofgeese/core@zsylvia/renovate@wdn2010/cdxgen@we2rss/coreadash-ts-helper@wondon/staticauth0-deploy-cli@acala-network/chopsticksapollo@alauda/custom-webpack@bastienmoulia/ng-swagger-gen@cyclonedx/cdxgen@cyber-tools/create-cyber-tools@cythral/renovateconsole-cat-snyk@devlego/server@devlego/worker@dfatwork-pkgs/backstage-clibrowserstack-node-sdk@black_hole/test@benddao/bend-lending-protocol@bcgov-ccbc/ccbc-node-sp-auth@boundnft/boundnft-protocol@build-script/poormans-package-change@blitzjs/clinode-global-proxynode-sp-authnode-sp-auth-docxnode-sp-auth-nocolorsnuxeo-cliproxify-vercelorganization-algorithm-model-research-website-application-electronorganization-application-ui-ux-website-application-electronorganization-artificial-intelligence-computer-vision-website-application-electronorganization-robotics-sensors-website-application-electronprint-puppeteeroxygen-clireact-native-teads-sdk-moduleplatformio-node-helper-codeserverplatformio-node-helperspodcast-dlrss-telegram-botrest-replayerverdaccio-auth0-uiverdaccio-google-oauthverdaccio-google-oauth-uiverdaccio-google-oauth-ui-2verdaccio-doreamon-oauth2verdaccio-passport-google-oauth-uiverdaccio-paysera-gitlab-oauthverdaccio-oidc-uiverdaccio-openidverdaccio-needle-github-oauth-uiverdaccio-github-oauth-uiverdaccio-github-oauth-ui-teamverdaccio-github-oauth-ui-without-groupsverdaccio-gitlab-oauthverdaccio-gitlab-oauth-uiverdaccio-gitlab-oauth2verdaccio-gitlab-oauth4verdaccio-auth0-ui2yeoman-doctoryodq-surgiothehunt-paymentsmee-client-proxysurgio-libre
3.0.0

3 years ago

2.2.0

3 years ago

2.1.12

4 years ago

2.1.10

4 years ago

2.1.11

4 years ago

2.1.9

4 years ago

2.1.8

4 years ago

2.1.7

4 years ago

2.1.6

4 years ago

2.1.5

4 years ago

2.1.4

4 years ago

2.1.3

4 years ago

2.1.2

4 years ago

2.1.1

5 years ago

2.1.0

5 years ago

2.0.3

5 years ago

2.0.2

5 years ago

2.0.1

5 years ago

2.0.0

5 years ago

1.13.1

5 years ago

1.13.0

5 years ago

1.12.2

5 years ago

1.12.1

5 years ago

1.12.0

5 years ago

1.11.0

5 years ago

1.10.1

5 years ago

1.10.0

5 years ago

1.9.2

5 years ago

1.9.1

5 years ago

1.9.0

5 years ago

1.8.1

5 years ago

1.8.0

5 years ago

1.7.1

5 years ago

1.7.0

5 years ago

1.6.0

5 years ago

1.5.0

5 years ago

1.4.0

5 years ago

1.3.2

5 years ago

1.3.1

5 years ago

1.3.0

5 years ago

1.2.2

5 years ago

1.2.1

5 years ago

1.2.0

5 years ago

1.1.1

5 years ago

1.1.0

5 years ago

1.0.0

5 years ago