Req

https://github.com/wojtekmach/req
Admin
Req is a batteries-included HTTP client for Elixir, offering automatic response decompression,...
Tokens:103,707
Snippets:707
Trust Score:9.4
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Quick Start: Install and Make a Request with Req.get!

Source: https://github.com/wojtekmach/req/blob/main/README.md

Install Req v0.8.0-rc via Mix.install and make a GET request to the GitHub API, decoding the JSON response body and accessing the 'description' field. The output is shown as a comment.

```elixir
Mix.install([
  {:req, "~> 0.8.0-rc"}
])

Req.get!("https://api.github.com/repos/wojtekmach/req").body["description"]
#=> "Req is a batteries-included HTTP client for Elixir."
```

--------------------------------

### Example: with brotli installed

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Decompress.md

Installs the brotli package and sends a request with compressed: true. The example shows the Accept-Encoding header sent to the server, which includes zstd, br, and gzip.

```elixir
Mix.install([:req, {:brotli, "~> 0.3.0"}])
Req.get!("https://httpbingo.org/anything", compressed: true).body["headers"]["Accept-Encoding"]
#=> ["zstd, br, gzip"]
```

--------------------------------

### Header accessors example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Response.md

Example of putting and getting a header on a response, showing the returned list of values.

```elixir
resp = Req.Response.put_header(%Req.Response{}, "content-type", "application/json")
Req.Response.get_header(resp, "content-type")
#=> ["application/json"]
```

--------------------------------

### Create fully configured Req client and perform GET request

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/configuration.md

Creates a fully configured Req client with base URL, headers, bearer auth, compression, success expectation, redirects, retries, connection options, and timeouts. The example then performs a GET request with query parameters. Note that `System.fetch_env!` raises if the environment variable is missing.

```elixir
req =
  Req.new(
    base_url: "https://api.example.com",
    headers: [accept: "application/json"],
    auth: {:bearer, System.fetch_env!("API_TOKEN")},
    compressed: true,
    expect: :successful,
    redirect: true,
    max_redirects: 5,
    retry: :transient,
    max_retries: 5,
    retry_delay: fn n -> 100 * Integer.pow(2, n) end,
    connect_options: [timeout: 5_000, protocols: [:http2]],
    receive_timeout: 30_000
  )

Req.get!(req, url: "/items", params: [page: 1])
```

--------------------------------

### Example: decompress response with compressed: true

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Decompress.md

Sends a GET request with compressed: true, which sets accept-encoding and decompresses the response body. The example shows the first 15 bytes of the decompressed body.

```elixir
response = Req.get!("https://elixir-lang.org", compressed: true)
binary_part(response.body, 0, 15)
#=> "<!DOCTYPE html>"
```

--------------------------------

### Req.Response.new/1 examples

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Response.md

Examples of creating a response with a keyword list and with a Finch.Response struct, showing header normalization.

```elixir
Req.Response.new(status: 200, body: "body")
#=> %Req.Response{status: 200, headers: %{}, body: "body"}

Req.Response.new(%Finch.Response{status: 200, headers: [{"content-type", "text/html"}]})
#=> %Req.Response{status: 200, headers: %{"content-type" => ["text/html"]}, body: ""}
```

--------------------------------

### Basic redirect example with debug log

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Redirect.md

Shows a simple GET request that follows a redirect, with a debug log message and the resulting status.

```elixir
Req.get!("http://api.github.com").status
# 23:24:11.670 [debug] redirecting to https://api.github.com/
#=> 200
```

--------------------------------

### Examples

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Plug.md

Usage examples for Req.Plug, including module plugs, function plugs, JSON responses, simulated network errors, and error cases.

```APIDOC
## Examples

### Module plug
elixir
defmodule Echo do
  def call(conn, _) do
    "/" <> path = conn.request_path
    Plug.Conn.send_resp(conn, 200, path)
  end
end

Req.get!("http:///hello", plug: Echo).body
#=> "hello"


### Function plug / service stub
elixir
echo = fn conn ->
  "/" <> path = conn.request_path
  Plug.Conn.send_resp(conn, 200, path)
end
Req.get!("http:///hello", plug: echo).body
#=> "hello"


### JSON API response with Req.Test.json/2
elixir
plug = fn conn -> Req.Test.json(conn, %{message: "Hello, World!"}) end
resp = Req.get!(plug: plug)
resp.body
#=> %{"message" => "Hello, World!"}


### Simulated network errors
elixir
plug = fn conn -> Req.Test.transport_error(conn, :timeout) end
Req.get(plug: plug, retry: false)
#=> {:error, %Req.TransportError{reason: :timeout}}


### Error case — plug returning something else than a conn
elixir
bad = fn _conn -> :oops end
# Req.get!(plug: bad)
# ** (ArgumentError) expected to return %Plug.Conn{}, got: :oops

```

--------------------------------

### Example: raw compressed bytes with raw: true

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Decompress.md

Sends a GET request with compressed: true and raw: true, which disables decompression. The example shows the content-encoding header and the first two bytes of the raw body.

