Finch v0.1.1 Finch 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 Finch, you can use the client you have started, by passing the name of your client as the first argument of Finch.request/3,4,5,6:

Finch.request(MyFinch, :get, "https://hex.pm")

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

A body associated with a request.

An HTTP request method represented as an atom() or a String.t().

The :name provided to Finch in start_link/1.

A Uniform Resource Locator, the address of a resource on the Web.

Functions

Returns a specification to start this module under a supervisor.

Sends an HTTP request and returns the response.

Start an instance of Finch.

Link to this section Types

A body associated with a request.

Link to this type

http_method()

View Source
http_method() ::
  :get | :post | :head | :patch | :delete | :options | :put | String.t()

An HTTP request method represented as an atom() or a String.t().

The following atom methods are supported: :get, :post, :put, :patch, :delete, :head, :options. You can use any arbitrary method by providing it as a String.t().

The :name provided to Finch in start_link/1.

A Uniform Resource Locator, the address of a resource on the Web.

Link to this section Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

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

View Source
request(name(), http_method(), url(), Mint.Types.headers(), body(), keyword()) ::
  {:ok, Finch.Response.t()} | {:error, Mint.Types.error()}

Sends an HTTP request and returns the response.

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.

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

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