Ruby Proxy Headers

Send and receive custom proxy headers during HTTPS CONNECT tunneling in modern Ruby HTTP workflows (for example ProxyMeshX-ProxyMesh-IP / X-ProxyMesh-Country).

The problem

Most Ruby HTTP clients use Net::HTTP, Faraday, or libcurl without exposing:

1. Extra headers on the CONNECT request to the proxy.
2. Headers from the proxy’s CONNECT response (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.

Why teams use this

• 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.

Installation

gem install ruby-proxy-headers

Or 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.

Net::HTTP

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))putsres.bodyputshttp.last_proxy_connect_response_headers['X-ProxyMesh-IP']

Call RubyProxyHeaders::NetHTTP.patch! once before creating connections. You can also read the last CONNECT response headers on the current thread via RubyProxyHeaders.proxy_connect_response_headers.

Faraday

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')putsres.headers['X-ProxyMesh-IP']

Uses the registered adapter :ruby_proxy_headers_net_http, which merges proxy CONNECT response headers into Faraday’s response headers.

HTTParty

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'},# optionalconnection_adapter: RubyProxyHeaders::ProxyHeadersConnectionAdapter)putsRubyProxyHeaders.proxy_connect_response_headers['X-ProxyMesh-IP']

Excon (send-only; CONNECT response headers)

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 — see DEFERRED.md.

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)

Testing (live proxy)

Same environment variables as python-proxy-headers:

Variable	Role
PROXY_URL	Proxy URL (required for 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@proxyhost:port
bundle exec ruby test/test_proxy_headers.rb -v

Related

• python-proxy-headers
• javascript-proxy-headers
• proxy-examples (Ruby)