Finch

https://finch.hexdocs.pm/
Admin
Finch is an HTTP client with a focus on performance, built on top of Mint and NimblePool, providing...
Tokens:29,559
Snippets:298
Trust Score:9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Async Request Example

Source: https://finch.hexdocs.pm/

Demonstrates making an asynchronous GET request and processing the response chunks. Note that async requests are not automatically retried on pool draining.

```elixir
iex> req = Finch.build(:get, "https://httpbin.org/stream/5")
iex> ref = Finch.async_request(req, MyFinch)
iex> flush()
{ref, {:status, 200}}
{ref, {:headers, [...]}}
{ref, {:data, "..."}}
{ref, :done}
```

--------------------------------

### Start Finch with Unix Socket

Source: https://finch.hexdocs.pm/

Use this to start Finch and configure it to listen on a Unix domain socket. The socket path is specified in the pools configuration.

```elixir
Finch.start_link(
  name: MyFinch,
  pools: %{
    "http+unix:///tmp/socket" => [size: 5]
  }
)
```

--------------------------------

### Finch Initialization and Configuration

Source: https://finch.hexdocs.pm/

Functions for starting and configuring Finch instances.

```APIDOC
## Finch Initialization and Configuration

### `Finch.start_link/1`

Starts an instance of Finch.

**Arguments:**

* `opts` - Options for starting the Finch instance, such as `:name` and `:pools`.
```

--------------------------------

### Start Finch Instance with URL Pool Configuration

Source: https://finch.hexdocs.pm/

Starts a Finch instance with a specific pool configuration for a given URL. The pool uses the :default tag unless a Finch.Pool.t() struct is used as the key.

```Elixir
Finch.start_link(
  name: MyFinch,
  pools: %{
    "https://api.example.com" => [size: 10, count: 2]
  }
)
```

--------------------------------

### Start a User-Managed Finch Pool

Source: https://finch.hexdocs.pm/Finch.Pool.html

Use Finch.Pool.child_spec/1 to generate a child specification for starting a pool under your own supervision tree. This requires a Finch instance to be started first.

```elixir
children = [
  {Finch, name: MyFinch},
  {Finch.Pool, finch: MyFinch, pool: Finch.Pool.new("https://api.internal", tag: :api), size: 10}
]
Supervisor.start_link(children, strategy: :one_for_one)
```

--------------------------------

### Start Finch Dynamically

Source: https://finch.hexdocs.pm/

Dynamically start a Finch instance. This is less common and typically used in specific scenarios.

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

--------------------------------

### Start Finch with a Name

Source: https://finch.hexdocs.pm/

Start Finch as part of your supervision tree by providing a name. This is the most common way to integrate Finch into your application.

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

--------------------------------

### Start a Finch Pool

Source: https://finch.hexdocs.pm/

Dynamically starts a pool under Finch's supervision tree. Returns :ok if the pool was started or already exists. Accepts pool configuration options.

```elixir
@spec start_pool(name(), Finch.Pool.t(), keyword()) :: :ok
```

```elixir
Finch.start_pool(MyFinch, Finch.Pool.new("https://api.example.com", tag: :api), size: 10)
```

--------------------------------

### start_pool

Source: https://finch.hexdocs.pm/Finch.html

Starts a Finch pool dynamically under Finch's supervision tree. It returns `:ok` if the pool was started or already exists. Pool configuration options are similar to `Finch.start_link/1`.

```APIDOC
## start_pool(name, pool, opts \\ [])

### Description
Starts a pool dynamically under Finch's internal supervision tree.
Returns `:ok` if the pool was started or already exists.

### Parameters
#### Path Parameters
- **name** (name()) - The name of the Finch client.
- **pool** (Finch.Pool.t()) - The pool definition.
- **opts** (keyword()) - Pool configuration options such as `:size`, `:count`, `:protocols`, `:conn_opts`, etc.

### Response
#### Success Response
- `:ok` - The pool was started or already exists.

### Example
```elixir
Finch.start_pool(MyFinch, Finch.Pool.new("https://api.example.com", tag: :api), size: 10)
```
```

--------------------------------

### Finch.start_pool/3

Source: https://finch.hexdocs.pm/Finch.html

Starts a pool dynamically under Finch's internal supervision tree.

```APIDOC
## `Finch.start_pool/3`

Starts a pool dynamically under Finch's internal supervision tree.

### Function Signature

`start_pool(name, pool, opts \\ [])`

### Parameters

*   `name` (Finch.name()): The name of the Finch instance.
*   `pool` (Finch.Pool.t()): The pool configuration.
*   `opts` (keyword()): Optional arguments.
```

--------------------------------

### Start User-Managed Finch Pools

Source: https://finch.hexdocs.pm/

Start Finch pools under your own supervision tree. The Finch instance must be started first. Integrates with Finch.request/2, Finch.stop_pool/2, Finch.get_pool_status/2, and Finch.find_pool/2.

```elixir
children = [
  {Finch, name: MyFinch},
  {Finch.Pool, finch: MyFinch, pool: Finch.Pool.new("https://api.internal", tag: :api), size: 10},
  {Finch.Pool, finch: MyFinch, pool: Finch.Pool.new("https://node-2.internal", tag: :node2), size: 10}
]
Supervisor.start_link(children, strategy: :one_for_one)
```

