Run at most concurrency requests at once, 1 to 1,024, over at most 10,000 requests. Results keep input order, and a failure occupies only its own position. Bodies retained across results are bounded by config.with_max_batch_bytes: once reached, the response being collected fails and requests not yet sent fail with LimitExceeded(BatchBytes, ..) and NotSent.

The correlation this view tags its events with, set by with_correlation, or None. A library that receives a caller’s view reads the caller’s correlation here and copies it into its own telemetry, instead of asking the caller to pass it twice:

let correlation = http_gun.correlation(client)

The handle of the client registered under name by supervised. Pure: it does not check that the client is running.

Open a response whose body the calling process reads. Close the body when done, even after reading it to the end; prefer with_response when the response fits inside one callback.

Send a request and collect its response, up to the body limit. An oversized body fails with LimitExceeded(ResponseBodyBytes, ..), the response status and its headers, unless the view chose Truncate. Every failure after the head arrived keeps the status (error.status) and the headers after the client’s redaction (error.headers). The body is closed on every path.

Validate the configuration, then start a client with its own connection pool, linked to the caller.

Read the pool’s counters. Holds no request history or credentials.

Refuse new requests, fail queued ones with ClientClosed and NotSent, let active HTTP exchanges finish within the shutdown timeout, then cancel them and close every connection. Stopping ends access to retained response bodies, including unread bytes after HTTP EOF. Callers needing old application results must await and consume them before stopping the client.

Returns when the client has stopped; stopping a stopped client returns at once. Meant for clients from start: a supervisor restarts a supervised client that stops.

A child specification for a supervisor. The client registers under name, so named(name) reaches it across restarts. An invalid configuration fails the child’s start.

let name = process.new_name("http_client")
let assert Ok(_) =
  static_supervisor.new(static_supervisor.OneForOne)
  |> static_supervisor.add(http_gun.supervised(config.default(), name))
  |> static_supervisor.start
let client = http_gun.named(name)

Add an independent cancellation token while retaining this view’s tokens. Cancellation by any retained token ends unfinished requests through this view. Adding the same token twice has no additional effect. This pure view operation starts no process, changes no other view and never cancels a token.

Collect at most bytes of each response body in send and batch through this view, replacing config.with_max_response_body_bytes, and choose what happens past the limit. A negative limit fails each request with InvalidRequest(InvalidBodyLimit) before it is sent.

Replace this view’s cancellation tokens with token. Unfinished requests through the resulting view cancel when that token is cancelled. Other views and tokens remain unchanged. Cancellation never enters cassette matching.

Tag the lifecycle events of requests made through this view with the caller’s correlation, under the correlation metadata key, so they join the events of other packages working on the same unit. Every request still gets its own request_id. A later call replaces the correlation.

End every request made through this view by an absolute deadline shared across calls. It replaces the client’s request timeout; combined with with_timeout, the earlier of the two applies.

Narrow the destinations of this view: a request must satisfy the client’s policy and every policy added this way, including the addresses of a pooled connection it would reuse. A view can never widen what the client admits; host name resolution stays the client’s.

A client configured with config.require_view_destination refuses requests through a view unless one of its policies chooses a destination: it sets destination.only_hosts, or it refuses an address class the client admits. A policy that admits everything the client admits and only tightens destination.with_plaintext chooses none, so a library that tightens the scheme on a caller’s view never lifts the application’s requirement:

// A library: tightens the scheme, chooses no destination.
let scheme =
  destination.default()
  |> destination.allow_loopback
  |> destination.allow_private
  |> destination.with_plaintext(destination.PlaintextToLoopbackOnly)
client |> http_gun.with_destination(scheme)

Replace the client’s idle timeout for this view: the longest gap without bytes while the response’s owner waits for its head or reads its body. Use it for a model that thinks before its first token, or a stream with sparse keepalives.

Open a response, run run with it and close the body when run returns or raises. on_failure maps an opening failure into the callback’s error type:

use response <- http_gun.with_response(client, req, AppHttpError)
read_events(response.body)

Bound each request made through this view from admission to its last byte, replacing the client’s request timeout, shorter or longer. config.Infinity lifts the bound for a long-lived stream; the connect, pool and idle timeouts still apply.