Global HTTP/HTTPS proxy agent configurable using environment variables.
Global HTTP/HTTPS proxy configurable using environment variables.
global-agent/bootstrap
To configure HTTP proxy:
global-agent/bootstrap.
GLOBAL_AGENT_HTTP_PROXYenvironment 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, -rconfiguration, e.g.
$ export GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8080 $ node -r 'global-agent/bootstrap' your-script.js
bootstraproutine
Instead of importing a self-initialising script with side-effects as demonstrated in the setup proxy using
global-agent/bootstrapdocumentation, you can import
bootstraproutine 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(); }
createGlobalProxyAgent
If you do not want to use
global.GLOBAL_AGENTvariable, then you can use
createGlobalProxyAgentto instantiate a controlled instance of
global-agent, e.g.
import { createGlobalProxyAgent } from 'global-agent';const globalProxyAgent = createGlobalProxyAgent();
Unlike
bootstraproutine,
createGlobalProxyAgentfactory does not create
global.GLOBAL_AGENTvariable and does not guard against multiple initializations of
global-agent. The result object of
createGlobalProxyAgentis equivalent to
global.GLOBAL_AGENT.
global-agent/bootstrapscript copies
process.env.GLOBAL_AGENT_HTTP_PROXYvalue to
global.GLOBAL_AGENT.HTTP_PROXYand continues to use the latter variable.
You can override the
global.GLOBAL_AGENT.HTTP_PROXYvalue 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-agentconfiguration is available under
global.GLOBAL_AGENTnamespace.
The
GLOBAL_AGENT_NO_PROXYenvironment variable specifies a pattern of URLs that should be excluded from proxying.
GLOBAL_AGENT_NO_PROXYvalue 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.
The environment variable
GLOBAL_AGENT_HTTPS_PROXYcan be set to specify a separate proxy for HTTPS requests. When this variable is not set
GLOBAL_AGENT_HTTP_PROXYis used for both HTTP and HTTPS requests.
global-agentis using
roarrlogger 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=trueenvironment variable to enable log printing to stdout.
roarr-cliprogram to pretty-print the logs.
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;
|Name|Description|Default| |---|---|---| |
GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE|Defines namespace of
HTTP_PROXY,
HTTPS_PROXYand
NO_PROXYenvironment variables.|
GLOBAL_AGENT_| |
GLOBAL_AGENT_FORCE_GLOBAL_AGENT|Forces to use
global-agentHTTP(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_AGENTis initialized by
bootstraproutine.
global.GLOBAL_AGENThas 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.|
global-agentworks with all libraries that internally use
http.request.
global-agenthas been tested to work with:
global-agentoverrides explicitly configured HTTP(S) agent?
By default,
global-agentoverrides
agentproperty of any HTTP request, even if
agentproperty 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).globalAgentinstance pre-configured with
keepAlive: true).
This behaviour can be disabled with
GLOBAL_AGENT_FORCE_GLOBAL_AGENT=falseenvironment variable. When disabled, then
global-agentwill only set
agentproperty when it is not already defined or if
agentis an instance of
http(s).globalAgent.
global-agent/bootstrapdoes not use
HTTP_PROXY?
request) change their behaviour when
HTTP_PROXYenvironment variable is present. Using a namespaced environment variable prevents conflicting library behaviour.
You can override this behaviour by configuring
GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACEvariable, e.g.
$ export GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE=
Now script initialized using
global-agent/bootstrapwill use
HTTP_PROXY,
HTTPS_PROXYand
NO_PROXYenvironment variables.
global-tunneland
tunnel?
global-tunnel(including
global-tunnel-ngand
tunnel) are designed to support legacy Node.js versions. They use various workarounds and rely on monkey-patching
http.request,
http.get,
https.requestand
https.getmethods.
In contrast,
global-agentsupports Node.js v10 and above, and does not implements workarounds for the older Node.js versions.