HTTP response struct implementing the Browser Fetch API Response interface.

This module represents an HTTP response with full compatibility with the Browser Fetch API standard. It supports both buffered and streaming responses, body consumption tracking, response cloning, and multiple read formats.

Browser Fetch API Compatibility

This module implements the JavaScript Fetch API Response interface:

• status - HTTP status code (e.g., 200, 404, 500)
• status_text - Status message ("OK", "Not Found", etc.)
• ok - Boolean for success status (200-299)
• headers - Response headers as HTTP.Headers struct
• body - Response body as binary, or stream PID for streaming responses
• body_used - Track if body has been consumed
• url - The requested URL as URI struct
• redirected - Whether response was redirected
• type - Response type (:basic, :cors, :error, :opaque)
• stream - Stream process PID for streaming responses (nil for buffered)

Network responses expose the actual http_version (:http1, :http2, or :http3). HTTP/2 and HTTP/3 retain ordered {status, headers} informational blocks in informational when the final response arrives. Buffered trailers are available in trailers when the promise completes, separate from initial headers. Streamed trailers arrive as {:stream_trailers, stream_pid, headers} after body delivery acknowledgements and immediately before {:stream_end, stream_pid}; the immutable response's trailers field remains empty.

HTTP/2 retains at most 128 informational blocks and 65,536 bytes of informational fields in total. Trailers have at most 256 fields and 65,536 bytes. These byte budgets include 32 bytes of overhead per field, and the protocol's HPACK limits also apply. Exceeding a retention budget fails with :http2_informational_limit or :http2_trailers_limit rather than dropping fields. HTTP/1 informational fields are currently not exposed. HTTP/1 trailers retain at most 128 fields and 65,536 serialized bytes, including delimiters, and reject malformed or forbidden fields. Permitted undeclared response trailers are accepted; Trailer declarations are advisory and validated. Exposing metadata does not establish gRPC support.

HTTP Content-Encoding

Network responses transparently decode gzip (including concatenated members) and zlib-wrapped deflate on HTTP/1.1, HTTP/2 and HTTP/3. Supported coding chains and repeated header fields decode in reverse order; identity is a no-op. If any coding is unsupported (for example br), the entire body passes through unchanged. No Accept-Encoding header is added automatically; callers may explicitly request gzip, deflate.

Decoding applies only to Content-Encoding. A .tgz download without that header keeps its original archive bytes, regardless of URL or Content-Type. Manually constructed responses are also unchanged. HEAD and body-forbidden statuses expose their empty body without decoding.

All network body consumers (text/1, json/1, read_all/1, array_buffer/1, blob/1, clone/1 and write_to/2) see decoded bytes, as do direct stream readers. Stream decoding is incremental and retains delivery acknowledgements and trailer ordering. A response stream is consumed once; buffered bodies can be read repeatedly. Chunk boundaries may change during decoding.

Initial headers retain the server's values, including Content-Encoding and the encoded Content-Length. That length also determines whether a response is buffered or streamed; it is not the decoded byte count. Streaming telemetry chunk/stop byte counts describe the decoded bytes, while streaming start retains the encoded length. Decoded bodies can be larger than encoded bodies.

Malformed or truncated supported encodings fail buffered fetches with {:error, {:invalid_content_encoding, coding}}. Streams deliver {:stream_error, stream_pid, {:invalid_content_encoding, coding}}; write_to/2 returns that error, while read methods raise the usual stream-read RuntimeError. A failed file write may leave partial decoded bytes. Raw (non-zlib-wrapped) deflate is rejected as malformed.

Response Methods

• json/1 - Parse response as JSON
• text/1 - Read response as text
• arrayBuffer/1 - Read response as binary
• blob/1 - Read response as Blob with metadata
• clone/1 - Clone response for multiple reads

Elixir-Specific Differences

Immutability: Unlike JavaScript, Elixir responses are immutable. The body_used property won't automatically update across function calls. Use clone/1 before multiple reads.

Synchronous Returns: Methods like json() and text() return values directly instead of Promises, following Elixir conventions.

Stream Handling: Large responses expose a stream process in body, with stream retained as a compatibility alias.

Struct Fields

• status - HTTP status code (e.g., 200, 404, 500)
• status_text - Status message (e.g., "OK", "Not Found")
• ok - Boolean indicating success (true for 200-299)
• headers - Response headers as HTTP.Headers struct
• body - Response body as binary, or stream PID for streaming responses
• body_used - Whether body has been consumed (Browser API behavior)
• url - The requested URL as URI struct
• redirected - Whether response was redirected
• type - Response type (:basic, :cors, :error, :opaque)
• stream - Stream process PID for streaming responses (nil for buffered)

Streaming vs Buffered Responses

Responses are automatically streamed when:

• Content-Length > 5MB
• Content-Length header is missing/unknown

Buffered responses have the complete body in the body field:

%HTTP.Response{
  status: 200,
  body: "response data",
  stream: nil
}

Streaming responses expose the stream PID on body, with the same PID retained on stream for compatibility:

  %HTTP.Response{
    status: 200,
    body: #PID<0.123.0>,
    stream: #PID<0.123.0>
  }

Usage

# Simple text response
response = HTTP.fetch("https://example.com") |> HTTP.Promise.await()
text = HTTP.Response.text(response)

# JSON parsing
response = HTTP.fetch("https://api.example.com/data") |> HTTP.Promise.await()
{:ok, json} = HTTP.Response.json(response)

# Write to file (works with both streaming and buffered)
response = HTTP.fetch("https://example.com/file.zip") |> HTTP.Promise.await()
:ok = HTTP.Response.write_to(response, "/tmp/file.zip")

# Get specific header
content_type = HTTP.Response.get_header(response, "content-type")

# Parse Content-Type
{media_type, params} = HTTP.Response.content_type(response)

Streaming Responses

For streaming responses, use read_all/1 or write_to/2 to consume the stream:

# Read entire stream into memory
body = HTTP.Response.read_all(response)

# Write stream directly to file (more memory efficient)
:ok = HTTP.Response.write_to(response, "/path/to/file")