--------------------------------

### start_link/1

Source: https://finch.hexdocs.pm/Finch.html

Starts a new Finch instance with the given options, including the instance name and a map of pool configurations. Pools can be identified by URL strings or Finch.Pool structs for tagged pools.

```APIDOC
## start_link(opts)

Start an instance of Finch.

### Options
  * `:name` - The name of your Finch instance. Required.
  * `:pools` - A map of pool identifiers to configuration options. See the ":pools" subsection below.

### :name
The name of your Finch instance. It is used to identify the instance when making requests and when calling other functions like `Finch.start_pool/3` or `Finch.get_pool_status/2`.
#### Examples
```elixir
Finch.start_link(name: MyFinch)
```

### :pools
A map where each key identifies a pool and each value is a keyword list of pool configuration options (see "Pool Configuration Options" below). Default is `%{:default => [size: 50, count: 1]}`.
**Pool keys** may be:
  * URL string – A binary URL. Pools created from URLs use the `:default` tag unless you use a `Finch.Pool.t/0` struct as the key instead.
  * `Finch.Pool.t/0` struct – Created with `Finch.Pool.new/2`. Use this when you need tagged pools (e.g. to run multiple pools for the same host with different configs).
  * URL string with `http+unix://` or `https+unix://` – For Unix domain sockets (e.g. `"http+unix:///tmp/socket"`)
  * `:default` – Catch-all. Any request whose pool is not in the map will use this config when its pool is started.

When making a request with a `:pool_tag` option, that tag must exist in your pool configuration. If it does not, the request uses the `:default` configuration.
#### Examples
```elixir
# URL keys (pool uses :default tag)
Finch.start_link(
  name: MyFinch,
  pools: %{
    "https://api.example.com" => [size: 10, count: 2]
  }
)

# Tagged pools via Finch.Pool.new/2
Finch.start_link(
  name: MyFinch,
  pools: %{
    Finch.Pool.new("https://api.example.com", tag: :bulk) => [size: 100, count: 1],
    Finch.Pool.new("https://api.example.com", tag: :realtime) => [size: 10, count: 2]
  }
)
```
```

--------------------------------

### Start Finch Instance with Tagged Pools

Source: https://finch.hexdocs.pm/

Starts a Finch instance with multiple tagged pools for the same host, allowing different configurations for different purposes. Finch.Pool.new/2 is used to create tagged pool keys.

```Elixir
Finch.start_link(
  name: MyFinch,
  pools: %{
    Finch.Pool.new("https://api.example.com", tag: :bulk) => [size: 100, count: 1],
    Finch.Pool.new("https://api.example.com", tag: :realtime) => [size: 10, count: 2]
  }
)
```

--------------------------------

### start_pool

Source: https://finch.hexdocs.pm/

Starts a Finch connection pool dynamically. It can be used to manage pools for different services or configurations. The function returns :ok if the pool is successfully started or if it already exists.

```APIDOC
## start_pool(name, pool, opts \\ [])

### Description
Starts a pool dynamically under Finch's internal supervision tree.

### Method
`start_pool/3`

### Parameters
#### Path Parameters
- **name** (name()) - The name of the Finch supervisor.
- **pool** (Finch.Pool.t()) - The pool configuration.
- **opts** (keyword()) - Options for starting the pool. Same as `Finch.start_link/1`.

### Response
#### Success Response
- `:ok` - The pool was started or already exists.

### Example
```elixir
Finch.start_pool(MyFinch, Finch.Pool.new("https://api.example.com", tag: :api), size: 10)
```
```

--------------------------------

### User-managed pools

Source: https://finch.hexdocs.pm/Finch.html

Demonstrates how to start Finch pools under your own supervision tree using `Finch.Pool.child_spec/1` and how to add pools dynamically using `Finch.start_pool/3`.

```APIDOC
## User-managed pools

You can start pools under your own supervision tree using `Finch.Pool.child_spec/1`. The Finch instance must be started first. User-managed pools integrate with `Finch.request/2`, `Finch.stop_pool/2`, `Finch.get_pool_status/2`, and `Finch.find_pool/2`:

```elixir
children = [
  {Finch, name: MyFinch},
  {Finch.Pool, finch: MyFinch, pool: Finch.Pool.new("https://api.internal", tag: :api), size: 10},
  {Finch.Pool, finch: MyFinch, pool: Finch.Pool.new("https://node-2.internal", tag: :node2), size: 10}
]
Supervisor.start_link(children, strategy: :one_for_one)
```

To add pools dynamically under Finch's internal supervisor, use `Finch.start_pool/3`:

```elixir
Finch.start_pool(MyFinch, Finch.Pool.new("https://api.example.com", tag: :api), size: 10)
```

Use `Finch.find_pool/2` to check if a pool exists:

```elixir
case Finch.find_pool(MyFinch, Finch.Pool.new("https://api.internal", tag: :api)) do
  {:ok, _pid} -> # Pool exists
  :error -> # Pool not found
end
```
```

--------------------------------

### start_link/1

Source: https://finch.hexdocs.pm/

Starts a new instance of Finch with a given name and a map of pool configurations. Pools can be identified by URL strings or `Finch.Pool.t()` structs for tagged pools, allowing for flexible configuration of connection pools.

```APIDOC
## start_link(opts)

