HTTP.FetchOptions (http_fetch v0.9.0)

Options processing and validation for HTTP.fetch/2 requests.

This module handles the conversion of various option formats (maps, keyword lists, structs) into structured options for the internal socket transport. It provides a flexible API that supports both simple and advanced HTTP client configurations.

Options Categories

Options are divided into two main categories:

  1. Request Options - Request-specific settings consumed by the socket transport:

    • timeout - Request timeout in milliseconds
    • connect_timeout - Connection timeout in milliseconds
    • ssl - SSL/TLS options
    • autoredirect - Follow redirects automatically

  2. Compatibility Options - Parsed for source compatibility, but broad legacy-client option parity is intentionally not implemented:

    • socket_opts - Socket-level options

    The socket transport does not implement legacy :httpc options such as proxy_auth, version, relaxed, body_format, full_result, headers_as_is, receiver, or ipv6_host_with_brackets; they are retained only when converting option structs back to keyword lists.

Basic Usage

# Simple options as keyword list
HTTP.fetch("https://api.example.com", [
  method: "POST",
  headers: %{"Content-Type" => "application/json"},
  timeout: 10_000
])

# Complex options with HTTP and client settings
HTTP.fetch("https://api.example.com", [
  method: "GET",
  timeout: 5_000,
  connect_timeout: 2_000,
  ssl: [verify: :verify_peer],
  body_format: :binary
])

Advanced Configuration

# Using options and opts keywords for fine control
HTTP.fetch("https://api.example.com", [
  method: "POST",
  body: "data",
  # Request-specific options
  options: [
    timeout: 10_000,
    connect_timeout: 5_000
  ],
  # Compatibility options
  opts: [
    sync: false,
    body_format: :binary
  ]
])

Flat vs Structured Options

The module supports both flat and structured option formats:

# Flat format (recommended for simplicity)
[method: "POST", timeout: 5_000, body_format: :binary]

# Structured format (for explicit control)
[
  method: "POST",
  options: [timeout: 5_000],
  opts: [body_format: :binary]
]

Both formats are equivalent; the module automatically categorizes options.

Summary

Types

t()

Functions

get_body(fetch_options)

Extracts body from options.

get_content_type(fetch_options)

Extracts content type from options.

get_headers(fetch_options)

Extracts headers from options.

get_method(fetch_options)

Extracts the HTTP method from options.

new(options)

Creates a new FetchOptions struct from various input formats. Supports flat map, keyword list, or existing FetchOptions struct.

to_http_options(options)

Converts FetchOptions to request options.

to_options(options)

Converts FetchOptions to compatibility client options.

Types

t()

@type t() :: %HTTP.FetchOptions{
  autoredirect: boolean() | nil,
  body: any(),
  body_format: atom() | nil,
  connect_timeout: integer() | nil,
  content_type: String.t() | nil,
  full_result: boolean() | nil,
  headers: HTTP.Headers.t(),
  headers_as_is: boolean() | nil,
  ipv6_host_with_brackets: boolean() | nil,
  method: atom(),
  options: keyword(),
  opts: keyword(),
  proxy_auth: tuple() | nil,
  receiver: pid() | function() | tuple() | nil,
  relaxed: boolean() | nil,
  signal: any() | nil,
  socket_opts: list() | nil,
  ssl: list() | nil,
  stream: atom() | tuple() | nil,
  timeout: integer() | nil,
  unix_socket: String.t() | nil,
  version: String.t() | nil
}

Functions

get_body(fetch_options)

@spec get_body(t()) :: any()

Extracts body from options.

get_content_type(fetch_options)

@spec get_content_type(t()) :: String.t() | nil

Extracts content type from options.

get_headers(fetch_options)

@spec get_headers(t()) :: HTTP.Headers.t()

Extracts headers from options.

get_method(fetch_options)

@spec get_method(t()) :: atom()

Extracts the HTTP method from options.

new(options)

@spec new(map() | keyword() | t()) :: t()

Creates a new FetchOptions struct from various input formats. Supports flat map, keyword list, or existing FetchOptions struct.

to_http_options(options)

@spec to_http_options(t()) :: keyword()

Converts FetchOptions to request options.

to_options(options)

@spec to_options(t()) :: keyword()

Converts FetchOptions to compatibility client options.