View Source Finch (Finch v0.15.0)
An HTTP client with a focus on performance, built on top of Mint and NimblePool.
We try to achieve this goal by providing efficient connection pooling strategies and avoiding copying wherever possible.
usage
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 by default, if you need to
terminate them after some idle time, use the pool_max_idle_time
option (available only for HTTP1 pools).
telemetry
Telemetry
Finch uses Telemetry to provide instrumentation. See the Finch.Telemetry
module for details on specific events.
logging-tls-secrets
Logging TLS Secrets
Finch supports logging TLS secrets to a file. These can be later used in a tool such as
Wireshark to decrypt HTTPS sessions. To use this feature you must specify the file to
which the secrets should be written. If you are using TLSv1.3 you must also add
keep_secrets: true
to your pool :transport_opts
. For example:
{Finch,
name: MyFinch,
pools: %{
default: [conn_opts: [transport_opts: [keep_secrets: true]]]
}}
There are two different ways to specify this file:
- The
:ssl_key_log_file
connection option in your pool configuration. For example:
{Finch,
name: MyFinch,
pools: %{
default: [
conn_opts: [
ssl_key_log_file: "/writable/path/to/the/sslkey.log"
]
]
}}
- Alternatively, you could also set the
SSLKEYLOGFILE
environment variable.
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
@type name() :: atom()
The :name
provided to Finch in start_link/1
.
@type stream(acc) :: ({:status, integer()} | {:headers, Mint.Types.headers()} | {:data, binary()}, acc -> acc)
The stream function given to stream/5
.
Link to this section Functions
@spec build( Finch.Request.method(), Finch.Request.url(), Finch.Request.headers(), Finch.Request.body(), Keyword.t() ) :: Finch.Request.t()
Builds an HTTP request to be sent with request/3
or stream/4
.
It is possible to send the request body in a streaming fashion. In order to do so, the
body
parameter needs to take form of a tuple {:stream, body_stream}
, where body_stream
is a Stream
.
Returns a specification to start this module under a supervisor.
See Supervisor
.
@spec request(Finch.Request.t(), name(), keyword()) :: {:ok, Finch.Response.t()} | {:error, Exception.t()}
Sends an HTTP request and returns a Finch.Response
struct.
options
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
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, a tuple{scheme, {:local, unix_socket}}
whereunix_socket
is the path for the socket, 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: 50, count: 1]}
.
pool-configuration-options
Pool Configuration Options
:protocol
- The type of connection and pool to use. The default value is:http1
.:size
(pos_integer/0
) - Number of connections to maintain in each pool. Used only by HTTP1 pools since HTTP2 is able to multiplex requests through a single connection. In other words, for HTTP2, the size is always 1 and the:count
should be configured in order to increase capacity. The default value is50
.:count
(pos_integer/0
) - Number of pools to start. HTTP1 pools are able to re-use connections in the same pool and establish new ones only when necessary. However, if there is a high pool count and few requests are made, these requests will be scattered across pools, reducing connection reuse. It is recommended to increase the pool count for HTTP1 only if you are experiencing high checkout times. The default value is1
.:max_idle_time
(timeout/0
) - The maximum number of milliseconds an HTTP1 connection is allowed to be idle before being closed during a checkout attempt.:conn_opts
(keyword/0
) - 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[]
.:pool_max_idle_time
(timeout/0
) - The maximum number of milliseconds that a pool can be idle before being terminated, used only by HTTP1 pools. This options is forwarded to NimblePool and it starts and idle verification cycle that may impact performance if misused. For instance setting a very low timeout may lead to pool restarts. For more information see NimblePool'shandle_ping/2
documentation. The default value is:infinity
.:conn_max_idle_time
(timeout/0
) - The maximum number of milliseconds an HTTP1 connection is allowed to be idle before being closed during a checkout attempt. The default value is:infinity
.
@spec stream(Finch.Request.t(), name(), acc, stream(acc), keyword()) :: {:ok, acc} | {:error, Exception.t()} 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
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
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
.