honeyryder

Proxy

The proxy plugin allows one to send HTTP requests through a proxy.

It supports HTTP, HTTPS/CONNECT tunnel, Socks4, Socks4a and Socks5 out-of-the-box (and SSH proxies if you load the :proxy/ssh plugin).

All examples will assume the fictitious 10.10.0.1:51432 address/port pair. Replace the examples with your own.

Options

After enabling the plugin, you can call a #proxy method, which can receive the following options:

  • :uri: the proxy URI or a list of proxy URIs (see examples below)
  • :username: proxy user (optional)
  • :password: proxy password (optional)
  • :scheme: proxy auth scheme (optional)
  • :no_proxy: list of domains/patterns that bypass the proxy (optional)
# Use an HTTP cache proxy to route clear-text HTTP requests:
HTTPX.plugin(:proxy).with_proxy(uri: "http://10.10.0.1:51432").get("http://dn.pt")
# try another proxy if the first one fails
HTTPX.plugin(:proxy).with_proxy(uri: %w[https://10.10.0.1:51432 https://10.12.3.2:8080]).get("https://google.pt")
# Use an HTTPS `CONNECT` proxy to tunnel secure HTTP(S) requests.
HTTPX.plugin(:proxy).with_proxy(uri: "https://10.10.0.1:51432").get("https://google.pt")
# Use a SOCKS proxy
HTTPX.plugin(:proxy).with_proxy(uri: "socks4://10.10.0.1:51432").get("https://google.pt")
HTTPX.plugin(:proxy).with_proxy(uri: "socks4a://10.10.0.1:51432").get("https://google.pt")
HTTPX.plugin(:proxy).with_proxy(uri: "socks5://10.10.0.1:51432").get("https://google.pt")

# no proxy
HTTPX.plugin(:proxy).with_proxy(uri: "http://10.10.0.1:51432", no_proxy: ["dn.pt", /.*\.google\.com/]).get("http://dn.pt")

Authentication

httpx supports proxy authentication for all the supported HTTP authentication schemes:

proxy_http = HTTPX.plugin(:proxy)
# will do basic auth by default
proxy_http.with_proxy(uri: "http://10.10.0.1:51432", username: "user", password: "password").get("http://dn.pt")
# can also explicitly call basic auth
proxy_http.with_proxy_basic_auth(uri: "http://10.10.0.1:51432", username: "user", password: "password").get("http://dn.pt")
# proxy digest auth (since v0.20)
proxy_http.with_proxy_digest_auth(uri: "http://10.10.0.1:51432", username: "user", password: "password").get("http://dn.pt")
# proxy ntlm auth (since v0.20)
proxy_http.with_proxy_ntlm_auth(uri: "http://10.10.0.1:51432", username: "user", password: "password").get("http://dn.pt")

SSH

This plugin creates an SSH connection (using the net-ssh-gateway gem) and tunnels all requests from the session through it.

session = HTTPX.plugin(:"proxy/ssh")
               .with_proxy(uri: "ssh://10.10.0.1:51432",
                           username: "root",
                           password: "root")
response = session.get("https://google.pt")

ENV http_proxy/https_proxy/no_proxy

If the proxy environment variables are defined, HTTPX will load with the :proxy plugin turned on by default. It will therefore route or not route the requests through a proxy based on those environment variables.

FAQ

What about socks5h?

“socks5h” is an old nomenclature for “socks5 and DNS resolution done in proxy”. However in practice, most implementations in the wild of socks5 default to sendig the domain to be resolved from the proxy, so they’re socks5h-compliant by default, and the :proxy plugin implementation of httpx is no exception. Next: Auth