Start an instance of Finch.

## Options
  * `:name` - The name of your Finch instance. Required.
  * `:pools` - A map of pool identifiers to configuration options. See the ":pools" subsection below.

### :name
The name of your Finch instance. It is used to identify the instance when making requests and when calling other functions like `Finch.start_pool/3` or `Finch.get_pool_status/2`.
#### Examples
```elixir
Finch.start_link(name: MyFinch)
```

### :pools
A map where each key identifies a pool and each value is a keyword list of pool configuration options (see "Pool Configuration Options" below). Default is `%{:default => [size: 50, count: 1]}`.
**Pool keys** may be:
  * URL string – A binary URL. Pools created from URLs use the `:default` tag unless you use a `Finch.Pool.t/0` struct as the key instead.
  * `Finch.Pool.t/0` struct – Created with `Finch.Pool.new/2`. Use this when you need tagged pools (e.g. to run multiple pools for the same host with different configs).
  * URL string with `http+unix://` or `https+unix://` – For Unix domain sockets (e.g. `"http+unix:///tmp/socket"`)
  * `:default` – Catch-all. Any request whose pool is not in the map will use this config when its pool is started.

When making a request with a `:pool_tag` option, that tag must exist in your pool configuration. If it does not, the request uses the `:default` configuration.
#### Examples
```elixir
# URL keys (pool uses :default tag)
Finch.start_link(
  name: MyFinch,
  pools: %{
    "https://api.example.com" => [size: 10, count: 2]
  }
)

# Tagged pools via Finch.Pool.new/2
Finch.start_link(
  name: MyFinch,
  pools: %{
    Finch.Pool.new("https://api.example.com", tag: :bulk) => [size: 100, count: 1],
    Finch.Pool.new("https://api.example.com", tag: :realtime) => [size: 10, count: 2]
  }
)
```
```

--------------------------------

### Start Finch Pool Dynamically

Source: https://finch.hexdocs.pm/

Add pools dynamically under Finch's internal supervisor. This function starts a pool and registers it.

```elixir
Finch.start_pool(MyFinch, Finch.Pool.new("https://api.example.com", tag: :api), size: 10)
```

--------------------------------

### Round Robin Strategy Example

Source: https://finch.hexdocs.pm/Finch.Pool.Strategy.RoundRobin.html

Demonstrates how to initialize a new round-robin counter and use it with Finch.request. It is recommended to share the counter state across all usages of the same pool for proper round-robin distribution.

```elixir
counter = Finch.Pool.Strategy.RoundRobin.new()
Finch.request(req, MyFinch, pool_strategy: {Finch.Pool.Strategy.RoundRobin, counter})
```

--------------------------------

### Configure Finch Pools by URL

Source: https://finch.hexdocs.pm/

Configure specific pool sizes and counts for known URLs when starting Finch. Unconfigured URLs use the :default configuration.

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

--------------------------------

### Using RoundRobin Strategy Directly

Source: https://finch.hexdocs.pm/Finch.Pool.Strategy.html

For performance-critical paths, pass the strategy function directly to avoid dynamic module dispatch. This example shows the RoundRobin strategy with its counter state.

```elixir
Finch.request(req, MyFinch, pool_strategy: {&Finch.Pool.Strategy.RoundRobin.select/2, counter})
```

--------------------------------

### Start Finch with Custom Default Configuration

Source: https://finch.hexdocs.pm/

Configure Finch with a custom default pool configuration, specifying the size and count for the default pool. This is useful for fine-tuning connection pool behavior.

```elixir
Finch.start_link(
  name: MyFinch,
  pools: %{
    :default => [size: 25, count: 2]
  }
)
```

--------------------------------

### Implementing a Custom LeastBusy Strategy

Source: https://finch.hexdocs.pm/Finch.Pool.Strategy.html

Shows how to implement a custom pool strategy by defining a module that adheres to the Finch.Pool.Strategy behavior. This example selects the worker with the least busy message queue.

```elixir
defmodule MyApp.LeastBusy do
  @behaviour Finch.Pool.Strategy

  @impl true
  def select(entries, _) do
    Enum.min_by(entries, fn {pid, _mod} ->
      case Process.info(pid, :message_queue_len) do
        {:message_queue_len, len} -> len
        nil -> :infinity
      end
    end)
  end
end

Finch.request(req, MyFinch, pool_strategy: MyApp.LeastBusy)
```

--------------------------------

### Build and Request with Finch

Source: https://finch.hexdocs.pm/

Build an HTTP GET request and send it using a named Finch instance. Finch parses URLs for HTTP/1 and manages connection pools per origin.

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

--------------------------------

### Finch.get_pool_status/2

Source: https://finch.hexdocs.pm/Finch.html

Get pool metrics.

```APIDOC
## `Finch.get_pool_status/2`

Get pool metrics.

### Function Signature

`get_pool_status(finch_name, pool_identifier)`

### Parameters

*   `finch_name` (Finch.name()): The name of the Finch instance.
*   `pool_identifier` (Finch.pool_identifier()): The identifier of the pool to get status for.

### Returns

*   `Finch.pool_metrics()`: Metrics for the specified pool.
```

--------------------------------

### Finch.Pool.child_spec/1

Source: https://finch.hexdocs.pm/Finch.Pool.html

Returns a child specification for starting a pool under your own supervision tree. This allows independent management of pool lifecycles.

```APIDOC
## Finch.Pool.child_spec/1