```elixir
response = Req.get!("https://elixir-lang.org", compressed: true, raw: true)
Req.Response.get_header(response, "content-encoding")
#=> ["gzip"]
binary_part(response.body, 0, 2)
#=> <<31, 139>>
```

--------------------------------

### load_netrc/1 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Utils.md

Example using StringIO to simulate a .netrc file and load it with Req.Utils.load_netrc/1. Returns a map with machine as key and {login, password} tuple.

```elixir
{:ok, pid} = StringIO.open("machine localhost\nlogin foo\npassword bar\n")
Req.Utils.load_netrc(pid)
#=> %{"localhost" => {"foo", "bar"}}
```

--------------------------------

### Req.Test.expect/3 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Test.md

Example of using Req.Test.expect/3 to set up multiple expectations with different responses, then fetching them in order.

```elixir
Req.Test.expect(MyStub, &Req.Test.transport_error(&1, :econnrefused))
Req.Test.expect(MyStub, 2, &Plug.Conn.send_resp(&1, 500, "internal server error"))
Req.Test.expect(MyStub, &Plug.Conn.send_resp(&1, 200, "ok"))
Req.get!(plug: {Req.Test, MyStub}).body
#=> "ok"
```

--------------------------------

### Req.Test.json/2 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Test.md

Example of using Req.Test.json/2 in a plug to return a JSON response, then fetching it with Req.get! and inspecting the body.

```elixir
plug = fn conn -> Req.Test.json(conn, %{celsius: 25.0}) end
resp = Req.get!(plug: plug)
resp.body
#=> %{"celsius" => 25.0}
```

--------------------------------

### Req.Response.json/1 example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Response.md

Example of building a response with a JSON-encoded body, showing the resulting content-type header.

```elixir
Req.Response.json(%{hello: 42})
# body: ~s|{"hello":42}|, content-type: ["application/json"]
```

--------------------------------

### Basic, bearer, and digest authentication examples

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Auth.md

Shows how to use the :auth option with :basic, :bearer, and :digest tuples. Each example makes a request to httpbingo.org and returns the status code.

```elixir
Req.get!("https://httpbingo.org/basic-auth/foo/bar", auth: {:basic, "foo:bar"}).status
#=> 200
```

```elixir
Req.get!("https://httpbingo.org/bearer", auth: {:bearer, "foo"}).status
#=> 200
```

```elixir
Req.get!("https://httpbingo.org/digest-auth/auth/user/pass", auth: {:digest, "user:pass"}).status
#=> 200
```

--------------------------------

### Req.Response.to_map/1 example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Response.md

Example of converting a response to a map, showing headers as a list of tuples.

```elixir
resp = Req.Response.new(status: 200, headers: %{"server" => ["test"]}, body: "hello")
Req.Response.to_map(resp)
#=> %{status: 200, body: "hello", headers: [{"server", "test"}], trailers: []}
```

--------------------------------

### Custom supervised pool

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Finch.md

Example of starting a custom Finch pool in a supervision tree and using it with Req.get!.

```APIDOC
## Custom supervised pool

### Description
Shows how to start a custom Finch pool with a specific size and use it with Req.get!.

### Method
GET

### Endpoint
https://httpbingo.org/json

### Parameters
#### Query Parameters
- **finch** (list) - Required - Finch pool configuration with `name: MyFinch`.

### Request Example
```elixir
children = [
  {Finch, name: MyFinch, pools: %{default: [size: 70]}}
]
# ...then: Req.get!("https://httpbingo.org/json", finch: [name: MyFinch])
```

### Response
#### Success Response (200)
- **body** (any) - The response body.
```

--------------------------------

### Examples

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Decode.md

Provides usage examples for Req.Decode, including default JSON decoding, opting into archive decoding, disabling decoding, and using a custom decoder with error handling.

```APIDOC
## Examples

### Description
Usage examples for Req.Decode.

### Example 1: Default JSON decoding
```elixir
Req.get!("https://httpbingo.org/json").body["slideshow"]["title"]
#=> "Sample Slide Show"
```

### Example 2: Opt-in to archive decoding
```elixir
Req.get!("https://example.com/archive.zip", decoders: [:zip]).body["file.txt"]
```

### Example 3: Disable all decoding
```elixir
Req.get!("https://httpbingo.org/json", decoders: false).body
```

### Example 4: Custom decoder with error handling
```elixir
decoders = [
  {"application/x-custom", fn body ->
    case parse_custom(body) do
      {:ok, value} -> {:ok, value}
      {:error, reason} -> {:error, RuntimeError.exception("custom decode failed: #{inspect(reason)}")}
    end
  end}
]
Req.get!("https://example.com/data", decoders: decoders)
```

```

--------------------------------

### aws_sigv4_headers/1 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Utils.md

Example call to Req.Utils.aws_sigv4_headers/1 with sample credentials and request details. Returns a list of headers including authorization, x-amz-content-sha256, and x-amz-date.

