Behaviour for HTTPower adapters.

Adapters are responsible for making the actual HTTP requests using a specific HTTP client library (Req, Tesla, etc.). HTTPower's features like retry logic, circuit breakers, and rate limiting sit above the adapter layer.

Implementing an Adapter

To implement an adapter, create a module that implements the request/5 callback:

defmodule MyApp.CustomAdapter do
  @behaviour HTTPower.Adapter

  @impl true
  def request(method, url, body, headers, opts) do
    # Make HTTP request using your preferred HTTP client
    # Convert response to {:ok, %HTTPower.Response{}} or {:error, reason}
  end
end

Built-in Adapters

HTTPower ships with three built-in adapters:

• HTTPower.Adapter.Finch - Uses Finch HTTP client, built on Mint + NimblePool (default)
• HTTPower.Adapter.Req - Uses Req HTTP client (batteries-included)
• HTTPower.Adapter.Tesla - Uses Tesla HTTP client (bring-your-own-config)

Using an Adapter

Specify the adapter when making requests:

# Use default (Finch) adapter
HTTPower.get("https://api.example.com")

# Use explicit Req adapter
HTTPower.get("https://api.example.com", adapter: HTTPower.Adapter.Req)

# Use Tesla adapter with your Tesla client
tesla_client = Tesla.client([Tesla.Middleware.JSON])
HTTPower.get("https://api.example.com",
  adapter: {HTTPower.Adapter.Tesla, tesla_client})

Adapter Contract

Adapters must return responses in a standardized format:

• Success: {:ok, %HTTPower.Response{status: integer(), headers: %{String.t() => [String.t()]}, body: binary() | nil}}. Headers are always list-valued (see normalize_response_headers/1); the body is the raw, undecoded payload — HTTPower.Codec decodes it above the adapter layer.
• Failure: {:error, reason} where reason is a bare atom (transport failures via unwrap_transport_error/1; usage errors like :missing_tesla_client). HTTPower wraps it into an %HTTPower.Error{} at the retry boundary (HTTPower.Retry), so the adapter never builds the error struct itself.

HTTPower's retry logic and error handling work consistently across all adapters.

Connection Options (Uniform Vocabulary)

HTTPower keeps a uniform connection vocabulary — timeout:, ssl_verify:, proxy: — so callers write HTTPower's terms, never a backend's dialect. These options arrive in opts untouched, and the adapter maps them onto its backend wherever the backend accepts them:

• Req honors all three per request.
• Finch honors timeout: (and pool_timeout:) per request; TLS and proxy are fixed at pool start (config :httpower, :finch_pools), so per-request ssl_verify:/proxy: have no effect.
• Tesla defers all three to the user's Tesla client.

This bounded leak is the accepted contract: an adapter that cannot honor an option per request must say so in its moduledoc and point at where its backend fixes the setting — never silently approximate it. Custom adapters should follow the same rule. timeout: is expressed in seconds; the adapter converts to its backend's unit.