@spec async_request(Finch.Request.t(), name(), request_opts()) :: request_ref()

Sends an HTTP request asynchronously, returning a request reference.

If the request is sent using HTTP1, an extra process is spawned to consume messages from the underlying socket. The messages are sent to the current process as soon as they arrive, as a firehose. If you wish to maximize request rate or have more control over how messages are streamed, a strategy using request/3 or stream/5 should be used instead.

Receiving the response

Response information is sent to the calling process as it is received in {ref, response} tuples.

If the calling process exits before the request has completed, the request will be canceled.

Responses include:

• {:status, status} - HTTP response status
• {:headers, headers} - HTTP response headers
• {:data, data} - section of the HTTP response body
• {:error, exception} - an error occurred during the request
• :done - request has completed successfully

On a successful request, a single :status message will be followed by a single :headers message, after which more than one :data messages may be sent. If trailing headers are present, a final :headers message may be sent. Any :done or :error message indicates that the request has succeeded or failed and no further messages are expected.

Example

iex> req = Finch.build(:get, "https://httpbin.org/stream/5")
iex> ref = Finch.async_request(req, MyFinch)
iex> flush()
{ref, {:status, 200}}
{ref, {:headers, [...]}}
{ref, {:data, "..."}}
{ref, :done}

Options

Shares options with request/3.

@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.

@spec cancel_async_request(request_ref()) :: :ok

Cancels a request sent with async_request/3.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec get_pool_status(name(), url :: String.t() | scheme_host_port()) ::
  {:ok, [Finch.HTTP1.PoolMetrics.t()]}
  | {:ok, [Finch.HTTP2.PoolMetrics.t()]}
  | {:error, :not_found}

Get pool metrics list.

The number of items present on the metrics list depends on the :count option each metric will have a pool_index going from 1 to :count.

The metrics struct depends on the pool scheme defined on the :protocols option Finch.HTTP1.PoolMetrics for :http1 and Finch.HTTP2.PoolMetrics for :http2.

See the Finch.HTTP1.PoolMetrics and Finch.HTTP2.PoolMetrics for more details.

{:error, :not_found} may return on 2 scenarios:

• There is no pool registered for the given pair finch instance and url
• The pool is configured with start_pool_metrics? option false (default)

Example

iex> Finch.get_pool_status(MyFinch, "https://httpbin.org")
{:ok, [
  %Finch.HTTP1.PoolMetrics{
    pool_index: 1,
    pool_size: 50,
    available_connections: 43,
    in_use_connections: 7
  },
  %Finch.HTTP1.PoolMetrics{
    pool_index: 2,
    pool_size: 50,
    available_connections: 37,
    in_use_connections: 13
  }]
}

@spec request(Finch.Request.t(), name(), request_opts()) ::
  {: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 is 5_000.

• :receive_timeout - The maximum time to wait for each chunk to be received before returning an error. Default value is 15_000.

• :request_timeout - The amount of time to wait for a complete response before returning an error. This timeout only applies to HTTP/1, and its current implementation is a best effort timeout, it does not guarantee the call will return precisely when the time has elapsed. Default value is :infinity.

@spec request!(Finch.Request.t(), name(), request_opts()) :: Finch.Response.t()

Sends an HTTP request and returns a Finch.Response struct or raises an exception in case of failure.

See request/3 for more detailed information.

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}} where unix_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

• :protocol

• :protocols - The type of connections to support.

  If using :http1 only, an HTTP1 pool without multiplexing is used. If using :http2 only, an HTTP2 pool with multiplexing is used. If both are listed, then both HTTP1/HTTP2 connections are supported (via ALPN), but there is no multiplexing.

  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 is 50.

• :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 is 1.

• :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 to Mint.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's handle_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.

• :start_pool_metrics? (boolean/0) - When true, pool metrics will be collected and available through Finch.pool_status/2 The default value is false.

@spec stream(Finch.Request.t(), name(), acc, stream(acc), request_opts()) ::
  {: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.

See also stream_while/5.

HTTP2 streaming and back-pressure

At the moment, streaming over HTTP2 connections do not provide any back-pressure mechanism: this means the response will be sent to the client as quickly as possible. Therefore, you must not use streaming over HTTP2 for non-terminating responses or when streaming large responses which you do not intend to keep in memory.

Stream commands

• {:status, status} - the http response status
• {:headers, headers} - the http response headers
• {:data, data} - a streaming section of the http response body
• {:trailers, trailers} - the http response trailers

Options

Shares options with request/3.

Examples

path = "/tmp/archive.zip"
file = File.open!(path, [:write, :exclusive])
url = "https://example.com/archive.zip"
request = Finch.build(:get, url)

Finch.stream(request, MyFinch, nil, fn
  {:status, status}, _acc ->
    IO.inspect(status)

  {:headers, headers}, _acc ->
    IO.inspect(headers)

  {:data, data}, _acc ->
    IO.binwrite(file, data)
end)

File.close(file)

@spec stream_while(Finch.Request.t(), name(), acc, stream_while(acc), request_opts()) ::
  {:ok, acc} | {:error, Exception.t()}
when acc: term()

Streams an HTTP request until it finishes or fun returns {:halt, acc}.

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:

• {:cont, acc} to continue streaming
• {:halt, acc} to halt streaming

See also stream/5.

HTTP2 streaming and back-pressure

At the moment, streaming over HTTP2 connections do not provide any back-pressure mechanism: this means the response will be sent to the client as quickly as possible. Therefore, you must not use streaming over HTTP2 for non-terminating responses or when streaming large responses which you do not intend to keep in memory.

Stream commands

• {:status, status} - the http response status
• {:headers, headers} - the http response headers
• {:data, data} - a streaming section of the http response body
• {:trailers, trailers} - the http response trailers

Options

Shares options with request/3.

Examples

path = "/tmp/archive.zip"
file = File.open!(path, [:write, :exclusive])
url = "https://example.com/archive.zip"
request = Finch.build(:get, url)

Finch.stream_while(request, MyFinch, nil, fn
  {:status, status}, acc ->
    IO.inspect(status)
    {:cont, acc}

  {:headers, headers}, acc ->
    IO.inspect(headers)
    {:cont, acc}

  {:data, data}, acc ->
    IO.binwrite(file, data)
    {:cont, acc}
end)

File.close(file)