# ReqProxy

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`:

```elixir
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](https://curl.se/docs/manpage.html#ENVIRONMENT) 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?](https://about.gitlab.com/blog/we-need-to-talk-no-proxy/)".

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`:

```elixir
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`:

```elixir
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](https://github.com/elixir-lang/ex_doc):

```sh
mix docs
```

and published on [HexDocs](https://hexdocs.pm):

```sh
mix hex.publish
```

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

[Req]: https://hexdocs.pm/req/

Run tests with:

```sh
mix test
```