ruby-proxy-headers 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a39a089e5181641efdaa2920edfd958bc127311e54be9942fdf5ae563ded24a
+  data.tar.gz: 0c138a06ea8d8b6dad7ed943b40e67964d05b0daf680e68ac1825a565647596a
+SHA512:
+  metadata.gz: 5efd2419ca3cc85309f54823e5a98b59b465cbf98bc32b39503aa9ff11b14732fef71cc6bd5bdb413083b1addeb269bb22b4bdc5093cac29083419823173a234
+  data.tar.gz: 4fbaf515b270d7544a70bbfab697fe5594820161733290761367f6daee2d225484f3baaea9283420a1230a088a5dd981d7ca9d6a2c7a44f2c5a07e585cb66aa8

data/DEFERRED.md

@@ -0,0 +1,29 @@
+# Deferred / not fully supported
+
+## Typhoeus / Ethon
+
+**Status:** Not implemented in this gem.
+
+[Ethon](https://github.com/typhoeus/ethon) does not expose `CURLOPT_PROXYHEADER` (or equivalent) in its `Ethon::Easy` option mapping as of ethon 0.18.x. Adding CONNECT response header capture would require Ethon/libcurl changes or a custom C extension.
+
+**Workaround:** Use `Net::HTTP` + {RubyProxyHeaders::NetHTTP.patch!} or Faraday with `ruby_proxy_headers_net_http` adapter.
+
+---
+
+## Mechanize
+
+**Status:** Not implemented.
+
+[Mechanize](https://github.com/sparklemotion/mechanize) uses [net-http-persistent](https://github.com/drbrain/net-http-persistent), which maintains its own connection layer on top of `Net::HTTP`. Our prepend patch targets `Net::HTTP#connect` on instances Mechanize creates, but verifying header propagation and lifecycle across the persistent pool needs dedicated work.
+
+**Workaround:** Use patched `Net::HTTP` or Faraday for fetches; use Mechanize only when custom CONNECT headers are not required.
+
+---
+
+## Excon — reading CONNECT response headers
+
+**Status:** Sending extra CONNECT headers is supported upstream via `:ssl_proxy_headers`.
+
+Excon’s public `Excon::Response` for the **origin** request does **not** include headers from the proxy’s `CONNECT` response (only the tunneled HTTPS response headers). Capturing `X-ProxyMesh-IP` from CONNECT would require patching Excon internals or a fork.
+
+**Workaround:** Use Net::HTTP / Faraday integrations in this gem, which merge CONNECT headers into the client response where applicable.

data/IMPLEMENTATION_PRIORITY.md

@@ -0,0 +1,72 @@
+# ruby-proxy-headers — implementation plan
+
+Prioritized roadmap for extension modules, aligned with [javascript-proxy-headers](https://github.com/proxymesh/javascript-proxy-headers) and [python-proxy-headers](https://github.com/proxymesh/python-proxy-headers).
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    ruby-proxy-headers                        │
+├─────────────────────────────────────────────────────────────┤
+│  Faraday / HTTParty / Excon helpers                        │
+│       │                                                      │
+│       ▼                                                      │
+│  Net::HTTP patch — CONNECT send + capture + thread-local   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Phase 1 — Net::HTTP core (**done — v0.1+**)
+
+- `RubyProxyHeaders::NetHTTP.patch!` extends `Net::HTTP#connect` for HTTPS + proxy.
+- `last_proxy_connect_response_headers` on the `Net::HTTP` instance.
+- `Thread.current[:ruby_proxy_headers_connect_headers]` + `RubyProxyHeaders.proxy_connect_response_headers` for cross-library reads.
+
+**File:** `lib/ruby_proxy_headers/net_http.rb`
+
+---
+
+## Phase 2 — Faraday (**done — v0.2+**)
+
+- Adapter `ruby_proxy_headers_net_http` (subclass of `Faraday::Adapter::NetHttp`) merges CONNECT response headers into Faraday response headers.
+- Helper `RubyProxyHeaders::FaradayIntegration.connection(...)`.
+
+**File:** `lib/ruby_proxy_headers/faraday.rb`
+
+---
+
+## Phase 3 — HTTParty (**done — v0.2+**)
+
+- `RubyProxyHeaders::ProxyHeadersConnectionAdapter` — pass `proxy_connect_request_headers` in HTTParty options.
+
+**File:** `lib/ruby_proxy_headers/httparty.rb`
+
+---
+
+## Phase 4 — Typhoeus / Ethon (**deferred**)
+
+Ethon does not expose libcurl `CURLOPT_PROXYHEADER` in its option layer. See [DEFERRED.md](DEFERRED.md).
+
+---
+
+## Phase 5 — Excon (**partial — v0.2+**)
+
+- **Sending** extra CONNECT headers: supported upstream via `:ssl_proxy_headers`; `RubyProxyHeaders::ExconIntegration.get` passes them through.
+- **Reading** CONNECT response headers: not exposed on `Excon::Response` for the tunneled request. See [DEFERRED.md](DEFERRED.md).
+
+**File:** `lib/ruby_proxy_headers/excon.rb`
+
+---
+
+## Phase 6 — Mechanize (**deferred**)
+
+Uses `net-http-persistent`; needs dedicated integration. See [DEFERRED.md](DEFERRED.md).
+
+---
+
+## Testing
+
+`bundle exec ruby test/test_proxy_headers.rb` with `PROXY_URL` set. Modules: `net_http`, `faraday`, `httparty`, `excon` (excon is a smoke test; CONNECT response headers are not asserted).
+
+---
+
+*Updated: March 2026*

data/LIBRARY_RESEARCH.md

@@ -0,0 +1,71 @@
+# Ruby library proxy header support (CONNECT tunnel)
+
+This document analyzes the Ruby HTTP / scraping stack used in [proxy-examples](https://github.com/proxymesh/proxy-examples/tree/main/ruby) for **custom headers on HTTPS `CONNECT`** and **reading the proxy `CONNECT` response headers**.
+
+## Executive summary
+
+| Library | Native CONNECT header API | Extension approach |
+|---------|---------------------------|---------------------|
+| **Net::HTTP** (stdlib) | No — tunnel is hard-coded in `#connect` | **Implemented:** prepend patch; optional `proxy_connect_request_headers`; `last_proxy_connect_response_headers` |
+| **Faraday** | No — delegates to adapters (`net_http`, etc.) | **High:** use patched `Net::HTTP` with `Faraday.new(connection_options)` or custom adapter that sets `proxy_connect_request_headers` |
+| **HTTParty** | No — built on `Net::HTTP` | **High:** global or per-class `Net::HTTP` instances after `patch!`; or subclass `Connection` if needed |
+| **Mechanize** | No — uses `Net::HTTP` / persistent connections internally | **Medium–high:** ensure Mechanize’s internal HTTP object gets the same patched behavior and header accessors |
+| **Excon** | **Send:** yes — `:ssl_proxy_headers` on connection. **Read CONNECT response:** not exposed on origin `Excon::Response` | **Partial:** use `:ssl_proxy_headers` for sends; reading `X-ProxyMesh-IP` from CONNECT needs upstream Excon changes (see [DEFERRED.md](DEFERRED.md)) |
+| **Typhoeus / Ethon** | Partial — libcurl has proxy options | **Medium:** map headers to `CURLOPT_PROXYHEADER` / related options (libcurl version dependent); capture CONNECT response via callbacks or debug hooks where supported |
+| **Nokogiri** | N/A (XML/HTML parser only) | **N/A** — proxying is whatever HTTP client fetches the document (usually `Net::HTTP`) |
+
+As with Node and Python stacks, **none** of the high-level Ruby clients expose a first-class “proxy CONNECT request/response headers” API; extensions must hook **below** the HTTP library (stdlib `Net::HTTP`), **inside** Faraday’s adapter, or **at** the libcurl / Excon layer.
+
+## Connection flow (HTTPS over HTTP proxy)
+
+```
+Client -- CONNECT + custom headers --> Proxy
+Client <-- CONNECT response headers --- Proxy
+Client === TLS tunnel =================> Origin
+```
+
+## Net::HTTP (stdlib)
+
+MRI implements the tunnel in `Net::HTTP#connect` (see `net/http.rb`): it writes `CONNECT host:port`, `Host`, optional `Proxy-Authorization`, then reads the response with `Net::HTTPResponse.read_new` and calls `#value` without exposing headers to callers.
+
+**Feasibility:** High — same pattern as Python’s `HTTPSConnection._tunnel` override in `python-proxy-headers`.
+
+## Faraday
+
+Uses adapters; default `net_http` adapter constructs `Net::HTTP`. If `Net::HTTP` is patched and exposes `proxy_connect_request_headers`, Faraday can pass options through `connection` / `request` options in a thin wrapper.
+
+**Feasibility:** High once `Net::HTTP` support is stable.
+
+## HTTParty
+
+Uses `Net::HTTP` under the hood for sync requests. After `RubyProxyHeaders::NetHTTP.patch!`, new `Net::HTTP` objects support the new accessors.
+
+**Feasibility:** High — may need documented patterns for `default_options` and connection lifecycle.
+
+## Mechanize
+
+Builds on `net/http` (often `net-http-persistent`). May require verifying that the patched `connect` runs for its connections and that response/header capture is visible on the right object.
+
+**Feasibility:** Medium.
+
+## Excon
+
+Own implementation of proxy and TLS; does not use `Net::HTTP#connect`.
+
+**Feasibility:** Medium — requires a dedicated Excon middleware or socket layer similar to the JavaScript core agent.
+
+## Typhoeus / Ethon (libcurl)
+
+libcurl can send additional headers to the proxy; exact options depend on libcurl version (e.g. proxy header lists). CONNECT response header visibility may require `CURLOPT_DEBUGFUNCTION` or version-specific features.
+
+**Feasibility:** Medium — needs research per libcurl version and Ethon API surface.
+
+## Nokogiri
+
+Parsing only; no network layer.
+
+**Feasibility:** N/A — combine with `Net::HTTP` + patch or another extended client.
+
+---
+
+*Last updated: March 2026*

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProxyMesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+# Ruby Proxy Headers
+
+Send and receive custom proxy headers during HTTPS `CONNECT` tunneling in modern Ruby HTTP workflows (for example [ProxyMesh](https://proxymesh.com) `X-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
+
+```bash
+gem install ruby-proxy-headers
+```
+
+Or add to your `Gemfile`:
+
+```ruby
+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
+
+```ruby
+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 last CONNECT response headers on the current thread via `RubyProxyHeaders.proxy_connect_response_headers`.
+
+## Faraday
+
+```ruby
+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 `CONNECT` response headers into Faraday’s response headers.
+
+## HTTParty
+
+```ruby
+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']
+```
+
+## 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](DEFERRED.md).
+
+```ruby
+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](https://github.com/proxymesh/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 |
+
+```bash
+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](https://github.com/proxymesh/python-proxy-headers)
+- [javascript-proxy-headers](https://github.com/proxymesh/javascript-proxy-headers)
+- [proxy-examples (Ruby)](https://github.com/proxymesh/proxy-examples/tree/main/ruby)

data/lib/ruby_proxy_headers/connection.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'openssl'
+require 'uri'
+
+module RubyProxyHeaders
+  # Handles HTTPS CONNECT tunneling with custom proxy headers.
+  # This is the core component that manages the proxy connection,
+  # sends custom headers, and captures proxy response headers.
+  class Connection
+    attr_reader :proxy_response_headers, :proxy_response_status, :socket
+
+    # @param proxy [String, Hash] Proxy URL or hash with :host, :port, :user, :password
+    # @param options [Hash] Connection options
+    # @option options [Hash] :proxy_headers Custom headers to send during CONNECT
+    # @option options [Integer] :connect_timeout Connection timeout in seconds (default: 30)
+    # @option options [Boolean] :verify_ssl Verify SSL certificates (default: true)
+    def initialize(proxy, options = {})
+      @proxy = proxy.is_a?(String) ? RubyProxyHeaders.parse_proxy_url(proxy) : proxy
+      @proxy_headers = options[:proxy_headers] || {}
+      @connect_timeout = options[:connect_timeout] || 30
+      @verify_ssl = options.fetch(:verify_ssl, true)
+      @proxy_response_headers = {}
+      @proxy_response_status = nil
+      @socket = nil
+    end
+
+    # Establish a tunnel through the proxy to the target host.
+    # @param target_host [String] Target hostname
+    # @param target_port [Integer] Target port (default: 443)
+    # @return [OpenSSL::SSL::SSLSocket] TLS-wrapped socket to target
+    def connect(target_host, target_port = 443)
+      # Connect to proxy
+      @socket = TCPSocket.new(@proxy[:host], @proxy[:port])
+      @socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+
+      # Send CONNECT request with custom headers
+      connect_request = build_connect_request(target_host, target_port)
+      @socket.write(connect_request)
+
+      # Read and parse CONNECT response
+      response = read_connect_response
+      parse_connect_response(response)
+
+      # Check for successful connection
+      unless (200..299).cover?(@proxy_response_status)
+        @socket.close
+        raise_connect_error
+      end
+
+      # Upgrade to TLS
+      upgrade_to_tls(target_host)
+    end
+
+    # Close the connection
+    def close
+      @socket&.close
+    end
+
+    private
+
+    def build_connect_request(target_host, target_port)
+      request_lines = [
+        "CONNECT #{target_host}:#{target_port} HTTP/1.1",
+        "Host: #{target_host}:#{target_port}"
+      ]
+
+      # Add proxy authentication if provided
+      if @proxy[:user]
+        auth = RubyProxyHeaders.build_auth_header(@proxy[:user], @proxy[:password])
+        request_lines << "Proxy-Authorization: #{auth}"
+      end
+
+      # Add custom proxy headers
+      @proxy_headers.each do |name, value|
+        request_lines << "#{name}: #{value}"
+      end
+
+      request_lines << 'Proxy-Connection: keep-alive'
+      request_lines << ''
+      request_lines << ''
+
+      request_lines.join("\r\n")
+    end
+
+    def read_connect_response
+      response = String.new
+      loop do
+        line = @socket.gets
+        break if line.nil?
+
+        response << line
+        break if line == "\r\n" || line == "\n"
+      end
+      response
+    end
+
+    def parse_connect_response(response)
+      lines = response.split(/\r?\n/)
+      return if lines.empty?
+
+      # Parse status line
+      status_line = lines.shift
+      if (match = status_line.match(%r{HTTP/[\d.]+\s+(\d+)}))
+        @proxy_response_status = match[1].to_i
+      end
+
+      # Parse headers
+      @proxy_response_headers = {}
+      lines.each do |line|
+        break if line.empty?
+
+        if (header_match = line.match(/^([^:]+):\s*(.*)$/))
+          name = header_match[1].downcase
+          value = header_match[2]
+          @proxy_response_headers[name] = value
+        end
+      end
+    end
+
+    def upgrade_to_tls(target_host)
+      ssl_context = OpenSSL::SSL::SSLContext.new
+      ssl_context.verify_mode = @verify_ssl ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+
+      ssl_socket = OpenSSL::SSL::SSLSocket.new(@socket, ssl_context)
+      ssl_socket.hostname = target_host
+      ssl_socket.sync_close = true
+      ssl_socket.connect
+
+      @socket = ssl_socket
+    end
+
+    def raise_connect_error
+      case @proxy_response_status
+      when 407
+        raise ProxyAuthenticationError, "Proxy authentication required (407)"
+      else
+        raise ConnectError, "Proxy CONNECT failed with status #{@proxy_response_status}"
+      end
+    end
+  end
+end

data/lib/ruby_proxy_headers/excon.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+begin
+  require 'excon'
+rescue LoadError => e
+  raise LoadError, "excon is required for ruby_proxy_headers/excon (#{e.message})"
+end
+
+module RubyProxyHeaders
+  # Excon already supports extra CONNECT headers via +:ssl_proxy_headers+ (see
+  # Excon::SSLSocket). This module documents the mapping and a small helper.
+  #
+  # Reading CONNECT response headers is not exposed on Excon's public response
+  # object for the origin request; use thread-local {RubyProxyHeaders.proxy_connect_response_headers}
+  # only when the underlying transport is patched Net::HTTP, not Excon.
+  module ExconIntegration
+    module_function
+
+    # @param proxy_url [String]
+    # @param proxy_connect_headers [Hash] sent to the proxy during HTTPS CONNECT (Excon key: :ssl_proxy_headers)
+    # @param excon_opts [Hash] merged into Excon.get / Excon.new options
+    def get(url, proxy_url:, proxy_connect_headers: nil, **excon_opts)
+      opts = {
+        proxy: normalize_proxy_url(proxy_url),
+        ssl_proxy_headers: proxy_connect_headers,
+        ssl_verify_peer: true
+      }.merge(excon_opts)
+      Excon.get(url, opts)
+    end
+
+    def normalize_proxy_url(proxy_url)
+      s = proxy_url.to_s.strip
+      return s if s.match?(/\A[a-z][a-z0-9+\-.]*:\/\//i)
+
+      "http://#{s}"
+    end
+  end
+end

data/lib/ruby_proxy_headers/faraday.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'net_http'
+
+begin
+  require 'faraday'
+  require 'faraday/net_http'
+rescue LoadError => e
+  raise LoadError,
+        'faraday and faraday-net_http are required for ruby_proxy_headers/faraday ' \
+        "(#{e.message})"
+end
+
+module RubyProxyHeaders
+  # Faraday adapter that merges proxy CONNECT response headers into Faraday response headers.
+  # Use with {RubyProxyHeaders::NetHTTP.patch!}.
+  module FaradayAdapter
+    class NetHttp < ::Faraday::Adapter::NetHttp
+      def request_with_wrapped_block(http, env, &block)
+        res = super
+        merge_proxy_headers(env, http)
+        res
+      end
+
+      private
+
+      def merge_proxy_headers(env, http)
+        return unless env[:response_headers]
+        return unless http.respond_to?(:last_proxy_connect_response_headers)
+
+        ph = http.last_proxy_connect_response_headers
+        return unless ph.is_a?(Hash)
+
+        ph.each do |k, v|
+          next if v.nil?
+
+          env[:response_headers][k] ||= v
+        end
+      end
+    end
+  end
+end
+
+Faraday::Adapter.register_middleware(
+  ruby_proxy_headers_net_http: RubyProxyHeaders::FaradayAdapter::NetHttp
+)
+
+module RubyProxyHeaders
+  module FaradayIntegration
+    module_function
+
+    def patch!
+      RubyProxyHeaders::NetHTTP.patch!
+    end
+
+    # Builds a Faraday connection with the custom Net::HTTP adapter and optional CONNECT headers.
+    #
+    # @param proxy [String] proxy URL
+    # @param proxy_connect_headers [Hash, nil] headers to send on CONNECT (e.g. X-ProxyMesh-IP)
+    # @param url [String, nil] optional base URL
+    def connection(proxy:, proxy_connect_headers: nil, url: nil, &block)
+      patch!
+      opts = { proxy: proxy }
+      opts[:url] = url if url
+      ::Faraday.new(opts) do |f|
+        f.adapter :ruby_proxy_headers_net_http do |http|
+          http.proxy_connect_request_headers = proxy_connect_headers if proxy_connect_headers&.any?
+        end
+        yield f if block_given?
+      end
+    end
+  end
+end

data/lib/ruby_proxy_headers/http_gem.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RubyProxyHeaders
+  # HTTP.rb (http gem) integration for proxy headers support.
+  #
+  # @example
+  #   client = RubyProxyHeaders::HTTPGem.create_client(
+  #     proxy: 'http://user:pass@proxy:8080',
+  #     proxy_headers: { 'X-ProxyMesh-Country' => 'US' }
+  #   )
+  #   
+  #   response = client.get('https://example.com')
+  #   puts response.proxy_response_headers
+  #
+  module HTTPGem
+    # Create an HTTP client with proxy header support.
+    # @param proxy [String] Proxy URL
+    # @param proxy_headers [Hash] Custom headers to send to proxy
+    # @param options [Hash] Additional HTTP.rb options
+    # @return [ProxyClient]
+    def self.create_client(proxy:, proxy_headers: {}, **options)
+      ProxyClient.new(proxy: proxy, proxy_headers: proxy_headers, **options)
+    end
+
+    # Make a GET request with proxy headers.
+    def self.get(url, proxy:, proxy_headers: {}, **options)
+      create_client(proxy: proxy, proxy_headers: proxy_headers).get(url, **options)
+    end
+
+    # Make a POST request with proxy headers.
+    def self.post(url, proxy:, proxy_headers: {}, body: nil, **options)
+      create_client(proxy: proxy, proxy_headers: proxy_headers).post(url, body: body, **options)
+    end
+
+    # Proxy client wrapper for HTTP.rb
+    class ProxyClient
+      def initialize(proxy:, proxy_headers: {}, **options)
+        @proxy = proxy
+        @proxy_headers = proxy_headers
+        @options = options
+        @last_proxy_response_headers = nil
+      end
+
+      attr_reader :last_proxy_response_headers
+
+      def get(url, **options)
+        request(:get, url, **options)
+      end
+
+      def post(url, body: nil, **options)
+        request(:post, url, body: body, **options)
+      end
+
+      def put(url, body: nil, **options)
+        request(:put, url, body: body, **options)
+      end
+
+      def delete(url, **options)
+        request(:delete, url, **options)
+      end
+
+      private
+
+      def request(method, url, **options)
+        uri = URI.parse(url)
+
+        # Use our core connection for HTTPS
+        if uri.scheme == 'https'
+          response = RubyProxyHeaders::NetHTTP.request(
+            method,
+            url,
+            proxy: @proxy,
+            proxy_headers: @proxy_headers,
+            headers: options[:headers],
+            body: options[:body]
+          )
+          @last_proxy_response_headers = response.proxy_response_headers
+          return response
+        end
+
+        # For HTTP, use standard http gem
+        require 'http'
+
+        proxy_uri = URI.parse(@proxy)
+        ::HTTP.via(
+          proxy_uri.host,
+          proxy_uri.port,
+          proxy_uri.user,
+          proxy_uri.password
+        ).send(method, url, **options)
+      end
+    end
+  end
+end

data/lib/ruby_proxy_headers/httparty.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'net_http'
+
+begin
+  require 'httparty'
+rescue LoadError => e
+  raise LoadError, "httparty is required for ruby_proxy_headers/httparty (#{e.message})"
+end
+
+module RubyProxyHeaders
+  # Drop-in connection adapter: pass +:proxy_connect_request_headers+ in options
+  # (along with +http_proxyaddr+ / +http_proxyport+ / etc.).
+  #
+  # After the request, read CONNECT response headers via
+  # {RubyProxyHeaders.proxy_connect_response_headers} (thread-local).
+  class ProxyHeadersConnectionAdapter < HTTParty::ConnectionAdapter
+    def connection
+      http = super
+      if http.respond_to?(:proxy_connect_request_headers=)
+        h = options[:proxy_connect_request_headers] || options[:proxy_connect_headers]
+        http.proxy_connect_request_headers = h if h&.any?
+      end
+      http
+    end
+  end
+end

data/lib/ruby_proxy_headers/net_http.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'net/protocol'
+require 'openssl'
+require 'resolv'
+require 'timeout'
+
+module RubyProxyHeaders
+  # Patches Net::HTTP#connect for HTTPS-over-proxy so extra headers can be sent on
+  # the CONNECT request and response headers can be read (e.g. ProxyMesh
+  # X-ProxyMesh-IP). Based on the same tunnel flow as Python's http.client / urllib3
+  # extensions in python-proxy-headers.
+  #
+  # @example
+  #   require 'ruby_proxy_headers/net_http'
+  #   RubyProxyHeaders::NetHTTP.patch!
+  #
+  #   http = Net::HTTP.new(uri.host, uri.port, proxy.host, proxy.port, proxy.user, proxy.password)
+  #   http.use_ssl = true
+  #   http.proxy_connect_request_headers = { 'X-ProxyMesh-IP' => '203.0.113.1' }
+  #   res = http.request(Net::HTTP::Get.new(uri))
+  #   p http.last_proxy_connect_response_headers
+  module NetHTTP
+    unless const_defined?(:ORIGINAL_CONNECT, false)
+      ORIGINAL_CONNECT = ::Net::HTTP.instance_method(:connect)
+    end
+
+    module Extension
+      attr_accessor :proxy_connect_request_headers
+      attr_reader :last_proxy_connect_response_headers
+
+      def connect
+        if use_ssl? && proxy?
+          connect_with_proxy_tunnel
+        else
+          RubyProxyHeaders::NetHTTP::ORIGINAL_CONNECT.bind_call(self)
+        end
+      end
+
+      private
+
+      # Duplicates Net::HTTP#connect (MRI 3.2) for the HTTPS + proxy branch, with
+      # optional extra CONNECT headers and capture of the CONNECT response headers.
+      def connect_with_proxy_tunnel
+        s = nil
+        if use_ssl?
+          @ssl_context = OpenSSL::SSL::SSLContext.new
+        end
+
+        if proxy?
+          conn_addr = proxy_address
+          conn_port = proxy_port
+        else
+          conn_addr = conn_address
+          conn_port = port
+        end
+
+        debug "opening connection to #{conn_addr}:#{conn_port}..."
+        s = Timeout.timeout(@open_timeout, Net::OpenTimeout) do
+          begin
+            TCPSocket.open(conn_addr, conn_port, @local_host, @local_port)
+          rescue StandardError => e
+            raise e, "Failed to open TCP connection to " \
+              "#{conn_addr}:#{conn_port} (#{e.message})"
+          end
+        end
+        s.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+        debug 'opened'
+
+        if use_ssl?
+          if proxy?
+            plain_sock = Net::BufferedIO.new(s, read_timeout: @read_timeout,
+                                            write_timeout: @write_timeout,
+                                            continue_timeout: @continue_timeout,
+                                            debug_output: @debug_output)
+            buf = +"CONNECT #{conn_address}:#{@port} HTTP/#{::Net::HTTP::HTTPVersion}\r\n" \
+              "Host: #{@address}:#{@port}\r\n"
+            if proxy_user
+              credential = ["#{proxy_user}:#{proxy_pass}"].pack('m0')
+              buf << "Proxy-Authorization: Basic #{credential}\r\n"
+            end
+            if proxy_connect_request_headers&.any?
+              proxy_connect_request_headers.each do |k, v|
+                buf << "#{k}: #{v}\r\n"
+              end
+            end
+            buf << "\r\n"
+            plain_sock.write(buf)
+
+            proxy_res = ::Net::HTTPResponse.read_new(plain_sock)
+            @last_proxy_connect_response_headers = {}
+            proxy_res.each_header do |k, v|
+              @last_proxy_connect_response_headers[k] = v
+            end
+            Thread.current[:ruby_proxy_headers_connect_headers] = @last_proxy_connect_response_headers.dup
+            proxy_res.value
+          end
+
+          ssl_parameters = {}
+          iv_list = instance_variables
+          Net::HTTP::SSL_IVNAMES.each_with_index do |ivname, i|
+            if iv_list.include?(ivname)
+              value = instance_variable_get(ivname)
+              unless value.nil?
+                ssl_parameters[Net::HTTP::SSL_ATTRIBUTES[i]] = value
+              end
+            end
+          end
+          @ssl_context.set_params(ssl_parameters)
+          unless @ssl_context.session_cache_mode.nil?
+            @ssl_context.session_cache_mode =
+              OpenSSL::SSL::SSLContext::SESSION_CACHE_CLIENT |
+              OpenSSL::SSL::SSLContext::SESSION_CACHE_NO_INTERNAL_STORE
+          end
+          if @ssl_context.respond_to?(:session_new_cb)
+            @ssl_context.session_new_cb = proc { |sock, sess| @ssl_session = sess }
+          end
+
+          verify_hostname = @ssl_context.verify_hostname
+
+          case @address
+          when Resolv::IPv4::Regex, Resolv::IPv6::Regex
+            @ssl_context.verify_hostname = false
+          else
+            ssl_host_address = @address
+          end
+
+          debug "starting SSL for #{conn_addr}:#{conn_port}..."
+          s = OpenSSL::SSL::SSLSocket.new(s, @ssl_context)
+          s.sync_close = true
+          s.hostname = ssl_host_address if s.respond_to?(:hostname=) && ssl_host_address
+
+          if @ssl_session &&
+             Process.clock_gettime(Process::CLOCK_REALTIME) < @ssl_session.time.to_f + @ssl_session.timeout
+            s.session = @ssl_session
+          end
+          ssl_socket_connect(s, @open_timeout)
+          if (@ssl_context.verify_mode != OpenSSL::SSL::VERIFY_NONE) && verify_hostname
+            s.post_connection_check(@address)
+          end
+          debug "SSL established, protocol: #{s.ssl_version}, cipher: #{s.cipher[0]}"
+        end
+        @socket = Net::BufferedIO.new(s, read_timeout: @read_timeout,
+                                     write_timeout: @write_timeout,
+                                     continue_timeout: @continue_timeout,
+                                     debug_output: @debug_output)
+        @last_communicated = nil
+        on_connect
+      rescue StandardError => e
+        if s
+          debug "Conn close because of connect error #{e}"
+          s.close
+        end
+        raise
+      end
+    end
+
+    class << self
+      def patch!
+        return if @patched
+
+        ::Net::HTTP.prepend(Extension)
+        @patched = true
+      end
+
+      def patched?
+        @patched == true
+      end
+    end
+  end
+end

data/lib/ruby_proxy_headers/rest_client.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RubyProxyHeaders
+  # RestClient integration for proxy headers support.
+  #
+  # @example
+  #   response = RubyProxyHeaders::RestClient.get(
+  #     'https://example.com',
+  #     proxy: 'http://user:pass@proxy:8080',
+  #     proxy_headers: { 'X-ProxyMesh-Country' => 'US' }
+  #   )
+  #   puts response.proxy_response_headers
+  #
+  module RestClient
+    # Make a GET request with proxy headers.
+    def self.get(url, proxy:, proxy_headers: {}, **options)
+      request(:get, url, proxy: proxy, proxy_headers: proxy_headers, **options)
+    end
+
+    # Make a POST request with proxy headers.
+    def self.post(url, proxy:, proxy_headers: {}, payload: nil, **options)
+      request(:post, url, proxy: proxy, proxy_headers: proxy_headers, body: payload, **options)
+    end
+
+    # Make a PUT request with proxy headers.
+    def self.put(url, proxy:, proxy_headers: {}, payload: nil, **options)
+      request(:put, url, proxy: proxy, proxy_headers: proxy_headers, body: payload, **options)
+    end
+
+    # Make a DELETE request with proxy headers.
+    def self.delete(url, proxy:, proxy_headers: {}, **options)
+      request(:delete, url, proxy: proxy, proxy_headers: proxy_headers, **options)
+    end
+
+    # Make a request with proxy headers.
+    def self.request(method, url, proxy:, proxy_headers: {}, **options)
+      require 'rest-client'
+
+      uri = URI.parse(url)
+
+      # For HTTPS with proxy headers, use our core connection
+      if uri.scheme == 'https' && !proxy_headers.empty?
+        response = RubyProxyHeaders::NetHTTP.request(
+          method,
+          url,
+          proxy: proxy,
+          proxy_headers: proxy_headers,
+          headers: options[:headers],
+          body: options[:body]
+        )
+        return response
+      end
+
+      # For HTTP or no proxy headers, use standard RestClient
+      ::RestClient.proxy = proxy
+      response = ::RestClient.send(method, url, options)
+      ProxyResponse.new(response, {})
+    end
+
+    # Response wrapper with proxy headers accessor
+    class ProxyResponse
+      attr_reader :proxy_response_headers
+
+      def initialize(response, proxy_headers)
+        @response = response
+        @proxy_response_headers = proxy_headers
+      end
+
+      def code
+        @response.code
+      end
+
+      def body
+        @response.body
+      end
+
+      def headers
+        @response.headers
+      end
+
+      def method_missing(method, *args, &block)
+        @response.send(method, *args, &block)
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        @response.respond_to?(method, include_private) || super
+      end
+    end
+  end
+end

data/lib/ruby_proxy_headers/typhoeus.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module RubyProxyHeaders
+  # Typhoeus/Ethon integration for proxy headers support.
+  # Typhoeus wraps libcurl, which has native support for CURLOPT_PROXYHEADER.
+  #
+  # @example
+  #   response = RubyProxyHeaders::Typhoeus.get(
+  #     'https://example.com',
+  #     proxy: 'http://user:pass@proxy:8080',
+  #     proxy_headers: { 'X-ProxyMesh-Country' => 'US' }
+  #   )
+  #   puts response.proxy_response_headers
+  #
+  module Typhoeus
+    # Make a GET request with proxy headers.
+    # @param url [String] Target URL
+    # @param proxy [String] Proxy URL
+    # @param proxy_headers [Hash] Custom headers to send to proxy
+    # @param options [Hash] Additional Typhoeus options
+    # @return [ProxyResponse]
+    def self.get(url, proxy:, proxy_headers: {}, **options)
+      request(:get, url, proxy: proxy, proxy_headers: proxy_headers, **options)
+    end
+
+    # Make a POST request with proxy headers.
+    def self.post(url, proxy:, proxy_headers: {}, body: nil, **options)
+      request(:post, url, proxy: proxy, proxy_headers: proxy_headers, body: body, **options)
+    end
+
+    # Make a request with proxy headers.
+    # @param method [Symbol] HTTP method
+    # @param url [String] Target URL
+    # @param proxy [String] Proxy URL
+    # @param proxy_headers [Hash] Custom headers to send to proxy
+    # @param options [Hash] Additional Typhoeus options
+    # @return [ProxyResponse]
+    def self.request(method, url, proxy:, proxy_headers: {}, **options)
+      require 'typhoeus'
+
+      uri = URI.parse(url)
+
+      # For HTTPS, we need custom handling since Typhoeus doesn't expose CURLOPT_PROXYHEADER
+      if uri.scheme == 'https' && !proxy_headers.empty?
+        # Use our core connection for now
+        # TODO: Extend Ethon to expose CURLOPT_PROXYHEADER for native support
+        response = RubyProxyHeaders::NetHTTP.request(
+          method,
+          url,
+          proxy: proxy,
+          proxy_headers: proxy_headers,
+          headers: options[:headers],
+          body: options[:body]
+        )
+        return response
+      end
+
+      # For HTTP or no proxy headers, use standard Typhoeus
+      typhoeus_options = options.merge(
+        proxy: proxy,
+        method: method
+      )
+
+      response = ::Typhoeus::Request.new(url, typhoeus_options).run
+      ProxyResponse.new(response, {})
+    end
+
+    # Response wrapper with proxy headers accessor
+    class ProxyResponse
+      attr_reader :proxy_response_headers
+
+      def initialize(response, proxy_headers)
+        @response = response
+        @proxy_response_headers = proxy_headers
+      end
+
+      def code
+        @response.code
+      end
+
+      def body
+        @response.body
+      end
+
+      def headers
+        @response.headers
+      end
+
+      def success?
+        @response.success?
+      end
+
+      def method_missing(method, *args, &block)
+        @response.send(method, *args, &block)
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        @response.respond_to?(method, include_private) || super
+      end
+    end
+  end
+end

data/lib/ruby_proxy_headers/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RubyProxyHeaders
+  VERSION = '0.2.0'
+end

data/lib/ruby_proxy_headers.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'ruby_proxy_headers/version'
+require_relative 'ruby_proxy_headers/net_http'
+
+module RubyProxyHeaders
+  # CONNECT response headers from the last Net::HTTP-based proxied HTTPS request on this thread.
+  def self.proxy_connect_response_headers
+    Thread.current[:ruby_proxy_headers_connect_headers]
+  end
+end

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification
+name: ruby-proxy-headers
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- ProxyMesh
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: excon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.24'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.24'
+- !ruby/object:Gem::Dependency
+  name: mechanize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: typhoeus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: |
+  Extensions for Ruby HTTP stacks to send custom headers on HTTPS CONNECT to a proxy
+  and read headers from the proxy CONNECT response (e.g. X-ProxyMesh-IP).
+email: support@proxymesh.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- DEFERRED.md
+- IMPLEMENTATION_PRIORITY.md
+- LIBRARY_RESEARCH.md
+- LICENSE
+- README.md
+- lib/ruby_proxy_headers.rb
+- lib/ruby_proxy_headers/connection.rb
+- lib/ruby_proxy_headers/excon.rb
+- lib/ruby_proxy_headers/faraday.rb
+- lib/ruby_proxy_headers/http_gem.rb
+- lib/ruby_proxy_headers/httparty.rb
+- lib/ruby_proxy_headers/net_http.rb
+- lib/ruby_proxy_headers/rest_client.rb
+- lib/ruby_proxy_headers/typhoeus.rb
+- lib/ruby_proxy_headers/version.rb
+homepage: https://github.com/proxymesh/ruby-proxy-headers
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/proxymesh/ruby-proxy-headers
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Custom proxy CONNECT headers for Ruby HTTP clients (ProxyMesh, etc.)
+test_files: []