### Description
Returns a child specification for starting a pool under your own supervision tree. This allows you to manage the lifecycle of pools independently from Finch's internal DynamicSupervisor. The pools integrate fully with Finch's APIs.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
`opts` - A keyword list of options:
  * `:finch` - Required. The name of your Finch instance.
  * `:pool` - Required. A `Finch.Pool.t()` struct identifying the pool.
  * All pool configuration options from `Finch.start_link/1` are supported: `:size`, `:count`, `:protocols`, `:conn_opts`, etc.

### Request Example
```elixir
children = [
  {Finch, name: MyFinch},
  {Finch.Pool, finch: MyFinch, pool: Finch.Pool.new("https://api.internal", tag: :api), size: 10}
]
Supervisor.start_link(children, strategy: :one_for_one)
```

### Response
#### Success Response (200)
- `child_spec` - A supervisor child specification for the pool.

#### Response Example
```elixir
{Finch.Pool, finch: MyFinch, pool: %Finch.Pool{...}, size: 10}
```

### Notes
  * The Finch instance must be started before the user-managed pool
  * `Finch.stop_pool/2` works on user-managed pools
  * `Finch.get_pool_status/2` works if `start_pool_metrics?: true`
```

--------------------------------

### Finch Pool Management

Source: https://finch.hexdocs.pm/

Functions for managing Finch pools, including starting, stopping, finding, and checking their status.

```APIDOC
## Finch Pool Management

### `Finch.Pool.child_spec/1`

Returns a child specification for starting a Finch pool under a supervision tree.

### `Finch.start_pool/3`

Starts a pool dynamically under Finch's internal supervision tree.

**Arguments:**

* `name` - The name of the Finch instance.
* `pool` - The pool configuration, typically created with `Finch.Pool.new/2`.
* `opts` - Optional arguments for starting the pool.

### `Finch.find_pool/2`

Finds a pool by its configuration and returns its PID if found.

**Arguments:**

* `name` - The name of the Finch instance.
* `pool` - The pool configuration to search for.

**Returns:**

* `{:ok, pid}` if the pool is found.
* `:error` if the pool is not found.

### `Finch.get_pool_status/2`

Retrieves metrics for a specific pool.

**Arguments:**

* `finch_name` - The name of the Finch instance.
* `pool_identifier` - The identifier of the pool.

### `Finch.stop_pool/2`

Stops the pool of processes associated with the given pool identifier.

**Arguments:**

* `finch_name` - The name of the Finch instance.
* `pool_identifier` - The identifier of the pool to stop.

### `Finch.get_pool_count/2`

Returns the current worker count for the given pool.

**Arguments:**

* `finch_name` - The name of the Finch instance.
* `pool_identifier` - The identifier of the pool.

### `Finch.set_pool_count/3`

Dynamically changes the number of pool workers for the given pool.

**Arguments:**

* `finch_name` - The name of the Finch instance.
* `pool_identifier` - The identifier of the pool.
* `count` - The desired number of workers.
```

--------------------------------

### Get Finch Pool Status Metrics

Source: https://finch.hexdocs.pm/

Retrieves metrics for a specific Finch pool or all pools under the :default configuration. Metrics include connection counts and pool size.

```elixir
@spec get_pool_status(name(), :default | pool_identifier()) ::
  {:ok, pool_metrics()} | {:ok, default_pool_metrics()} | {:error, :not_found}
```

```elixir
iex> Finch.get_pool_status(MyFinch, "https://httpbin.org")
{:ok, [
  %Finch.HTTP1.PoolMetrics{
    pool_index: 1,
    pool_size: 50,
    available_connections: 43,
    in_use_connections: 7
  },
  %Finch.HTTP1.PoolMetrics{
    pool_index: 2,
    pool_size: 50,
    available_connections: 37,
    in_use_connections: 13
  }]
}
```

```elixir
iex> Finch.get_pool_status(MyFinch, :default)
{:ok,
 %{
   %Finch.Pool{host: "httpbin.com", port: 443, scheme: :https, tag: :default} => [
     %Finch.HTTP1.PoolMetrics{
       pool_index: 1,
       pool_size: 50,
       available_connections: 43,
       in_use_connections: 7
     }
   ]
 }}
```

--------------------------------

### Initialize Hash Strategy

Source: https://finch.hexdocs.pm/Finch.Pool.Strategy.Hash.html

Initializes the Hash strategy with a key or defaults to `self()`. Use this to establish connection affinity.

```elixir
key = Finch.Pool.Strategy.Hash.new()
Finch.request(req, MyFinch, pool_strategy: {Finch.Pool.Strategy.Hash, key})
```

```elixir
## equivalent to the above
Finch.request(req, MyFinch, pool_strategy: {Finch.Pool.Strategy.Hash, self()})
```

--------------------------------

### Get Finch Pool Worker Count

Source: https://finch.hexdocs.pm/

Retrieves the current number of workers for a specific Finch pool. Returns :error if the pool is not found.

```elixir
@spec get_pool_count(name(), pool_identifier()) ::
  {:ok, pos_integer()} | {:error, :not_found}
