HTTP request configuration struct.

This module provides a structured way to build HTTP requests with proper conversion to the internal HTTP/1.1 wire format. It handles method normalization, header processing, body encoding, and FormData support.

Supported Methods

• :get - GET requests
• :head - HEAD requests
• :post - POST requests (with body)
• :put - PUT requests (with body)
• :delete - DELETE requests
• :patch - PATCH requests (with body)

Any nonempty ASCII HTTP token is accepted, including DAV methods such as :propfind and :report. Atom methods are uppercased; binary methods retain their case because extension methods are case-sensitive. Whitespace, control characters, non-ASCII bytes and token separators are rejected before normalization.

By default, GET, HEAD, and DELETE request bodies are omitted for compatibility. Set request_mode: :proxy to retain entities for all admitted methods. HEAD response bodies remain empty regardless of the request mode.

Usage

# Basic request
request = %HTTP.Request{
  method: :get,
  url: URI.parse("https://api.example.com/data"),
  headers: HTTP.Headers.new([{"Accept", "application/json"}])
}

# POST with JSON body
request = %HTTP.Request{
  method: :post,
  url: URI.parse("https://api.example.com/posts"),
  headers: HTTP.Headers.new([{"Authorization", "Bearer token"}]),
  content_type: "application/json",
  body: JSON.encode!(%{title: "Hello"}),
  transport_options: [timeout: 10_000]
}

# FormData upload
form = HTTP.FormData.new()
       |> HTTP.FormData.append_field("name", "John")
       |> HTTP.FormData.append_file("photo", "photo.jpg", file_stream)

request = %HTTP.Request{
  method: :post,
  url: URI.parse("https://api.example.com/upload"),
  body: form
}

Default Headers

The library automatically adds a User-Agent header if not provided, containing information about the runtime environment (OS, architecture, OTP version, Elixir version, and library version).