Send custom proxy headers on HTTPS CONNECT and read proxy response headers back in Ruby HTTP clients. Works with any proxy provider; works best with ProxyMesh.
Most Ruby HTTP clients use Net::HTTP, Faraday, or libcurl without exposing:
- Custom proxy headers on the
CONNECTrequest to the proxy. - The proxy response headers from the CONNECT request (often discarded after the tunnel is established).
This library adds opt-in support for Net::HTTP, Faraday (2.x via faraday-net_http), HTTParty, and documents Excon’s built-in :ssl_proxy_headers for sends.
- Geo-targeting at tunnel setup: Send country/session directives on
CONNECT. - Sticky-session observability: Read proxy-assigned headers like
X-ProxyMesh-IP. - Works with common Ruby stacks: Useful for scraping and API clients using Net::HTTP-based flows.
Integration coverage at a glance:
| Client | Proxy headers on CONNECT | Proxy response headers |
|---|---|---|
| Net::HTTP | Yes | Yes |
Faraday (2.x + faraday-net_http) |
Yes | Yes |
| HTTParty | Yes | Yes (thread-local or adapter) |
| HTTP.rb | Yes | Yes |
| RestClient | Yes | Yes |
| Typhoeus | Yes | Yes |
| Excon | Yes (send-only) | No — CONNECT response not exposed on the origin response |
| Mechanize | Not supported | Not supported |
Mechanize uses net-http-persistent; this gem does not integrate it. Use patched Net::HTTP or Faraday when custom CONNECT headers are required.
gem install ruby-proxy-headersOr add to your Gemfile:
gem 'ruby-proxy-headers'The Net::HTTP patch is pure Ruby. Install faraday, faraday-net_http, httparty, and/or excon when you use those integrations.
Examples for each supported client:
require 'uri'
require 'openssl'
require 'ruby_proxy_headers/net_http'
RubyProxyHeaders::NetHTTP.patch!
uri = URI('https://api.ipify.org?format=json')
proxy = URI(ENV.fetch('PROXY_URL'))
http = Net::HTTP.new(uri.host, uri.port, proxy.host, proxy.port, proxy.user, proxy.password)
http.use_ssl = true
# Optional: headers to send on CONNECT (e.g. sticky IP)
http.proxy_connect_request_headers = { 'X-ProxyMesh-IP' => '203.0.113.1' }
res = http.request(Net::HTTP::Get.new(uri))
puts res.body
puts http.last_proxy_connect_response_headers['X-ProxyMesh-IP']Call RubyProxyHeaders::NetHTTP.patch! once before creating connections. You can also read the proxy response headers from the last proxied HTTPS request on the current thread via RubyProxyHeaders.proxy_connect_response_headers.
require 'ruby_proxy_headers/faraday'
conn = RubyProxyHeaders::FaradayIntegration.connection(
proxy: ENV.fetch('PROXY_URL'),
proxy_connect_headers: { 'X-ProxyMesh-Country' => 'US' } # optional
)
res = conn.get('https://api.ipify.org?format=json')
puts res.headers['X-ProxyMesh-IP']Uses the registered adapter :ruby_proxy_headers_net_http, which merges proxy response headers from the CONNECT request into Faraday’s response headers.
require 'httparty'
require 'ruby_proxy_headers/httparty'
RubyProxyHeaders::NetHTTP.patch!
proxy = URI(ENV.fetch('PROXY_URL'))
HTTParty.get(
'https://api.ipify.org?format=json',
http_proxyaddr: proxy.host,
http_proxyport: proxy.port,
http_proxyuser: proxy.user,
http_proxypass: proxy.password,
proxy_connect_request_headers: { 'X-ProxyMesh-IP' => '203.0.113.1' }, # optional
connection_adapter: RubyProxyHeaders::ProxyHeadersConnectionAdapter
)
puts RubyProxyHeaders.proxy_connect_response_headers['X-ProxyMesh-IP']Requires the http gem 6 or newer. Proxy headers are sent on CONNECT by HTTP.rb itself.
require 'ruby_proxy_headers/http_gem'
client = RubyProxyHeaders::HTTPGem.create_client(
proxy: 'http://user:pass@proxy.example.com:31280',
proxy_headers: { 'X-ProxyMesh-Country' => 'US' }
)
response = client.get('https://api.ipify.org?format=json')
puts response.proxy_response_headers['X-ProxyMesh-IP']RestClient performs the request. The Net::HTTP patch adds the CONNECT headers.
require 'ruby_proxy_headers/rest_client'
response = RubyProxyHeaders::RestClient.get(
'https://api.ipify.org?format=json',
proxy: 'http://user:pass@proxy.example.com:31280',
proxy_headers: { 'X-ProxyMesh-Country' => 'US' }
)
puts response.proxy_response_headers['X-ProxyMesh-IP']Requires Typhoeus 1.7. Proxy headers go to libcurl as CURLOPT_PROXYHEADER and are not copied onto the origin request. Header names are documented at https://docs.proxymesh.com/.
require 'ruby_proxy_headers/typhoeus'
response = RubyProxyHeaders::Typhoeus.get(
'https://api.ipify.org?format=json',
proxy: 'http://user:pass@proxy.example.com:31280',
proxy_headers: { 'X-ProxyMesh-Country' => 'US' }
)
puts response.proxy_response_headers['X-ProxyMesh-IP']response.headers remains the origin response.
Excon supports sending extra headers on CONNECT with :ssl_proxy_headers. Reading X-ProxyMesh-IP from the CONNECT response is not exposed on the origin response object.
require 'ruby_proxy_headers/excon'
RubyProxyHeaders::ExconIntegration.get(
'https://api.ipify.org?format=json',
proxy_url: ENV.fetch('PROXY_URL'),
proxy_connect_headers: { 'X-ProxyMesh-Country' => 'US' } # optional
)Same environment variables as python-proxy-headers:
| Variable | Role |
|---|---|
PROXY_URL |
Proxy URL (required for live tests) |
TEST_URL |
Target HTTPS URL (default https://api.ipify.org?format=json) |
PROXY_HEADER |
Header to read from CONNECT response (default X-ProxyMesh-IP) |
SEND_PROXY_HEADER |
Optional header name to send on CONNECT |
SEND_PROXY_VALUE |
Optional value for that header |
cd ruby-proxy-headers
bundle install
export PROXY_URL=http://user:pass@proxy.example.com:31280
bundle exec ruby test/test_proxy_headers.rb -vUnit and integration tests do not need a proxy:
bundle exec rspecAPI reference and runnable examples:
Sibling header libraries for other runtimes:
ProxyMesh created this library to help customers use custom headers to control proxy behavior, as documented at docs.proxymesh.com. It works with any proxy that supports custom headers on CONNECT.
MIT License