```

```elixir
{:ok, count} = Finch.get_pool_count(MyFinch, "https://example.com")
```

--------------------------------

### Finch HTTP Method Type

Source: https://finch.hexdocs.pm/Finch.Request.html

Represents an HTTP request method, supporting standard atoms like :get and :post, or any arbitrary method as a String.t().

```elixir
@type method() ::
  :get | :post | :head | :patch | :delete | :options | :put | String.t()
```

--------------------------------

### Using Hash-Based Strategy

Source: https://finch.hexdocs.pm/Finch.Pool.Strategy.html

Illustrates the use of the built-in Hash strategy, which maps the same key to the same worker, useful for connection affinity. The strategy is passed with its state (e.g., a team ID).

```elixir
Finch.request(req, MyFinch, pool_strategy: {Finch.Pool.Strategy.Hash, team_id})
```

--------------------------------

### Initialize Hash Strategy with Specific Key

Source: https://finch.hexdocs.pm/Finch.Pool.Strategy.Hash.html

Initializes the Hash strategy with a specific key, such as a tenant ID, for targeted routing. This ensures requests with the same key are consistently directed to the same worker.

```elixir
key = Finch.Pool.Strategy.Hash.new(tenant_id)
Finch.request(req, MyFinch, pool_strategy: {Finch.Pool.Strategy.Hash, key})
```

```elixir
## equivalent to the above
Finch.request(req, MyFinch, pool_strategy: {Finch.Pool.Strategy.Hash, tenant_id})
```

--------------------------------

### Create a Finch Pool for a Unix Socket

Source: https://finch.hexdocs.pm/Finch.Pool.html

Use Finch.Pool.new/1 with a URL that specifies a Unix socket scheme to create a pool struct for local socket connections.

```elixir
pool = Finch.Pool.new("http+unix:///tmp/socket")
```

--------------------------------

### Create a Tagged Finch Pool from a URL

Source: https://finch.hexdocs.pm/Finch.Pool.html

Use Finch.Pool.new/2 with a tag option to create a pool struct that can be identified by a specific tag. This is useful for managing multiple pools to the same host.

```elixir
pool = Finch.Pool.new("https://api.example.com", tag: :api)
```

--------------------------------

### Create a Tagged Finch Pool for a Unix Socket

Source: https://finch.hexdocs.pm/Finch.Pool.html

Use Finch.Pool.new/2 with a Unix socket URL and a tag option to create a pool struct for tagged Unix socket connections.

```elixir
pool = Finch.Pool.new("http+unix:///tmp/socket", tag: :api)
```

--------------------------------

### Add Private Metadata to Finch Request

Source: https://finch.hexdocs.pm/Finch.Request.html

Sets a new private key and value in the request metadata. This is useful for libraries and frameworks to inject information that can be retrieved later, for example, from Finch.Telemetry events.

```elixir
@spec put_private(t(), key :: atom(), value :: term()) :: t()
```

--------------------------------

### Finch Build Options Type

Source: https://finch.hexdocs.pm/Finch.Request.html

Defines build options as a list of build_opt types.

```elixir
@type build_opts() :: [build_opt()]
```

--------------------------------

### build/5

Source: https://finch.hexdocs.pm/Finch.html

Builds an HTTP request to be sent with Finch functions like `request/3`, `async_request/3`, `stream/5`, or `stream_while/5`. It allows specifying the method, URL, headers, body, and various build options.

```APIDOC
## build/5

### Description
Builds an HTTP request to be sent with `request/3`, `async_request/3`, `stream/5`, or `stream_while/5`. Request `body` can be one of: `nil`, `iodata`, `{:stream, enumerable}`, or `{:stream, req_body_fun}`.

### Function Signature
```elixir
@spec build(Finch.Request.method(), Finch.Request.url(), Finch.Request.headers(), Finch.Request.body(), Finch.Request.build_opts()) :: Finch.Request.t()
```

### Options
* `:unix_socket` - Path to a Unix domain socket to connect to instead of the URL host/port. The URL scheme still determines whether HTTP or HTTPS is used.
* `:pool_tag` - The tag to use when selecting which pool to use for this request. Defaults to `:default`.
```

--------------------------------

### build/5

Source: https://finch.hexdocs.pm/

Builds an HTTP request to be sent with Finch functions like `request/3`, `async_request/3`, `stream/5`, or `stream_while/5`. It supports various body types including nil, iodata, and streaming options.

```APIDOC
## build/5

### Description
Builds an HTTP request to be sent with `request/3`, `async_request/3`, `stream/5`, or `stream_while/5`. Request `body` can be one of:
  * `nil` - no body is sent with the request.
  * `iodata` - the body to send for the request.
  * `{:stream, enumerable}` - stream request body chunks emitted by an `Enumerable`.
  * `{:stream, req_body_fun}` - stream request body chunks emitted by `req_body_fun`. Can only be used with `Finch.stream_while/5` on HTTP/1 pools.
See `Finch.stream_while/5` for more information.

