Production reliability layer for Elixir HTTP clients. Adds reliability patterns and enterprise features on top of Finch, Req, or Tesla through an adapter system.

HTTPower supports multiple HTTP clients via adapters — Finch (high-performance, default), Req (batteries-included), and Tesla (bring-your-own-config) — while providing production reliability features that work consistently across all of them:

• Adapter pattern: Choose between Finch, Req, or Tesla HTTP clients
• Middleware pipeline: Rate limiting, circuit breaker, and request deduplication
• Smart retries: Exponential backoff with jitter and Retry-After header support
• PCI-compliant logging: Automatic sanitization of sensitive data with structured metadata
• Telemetry integration: Comprehensive observability for all operations
• Configuration profiles: Pre-built profiles for payment processing, high-volume APIs, and microservices
• Clean error handling: Never raises exceptions, always returns {:ok, response} or {:error, reason}
• Test utilities: Adapter-agnostic test helpers via HTTPower.Test

Basic Usage

# Simple GET request
HTTPower.get("https://api.example.com/users")

# POST with JSON body
HTTPower.post("https://api.example.com/users",
  json: %{name: "Alice", email: "alice@example.com"})

# POST with form data
HTTPower.post("https://api.example.com/login",
  form: [username: "alice", password: "secret"])

# POST with raw body
HTTPower.post("https://api.example.com/upload",
  body: raw_bytes,
  headers: %{"Content-Type" => "application/octet-stream"})

# Skip response decoding
HTTPower.get("https://api.example.com/data", raw: true)

# With configuration options
HTTPower.get("https://api.example.com/slow-endpoint",
  timeout: 30,
  max_retries: 5,
  retry_safe: true
)

Test Mode

HTTPower can block real HTTP requests during testing while allowing mocked requests:

# In test configuration
Application.put_env(:httpower, :test_mode, true)

# This will be blocked
HTTPower.get("https://real-api.com")  # {:error, %HTTPower.Error{reason: :network_blocked}}

# But this will work with Req.Test
HTTPower.get("https://api.com", plug: {Req.Test, MyApp})

Configuration Options

• timeout - Request timeout in seconds (default: 60)
• max_retries - Maximum retries after initial attempt (default: 3)
• retry_safe - Enable retries for connection resets (default: false)
• ssl_verify - Enable SSL verification (default: true)
• proxy - Proxy configuration (default: :system)
• headers - Request headers map
• json - Data to encode as JSON request body (sets Content-Type and Accept headers)
• form - Data to encode as form-urlencoded request body (keyword list or map, flat only)
• params - Query parameters to append to the URL (keyword list or map, flat only)
• raw - Skip automatic response body decoding when true (default: false)

Return Values

All HTTP methods return either:

• {:ok, %HTTPower.Response{}} - an HTTP response was received (any status code)
• {:error, %HTTPower.Error{}} - a transport/network error occurred

Important: {:ok, response} means the server responded, not that the request "succeeded" in a business logic sense. This includes 4xx and 5xx responses. After retries are exhausted for retryable status codes (500, 502, 503, 504), the final server response is still returned as {:ok, response}. Always check response.status to determine the HTTP outcome:

case HTTPower.get("https://api.example.com/users") do
  {:ok, %{status: status}} when status in 200..299 ->
    # Success
  {:ok, %{status: status} = response} ->
    # Server responded with non-2xx (including 5xx after retries exhausted)
  {:error, %HTTPower.Error{reason: reason}} ->
    # Transport error (timeout, connection refused, etc.)
end

HTTPower never raises exceptions for HTTP operations, ensuring your application stays stable even when external services fail. Configuration errors (such as passing an unknown profile to new/1) raise ArgumentError at client construction time, following standard Elixir conventions.

Configured Clients

You can create pre-configured client instances for reuse:

# Create a configured client
client = HTTPower.new(
  base_url: "https://api.example.com",
  headers: %{"Authorization" => "Bearer token"},
  timeout: 30,
  max_retries: 5
)

# Use the client for multiple requests
HTTPower.get(client, "/users")
HTTPower.post(client, "/users", json: %{name: "John"})

This is especially useful for API clients, different environments, or service-specific configuration.