Skip to content

About

Send and receive custom proxy headers during HTTPS CONNECT tunneling. Extensions for Faraday, HTTParty, HTTP.rb, Typhoeus, Excon, RestClient.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Ruby Proxy Headers

Gem Version

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.

The Problem

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

  1. Custom proxy headers on the CONNECT request to the proxy.
  2. 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.

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.

Supported Libraries

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.

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.

Quick Start

Examples for each supported client:

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

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')
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.

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' }, # optional
  connection_adapter: RubyProxyHeaders::ProxyHeadersConnectionAdapter
)

puts RubyProxyHeaders.proxy_connect_response_headers['X-ProxyMesh-IP']

HTTP.rb

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

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']

Typhoeus

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

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

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 -v

Unit and integration tests do not need a proxy:

bundle exec rspec

Documentation

API reference and runnable examples:

Other languages

Sibling header libraries for other runtimes:

Why ProxyMesh

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.

License

MIT License

About

Send and receive custom proxy headers during HTTPS CONNECT tunneling. Extensions for Faraday, HTTParty, HTTP.rb, Typhoeus, Excon, RestClient.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages