Finch (Finch v0.9.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.
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_fileconnection 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
SSLKEYLOGFILEenvironment 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
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
Builds an HTTP request to be sent with request/3 or stream/4.
When making HTTP/1.x requests, 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. This feature is not yet supported for HTTP/2 requests.
Returns a specification to start this module under a supervisor.
See Supervisor.
Specs
request(Finch.Request.t(), name(), keyword()) :: {:ok, Finch.Response.t()} | {:error, Exception.t()}
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, a tuple{scheme, {:local, unix_socket}}whereunix_socketis the path for the socket, 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: 50, 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. 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:countshould be configured in order to increase capacity. The default value is50.:count- 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- 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.: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()) :: {: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
{: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.