Finch (Finch v0.8.2) View Source

An HTTP client with a focus on performance, built on top of Mint and NimblePool.

Usage

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

children = [
  {Finch, name: MyFinch}
]

Or, in rare cases, dynamically:

Finch.start_link(name: MyFinch)

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

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.

children = [
  {Finch,
   name: MyConfiguredFinch,
   pools: %{
     :default => [size: 10],
     "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. Note pools are not automatically terminated if they are unused, so Finch is best suited when you are requesting a known list of static hosts.

Telemetry

Finch uses Telemetry to provide instrumentation. See the Finch.Telemetry module for details on specific events.

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:

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

There are two different ways to specify this file:

The :ssl_key_log_file connection option in your pool configuration. For example:

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

Alternatively, you could also set the SSLKEYLOGFILE environment variable.

Link to this section Summary

Types

name()

The :name provided to Finch in start_link/1.

stream(acc)

The stream function given to stream/5.

Functions

build(method, url, headers \\ [], body \\ nil)

Builds an HTTP request to be sent with request/3 or stream/4.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

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

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

request(name, method, url, headers, body \\ nil, opts \\ [])

start_link(opts)

Start an instance of Finch.

stream(req, name, acc, fun, opts \\ [])

Streams an HTTP request and returns the accumulator.

Link to this section Types

name()

Specs

name() :: atom()

The :name provided to Finch in start_link/1.

stream(acc)

Specs

stream(acc) ::
  ({:status, integer()}
   | {:headers, Mint.Types.headers()}
   | {:data, binary()},
   acc ->
     acc)

The stream function given to stream/5.

Link to this section Functions

build(method, url, headers \\ [], body \\ nil)

Specs

build(
  Finch.Request.method(),
  Finch.Request.url(),
  Finch.Request.headers(),
  Finch.Request.body()
) :: Finch.Request.t()

Builds an HTTP request to be sent with request/3 or stream/4.

When making HTTP/1.x requests, it is possible to send the request body in a streaming fashion. In order to do so, the body parameter needs to take form of a tuple {:stream, body_stream}, where body_stream is a Stream. This feature is not yet supported for HTTP/2 requests.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

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

Specs

request(Finch.Request.t(), name(), keyword()) ::
  {:ok, Finch.Response.t()} | {:error, Exception.t()}

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

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 a response before returning an error. Default value is 15_000.

request(name, method, url, headers, body \\ nil, opts \\ [])

start_link(opts)

Start an instance of Finch.

Options

:name - The name of your Finch instance. This field is required.
:pools - A map specifying the configuration for your pools. The keys should be URLs provided as binaries, or the atom :default to provide a catch-all configuration to be used for any unspecified URLs. See "Pool Configuration Options" below for details on the possible map values. Default value is %{default: [size: 50, count: 1]}.

Pool Configuration Options

:protocol - The type of connection and pool to use. The default value is :http1.
:size - Number of connections to maintain in each pool. Used only by HTTP1 pools since HTTP2 is able to multiplex requests through a single connection. In other words, for HTTP2, the size is always 1 and the :count should be configured in order to increase capacity. The default value is 50.
:count - Number of pools to start. HTTP1 pools are able to re-use connections in the same pool and establish new ones only when necessary. However, if there is a high pool count and few requests are made, these requests will be scattered across pools, reducing connection reuse. It is recommended to increase the pool count for HTTP1 only if you are experiencing high checkout times. The default value is 1.
:max_idle_time - The maximum number of milliseconds an HTTP1 connection is allowed to be idle before being closed during a checkout attempt. The default value is :infinity.
:conn_opts - These options are passed to Mint.HTTP.connect/4 whenever a new connection is established. :mode is not configurable as Finch must control this setting. Typically these options are used to configure proxying, https settings, or connect timeouts. The default value is [].

stream(req, name, acc, fun, opts \\ [])

Specs

stream(Finch.Request.t(), name(), acc, stream(acc), keyword()) ::
  {:ok, acc} | {:error, Exception.t()}
when acc: term()

Streams an HTTP request and returns the accumulator.

A function of arity 2 is expected as argument. The first argument is a tuple, as listed below, and the second argument is the accumulator. The function must return a potentially updated accumulator.

Stream commands

{:status, status} - the status of the http response
{:headers, headers} - the headers of the http response
{:data, data} - a streaming section of the http body

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 a response before returning an error. Default value is 15_000.