Finch (Finch v0.4.0) 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.

Link to this section Summary

Types

The :name provided to Finch in start_link/1.

The stream function given to stream/5.

Functions

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

Returns a specification to start this module under a supervisor.

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

Start an instance of Finch.

Streams an HTTP request and returns the accumulator.

Link to this section Types

Specs

name() :: atom()

The :name provided to Finch in start_link/1.

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

Link to this function

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

View Source

Specs

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

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

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

View Source

Specs

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

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.

Link to this function

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

View Source

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: 10, 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. The default value is 10.

  • :count - Number of pools to start. The default value is 1.

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

Link to this function

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

View Source

Specs

stream(Finch.Request.t(), name(), acc, stream(acc), keyword()) :: acc
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.