global-agent-ts

Global HTTP/HTTPS proxy configurable using environment variables.

Usage

```
createGlobalProxyAgent
```
Environment variables
```
global.GLOBAL_AGENT
```

Supported libraries
FAQ

Usage

global-agent-ts/bootstrap

To configure HTTP proxy:

Import
```
global-agent-ts/bootstrap
```
.
Export HTTP proxy address as
```
GLOBAL_AGENT_HTTP_PROXY
```
environment variable.

Code:

import 'global-agent-ts/bootstrap';

// or:
// import {bootstrap} from 'global-agent-ts';
// 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-ts/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-ts/bootstrap

documentation, you can import

bootstrap

routine and explicitly evaluate the bootstrap logic, e.g.

import {
  bootstrap
} from 'global-agent-ts';

bootstrap();

This is useful if you need to conditionally bootstrap

global-agent-ts

, e.g.

import {
  bootstrap
} from 'global-agent-ts';
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-ts` 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-ts

, e.g.

import {
  createGlobalProxyAgent
} from 'global-agent-ts';

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-ts

. The result object of

createGlobalProxyAgent

is equivalent to

global.GLOBAL_AGENT

Runtime configuration

global-agent-ts/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-ts

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-ts

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-ts` 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`)
 * @property rejectUnauthorized `false` - all invalid SSL certificates are ignored and no error is thrown.
 *                              `true` - an error is thrown when an invalid SSL certificate is detected.
 *                              (Default: `undefined`)
 */
type ProxyAgentConfigurationInputType = {|
  +environmentVariableNamespace?: string,
  +forceGlobalAgent?: boolean,
  +socketConnectionTimeout?: number,
  +rejectUnauthorized?: boolean,
|};

(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-ts` 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 HTTP_PROXY value.	N/A
`${NAMESPACE}HTTPS_PROXY`	Sets the initial proxy controller HTTPS_PROXY 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-ts

works with all libraries that internally use

http.request

global-agent-ts

has been tested to work with:

FAQ

What is the reason

global-agent-ts

overrides explicitly configured HTTP(S) agent?

By default,

global-agent-ts

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-ts

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-ts/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-ts/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-ts

supports Node.js v10 and above, and does not implements workarounds for the older Node.js versions.

global-agent-ts

Global HTTP/HTTPS proxy configurable using environment variables.

Usage

API

```
createGlobalProxyAgent
```
Environment variables
```
global.GLOBAL_AGENT
```

Supported libraries
FAQ

Usage

Setup proxy using

global-agent-ts/bootstrap

To configure HTTP proxy:

Import
```
global-agent-ts/bootstrap
```
.
Export HTTP proxy address as
```
GLOBAL_AGENT_HTTP_PROXY
```
environment variable.

Code:

import 'global-agent-ts/bootstrap';

// or:
// import {bootstrap} from 'global-agent-ts';
// 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-ts/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-ts/bootstrap

documentation, you can import

bootstrap

routine and explicitly evaluate the bootstrap logic, e.g.

import {
  bootstrap
} from 'global-agent-ts';

bootstrap();

This is useful if you need to conditionally bootstrap

global-agent-ts

, e.g.

import {
  bootstrap
} from 'global-agent-ts';
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-ts` 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-ts

, e.g.

import {
  createGlobalProxyAgent
} from 'global-agent-ts';

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-ts

. The result object of

createGlobalProxyAgent

is equivalent to

global.GLOBAL_AGENT

Runtime configuration

global-agent-ts/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-ts

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-ts

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-ts` 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`)
 * @property rejectUnauthorized `false` - all invalid SSL certificates are ignored and no error is thrown.
 *                              `true` - an error is thrown when an invalid SSL certificate is detected.
 *                              (Default: `undefined`)
 */
type ProxyAgentConfigurationInputType = {|
  +environmentVariableNamespace?: string,
  +forceGlobalAgent?: boolean,
  +socketConnectionTimeout?: number,
  +rejectUnauthorized?: boolean,
|};

(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-ts` 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 HTTP_PROXY value.	N/A
`${NAMESPACE}HTTPS_PROXY`	Sets the initial proxy controller HTTPS_PROXY 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-ts

works with all libraries that internally use

http.request

global-agent-ts

has been tested to work with:

FAQ

What is the reason

global-agent-ts

overrides explicitly configured HTTP(S) agent?

By default,

global-agent-ts

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-ts

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-ts/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-ts/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-ts

supports Node.js v10 and above, and does not implements workarounds for the older Node.js versions.

global-agent-ts

Related Skills

<h1 align="center">

2. Apply Deepthink Protocol (reason about dependencies

- Identify gaps