```elixir
Req.Utils.aws_sigv4_headers(
  access_key_id: "AKID", secret_access_key: "SECRET", region: "us-east-1",
  service: "s3", datetime: ~U[2024-01-01 00:00:00Z], method: :get,
  url: "https://s3.amazonaws.com/bucket/key", headers: [], body: ""
)
```

--------------------------------

### Req.request/2 usage examples

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.md

Examples of using Req.request/2 and Req.request!/2 with different argument forms: a keyword list and a Req.Request struct with method and json options.

```elixir
{:ok, response} = Req.request(url: "https://api.github.com/repos/wojtekmach/req")
response = Req.request!(Req.new(url: "https://httpbingo.org"), method: :post, json: %{a: 1})
```

--------------------------------

### Request function usage examples

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.md

Examples of using Req.get/2, Req.post!/2, Req.delete/2, and Req.get!/2 with error handling. The bang variants raise exceptions on error.

```elixir
{:ok, resp} = Req.get("https://api.github.com/repos/wojtekmach/req")
resp = Req.post!("https://httpbingo.org/post", json: %{x: 1, y: 2})
{:ok, resp} = Req.delete("https://httpbingo.org/anything")

try do
  Req.get!("https://httpbingo.org/status/404", expect: :successful)
rescue
  e in Req.UnexpectedStatusError -> IO.puts(Exception.message(e))
end
```

--------------------------------

### Req.Test.redirect/2 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Test.md

Example of using Req.Test.redirect/2 to redirect to a local path, then serving a text response for that path.

```elixir
plug = fn
  conn when conn.request_path == nil -> Req.Test.redirect(conn, to: "/hello")
  conn when conn.request_path == "/hello" -> Req.Test.text(conn, "Hello, World!")
end
Req.get!(plug: plug, url: "http://example.com").body
#=> "Hello, World!"
```

--------------------------------

### http_digest_auth/5 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Utils.md

Example call to Req.Utils.http_digest_auth/5 with a sample challenge header. Returns {:ok, value} where value is the Authorization header value.

```elixir
challenge = ~s(Digest realm="example", nonce="abc123", qop="auth")
{:ok, value} = Req.Utils.http_digest_auth(challenge, "user", "pass", :get, "/path")
```

--------------------------------

### Req.get! with various options

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Finch.md

Examples of using Req.get! with different options such as receive_timeout, unix_socket, connect_options, and finch pool configuration.

```APIDOC
## Req.get! with various options

### Description
Demonstrates how to use Req.get! with different options for timeouts, Unix sockets, connection options, and Finch pool configuration.

### Method
GET

### Endpoint
https://httpbingo.org/json

### Parameters
#### Query Parameters
- **receive_timeout** (integer) - Optional - Timeout in milliseconds for receiving a response.
- **unix_socket** (string) - Optional - Path to a Unix socket for the connection.
- **connect_options** (list) - Optional - List of connection options, e.g., `[timeout: 5000]`, `[protocols: [:http2]]`, `[transport_opts: [verify: :verify_none]]`.
- **finch** (list) - Optional - Finch pool configuration, e.g., `[name: MyFinch, pool_tag: :bulk]` or `[conn_max_idle_time: 10_000]`.

### Request Example
```elixir
Req.get!("https://httpbingo.org/json", receive_timeout: 1000)
Req.get!("http:///v1.41/_ping", unix_socket: "/var/run/docker.sock")
Req.get!(url, connect_options: [timeout: 5000])
Req.get!(url, connect_options: [protocols: [:http2]])
Req.get!(url, connect_options: [transport_opts: [verify: :verify_none]])
Req.get!("https://httpbingo.org/json", finch: [name: MyFinch, pool_tag: :bulk])
Req.get!("https://httpbingo.org/json", finch: [conn_max_idle_time: 10_000])
```

### Response
#### Success Response (200)
- **body** (any) - The response body.

#### Response Example
```elixir
Req.get!("http:///v1.41/_ping", unix_socket: "/var/run/docker.sock").body
#=> "OK"
```
```

--------------------------------

### Req.Decode usage examples

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Decode.md

Examples of using Req.get! with default decoding, opting into archive decoding with :zip, and disabling all decoding with decoders: false.

```elixir
Req.get!("https://httpbingo.org/json").body["slideshow"]["title"]
#=> "Sample Slide Show"

# opts-in to archive decoding:
Req.get!("https://example.com/archive.zip", decoders: [:zip]).body["file.txt"]

# disable all decoding:
Req.get!("https://httpbingo.org/json", decoders: false).body
```

--------------------------------

### MD5 and SHA-256 checksum examples

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Checksum.md

Illustrates using MD5 and SHA-256 checksum prefixes. The values are placeholders; compute the real digest for the actual body.

```elixir
Req.get!("https://httpbingo.org/json", checksum: "md5:...")
Req.get!("https://httpbingo.org/json", checksum: "sha256:...")
```

--------------------------------

### put_aws_sigv4/1 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Steps.md

Shows how to configure AWS SigV4 signing with Req.new/1, using environment variables for access keys. The example then makes a PUT request to an S3 bucket.

