Finch
Finch v0.13.0

View Source Finch (Finch v0.13.0)

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

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

usage

 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 by default, if you need to terminate them after some idle time, use the pool_max_idle_time option (available only for HTTP1 pools).

telemetry

 Telemetry

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

logging-tls-secrets

 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:

  1. 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"
     ]
   ]
 }}
  1. 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, opts \\ [])

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.

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

Link to this type

name()

View Source 
@type name() :: atom()

The :name provided to Finch in start_link/1.

Link to this type

stream(acc)

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

The stream function given to stream/5.

Link to this section Functions

Link to this function

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

View Source 
@spec build(
  Finch.Request.method(),
  Finch.Request.url(),
  Finch.Request.headers(),
  Finch.Request.body(),
  Keyword.t()
) :: Finch.Request.t()

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

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.

Link to this function

child_spec(init_arg)

View Source

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

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

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

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

options

 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.

Link to this function

start_link(opts)

View Source

Start an instance of Finch.

options

 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, a tuple {scheme, {:local, unix_socket}} where unix_socket is the path for the socket, 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

 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.

  • :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 [].

  • :pool_max_idle_time - The maximum number of milliseconds that a pool can be idle before being terminated, used only by HTTP1 pools. This options is forwarded to NimblePool and it starts and idle verification cycle that may impact performance if misused. For instance setting a very low timeout may lead to pool restarts. For more information see NimblePool's handle_ping/2 documentation. The default value is :infinity.

  • :conn_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.

Link to this function

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

View Source 
@spec 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

 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

 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.