Bounded HTTP requests to an Attesto.OutboundTarget.screen/2 result.
All entry points take the screened target and a keyword list. Connections use only its IP tuples, in order, cycling if necessary; no DNS lookup is performed here. TLS SNI, peer verification and the Host header use the original host and authority. Connections are closed after each response.
Options shared by all three entry points:
:method- HTTP method (default:get).:headers- header pairs (default[]); Host is set from the target.:body- iodata ornil(defaultnil).:deadline- absoluteSystem.monotonic_time(:millisecond)deadline for the entire request (default: 15 seconds from entry).:receive_timeout- streaming idle-read timeout in milliseconds (default:infinity), capped by the remaining deadline.:body_limit- maximum response bytes (default 1 MiB), or:discard.:connect_timeout- milliseconds per connection attempt (default 3,000), always capped by the remaining deadline.:max_attempts- positive attempt bound (default 3).:connect_options- TLS trust/client certificates in:transport_opts,:protocols(default[:http1]) and:client_settings. Destination, peer verification, SNI, socket callbacks and timeouts cannot be replaced.:on_request- zero-arity callback immediately before calling Mint's request function, for a supervising deadline to mark uncertain delivery. It must return promptly. Default: no callback.
Only connection establishment (TCP and TLS handshake) is retried, on a
fresh socket. After Mint.HTTP.request/5 is called nothing is retried,
including POSTs and errors returned by that function.
{:error, {:not_sent, cause}} guarantees the request function was never
called. Causes are normalized Mint errors ({:transport, reason} or
{:http, protocol, reason}), :deadline_exceeded, or :invalid_request.
An exhausted deadline during connect returns :deadline_exceeded; otherwise
the last failed attempt supplies the cause. Invalid input is never retried.
Every entry point returns {:error, {:not_sent, cause}} before that
boundary or {:error, {:maybe_sent, cause}} after it. Both use the same
causes: {:transport, reason}, {:http, protocol, reason},
:deadline_exceeded, :too_large, and :invalid_request. No Mint error
struct is returned. Exceptions and caught exits/throws are guarded and
classified at the same boundary; unexpected failures are transport causes.
Summary
Functions
Streams a passive response. Requires :on_head (status, headers -> acc) and
:on_data (data, acc -> {:cont, acc} or {:halt, acc}) options.
Returns {:ok, acc} on completion or callback halt. :discard skips data
callbacks. The body limit and absolute deadline still apply to the stream.
Runs the request in an isolated process without consuming caller socket messages.
Runs the request inline, consuming only messages for its own socket.
Types
@type normalized_error() :: {:not_sent | :maybe_sent, cause()}
@type response() :: %{ status: non_neg_integer(), headers: [{binary(), binary()}], body: binary() }
Functions
@spec passive_request( Attesto.OutboundTarget.screened(), keyword() ) :: {:ok, term()} | {:error, normalized_error()}
Streams a passive response. Requires :on_head (status, headers -> acc) and
:on_data (data, acc -> {:cont, acc} or {:halt, acc}) options.
Returns {:ok, acc} on completion or callback halt. :discard skips data
callbacks. The body limit and absolute deadline still apply to the stream.
@spec request( Attesto.OutboundTarget.screened(), keyword() ) :: {:ok, response()} | {:error, normalized_error()}
Runs the request in an isolated process without consuming caller socket messages.
@spec request_inline( Attesto.OutboundTarget.screened(), keyword() ) :: {:ok, response()} | {:error, normalized_error()}
Runs the request inline, consuming only messages for its own socket.