```elixir
req = Req.new(
  base_url: "https://s3.amazonaws.com",
  aws_sigv4: [
    access_key_id: System.get_env("AWS_ACCESS_KEY_ID"),
    secret_access_key: System.get_env("AWS_SECRET_ACCESS_KEY")
  ]
)
Req.put!(req, url: "/bucket1/key1", body: "Hello, World!")
```

--------------------------------

### Using Req.get_headers_list/1

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.md

Example of creating a request with headers and converting them to a list. The output is [{"accept", "application/json"}].

```elixir
req = Req.Request.new(headers: %{"accept" => ["application/json"]})
Req.get_headers_list(req)
#=> [{"accept", "application/json"}]
```

--------------------------------

### Using option accessors

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Request.md

Shows registering an option, setting it, getting it, and the error raised for unknown options.

```elixir
req = Req.Request.new() |> Req.Request.register_options([:foo])
req = Req.Request.put_option(req, :foo, 1)
Req.Request.get_option(req, :foo)  # => 1
# Req.Request.put_option(req, :bar, 1)  # ** (ArgumentError) unknown option :bar
```

--------------------------------

### Req.Test.stub/2 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Test.md

Example of using Req.Test.stub/2 to register a stub that returns an empty JSON response, then fetching it with Req.get!.

```elixir
Req.Test.stub(MyStub, fn conn -> Req.Test.json(conn, %{}) end)
Req.get!(plug: {Req.Test, MyStub}).body
#=> %{}
```

--------------------------------

### put_params/1 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Steps.md

Shows how to use put_params/1 with Req.get! to add query parameters. The example sends params x: 1 and y: 2 and inspects the response body's "args" field.

```elixir
Req.get!("https://httpbingo.org/anything/query", params: [x: 1, y: 2]).body["args"]
#=> %{"x" => ["1"], "y" => ["2"]}
```

--------------------------------

### Req.new/2 usage examples

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.md

Shows two ways to create a request with Req.new/2: using a keyword list with URL and auth, and using a URL string with method option.

```elixir
req = Req.new(url: "https://api.github.com", auth: {:bearer, "token"})
req = Req.new("https://elixir-lang.org", method: :head)
```

--------------------------------

### Req.get! with proxy

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Finch.md

Example of using Req.get! with a proxy and basic authentication.

```APIDOC
## Req.get! with proxy

### Description
Demonstrates how to use Req.get! with a proxy and basic authentication.

### Method
GET

### Endpoint
https://elixir-lang.org

### Parameters
#### Request Body
- **connect_options** (list) - Required - List of connection options including `proxy` and `proxy_headers`.
  - **proxy** (tuple) - Required - Proxy configuration: `{:http, "your.proxy.com", 8888, []}`.
  - **proxy_headers** (list) - Required - List of headers, e.g., `[{"proxy-authorization", "Basic " <> Base.encode64("user:pass")}]`.

### Request Example
```elixir
Req.new(
  url: "https://elixir-lang.org",
  connect_options: [
    proxy: {:http, "your.proxy.com", 8888, []},
    proxy_headers: [{"proxy-authorization", "Basic " <> Base.encode64("user:pass")}]
  ]
)
|> Req.get!()
```

### Response
#### Success Response (200)
- **body** (any) - The response body.
```

--------------------------------

### Req.ChecksumMismatchError message example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/errors.md

Example error message for Req.ChecksumMismatchError, showing the expected and actual checksum values in the format "#{type}:" <> hex.

```text
checksum mismatch
expected: sha1:bad
actual:   sha1:ae5891fe71e8c6432b552b0c3b4394e43f151493
```

--------------------------------

### put_range/1 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Steps.md

Shows how to use put_range/1 with Req.get! to request a specific byte range. The example requests bytes 0..3 from a 100-byte resource and checks the response status and body.

```elixir
response = Req.get!("https://httpbingo.org/range/100", range: 0..3)
# response.status == 206, response.body == "abcd"
```

--------------------------------

### Custom adapter implementation (MyAdapter)

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Adapter.md

Example of implementing a custom adapter by defining a module that uses @behaviour Req.Adapter and implements the stream/4 callback. The adapter is then used by passing the :adapter option to Req.new/2. The stream/4 function must build the request from the req struct, emit events via fun, and return one of the allowed shapes.

```elixir
defmodule MyAdapter do
  @behaviour Req.Adapter

  @impl true
  def stream(%Req.Request{} = req, acc, fun, state) do
    # build the request from req (method, url, headers via Req.Fields.get_list/1, body)
    # emit events via fun.(event, resp, acc, state)
    # return {:ok, resp, acc, state} | {:halt, resp, acc, state} | {{:error, err}, resp, acc, state}
  end
end

req = Req.new("https://example.com", adapter: MyAdapter)
Req.get!(req)
```

--------------------------------

### put_path_params/1 usage examples

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Steps.md

