<h1 align="center">
<a href="https://prompts.chat">
Global HTTP/HTTPS proxy configurable using environment variables.
Sign in to like and favorite skills
Global HTTP/HTTPS proxy configurable using environment variables.
global-agent-ts/bootstrapTo configure HTTP proxy:
global-agent-ts/bootstrap.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
bootstrap routineInstead of importing a self-initialising script with side-effects as demonstrated in the setup proxy using
documentation, you can import global-agent-ts/bootstrap
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(); }
createGlobalProxyAgentIf 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.
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.
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.
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.
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
program to pretty-print the logs.roarr-cli
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;
| Name | Description | Default |
|---|---|---|
| Defines namespace of , and environment variables. | |
| Forces to use HTTP(S) agent even when request was explicitly constructed with another agent. | |
| Destroys socket if connection is not established within the timeout. | |
| Sets the initial proxy controller HTTP_PROXY value. | N/A |
| Sets the initial proxy controller HTTPS_PROXY value. | N/A |
| Sets the initial proxy controller NO_PROXY value. | N/A |
global.GLOBAL_AGENTglobal.GLOBAL_AGENT is initialized by bootstrap routine.
global.GLOBAL_AGENT has the following properties:
| Name | Description | Configurable |
|---|---|---|
| Yes | Sets HTTP proxy to use. |
| Yes | Sets a distinct proxy to use for HTTPS requests. |
| Yes | Specifies a pattern of URLs that should be excluded from proxying. See Exclude URLs. |
global-agent-ts works with all libraries that internally use http.request.
global-agent-ts has been tested to work with:
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.
global-agent-ts/bootstrap does not use HTTP_PROXY?Some libraries (e.g.
) change their behaviour when request
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.
global-tunnel and tunnel?
(including global-tunnel
and global-tunnel-ng
) are designed to support legacy Node.js versions. They use various workarounds and rely on monkey-patching tunnel
, http.request
, http.get
and https.request
methods.https.get
In contrast,
global-agent-ts supports Node.js v10 and above, and does not implements workarounds for the older Node.js versions.