Routing Ruby HTTP Requests Through an Authenticated Proxy
By the ProxyV4 Engineering Team · Updated:
In Ruby's standard library you set a proxy by passing its address, port, username and password as the third to sixth arguments of Net::HTTP.start or Net::HTTP.new. Faraday and HTTParty wrap the same mechanism with friendlier options. The part that surprises people is the environment: Net::HTTP reads http_proxy even for HTTPS requests and never looks at https_proxy.
The Ruby Net::HTTP proxy arguments
The proxy goes into positional arguments after the target host and port, in the order address, port, user, password. Keyword options such as use_ssl follow. This script makes one HTTPS request and prints the IP the server saw:
require 'net/http'
require 'json'
uri = URI('https://proxyv4.com/api/my-ip')
Net::HTTP.start(uri.host, uri.port,
'203.0.113.10', PORT, 'USER', 'PASS',
use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|
res = http.request(Net::HTTP::Get.new(uri))
puts "#{res.code} exit IP: #{JSON.parse(res.body)['ip']}"
endIf the printed IP is your server's own address, the arguments were probably shifted by one position, a mistake that is easy to make with six positional values. Check http.proxy? and http.proxy_address inside the block when in doubt.
Net::HTTP.new and the no-proxy argument
Net::HTTP.new takes the same proxy arguments, plus a seventh: a comma-separated list of hosts that should bypass the proxy. That is handy when one code path talks to both an external API and an internal service.
http = Net::HTTP.new('example.com', 443,
'203.0.113.10', PORT, 'USER', 'PASS',
'localhost,.internal.example') # p_no_proxy
http.use_ssl = true
http.proxy? # => true
http.proxy_address # => "203.0.113.10"The Net::HTTP::Proxy class factory
Older code often uses Net::HTTP::Proxy(addr, port, user, pass), which returns a subclass of Net::HTTP with the proxy baked in. It still works, but passing the arguments to start or new is clearer and does not create a new class per proxy.
What :ENV does, and why https_proxy is ignored
The proxy address argument defaults to the symbol :ENV. In that mode Net::HTTP asks URI to find a proxy for the target, and it builds that lookup with the http scheme regardless of use_ssl. The result: only http_proxy (and no_proxy) is consulted, even for HTTPS. Many deploys set just https_proxy, as curl expects, and are then confused when Ruby goes direct.
- Set
http_proxy=http://USER:[email protected]:PORTfor Net::HTTP to pick up the environment. Use the lowercase name; the uppercase one is skipped in CGI-style environments. - Credentials inside the variable are used and URL-decoded, so percent-encode
@,:and/in the password. no_proxyentries match host suffixes and are honored in:ENVmode.- Faraday, by contrast, picks the variable that matches the target scheme, so it does read
https_proxyfor HTTPS URLs.
Turning the environment off
Pass nil as the proxy address to make a connection ignore the variables entirely. This is worth doing for health checks and internal calls in containers where a platform injects http_proxy globally.
# Ignore http_proxy / no_proxy completely for this connection
http = Net::HTTP.new('example.com', 443, nil)
# Or rely on the environment explicitly (this is the default)
http = Net::HTTP.new('example.com', 443, :ENV)Faraday proxy configuration
Faraday accepts a proxy option as a URL string or a hash with uri, user and password keys. Credentials in the URL are fine as long as they are percent-encoded. With the raise_error middleware, HTTP errors become exceptions, which makes proxy problems loud rather than silent:
require 'faraday'
conn = Faraday.new(
url: 'https://proxyv4.com',
proxy: 'http://USER:[email protected]:PORT',
request: { open_timeout: 10, timeout: 30 }
) do |f|
f.response :raise_error
end
puts conn.get('/api/my-ip').bodyWhen no proxy option is given, Faraday falls back to the environment variables and respects no_proxy. To make code paths predictable in a large app, switch that off globally and pass the proxy explicitly where you want it:
# Stop every Faraday connection from reading proxy variables
Faraday.ignore_env_proxy = trueThe proxy option works with the default net_http adapter and with most others; adapter-specific limits are noted in each adapter gem's documentation.
HTTParty proxy options
HTTParty hands four options straight to Net::HTTP: http_proxyaddr, http_proxyport, http_proxyuser and http_proxypass. Use them per call, or declare the proxy once on a class that includes HTTParty:
require 'httparty'
# Per request
res = HTTParty.get('https://proxyv4.com/api/my-ip',
http_proxyaddr: '203.0.113.10',
http_proxyport: PORT,
http_proxyuser: 'USER',
http_proxypass: 'PASS',
timeout: 30)
puts res.parsed_response['ip']
# Or for every call made through a client class
class PartnerApi
include HTTParty
base_uri 'https://api.example.com'
http_proxy '203.0.113.10', PORT, 'USER', 'PASS'
endBecause HTTParty sits on Net::HTTP, the http_proxy-only environment rule from the previous section applies whenever you do not pass the options. Setting them explicitly avoids that trap.
Ruby SOCKS proxy options
Neither Net::HTTP nor Faraday's default adapter speaks SOCKS. The usual add-on is the socksify gem, which adds a Net::HTTP.socks_proxy class method returning a proxied subclass; recent versions take username: and password: keywords for SOCKS5 login.
# gem install socksify
require 'socksify/http'
uri = URI('https://proxyv4.com/api/my-ip')
proxied = Net::HTTP.socks_proxy('203.0.113.10', PORT,
username: 'USER', password: 'PASS')
proxied.start(uri.host, uri.port, use_ssl: true) do |http|
puts http.get(uri.path).body
endAvoid the global socksify switch
socksify can also patch TCPSocket globally so every connection in the process goes through SOCKS. In a Rails app that includes database and Redis connections, so prefer the per-class socks_proxy form shown above.
Or skip SOCKS entirely
For plain web requests, an HTTP proxy gives the same exit IP and the same end-to-end TLS with zero extra gems. If your provider lets you enable both protocols on one port, use HTTP mode for Net::HTTP, Faraday and HTTParty, and keep SOCKS5 for tools that need it. The trade-offs are laid out in the HTTP vs SOCKS5 guide.
Static IPs for Rails background workers
Sidekiq or Active Job workers that call partner APIs are a classic place for a fixed outbound IP: the partner registers one address, rate limits follow that address, and autoscaled worker hosts all leave through it. A ProxyV4 private datacenter IPv4 is used by one tenant for the whole term and keeps the same address when you renew before expiry, so the registration does not break between deploys. Traffic is not metered, which suits workers that sync large exports.
Every proxy supports HTTP(S) and SOCKS5 with username and password, and per order you choose HTTP only, SOCKS5 only or both on one port. Switching modes can move the proxy to a new port, so update your credentials store from the order page after a change. It is not the right product if a target accepts only mobile IPs or if you need a new address per request, because rotating proxies are not on sale; IPv6 proxies are a separate product that only works on IPv6-ready sites. Buy a single IP from live pricing, point one worker at it, and scale once it behaves. A proxy that fails for a technical reason is covered by the refund policy as account credit.
Exceptions worth rescuing
Proxy failures surface in a small set of exception classes. Rescue them separately so logs say whether the proxy refused you or could not be reached:
begin
Net::HTTP.start(uri.host, uri.port, PROXY_IP, PROXY_PORT, USER, PASS,
use_ssl: true, open_timeout: 10) { |h| h.get(uri.path) }
rescue Net::HTTPClientException => e
warn "proxy refused the tunnel: #{e.message}" # 407 "Proxy Authentication Required"
rescue Errno::ECONNREFUSED, Net::OpenTimeout => e
warn "proxy unreachable: #{e.class}: #{e.message}"
endNet::HTTPClientExceptionwith407 "Proxy Authentication Required": the proxy rejected theCONNECTlogin on an HTTPS request. Ruby before 2.6 calls this classNet::HTTPServerException. For plainhttp://targets you get aNet::HTTPProxyAuthenticationRequiredresponse object instead of an exception. The 407 error page lists every cause.Errno::ECONNREFUSEDwithFailed to open TCP connection to 203.0.113.10:PORT: wrong port, or the proxy moved after a mode change.Net::OpenTimeout: the proxy port never answered, usually a firewall. Withoutopen_timeout, the default is 60 seconds per attempt; see the proxy timeout guide.Faraday::ConnectionFailedandFaraday::ProxyAuthError: Faraday's wrappers for the same two situations.
Frequently asked questions
Why does Ruby ignore my https_proxy variable?
Net::HTTP looks up the environment proxy using the http scheme, so it only reads http_proxy and no_proxy. Set http_proxy as well, or pass the proxy explicitly.
How do I check which proxy a Net::HTTP connection uses?
Call http.proxy?, http.proxy_address and http.proxy_port on the connection object, then request an IP echo endpoint to confirm the exit address.
Can I use a different proxy for each Sidekiq job?
Yes. Pass the proxy arguments when you open the connection inside the job, choosing from a list in your config. Avoid global settings such as environment variables if jobs need different IPs.
Does Ruby support SOCKS5 proxies with authentication?
Not in the standard library. The socksify gem adds SOCKS support to Net::HTTP, and recent versions accept a username and password; ProxyV4 proxies accept SOCKS5 logins when that mode is enabled on the order.
Will my proxy IP change when I renew it?
Not with ProxyV4: renewing before expiry keeps the same address, so partner registrations tied to the IP keep working.
Fixed IPs for Ruby and Rails jobs
Give your workers a private IPv4 that only you use and that stays the same on renewal, with HTTP(S) and SOCKS5 login and unmetered traffic. Start with one IP and add more as jobs grow.
Get a static IP