# `CloakedReq`
[🔗](https://github.com/rubas/cloaked_req/blob/v0.7.0/lib/cloaked_req.ex#L1)

Req adapter powered by Rust `wreq`.

- `attach/2`: set adapter and merge options
- `impersonate/2`: set browser profile
- `run/1`: adapter entry point, called by Req

# `attach`

```elixir
@spec attach(Req.Request.t(), keyword()) :: Req.Request.t()
```

Attaches `CloakedReq` adapter behavior to an existing `Req.Request`.

Supported adapter-relevant options:

- `:cookie_jar` - `%CloakedReq.CookieJar{}` for automatic cookie persistence
- `:connect_options` - Req transport options for `:timeout`, `:proxy`, and `:proxy_headers`.
  `:timeout` (default: 30 s) bounds opening a connection: DNS, TCP, the proxy
  tunnel, and TLS.
- `:receive_timeout` - Req option (default: 15 s). The README states what it bounds.
- `:impersonate` - profile atom (e.g. `:chrome_136`, `:"safari_17.4.1"`)
- `:insecure_skip_verify` - boolean
- `:local_address` - outbound source IP as string, IPv4 tuple, or IPv6 tuple
- `:max_body_size` - positive integer or `:unlimited` (default: 10 MB); caps
  both the request body (rejected before sending if larger) and the response
  body (truncated to an error once it exceeds the limit)
- `:pool` - `%CloakedReq.Pool{}` built with `CloakedReq.Pool.new/1`, routing
  the request through a dedicated, isolated client and connection pool. The
  pool's client governs the impersonation profile, TLS verification, and
  connect timeout, so per-request `:impersonate`, `:insecure_skip_verify`, and
  the `:connect_options` connect timeout are ignored (still validated if
  given). The `:connect_options` proxy, `:local_address`, headers, body,
  `:cookie_jar`, and `:receive_timeout` still apply per request.

## Examples

    iex> req = Req.new(url: "https://example.com") |> CloakedReq.attach(impersonate: :chrome_136)
    iex> req.adapter
    CloakedReq
    iex> Req.Request.get_option(req, :impersonate)
    :chrome_136

# `impersonate`

```elixir
@spec impersonate(Req.Request.t(), atom()) :: Req.Request.t()
```

Sets the impersonation profile and configures the `CloakedReq` Req adapter.

## Examples

    iex> req = Req.new(url: "https://example.com") |> CloakedReq.impersonate(:chrome_136)
    iex> Req.Request.get_option(req, :impersonate)
    :chrome_136
    iex> req.adapter
    CloakedReq

# `run`

```elixir
@spec run(Req.Request.t()) :: {Req.Request.t(), Req.Response.t() | Exception.t()}
```

Runs the request through the native transport. Req calls this as the adapter.

A timeout, a refused connection, or a closed connection returns
`%Req.TransportError{}` with the reason `:timeout`, `:econnrefused`, or
`:closed`, so Req's `:retry` step treats it like a Finch failure. Every other
failure returns `%CloakedReq.AdapterError{}` and is not retried.

---

*Consult [api-reference.md](api-reference.md) for complete listing*