ReqProxy

Copy Markdown View Source

A Req plugin to set Mint proxy parameters according to system environment variables such as https_proxy. This allows Req to behave like most other high-level HTTP clients, on systems where proxying should be automatically configured.

Simplified usage is possible when the caller knows which proxy to use, this can be passed through the :proxy request option.

Usage

To add the ReqProxy step to a request, call attach/1:

Req.new()
|> ReqProxy.attach()

Options

  • :proxy - Overrides any other proxy environment or connect_options. Passing an empty string "" or the atom :none disables proxying. Passing a URL will use it as a proxy. Example: proxy: "http://proxy.domain:8080"

Environment variables

See the curl manual for a classic overview of each environment variable. The curl man page leaves some room for interpretation, see also Stan Hu's discussion of quirks in "We need to talk: Can we standardize NO_PROXY?". We've tried to follow curl conventions here, for example a no_proxy entry without a leading dot is tested against URLs as both a full hostname and as a subdomain suffix. Refer to the test suite for a complete list of edge cases.

The destination will be matched against several optional environment variables, in this order:

  • If the host matches any term in the comma-separated no_proxy variable, then no proxy will be used. Host patterns are given by any of:

    • A single asterix "*" matches all hosts.
    • Exact host name or IP match, eg. no_proxy="a.test" matches a.test.
    • Subdomain match, eg. no_proxy=".a.test" matches api.a.test.
    • Contained in a CIDR block, eg. no_proxy="127.0.0.0/24" matches 127.0.0.1.

  • http_proxy or https_proxy will be used depending on the destination scheme. Other named schemes will be looked up dynamically, eg. "ftp_proxy".

  • all_proxy is the ultimate fallback: if no other proxy is found and the target host is not ruled out for proxying, then the all_proxy value is used.

Installation

req_proxy can be added to a project through mix.exs:

def deps do
  [
    {:req_proxy, "~> 0.1.0"}
  ]
end

If you want to use CIDR blocks in the no_proxy list, you must also include :inet_cidr:

def deps do
  [
    {:req_proxy, "~> 0.1.0"},
    {:inet_cidr, "~> 1.0.0"}
  ]
end

The dependency on :inet_cidr is soft: if the library is unavailable then a warning will be logged for every request that could not parse a CIDR block.

Development

Documentation can be generated with ExDoc:

mix docs

and published on HexDocs:

mix hex.publish

The docs will be published at https://hexdocs.pm/req_proxy.

Run tests with:

mix test