### Method
`build/5`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* `method` (Finch.Request.method()) - The HTTP method.
* `url` (Finch.Request.url()) - The URL for the request.
* `headers` (Finch.Request.headers()) - Optional headers for the request.
* `body` (Finch.Request.body()) - The request body, can be nil, iodata, or a stream.
* `opts` (Finch.Request.build_opts()) - Options for building the request, such as `:unix_socket` or `:pool_tag`.
```

--------------------------------

### Create a Finch Pool from a URL

Source: https://finch.hexdocs.pm/Finch.Pool.html

Use Finch.Pool.new/1 to create a pool struct from a given URL. This is useful for establishing connections to external APIs.

```elixir
pool = Finch.Pool.new("https://api.example.com")
```

--------------------------------

### Finch Request Options Type

Source: https://finch.hexdocs.pm/

A list of `request_opt()` used to configure Finch requests.

```Elixir
@type request_opts() :: [request_opt()]
```

--------------------------------

### Upload File using Streamed Request Body

Source: https://finch.hexdocs.pm/

Demonstrates uploading a file by providing a `req_body_fun` to Finch.build. This function reads the file in chunks and sends them as the request body.

```elixir
file = File.open!("/tmp/archive.zip", [:read])

req_body_fun = fn file ->
  case IO.binread(file, 4096) do
    :eof -> {:done, file}
    data -> {:data, data, file}
  end
end

request = Finch.build(:post, "https://example.com/upload", [], {:stream, req_body_fun})

resp_fun = fn
  {:status, status}, acc ->
    IO.inspect(status)
    {:cont, acc}

  {:headers, headers}, acc ->
    IO.inspect(headers)
    {:cont, acc}

  {:data, data}, acc ->
    IO.inspect(data)
    {:cont, acc}
end

{:ok, file} = Finch.stream_while(request, MyFinch, file, resp_fun)
File.close(file)
```

--------------------------------

### Finch.request/2

Source: https://finch.hexdocs.pm/Finch.html

Sends an HTTP request and returns a `Finch.Response` struct.

```APIDOC
## `Finch.request/2`

Sends an HTTP request and returns a `Finch.Response` struct.

### Function Signature

`request(req, name, opts \\ [])`

### Parameters

*   `req` (Finch.build/5): The HTTP request to send.
*   `name` (Finch.name()): The name of the Finch instance.
*   `opts` (Finch.request_opts()): Options for the request.
```

--------------------------------

### Specify TLS Key Log File in Pool Configuration

Source: https://finch.hexdocs.pm/Finch.html

Sets the `:ssl_key_log_file` connection option within the pool configuration to specify where TLS secrets should be written.

```elixir
{Finch,
 name: MyFinch,
 pools: %{
   default: [
     conn_opts: [
       ssl_key_log_file: "/writable/path/to/the/sslkey.log"
     ]
   ]
 }}
```

--------------------------------

### async_request

Source: https://finch.hexdocs.pm/Finch.html

Sends an HTTP request asynchronously, returning a request reference. Response information is sent to the calling process as it is received in {ref, response} tuples.

```APIDOC
## async_request(req, name, opts \\ [])

### Description
Sends an HTTP request asynchronously, returning a request reference. If the request is sent using HTTP1, an extra process is spawned to consume messages from the underlying socket. The messages are sent to the current process as soon as they arrive, as a firehose. If you wish to maximize request rate or have more control over how messages are streamed, a strategy using `request/3` or `stream/5` should be used instead.

### Receiving the response
Response information is sent to the calling process as it is received in `{ref, response}` tuples.
If the calling process exits before the request has completed, the request will be canceled.
Responses include:
  * `{:status, status}` - HTTP response status
  * `{:headers, headers}` - HTTP response headers
  * `{:data, data}` - section of the HTTP response body
  * `{:error, exception}` - an error occurred during the request
  * `:done` - request has completed successfully

On a successful request, a single `:status` message will be followed by a single `:headers` message, after which more than one `:data` messages may be sent. If trailing headers are present, a final `:headers` message may be sent. Any `:done` or `:error` message indicates that the request has succeeded or failed and no further messages are expected.

### Method
`async_request/3`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### async_request

Source: https://finch.hexdocs.pm/

Sends an HTTP request asynchronously, returning a request reference. Response information is sent to the calling process as it is received in {ref, response} tuples.

```APIDOC
## async_request(req, name, opts \\ [])

### Description
Sends an HTTP request asynchronously, returning a request reference. Response information is sent to the calling process as it is received in {ref, response} tuples.
If the request is sent using HTTP1, an extra process is spawned to consume messages from the underlying socket. The messages are sent to the current process as soon as they arrive, as a firehose. If you wish to maximize request rate or have more control over how messages are streamed, a strategy using `request/3` or `stream/5` should be used instead.

## Receiving the response
Response information is sent to the calling process as it is received in `{ref, response}` tuples.
If the calling process exits before the request has completed, the request will be canceled.
Responses include:
  * `{:status, status}` - HTTP response status
  * `{:headers, headers}` - HTTP response headers
  * `{:data, data}` - section of the HTTP response body
  * `{:error, exception}` - an error occurred during the request
  * `:done` - request has completed successfully


On a successful request, a single `:status` message will be followed by a single `:headers` message, after which more than one `:data` messages may be sent. If trailing headers are present, a final `:headers` message may be sent. Any `:done` or `:error` message indicates that the request has succeeded or failed and no further messages are expected.
```

--------------------------------

### request!/3

Source: https://finch.hexdocs.pm/Finch.html

