HTTP.FetchOptions (http_fetch v0.8.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 :httpc.request/4. It provides a flexible API that supports both simple and advanced HTTP client configurations.

Options Categories

Options are divided into two main categories:

  1. HTTP Options (3rd argument to :httpc.request/4) - Request-specific settings:

    • timeout - Request timeout in milliseconds
    • connect_timeout - Connection timeout in milliseconds
    • ssl - SSL/TLS options
    • autoredirect - Follow redirects automatically
    • proxy_auth - Proxy authentication
    • version - HTTP version
    • relaxed - Relaxed parsing mode

  2. Client Options (4th argument to :httpc.request/4) - Client behavior settings:

    • sync - Synchronous/asynchronous mode (default: false)
    • stream - Response streaming configuration
    • body_format - Response body format (:string or :binary)
    • full_result - Return full HTTP response
    • headers_as_is - Preserve header case
    • socket_opts - Socket-level options
    • receiver - Custom receiver process
    • ipv6_host_with_brackets - IPv6 host formatting

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 (3rd arg to :httpc.request)
  options: [
    timeout: 10_000,
    connect_timeout: 5_000
  ],
  # Client-specific options (4th arg to :httpc.request)
  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 HTTP options for :httpc.request 3rd argument. Returns keyword list of HttpOptions.

to_options(options)

Converts FetchOptions to options for :httpc.request 4th argument. Returns keyword list of 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 HTTP options for :httpc.request 3rd argument. Returns keyword list of HttpOptions.

to_options(options)

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

Converts FetchOptions to options for :httpc.request 4th argument. Returns keyword list of Options.