finch

<img alt="Finch" height="350px" src="assets/Finch_logo_onWhite.png#gh-light-mode-only">
<img alt="Finch" height="350px" src="assets/Finch_logo_all-White.png#gh-dark-mode-only">

[![CI](https://github.com/sneako/finch/actions/workflows/elixir.yml/badge.svg)](https://github.com/sneako/finch/actions/workflows/elixir.yml)
[![Hex pm](https://img.shields.io/hexpm/v/finch.svg?style=flat)](https://hex.pm/packages/finch)
[![Hexdocs.pm](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/finch/)

<!-- MDOC !-->

An HTTP client with a focus on performance, built on top of
[Mint](https://github.com/elixir-mint/mint) and [NimblePool](https://github.com/dashbitco/nimble_pool).

We attempt to achieve this goal by providing efficient connection pooling strategies and avoiding copying of memory wherever possible.

Most developers will most likely prefer to use the fabulous HTTP client [Req](https://github.com/wojtekmach/req) which takes advantage of Finch's pooling and provides an extremely friendly and pleasant to use API.

## Usage

In order to use Finch, you must start it and provide a `:name`. Often in your
supervision tree:

```elixir
children = [
  {Finch, name: MyFinch}
]
```

Or, in rare cases, dynamically:

```elixir
Finch.start_link(name: MyFinch)
```

Once you have started your instance of Finch, you are ready to start making requests:

```elixir
Finch.build(:get, "https://hex.pm") |> Finch.request(MyFinch)
```

When using HTTP/1, Finch will parse the passed in URL into a `{scheme, host, port}`
tuple, and maintain one or more connection pools for each `{scheme, host, port}` you
interact with.

You can also configure a pool size and count to be used for specific URLs that are
known before starting Finch. The passed URLs will be parsed into `{scheme, host, port}`,
and the corresponding pools will be started. See `Finch.start_link/1` for configuration
options.

```elixir
children = [
  {Finch,
   name: MyConfiguredFinch,
   pools: %{
     :default => [size: 10, count: 2],
     "https://hex.pm" => [size: 32, count: 8]
   }}
]
```

Pools will be started for each configured `{scheme, host, port}` when Finch is started.
For any unconfigured `{scheme, host, port}`, the pool will be started the first time
it is requested using the `:default` configuration. This means given the pool
configuration above each origin/`{scheme, host, port}` will launch 2 (`:count`) new pool
processes. So, if you encountered 10 separate combinations, that'd be 20 pool processes.

For how `:size` and `:count` interact on HTTP/1, how workers are chosen when `:count` is
greater than 1 (including the `:pool_strategy` request option), see the **Pool Configuration
Options** and **Multiple workers** sections in `Finch.start_link/1`.

### Pool Tagging

Finch supports pool tagging, which allows you to create separate pools for the same
`{scheme, host, port}` combination or Unix socket. This is useful when you need different
configurations or want to isolate traffic for d