Attaches Tor routing to an existing Req request.

new/1 builds a Tor client directly. Use attach/2 when a request already has other Req plugins or options, then run it with ReqTor.get!/2 or another ReqTor verb.

Calling attach/2 again updates options and does not add a second Tor step.

Options

• :tor_host - Tor SOCKS5 proxy host (default: "127.0.0.1")
• :tor_port - Tor SOCKS5 proxy port (default: 9050)
• :tor_enabled - Enable or skip Tor routing (default: true)
• :tor_insecure - TLS verification (default: :auto)
• :tor_browser - Use Tor Browser's user-agent (default: false)

Examples

iex> req = Req.new() |> ReqTor.attach()
iex> req.options[:tor_host]
"127.0.0.1"

iex> req = Req.new() |> ReqTor.attach(tor_port: 9150)
iex> req.options[:tor_port]
9150

req = Req.new(base_url: "http://example.onion") |> ReqTor.attach(tor_browser: true)
ReqTor.get!(req, url: "/")

@spec attached?(Req.Request.t()) :: boolean()

Returns true when the request was built for Tor.

A plain Req request returns false. tor_enabled: false does not remove the attachment; it only skips the proxy for that call.

Examples

iex> ReqTor.attached?(ReqTor.new())
true

iex> ReqTor.attached?(Req.new())
false

@spec check_tor?(Req.Request.t() | keyword()) :: boolean()

Checks whether this client exits through Tor.

Requests https://check.torproject.org/api/ip and reads the IsTor field. Accepts a request from new/1 or the same options as new/1.

Examples

req = ReqTor.new()
ReqTor.check_tor?(req)
#=> true

ReqTor.check_tor?(tor_port: 9150)
#=> true

@spec delete(
  Req.Request.t() | keyword() | URI.t() | String.t(),
  keyword()
) :: {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes a DELETE request through Tor.

Returns {:ok, response} or {:error, exception}.

The first argument is a URL, a keyword list, or a request from new/1. Tor options can be passed here or to new/1. Every other option is a Req option.

@spec delete!(
  Req.Request.t() | keyword() | URI.t() | String.t(),
  keyword()
) :: Req.Response.t()

Makes a DELETE request through Tor and returns the response, or raises.

The first argument is a URL, a keyword list, or a request from new/1. Tor options can be passed here or to new/1. Every other option is a Req option.

@spec exit_ip(Req.Request.t() | keyword()) ::
  {:ok, String.t() | nil} | {:error, term()}

Returns the Tor exit node IP address.

Accepts a request from new/1 or the same options as new/1.

Examples

req = ReqTor.new()
ReqTor.exit_ip(req)
#=> {:ok, "185.220.101.42"}

ReqTor.exit_ip(tor_port: 9150)
#=> {:ok, "185.220.101.42"}

@spec get(
  Req.Request.t() | keyword() | URI.t() | String.t(),
  keyword()
) :: {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes a GET request through Tor.

Returns {:ok, response} or {:error, exception}.

The first argument is a URL, a keyword list, or a request from new/1. Tor options can be passed here or to new/1. Every other option is a Req option.

@spec get!(
  Req.Request.t() | keyword() | URI.t() | String.t(),
  keyword()
) :: Req.Response.t()

Makes a GET request through Tor and returns the response, or raises.

The first argument is a URL, a keyword list, or a request from new/1. Tor options can be passed here or to new/1. Every other option is a Req option.

@spec head(
  Req.Request.t() | keyword() | URI.t() | String.t(),
  keyword()
) :: {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes a HEAD request through Tor.

Returns {:ok, response} or {:error, exception}.

The first argument is a URL, a keyword list, or a request from new/1. Tor options can be passed here or to new/1. Every other option is a Req option.

@spec head!(
  Req.Request.t() | keyword() | URI.t() | String.t(),
  keyword()
) :: Req.Response.t()

Makes a HEAD request through Tor and returns the response, or raises.

The first argument is a URL, a keyword list, or a request from new/1. Tor options can be passed here or to new/1. Every other option is a Req option.

@spec merge(
  Req.Request.t(),
  keyword()
) :: Req.Request.t()

Merges options into a request, attaching Tor when the request does not have it yet.

Examples

iex> req = ReqTor.new() |> ReqTor.merge(tor_port: 9150, base_url: "http://example.onion")
iex> req.options[:tor_port]
9150
iex> req.options[:base_url]
"http://example.onion"

@spec new(keyword()) :: Req.Request.t()

Builds a request that routes through Tor.

Tor options are listed in the module docs. Every other option is passed to Req.new/1.

Examples

iex> req = ReqTor.new()
iex> req.options[:tor_host]
"127.0.0.1"
iex> req.options[:tor_port]
9050
iex> ReqTor.attached?(req)
true

iex> req = ReqTor.new(base_url: "http://example.onion", tor_port: 9150)
iex> req.options[:base_url]
"http://example.onion"
iex> req.options[:tor_port]
9150

@spec patch(
  Req.Request.t() | keyword() | URI.t() | String.t(),
  keyword()
) :: {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes a PATCH request through Tor.

Returns {:ok, response} or {:error, exception}.

The first argument is a URL, a keyword list, or a request from new/1. Tor options can be passed here or to new/1. Every other option is a Req option.

@spec patch!(
  Req.Request.t() | keyword() | URI.t() | String.t(),
  keyword()
) :: Req.Response.t()

Makes a PATCH request through Tor and returns the response, or raises.

The first argument is a URL, a keyword list, or a request from new/1. Tor options can be passed here or to new/1. Every other option is a Req option.

@spec post(
  Req.Request.t() | keyword() | URI.t() | String.t(),
  keyword()
) :: {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes a POST request through Tor.

Returns {:ok, response} or {:error, exception}.

The first argument is a URL, a keyword list, or a request from new/1. Tor options can be passed here or to new/1. Every other option is a Req option.

@spec post!(
  Req.Request.t() | keyword() | URI.t() | String.t(),
  keyword()
) :: Req.Response.t()

Makes a POST request through Tor and returns the response, or raises.

The first argument is a URL, a keyword list, or a request from new/1. Tor options can be passed here or to new/1. Every other option is a Req option.

@spec put(
  Req.Request.t() | keyword() | URI.t() | String.t(),
  keyword()
) :: {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes a PUT request through Tor.

Returns {:ok, response} or {:error, exception}.

The first argument is a URL, a keyword list, or a request from new/1. Tor options can be passed here or to new/1. Every other option is a Req option.

@spec put!(
  Req.Request.t() | keyword() | URI.t() | String.t(),
  keyword()
) :: Req.Response.t()

Makes a PUT request through Tor and returns the response, or raises.

The first argument is a URL, a keyword list, or a request from new/1. Tor options can be passed here or to new/1. Every other option is a Req option.

@spec request(
  Req.Request.t() | keyword(),
  keyword()
) :: {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes an HTTP request through Tor.

Returns {:ok, response} or {:error, exception}. Set :method in the options or on the request. It defaults to the request's method.

The first argument is a keyword list or a request from new/1.

@spec request!(
  Req.Request.t() | keyword(),
  keyword()
) :: Req.Response.t()

Makes an HTTP request through Tor and returns the response, or raises.

See request/2.