Repository files navigation

An HTTP client with a focus on performance, built on top ofMint andNimblePool.

We attempt to achieve this goal by providing efficient connection pooling strategies and avoiding copying of memory wherever possible.

Most developers will most likely prefer to use the fabulous HTTP clientReq which takes advantage of Finch's pooling and provides an extremely friendly and pleasant to use API.

In order to use Finch, you must start it and provide a:name. Often in yoursupervision 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} youinteract with.

You can also configure a pool size and count to be used for specific URLs that areknown before starting Finch. The passed URLs will be parsed into{scheme, host, port},and the corresponding pools will be started. SeeFinch.start_link/1 for configurationoptions.

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 timeit is requested. Note pools are not automatically terminated by default, if you need toterminate them after some idle time, use thepool_max_idle_time option (available only for HTTP1 pools).

Finch uses Telemetry to provide instrumentation. See theFinch.Telemetrymodule for details on specific events.

Finch supports logging TLS secrets to a file. These can be later used in a tool such asWireshark to decrypt HTTPS sessions. To use this feature you must specify the file towhich the secrets should be written. If you are using TLSv1.3 you must also addkeep_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:

1. 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"]]}}

2. Alternatively, you could also set theSSLKEYLOGFILE environment variable.

The package can be installed by addingfinch to your list of dependencies inmix.exs:

defdepsdo[{:finch,"~> 0.19"}]end

The docs can be found athttps://hexdocs.pm/finch.