Attesto.PinnedHTTP (Attesto v2.28.0)

Copy Markdown View Source

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 or nil (default nil).
  • :deadline - absolute System.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

cause()

@type cause() ::
  {:transport, term()}
  | {:http, :http1 | :http2, term()}
  | :deadline_exceeded
  | :too_large
  | :invalid_request

normalized_error()

@type normalized_error() :: {:not_sent | :maybe_sent, cause()}

response()

@type response() :: %{
  status: non_neg_integer(),
  headers: [{binary(), binary()}],
  body: binary()
}

Functions

passive_request(target, opts \\ [])

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

request(target, opts \\ [])

@spec request(
  Attesto.OutboundTarget.screened(),
  keyword()
) :: {:ok, response()} | {:error, normalized_error()}

Runs the request in an isolated process without consuming caller socket messages.

request_inline(target, opts \\ [])

@spec request_inline(
  Attesto.OutboundTarget.screened(),
  keyword()
) :: {:ok, response()} | {:error, normalized_error()}

Runs the request inline, consuming only messages for its own socket.