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:defaultto 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/4whenever a new connection is established.:modeis 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.