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.
http_method()
View Sourcehttp_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
.
request(name, method, url, headers \\ [], body \\ nil, opts \\ [])
View Sourcerequest(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 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
: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[]
.