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
Functions
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
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
.
Returns a specification to start this module under a supervisor.
See Supervisor
.
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 is5_000
.:receive_timeout
- The maximum time to wait for a response before returning an error. Default value is15_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
: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 is10
.:count
- Number of pools to start. The default value is1
.:conn_opts
- These options are passed toMint.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[]
.
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 is5_000
.:receive_timeout
- The maximum time to wait for a response before returning an error. Default value is15_000
.