global-agent

Global HTTP/HTTPS proxy configurable using environment variables.

• Usage
  • Setup proxy
  • Runtime configuration
  • Exclude URLs
  • Enable logging
  • Events
• Supported libraries
• FAQ
  • How does it work?
  • What version of Node.js are supported?
  • What is the reason global-agent does not use HTTP_PROXY?
  • What is the difference from global-tunnel?

Usage

Setup proxy

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

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';

First HTTP request is going to use http://127.0.0.1:8001 proxy and 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 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.

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.

Events

global.GLOBAL_AGENT.eventEmitter is an instance of a Node.js event emitter.

• request event is emitted when a new HTTP request is proxied usign global-agent HTTP(S) agent.

Example:

global.GLOBAL_AGENT.eventEmitter.on('request', (request) => {
  request.once('response', (response) => {
    console.log({
      request,
      response
    });
  });
});

Supported libraries

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

global-agent has been tested to work with:

• got
• axios
• request

FAQ

How does it work?

global-agent configures http.globalAgent and https.globalAgent to use a custom Agent for HTTP and HTTPS.

What versions of Node.js are supported?

global-agent has been tested to work with Node v10 and above.

• global-agent works with Node.js v11.7.0 and above by overriding the http(s).globalAgent.
• global-agent works with Node.js v11.6 and below by overriding the http(s).get and http(s).request methods.

What is the reason global-agent 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.

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.