AshHooks.Http.Httpc (AshHooks v3.3.0)

Copy Markdown View Source

An AshHooks.Http adapter built on OTP's :httpc.

The adapter resolves and validates the destination, pins the connection address, and preserves the original hostname for TLS certificate verification, SNI, and the Host header. Redirects are returned without following them. TLS uses the OTP CA store unless cacerts: der_list supplies a private CA bundle. The operation deadline covers DNS, connection, send, and response collection; connection also has a separate, shorter ceiling.

This adapter does not export send_prepared/2. Raw-listener qualification found that :httpc normalizes percent escapes in the signed request target, so it cannot promise exact prepared bytes. Use AshHooks.Http.Bounded for endpoints declaring a host signer.

Response retention is capped by max_body_bytes (64 KiB by default). OTP streams 200 and 206 responses, so this adapter cancels collection at that limit. Other statuses are buffered inside :httpc before the adapter can truncate them. Use the default AshHooks.Http.Bounded adapter when the allocation of an untrusted error response must also be bounded. OTP's streaming interface does not distinguish 206 from 200; both are reported as 200 by this adapter and classified as successful delivery.

HTTPS URLs with literal IP hosts return {:error, :ip_literal_https_needs_bounded}. Use AshHooks.Http.Bounded for those endpoints: it can inspect the socket certificate's IP subject alternative name as well as validate its certificate chain.

Summary

Functions

Sends one request with an atom or case-insensitive method string, URL, binary header map, and binary body (nil means empty).

Functions

request(method, url, headers, body, opts \\ [])

@spec request(atom(), String.t(), map(), binary() | nil, keyword()) ::
  {:ok, %{status: integer(), headers: list(), body: binary() | nil}}
  | {:error, term()}

Sends one request with an atom or case-insensitive method string, URL, binary header map, and binary body (nil means empty).

Options are :timeout (15,000 ms for the whole operation), :connect_timeout (5,000 ms), :max_body_bytes (65,536 retained bytes), and :cacerts (DER certificates; defaults to the OTP CA store). validate_destination: false bypasses public-address validation and is intended only for controlled tests; keep validation enabled for untrusted URLs.

Only 200 and 206 response collection can stop at the body cap; other statuses buffer inside :httpc before truncation. Streamed 206 is reported as 200. Literal-IP HTTPS returns {:error, :ip_literal_https_needs_bounded}.

Returns {:ok, %{status: status, headers: header_pairs, body: bytes}} or {:error, reason} for invalid input, destination refusal, TLS, transport, timeout, or response framing failures. Redirects are returned without following.