Sends an HTTP request and returns a Finch.Response struct, raising an exception if the request fails. This is a convenience wrapper around `request/3` for cases where exceptions are preferred over tuples.

```APIDOC
## request!(req, name, opts \\ [])

@spec request!(Finch.Request.t(), name(), request_opts()) :: Finch.Response.t()

Sends an HTTP request and returns a `Finch.Response` struct or raises an exception in case of failure. See `request/3` for more detailed information.
```

--------------------------------

### Finch Build Option Type

Source: https://finch.hexdocs.pm/Finch.Request.html

Specifies the types of build options available, such as a Unix socket path or a pool tag.

```elixir
@type build_opt() :: {:unix_socket, String.t()} | {:pool_tag, Finch.Pool.pool_tag()}
```

--------------------------------

### Logging TLS Secrets

Source: https://finch.hexdocs.pm/Finch.html

Explains how to configure Finch to log TLS secrets for decryption with tools like Wireshark, using either the `:ssl_key_log_file` option or the `SSLKEYLOGFILE` environment variable.

```APIDOC
## Logging TLS Secrets

Finch supports logging TLS secrets to a file. These can be later used in a tool such as Wireshark to decrypt HTTPS sessions. To use this feature you must specify the file to which the secrets should be written. If you are using TLSv1.3 you must also add `keep_secrets: true` to your pool `:transport_opts`. For example:

```elixir
{Finch,
 name: MyFinch,
 pools: %{
   default: [conn_opts: [transport_opts: [keep_secrets: true]]]
 }}
```

There are two different ways to specify this file:
  1. The `:ssl_key_log_file` connection option in your pool configuration. For example:

```elixir
{Finch,
 name: MyFinch,
 pools: %{
   default: [
     conn_opts: [
       ssl_key_log_file: "/writable/path/to/the/sslkey.log"
     ]
   ]
 }}
```

  2. Alternatively, you could also set the `SSLKEYLOGFILE` environment variable.
```

--------------------------------

### request!/3

Source: https://finch.hexdocs.pm/

Sends an HTTP request and returns a `Finch.Response` struct, raising an exception if the request fails. This is a convenience function that wraps `request/3` and handles error propagation by raising.

```APIDOC
## request!(req, name, opts \\ [])

Sends an HTTP request and returns a `Finch.Response` struct or raises an exception in case of failure.
See `request/3` for more detailed information.
```

--------------------------------

### Send HTTP Request and Raise on Failure

Source: https://finch.hexdocs.pm/

Sends an HTTP request and returns a Finch.Response struct or raises an exception in case of failure. See request/3 for more detailed information.

```Elixir
@spec request!(Finch.Request.t(), name(), request_opts()) :: Finch.Response.t()
```

--------------------------------

### request/3

Source: https://finch.hexdocs.pm/

Sends an HTTP request and returns a `Finch.Response` struct. It handles connection draining for HTTP/2 pools by retrying requests on a fresh pool if the current one is draining. It also supports various options for timeouts and pool strategies.

```APIDOC
## request(req, name, opts \\ [])

Sends an HTTP request and returns a `Finch.Response` struct.
It can still raise exceptions if it was not possible to check out a connection in the given `:pool_timeout`.
See also `stream/5`.

### Connection draining
If the HTTP/2 pool this request is dispatched to is currently draining (see `http2: [max_connection_age: ...]`), the request is automatically retried on a fresh pool. The retry is transparent to the caller. See `async_request/3` for the async variant, which does not retry automatically.

## Options
  * `:pool_timeout` - This timeout is applied when we check out a connection from the pool. Default value is `5_000`.
  * `:receive_timeout` - The maximum time to wait for each chunk to be received before returning an error. Default value is `15_000`.
  * `:request_timeout` - The amount of time to wait for a complete response before returning an error. This timeout only applies to HTTP/1, and its current implementation is a best effort timeout, it does not guarantee the call will return precisely when the time has elapsed. Default value is `:infinity`.
  * `:pool_strategy` - When the pool has multiple shards (`count: N`), selects which shards handles the request. Default is random selection. See `pool_strategy/0` for details.
```

--------------------------------

### Configure Finch to Log TLS Secrets

Source: https://finch.hexdocs.pm/Finch.html

Configures Finch to log TLS secrets for decryption with tools like Wireshark. Requires specifying a file path for the secrets.

```elixir
{Finch,
 name: MyFinch,
 pools: %{
   default: [conn_opts: [transport_opts: [keep_secrets: true]]]
 }}
```

--------------------------------

### Finch.Pool.new/2

Source: https://finch.hexdocs.pm/Finch.Pool.html

Creates a new pool struct from a URL. Supports http, https, http+unix, and https+unix schemes. An optional tag can be provided for the pool.

```APIDOC
## Finch.Pool.new/2

### Description
Creates a new pool struct from a URL. Supports `http://`, `https://`, `http+unix://`, and `https+unix://` schemes.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
`input` - The URL string for the pool.
`opts` - A keyword list of options. Supports `:tag` for the pool tag (defaults to `:default`).

### Request Example
```elixir
# From URL
pool = Finch.Pool.new("https://api.example.com")

# Unix socket pool using URL
pool = Finch.Pool.new("http+unix:///tmp/socket")

# Tagged pool
pool = Finch.Pool.new("http+unix:///tmp/socket", tag: :api)
```

