Interface ProxySetting

A ProxySetting is a specific proxy setting to use, which is passed to a proxy agent who will manage creating a socket for the request (directly, or tunnelled, or whatever).

interface ProxySetting {
    additionalTrustedCAs?: CADefinition[];
    noProxy?: string[];
    proxyUrl: string;
    trustedCAs?: (string | CADefinition)[];
}

Properties

additionalTrustedCAs?: CADefinition[]

Extra CAs to trust for HTTPS connections to the proxy. Ignored if the connection to the proxy is not HTTPS.

This appends to the list of trusted CAs, and is mutually exclusive with the trustedCAs option, which completely overrides the list of CAs.

noProxy?: string[]

A list of no-proxy values, matching hosts' traffic should not be proxied.

This is a common proxy feature, but unfortunately isn't standardized. See https://about.gitlab.com/blog/2021/01/27/we-need-to-talk-no-proxy/ for some background. This implementation is intended to match Curl's behaviour, and any differences are a bug.

The currently supported formats are:

  • example.com (matches domain and all subdomains)
  • example.com:443 (matches domain and all subdomains, but only on that port)
  • 10.0.0.1 (matches IP, but only when used directly - does not resolve domains)

Some other formats (e.g. leading dots or *.) will work, but the leading characters are ignored. More formats may be added in future, e.g. CIDR ranges. To maximize compatibility with values used elsewhere, unrecognized formats will generally be ignored, but may match in unexpected ways.

proxyUrl: string

The URL for the proxy to forward traffic through.

This can be any URL supported by https://www.npmjs.com/package/proxy-agent. For example: http://..., socks5://..., pac+http://...

trustedCAs?: (string | CADefinition)[]

CAs to trust for HTTPS connections to the proxy. Ignored if the connection to the proxy is not HTTPS. If not specified, this will default to the Node defaults, or you can override them here completely.

This sets the complete list of trusted CAs, and is mutually exclusive with the additionalTrustedCAs option, which adds additional CAs (but also trusts the Node default CAs too).

This should be specified as either a { cert: string | Buffer } object or a { certPath: string } object (to read the cert from disk). The previous simple string format is supported but deprecated.