Shows how to use put_path_params/1 with Req.get! for both :colon and :curly path parameter styles. The first example uses a colon-style template and a keyword list, the second uses a curly-style template and a list of tuples with the :path_params_style option set to :curly.

```elixir
Req.get!("https://httpbingo.org/status/:code", path_params: [code: 201]).status      # => 201
Req.get!("https://httpbingo.org/status/{code}", path_params: [{"code", 201}], path_params_style: :curly).status
```

--------------------------------

### Module plug example: Echo

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Plug.md

Defines a module plug that echoes the request path. The plug is passed to Req.get! via the :plug option, and the response body is the path.

```elixir
defmodule Echo do
  def call(conn, _) do
    "/" <> path = conn.request_path
    Plug.Conn.send_resp(conn, 200, path)
  end
end

Req.get!("http:///hello", plug: Echo).body
#=> "hello"
```

--------------------------------

### Req.merge/2 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.md

Shows how to merge options into an existing request, adding basic auth to a base URL.

```elixir
req = Req.new(base_url: "https://httpbingo.org")
req = Req.merge(req, auth: {:basic, "alice:secret"})
```

--------------------------------

### Setting default options with Req.default_options/1

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.md

Example of setting a base_url default option and then using it in a request. The request to /status/201 returns status 201.

```elixir
Req.default_options(base_url: "https://httpbingo.org")
Req.get!("/status/201").status  # => 201
```

--------------------------------

### Set and get headers with put_header and put_new_header

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Request.md

Shows how to set a header with put_header, attempt to set a new header with put_new_header (which does not overwrite), and retrieve the header value with get_header. The output is ["application/json"] because put_new_header does not overwrite the existing header.

```elixir
req =
  Req.new()
  |> Req.Request.put_header("accept", "application/json")
  |> Req.Request.put_new_header("accept", "application/html")
Req.Request.get_header(req, "accept")
#=> ["application/json"]
```

--------------------------------

### Configure Finch pool via :finch option

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Finch.md

Passes pool configuration to Req through the `:finch` option. A named pool (`name: MyFinch, pool_tag: :bulk`) must be started separately; `conn_max_idle_time` is a pool option that causes a pool to be started or reused by option hash.

```elixir
Req.get!("https://httpbingo.org/json", finch: [name: MyFinch, pool_tag: :bulk])
Req.get!("https://httpbingo.org/json", finch: [conn_max_idle_time: 10_000])
```

--------------------------------

### put_user_agent/1 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Steps.md

Shows how to use put_user_agent/1 by setting the :user_agent option in a request. The response body contains the user-agent header value.

```elixir
Req.get!("https://httpbingo.org/user-agent", user_agent: "foo").body
```

--------------------------------

### Function plug example: echo

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Plug.md

Defines a function plug that echoes the request path. The plug is passed to Req.get! via the :plug option, and the response body is the path.

```elixir
echo = fn conn ->
  "/" <> path = conn.request_path
  Plug.Conn.send_resp(conn, 200, path)
end
Req.get!("http:///hello", plug: echo).body
#=> "hello"
```

--------------------------------

### Basic usage with exact status and atom expectation

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Expect.md

Shows how to use Req.get! with the :expect option. The first example expects status 200, the second expects a successful status (200..299) and raises Req.UnexpectedStatusError on mismatch.

```elixir
resp = Req.get!("https://httpbingo.org/status/200", expect: 200)
resp.status                    # => 200

Req.get!("https://httpbingo.org/status/404", expect: :successful)
# ** (Req.UnexpectedStatusError) expected response status :successful (200..299), got: 404
```

--------------------------------

### Use Req plugins with ReqEasyHTML, ReqS3, ReqHex, and ReqGitHubOAuth

Source: https://github.com/wojtekmach/req/blob/main/README.md

Installs and attaches several Req plugins to handle HTML, S3, Hex, and GitHub OAuth requests.

```elixir
Mix.install([
  {:req, "~> 0.8.0-rc"},
  {:req_easyhtml, "~> 0.2.0"},
  {:req_s3, "~> 0.2.3"},
  {:req_hex, "~> 0.2.0"},
  {:req_github_oauth, "~> 0.1.0"}
])

req =
  (Req.new(http_errors: :raise)
  |> ReqEasyHTML.attach()
  |> ReqS3.attach()
  |> ReqHex.attach()
  |> ReqGitHubOAuth.attach())

Req.get!(req, url: "https://elixir-lang.org").body[".entry-summary h5"]
#=>
# #EasyHTML[<h5>
#    Elixir is a dynamic, functional language for building scalable and maintainable applications.
#  </h5>]

Req.get!(req, url: "s3://ossci-datasets/mnist/t10k-images-idx3-ubyte.gz").body
#=> <<0, 0, 8, 3, ...>>

Req.get!(req, url: "https://repo.hex.pm/tarballs/req-0.1.0.tar").body["metadata.config"]["links"]
#=> %{"GitHub" => "https://github.com/wojtekmach/req"}

Req.get!(req, url: "https://api.github.com/user").body["login"]
# output:
# paste this user code:
#
#   6C44-30A8
#
# at:
#
#   https://github.com/login/device
#
# open browser window? [Yn]
# 15:22:28.350 [info] response: authorization_pending
# 15:22:33.519 [info] response: authorization_pending
# 15:22:38.678 [info] response: authorization_pending
#=> "wojtekmach"

Req.get!(req, url: "https://api.github.com/user").body["login"]
#=> "wojtekmach"
```

