global-agent
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/global-agent package

    3.0.0 • Public • Published

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

    Install

    npm i global-agent

    DownloadsWeekly Downloads

    1,092,343

    Version

    3.0.0

    License

    BSD-3-Clause

    Unpacked Size

    125 kB

    Total Files

    73

    Last publish

    Collaborators

    • gajus