Need help with global-agent?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

gajus
142 Stars 18 Forks Other 106 Commits 7 Opened issues

Description

Global HTTP/HTTPS proxy agent configurable using environment variables.

Services available

!
?

Need anything else?

Contributors list

# 6,624
GraphQL
express...
ecmascr...
React
88 commits
# 93,127
C#
c-sharp
package...
gitlab
2 commits
# 499,848
C++
Python
Node.js
HTTP
1 commit
# 13,213
Python
Shell
TypeScr...
datastr...
1 commit
# 8,986
CSS
Git
nextjs
Electro...
1 commit

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

|Name|Description|Default| |---|---|---| |

GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE
|Defines namespace of
HTTP_PROXY
,
HTTPS_PROXY
and
NO_PROXY
environment variables.|
GLOBAL_AGENT_
| |
GLOBAL_AGENT_FORCE_GLOBAL_AGENT
|Forces to use
global-agent
HTTP(S) agent even when request was explicitly constructed with another agent.|
true
| |
GLOBAL_AGENT_SOCKET_CONNECTION_TIMEOUT
|Destroys socket if connection is not established within the timeout.|
60000
| |
${NAMESPACE}_HTTP_PROXY
|Sets the initial proxy controller HTTPPROXY value.|N/A| |`${NAMESPACE}HTTPSPROXY`|Sets the initial proxy controller HTTPSPROXY value.|N/A| |
${NAMESPACE}_NO_PROXY
|Sets 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:

|Name|Description|Configurable| |---|---|---| |

HTTP_PROXY
|Yes|Sets HTTP proxy to use.| |
HTTPS_PROXY
|Yes|Sets a distinct proxy to use for HTTPS requests.| |
NO_PROXY
|Yes|Specifies 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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.