--------------------------------

### Reuse a request struct with Req.new and Req.get!

Source: https://github.com/wojtekmach/req/blob/main/README.md

Builds a request struct with a base URL and reuses it for multiple GET requests.

```elixir
req = Req.new(base_url: "https://api.github.com")

Req.get!(req, url: "/repos/sneako/finch").body["description"]
#=> "Elixir HTTP client, focused on performance"

Req.get!(req, url: "/repos/elixir-mint/mint").body["description"]
#=> "Functional HTTP client for Elixir with support for HTTP/1 and HTTP/2."
```

--------------------------------

### put_base_url/1 usage example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Steps.md

Shows how to use put_base_url/1 by setting the :base_url option in Req.new/1 and then making a request with a relative URL. The base URL is merged with the request URL when the request URL has no scheme.

```elixir
Req.new(base_url: "https://httpbingo.org") |> Req.get!(url: "/status/200")
```

--------------------------------

### default_options/0 and default_options/1

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.md

Functions to get and set the default options for Req requests. default_options/0 returns the current default options, while default_options/1 sets them globally.

```APIDOC
## default_options/0 and default_options/1

### Description
Returns or sets the default options for Req requests. The options are stored in the application environment under `:req, :default_options`.

### Function Signatures
- `default_options() :: keyword()`
- `default_options(keyword()) :: :ok`

### Parameters
- `options` (keyword()) - Required for `default_options/1` - The default options to set globally.

### Examples
```elixir
Req.default_options(base_url: "https://httpbingo.org")
Req.get!("/status/201").status  # => 201
```
```

--------------------------------

### Req.get! with unix_socket option

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Finch.md

Sends a GET request over a Unix socket to the Docker API endpoint and returns the response body. The example expects the body to be the string "OK".

```elixir
Req.get!("http:///v1.41/_ping", unix_socket: "/var/run/docker.sock").body
#=> "OK"
```

--------------------------------

### Req.Response.new/1

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Response.md

Creates a response from a keyword list, map, or any struct (e.g. %Finch.Response{}). Headers and trailers are normalized. Raises on unknown keyword keys.

```APIDOC
## Req.Response.new/1

### Description
Creates a response from a keyword list, map, or any struct (e.g. `%Finch.Response{}`, using `Map.take/2` on keys `:status, :headers, :body, :trailers, :private, :request`). Headers and trailers are normalized (values wrapped in lists, duplicates preserved). Raises on unknown keyword keys (via `Keyword.validate!/2`).

### Method
Function

### Endpoint
`Req.Response.new(options \\ [])`

### Parameters
- **options** (keyword() | map() | struct()) - Optional - Options to create the response.

### Request Example
```elixir
Req.Response.new(status: 200, body: "body")
#=> %Req.Response{status: 200, headers: %{}, body: "body"}

Req.Response.new(%Finch.Response{status: 200, headers: [{"content-type", "text/html"}]})
#=> %Req.Response{status: 200, headers: %{"content-type" => ["text/html"]}, body: ""}
```

### Response
#### Success Response
Returns a `Req.Response.t()` struct.

#### Response Example
```elixir
%Req.Response{status: 200, headers: %{}, body: "body"}
```
```

--------------------------------

### Dynamic credentials with function and MFA

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Auth.md

Shows how to use a 0-arity function or an MFA tuple to provide credentials dynamically. The function must return a valid auth value, and the MFA result is processed recursively.

```elixir
Req.get!("https://httpbingo.org/basic-auth/foo/bar", auth: fn -> {:basic, "foo:bar"} end)
```

```elixir
defmodule Authentication do
  def fetch_token, do: {:bearer, "abc"}
end
Req.get!("https://httpbingo.org/bearer", auth: {Authentication, :fetch_token, []})
```

--------------------------------

### Default retry with GET request

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Retry.md

Shows the default retry behavior with a GET request that first returns a 500 status and then a 200. The log message indicates a retry with a delay of 941ms and 2 attempts left.

```elixir
Req.get!("https://httpbingo.org/status/500,200").status
# [warning] retry: got response with status 500, will retry in 941ms, 2 attempts left
#=> 200
```

--------------------------------

### Req.Steps.__default__/0 - Default steps list

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Steps.md

Internal function returning the list of default request steps. Used by attach/1 to prepend the default steps to the request pipeline.