### Response
#### Success Response (200)
- `pool` (Finch.Pool.t()) - A struct representing the connection pool.

#### Response Example
```elixir
%Finch.Pool{host: "api.example.com", port: 443, scheme: :https, tag: :default}
```
```

--------------------------------

### Finch.find_pool/2

Source: https://finch.hexdocs.pm/Finch.html

Finds a pool by its configuration and returns the pool pid.

```APIDOC
## `Finch.find_pool/2`

Finds a pool by its configuration and returns the pool pid.

### Function Signature

`find_pool(name, pool)`

### Parameters

*   `name` (Finch.name()): The name of the Finch instance.
*   `pool` (Finch.Pool.t()): The pool configuration to search for.

### Returns

*   `{:ok, pid}` if the pool is found.
*   `:error` if the pool is not found.
```

--------------------------------

### Finch Request Building

Source: https://finch.hexdocs.pm/

Functions for constructing HTTP requests.

```APIDOC
## Finch Request Building

### `Finch.build/5`

Builds an HTTP request to be sent with `request/3`, `async_request/3`, `stream/5`, or `stream_while/5`.

**Arguments:**

* `method` - The HTTP method (e.g., :get, :post).
* `url` - The URL for the request.
* `headers` - A list of request headers.
* `body` - The request body (can be nil).
* `opts` - Optional arguments for building the request.
```

--------------------------------

### get_pool_status/2

Source: https://finch.hexdocs.pm/Finch.html

Fetches metrics for a specific Finch pool or all pools associated with the `:default` configuration. Metrics include pool size, available connections, and connections in use.

```APIDOC
## get_pool_status/2

### Description
Get pool metrics. When given a URL or pool identifier tuple, this returns the metrics list for that specific pool. The number of items in the metrics list depends on the configured `:count` option and each entry will have a `pool_index` going from 1 to `:count`. When `:default` is provided, Finch returns the metrics for all pools started from the `:default` configuration. In this case the return value is a map keyed by each pool's `{scheme, host, port}` tuple with the corresponding metrics list as the value. The metrics struct depends on the pool scheme defined in the `:protocols` option: `Finch.HTTP1.PoolMetrics` for `:http1` and `Finch.HTTP2.PoolMetrics` for `:http2`. See the documentation for those modules for more details. `{:error, :not_found}` is returned in the following scenarios: There is no pool registered for the given Finch instance and pool identifier. The pool has `start_pool_metrics?: false` (the default). `:default` is provided but no pools have been started from the `:default` configuration (or none have metrics enabled).

### Function Signature
```elixir
@spec get_pool_status(name(), :default | pool_identifier()) :: {:ok, pool_metrics()} | {:ok, default_pool_metrics()} | {:error, :not_found}
```

### Examples
```elixir
iex> Finch.get_pool_status(MyFinch, "https://httpbin.org")
{:ok, [
  %Finch.HTTP1.PoolMetrics{
    pool_index: 1,
    pool_size: 50,
    available_connections: 43,
    in_use_connections: 7
  },
  %Finch.HTTP1.PoolMetrics{
    pool_index: 2,
    pool_size: 50,
    available_connections: 37,
    in_use_connections: 13
  }]
}

iex> Finch.get_pool_status(MyFinch, :default)
{:ok,
 %{
   %Finch.Pool{host: "httpbin.com", port: 443, scheme: :https, tag: :default} => [
     %Finch.HTTP1.PoolMetrics{
       pool_index: 1,
       pool_size: 50,
       available_connections: 43,
       in_use_connections: 7
     }
   ]
 }}
```
```

--------------------------------

### request/3

Source: https://finch.hexdocs.pm/Finch.html

Sends an HTTP request using the provided Finch.Request struct and returns a Finch.Response struct or an error. It supports various options for configuring timeouts and pool strategies.

```APIDOC
## request(req, name, opts \\ [])

@spec request(Finch.Request.t(), name(), request_opts()) ::
  {:ok, Finch.Response.t()} | {:error, error()}

Sends an HTTP request and returns a `Finch.Response` struct. It can still raise exceptions if it was not possible to check out a connection in the given `:pool_timeout`. See also `stream/5`.

### Connection draining
If the HTTP/2 pool this request is dispatched to is currently draining (see `http2: [max_connection_age: ...]`), the request is automatically retried on a fresh pool. The retry is transparent to the caller. See `async_request/3` for the async variant, which does not retry automatically.

### Options
  * `:pool_timeout` - This timeout is applied when we check out a connection from the pool. Default value is `5_000`.
  * `:receive_timeout` - The maximum time to wait for each chunk to be received before returning an error. Default value is `15_000`.
  * `:request_timeout` - The amount of time to wait for a complete response before returning an error. This timeout only applies to HTTP/1, and its current implementation is a best effort timeout, it does not guarantee the call will return precisely when the time has elapsed. Default value is `:infinity`.
  * `:pool_strategy` - When the pool has multiple shards (`count: N`), selects which shards handles the request. Default is random selection. See `pool_strategy/0` for details.
```

--------------------------------

### Finch Headers Type

Source: https://finch.hexdocs.pm/Finch.Request.html

Defines the type for request headers, aliased from Mint.Types.headers.

```elixir
@type headers() :: Mint.Types.headers()
```
Tokens:
Raw