```elixir
@doc false
def __default__ do
  [
    expect: Req.Expect, retry: Req.Retry, decode: Req.Decode, into: Req.Into,
    checksum: Req.Checksum, decompress: Req.Decompress, redirect: Req.Redirect,
    put_user_agent: &Req.Steps.put_user_agent/1, encode_body: &Req.Steps.encode_body/1,
    put_base_url: &Req.Steps.put_base_url/1, auth: Req.Auth,
    put_params: &Req.Steps.put_params/1, put_path_params: &Req.Steps.put_path_params/1,
    put_range: &Req.Steps.put_range/1, compress_body: &Req.Steps.compress_body/1,
    put_aws_sigv4: &Req.Steps.put_aws_sigv4/1
  ]
end
```

--------------------------------

### Req.stream/4 usage example with NDJSON decoding

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.md

Streams an HTTP request and decodes data as NDJSON. The callback receives each decoded data chunk and returns {:cont, acc} to continue. This example uses the decoders: [text: :ndjson] option.

```elixir
{:ok, resp, acc} =
  Req.stream("http://httpbingo.org/stream/2", [], fn data, _resp, acc ->
    IO.inspect(data)
    {:cont, acc}
  end, decoders: [text: :ndjson])
```

--------------------------------

### Req.stream/4 error handling example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.md

Shows the error return tuple when streaming fails. The example uses retry: false and expects a connection refused error, resulting in {:error, err, resp, acc} where err is %Req.TransportError{reason: :econnrefused}.

```elixir
{:error, err, resp, acc} =
  Req.stream("http://localhost:9999", nil, fn _data, _resp, acc -> {:cont, acc} end, retry: false)
# err is %Req.TransportError{reason: :econnrefused}
```

--------------------------------

### Create request with Req.Request.new/1 and register options

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Request.md

Creates a request with a URL, registers the :decoders option, prepends the Req.Decode step, and fetches the response body.

```elixir
req =
  Req.Request.new(url: "https://api.github.com/repos/wojtekmach/req")
  |> Req.Request.register_options(:decoders)
  |> Req.Request.prepend_request_steps(decode: Req.Decode)
Req.get!(req).body["description"]
```

--------------------------------

### Header accessors

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Response.md

Functions to get, put, and delete response headers.

```APIDOC
## Header accessors

### Description
Functions to access and modify response headers.

### Functions

#### get_header/2
- **Signature**: `get_header(response, name)`
- **Description**: Returns the values of header `name`, or `[]` if absent.

#### put_header/3
- **Signature**: `put_header(response, name, value)`
- **Description**: Replaces (or adds) the header value.

#### delete_header/2
- **Signature**: `delete_header(response, name)`
- **Description**: Deletes all occurrences of the header.

### Request Example
```elixir
resp = Req.Response.put_header(%Req.Response{}, "content-type", "application/json")
Req.Response.get_header(resp, "content-type")
#=> ["application/json"]
```
```

--------------------------------

### Max redirects exceeded example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Redirect.md

Demonstrates the Req.TooManyRedirectsError when the max_redirects limit is exceeded.

```elixir
Req.get!("https://httpbingo.org/redirect/4", max_redirects: 3)
# ** (Req.TooManyRedirectsError) too many redirects (3)
```

--------------------------------

### Private accessors

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Response.md

Functions to get, put, and update private fields in a response.

```APIDOC
## Private accessors

### Description
Functions to access and modify the `:private` field of a response, reserved for libraries.

### Functions

#### get_private/3
- **Signature**: `get_private(response, key, default \\ nil)`
- **Description**: Gets the value of a private key, or the default if not present.

#### put_private/3
- **Signature**: `put_private(response, key, value)`
- **Description**: Assigns a private key.

#### update_private/4
- **Signature**: `update_private(response, key, default, fun)`
- **Description**: Updates a private key, inserting the default if not present.
```

--------------------------------

### Error handling - transport errors

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Finch.md

Example of handling transport errors when using Req.get.

```APIDOC
## Error handling - transport errors

### Description
Demonstrates how Req.get returns an error tuple for transport errors like timeouts.

### Method
GET

### Endpoint
https://httpbingo.org/delay/1

### Parameters
#### Query Parameters
- **receive_timeout** (integer) - Required - Timeout in milliseconds (set to 0).
- **retry** (boolean) - Required - Set to false to disable retries.

### Request Example
```elixir
Req.get("https://httpbingo.org/delay/1", receive_timeout: 0, retry: false)
```

### Response
#### Error Response
- **error** (tuple) - `{:error, %Req.TransportError{reason: :timeout}}`
```

--------------------------------

### Req.get! with receive_timeout

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Finch.md

Performs a GET request to https://httpbingo.org/json with a receive timeout of 1000 milliseconds.

```elixir
Req.get!("https://httpbingo.org/json", receive_timeout: 1000)
```

--------------------------------

### Trusted redirect false example

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Redirect.md

Shows that with redirect_trusted: false, authorization credentials are stripped on cross-host redirects.

```elixir
req = Req.new(url: "http://example.com/redirect", auth: {:bearer, "secret"})
resp = Req.get!(req, redirect_trusted: false)
# authorization header is absent from the redirected request
```

--------------------------------

### Req.Steps.attach/1 - Function head

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Steps.md

Internal function that registers all built-in option names and prepends the default steps. The full implementation is not shown on this page.

```elixir
@doc false
def attach(req)
```

--------------------------------

### Req.Request.new/1

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Request.md

Creates a new blank request struct with no built-in steps. Validates keys :method, :url, :headers, :body, :adapter, :options. Parses :url with URI.parse/1, builds :headers with Req.Fields.new_without_normalize/1, and converts :options to a map.

```APIDOC
## Req.Request.new/1

### Description
Returns a new blank request struct (no built-in steps). Validates keys `:method, :url, :headers, :body, :adapter, :options`. `:url` is parsed with `URI.parse/1`, `:headers` built with `Req.Fields.new_without_normalize/1`, `:options` converted to a map.

### Signature
```elixir
@spec new(keyword()) :: t()
def new(options \\ []) when is_list(options)
```

### Parameters
- **options** (keyword()) - Optional - A keyword list of request options. Valid keys: `:method`, `:url`, `:headers`, `:body`, `:adapter`, `:options`.

### Example
```elixir
req =
  Req.Request.new(url: "https://api.github.com/repos/wojtekmach/req")
  |> Req.Request.register_options(:decoders)
  |> Req.Request.prepend_request_steps(decode: Req.Decode)
Req.get!(req).body["description"]
```
```

--------------------------------

### Req.get! with checksum option

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Checksum.md

Performs a GET request with a SHA-1 checksum. On success, returns the response with status 200.

```elixir
resp = Req.get!("https://httpbingo.org/json", checksum: "sha1:ae5891fe71e8c6432b552b0c3b4394e43f151493")
resp.status
#=> 200
```

--------------------------------

### child_spec(options)

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Finch.md

Builds a Finch child specification with pool options. This is used internally by Req to start the Finch supervisor.

```APIDOC
## child_spec(options)

### Description
Builds a Finch child specification with pool options. This is used internally by Req to start the Finch supervisor.

### Method
N/A (Elixir function)

### Parameters
- **options** (map) - Required - Options for the Finch child spec. The `:name` option is popped and used for the Finch supervisor name.

### Returns
A Finch child specification (map).

```

--------------------------------

### Specifications for append_request_steps and prepend_request_steps

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Request.md

Shows the function signatures for append_request_steps and prepend_request_steps. These functions append or prepend {name, step} pairs to request_steps. A step is a 1-arity function, a module implementing stream/5 wrapper behavior, or a 5-arity wrapper function.

```elixir
@spec append_request_steps(t(), keyword(request_step() | module())) :: t()
def append_request_steps(request, steps)

@spec prepend_request_steps(t(), keyword(request_step() | module())) :: t()
def prepend_request_steps(request, steps)
```

--------------------------------

### Req.Plug.stream/4

Source: https://github.com/wojtekmach/req/blob/main/_autodocs/api-reference/Req.Plug.md

The main entry point of the Req.Plug adapter, implementing the Req.Adapter behaviour. It processes the request through the plug and returns a stream of response events.

```APIDOC
## Req.Plug.stream/4

### Description
Implements the `Req.Adapter` behaviour. Runs the request against a Plug instead of over the network. Used automatically when the `:plug` option is set.

### Method
stream

### Signature
`stream(request, acc, fun, state) when is_function(fun, 4)`

### Parameters
- **request** (map) - Required - The request struct.
- **acc** (term) - Required - Accumulator for the stream.
- **fun** (function) - Required - Function of arity 4 for processing events.
- **state** (term) - Required - Adapter state.

### Behavior
- Converts the request body (iodata / nil / `req_body_fun` / enumerable) to a binary, draining `req_body_fun` chunks (`{:halt, acc}` halts without calling the plug; `{:error, exception, acc}` short-circuits with that exception).
- Builds a `%Plug.Conn{}` via `Req.Plug.Adapter.conn/4`, sets request headers, calls `Plug.Conn.fetch_query_params(validate_utf8: false)`, puts the request private map (`:req_private`), and parses the body with `Plug.Parsers` (`:urlencoded, :multipart, :json`, pass `["*/*"]`, `json_decoder: JSON`). gzip/x-gzip `content-encoding` bodies are decompressed first (raising on decompression failure).
- The plug is invoked with `call_plug/2` (module, `{module, options}`, fun/1, fun/2 forms). A non-`%Plug.Conn{}` return raises `ArgumentError`.
- If `conn.private[:req_test_exception]` is set (via `Req.Test.transport_error/2`), that exception is returned as `{{:error, exception}, resp, acc, state}`.
- `finish_conn/1` validates the connection has a response (`conn.state != :unset`, otherwise raises with guidance), drains plug-test messages, and returns response chunks.
- Emits status/headers/data events; `into: :self` emulates async messages with a `%Req.Response.Async{}` body.

### Example
elixir
defmodule Echo do
  def call(conn, _) do
    "/" <> path = conn.request_path
    Plug.Conn.send_resp(conn, 200, path)
  end
end

Req.get!("http:///hello", plug: Echo).body
#=> "hello"

```
Tokens:
Raw