ruby-proxy-headers 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 227e0393d4ab8a6f03fa72d69541f07a20c73cec9eb3458266dbaa0b74fee36d
-  data.tar.gz: 299ef710e77b061929ce18159f37e82f002c7a8522b5f0c5ed4319f3d2ab517f
+  metadata.gz: 5f3b577a3e2e34161a02a0193d153850b0fbadd028a7286c05e23cfdf897e541
+  data.tar.gz: cc43f69b2da42d9177df10322db9544e640485d1464a4a2d472f85ce3b0d30d3
 SHA512:
-  metadata.gz: deae95ea2297961bc962a5d9e476ec09b88c85a6a2ac741e1c5d1cb15972f1dc096f2b52e16a70aaca28a77ce04568f00a1109abd2edbdfee45a9727841bff61
-  data.tar.gz: 55096cb62498dc26f1c1695c8bc46213db91bea6be4c2d056af152cdbbabd07873bc646c2db07a2e36764f8cd8a78188942c77d15b784c3c71acc3e91e2f8a75
+  metadata.gz: d6c6c2bcbbccdcf9d731018a3f37aedd15f8c47d0dd49e6f7fb050aadb8d2bce74987ddcc798fbb757f2d6058e1f503f2dc885b69ca9e3ff2eb29951306c7d1a
+  data.tar.gz: 1a9a0b38eaadab682f96ed45a850f93f8abd325987687c5ac9d46e21b88ba7980ef7e422f83a29f774a9db7eab41943ffa4e204d323c3333a0ff242453cc589a

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-11-12
+
+### Added
+
+- `RubyProxyHeaders::Typhoeus` sends proxy headers with libcurl `CURLOPT_PROXYHEADER` (`:proxyheader` and `headeropt: :separate` on Typhoeus 1.7 / Ethon 0.19) and exposes the CONNECT response, including `X-ProxyMesh-IP`, as `proxy_response_headers`.
+
+### Changed
+
+- Require Ruby >= 3.2. Dependabot resolves Bundler updates against the gemspec floor, and Ruby 3.1 cannot select nokogiri 1.19 (the release line that installs on the integration job's current Ruby).
+- Development dependencies for the Typhoeus adapter are `typhoeus` `~> 1.7` and `ethon` `>= 0.19.1`, `< 0.20`. The gem still has no runtime dependency on Typhoeus.
+- Gem metadata includes homepage, changelog, and bug tracker URIs. The published gem ships the guides under `docs/` and leaves the internal research notes out.
+- Faraday, HTTParty, Excon, and Net::HTTP guides describe `FaradayIntegration`, `ProxyHeadersConnectionAdapter`, `ExconIntegration`, and `NetHTTP.patch!`.
+
+### Fixed
+
+- HTTPS requests through `RubyProxyHeaders::Typhoeus` no longer call `RubyProxyHeaders::NetHTTP.request`, which is not defined.
+- HTTP.rb and RestClient no longer call that missing method. HTTP.rb uses its own `proxy_headers` on CONNECT. RestClient keeps using Net::HTTP, with CONNECT headers attached by the Net::HTTP patch.
+- The Net::HTTP patch no longer replaces `Net::HTTP#connect` with a copy of the Ruby 3.2 method. Socket setup, `timeouted_connect`, and HTTPS proxies stay in the installed net-http.
+- The Faraday adapter no longer overrides faraday-net_http's private `request_with_wrapped_block`. CONNECT response headers are merged from `build_connection` and `call`.
+- `NetHTTP.patch!` still applies after WebMock swaps `Net::HTTP` out and restores it.
+
+## [0.1.0] - 2024-02-28
+
+### Added
+
+- Initial release
+- Core `Connection` class for proxy CONNECT handling with custom headers
+- `NetHTTP` module for Net::HTTP integration
+- `Faraday` middleware for Faraday integration
+- `HTTParty` module for HTTParty integration
+- `HTTPGem` module for HTTP.rb integration
+- `Typhoeus` module for Typhoeus integration
+- `Excon` module for Excon integration
+- `RestClient` module for RestClient integration
+- Comprehensive documentation
+- Test suite with RSpec
+
+[Unreleased]: https://github.com/proxymesh/ruby-proxy-headers/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/proxymesh/ruby-proxy-headers/compare/v0.1.0...v0.3.0
+[0.1.0]: https://github.com/proxymesh/ruby-proxy-headers/releases/tag/v0.1.0

data/README.md

@@ -94,6 +94,53 @@ HTTParty.get(
 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.
+
+```ruby
+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.
+
+```ruby
+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/>.
+
+```ruby
+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 — see [DEFERRED.md](DEFERRED.md).
@@ -123,7 +170,7 @@ Same environment variables as [python-proxy-headers](https://github.com/proxymes
 ```bash
 cd ruby-proxy-headers
 bundle install
-export PROXY_URL=http://user:pass@proxyhost:port
+export PROXY_URL=http://user:pass@proxy.example.com:31280
 bundle exec ruby test/test_proxy_headers.rb -v
 ```
 

data/docs/core-api.md

@@ -0,0 +1,184 @@
+# Core API
+
+The core API provides low-level access to proxy connection handling. Use this for advanced use cases or when integrating with libraries not directly supported.
+
+## Connection Class
+
+The `RubyProxyHeaders::Connection` class handles the HTTPS CONNECT tunnel with custom headers.
+
+### Basic Usage
+
+```ruby
+require 'ruby_proxy_headers'
+
+connection = RubyProxyHeaders::Connection.new(
+  'http://user:pass@proxy.example.com:8080',
+  proxy_headers: { 'X-ProxyMesh-Country' => 'US' }
+)
+
+# Establish tunnel
+ssl_socket = connection.connect('api.ipify.org', 443)
+
+# Access proxy response headers
+puts connection.proxy_response_headers
+puts connection.proxy_response_status
+
+# Use the socket for your own HTTP implementation
+# ...
+
+connection.close
+```
+
+### Constructor
+
+```ruby
+RubyProxyHeaders::Connection.new(proxy, options = {})
+```
+
+**Parameters:**
+
+- `proxy` (String or Hash) - Proxy configuration
+  - String: `'http://user:pass@proxy:8080'`
+  - Hash: `{ host: 'proxy', port: 8080, user: 'user', password: 'pass' }`
+- `options` (Hash):
+  - `:proxy_headers` (Hash) - Headers to send during CONNECT
+  - `:connect_timeout` (Integer) - Timeout in seconds (default: 30)
+  - `:verify_ssl` (Boolean) - Verify SSL certificates (default: true)
+
+### Instance Methods
+
+#### `connect(target_host, target_port = 443)`
+
+Establish a tunnel through the proxy to the target.
+
+**Returns:** `OpenSSL::SSL::SSLSocket` - TLS-wrapped socket
+
+#### `close`
+
+Close the connection.
+
+### Instance Attributes
+
+- `proxy_response_headers` (Hash) - Headers from proxy CONNECT response
+- `proxy_response_status` (Integer) - HTTP status from CONNECT response
+- `socket` - The underlying socket
+
+## Utility Methods
+
+### `RubyProxyHeaders.parse_proxy_url(url)`
+
+Parse a proxy URL into components.
+
+```ruby
+result = RubyProxyHeaders.parse_proxy_url('http://user:pass@proxy:8080')
+# => { host: 'proxy', port: 8080, user: 'user', password: 'pass', scheme: 'http' }
+```
+
+### `RubyProxyHeaders.build_auth_header(user, password)`
+
+Build a Basic authentication header.
+
+```ruby
+auth = RubyProxyHeaders.build_auth_header('user', 'pass')
+# => "Basic dXNlcjpwYXNz"
+```
+
+## Error Classes
+
+### `RubyProxyHeaders::Error`
+
+Base error class.
+
+### `RubyProxyHeaders::ConnectError`
+
+Raised when proxy CONNECT fails.
+
+### `RubyProxyHeaders::ProxyAuthenticationError`
+
+Raised when proxy returns 407 (authentication required).
+
+## Example: Custom HTTP Implementation
+
+```ruby
+require 'ruby_proxy_headers'
+
+connection = RubyProxyHeaders::Connection.new(
+  ENV['PROXY_URL'],
+  proxy_headers: { 'X-ProxyMesh-Country' => 'US' }
+)
+
+begin
+  socket = connection.connect('example.com', 443)
+  
+  # Send HTTP request
+  socket.write("GET / HTTP/1.1\r\n")
+  socket.write("Host: example.com\r\n")
+  socket.write("Connection: close\r\n")
+  socket.write("\r\n")
+  
+  # Read response
+  response = socket.read
+  puts response
+  
+  # Access proxy headers
+  puts "Proxy IP: #{connection.proxy_response_headers['x-proxymesh-ip']}"
+ensure
+  connection.close
+end
+```
+
+## Example: Integration with Custom Client
+
+```ruby
+require 'ruby_proxy_headers'
+
+class CustomHttpClient
+  def initialize(proxy_url, proxy_headers = {})
+    @proxy_url = proxy_url
+    @proxy_headers = proxy_headers
+  end
+  
+  def get(url)
+    uri = URI.parse(url)
+    connection = RubyProxyHeaders::Connection.new(
+      @proxy_url,
+      proxy_headers: @proxy_headers
+    )
+    
+    begin
+      socket = connection.connect(uri.host, uri.port || 443)
+      
+      # Build request
+      request = "GET #{uri.request_uri} HTTP/1.1\r\n"
+      request += "Host: #{uri.host}\r\n"
+      request += "Connection: close\r\n"
+      request += "\r\n"
+      
+      socket.write(request)
+      response = socket.read
+      
+      {
+        body: parse_body(response),
+        proxy_headers: connection.proxy_response_headers
+      }
+    ensure
+      connection.close
+    end
+  end
+  
+  private
+  
+  def parse_body(response)
+    # Simple body extraction
+    response.split("\r\n\r\n", 2).last
+  end
+end
+
+client = CustomHttpClient.new(
+  ENV['PROXY_URL'],
+  'X-ProxyMesh-Country' => 'US'
+)
+
+result = client.get('https://api.ipify.org?format=json')
+puts result[:body]
+```

data/docs/excon.md

@@ -0,0 +1,29 @@
+# Excon
+
+[Excon](https://github.com/excon/excon) already sends extra CONNECT headers as `:ssl_proxy_headers`. `RubyProxyHeaders::ExconIntegration.get` passes them through.
+
+Excon does not expose the CONNECT response on the origin response, so `X-ProxyMesh-IP` is not readable from this client. See [DEFERRED.md](../DEFERRED.md).
+
+## Installation
+
+```ruby
+gem 'excon', '~> 1.4'
+gem 'ruby-proxy-headers'
+```
+
+## Usage
+
+```ruby
+require 'ruby_proxy_headers/excon'
+
+response = RubyProxyHeaders::ExconIntegration.get(
+  'https://api.ipify.org?format=json',
+  proxy_url: 'http://user:pass@proxy.example.com:31280',
+  proxy_connect_headers: { 'X-ProxyMesh-Country' => 'US' }
+)
+
+puts response.status
+puts response.body
+```
+
+Header names are documented at <https://docs.proxymesh.com/>.

data/docs/faraday.md

@@ -0,0 +1,29 @@
+# Faraday
+
+[Faraday](https://lostisland.github.io/faraday/) 2.x with `faraday-net_http` 3.4 or 3.5. `RubyProxyHeaders::FaradayIntegration` builds a connection whose adapter merges CONNECT response headers into `response.headers`.
+
+Proxy header names are documented at <https://docs.proxymesh.com/>.
+
+## Installation
+
+```ruby
+gem 'faraday', '~> 2.14'
+gem 'faraday-net_http', '~> 3.4'
+gem 'ruby-proxy-headers'
+```
+
+## Usage
+
+```ruby
+require 'ruby_proxy_headers/faraday'
+
+conn = RubyProxyHeaders::FaradayIntegration.connection(
+  proxy: 'http://user:pass@proxy.example.com:31280',
+  proxy_connect_headers: { 'X-ProxyMesh-Country' => 'US' }
+)
+
+response = conn.get('https://api.ipify.org?format=json')
+puts response.headers['X-ProxyMesh-IP']
+```
+
+`proxy_connect_headers` are sent only on the CONNECT request. Origin headers are the normal Faraday request headers. When both sides use the same header name, the origin value is kept.

data/docs/getting-started.md

@@ -0,0 +1,66 @@
+# Getting Started
+
+## Installation
+
+```ruby
+gem 'ruby-proxy-headers'
+```
+
+```bash
+gem install ruby-proxy-headers
+```
+
+Install `faraday` and `faraday-net_http`, `httparty`, `http` (>= 6), `rest-client`, `typhoeus` (~> 1.7), or `excon` only for the client you use.
+
+Proxy header names are documented at <https://docs.proxymesh.com/>. Examples below use `http://user:pass@proxy.example.com:31280`.
+
+## Net::HTTP
+
+```ruby
+require 'uri'
+require 'ruby_proxy_headers/net_http'
+
+RubyProxyHeaders::NetHTTP.patch!
+
+uri = URI('https://api.ipify.org?format=json')
+proxy = URI('http://user:pass@proxy.example.com:31280')
+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-Country' => 'US' }
+response = http.request(Net::HTTP::Get.new(uri))
+puts http.last_proxy_connect_response_headers['X-ProxyMesh-IP']
+```
+
+## Faraday
+
+```ruby
+require 'ruby_proxy_headers/faraday'
+
+conn = RubyProxyHeaders::FaradayIntegration.connection(
+  proxy: 'http://user:pass@proxy.example.com:31280',
+  proxy_connect_headers: { 'X-ProxyMesh-Country' => 'US' }
+)
+puts conn.get('https://api.ipify.org?format=json').headers['X-ProxyMesh-IP']
+```
+
+## HTTParty
+
+```ruby
+require 'httparty'
+require 'ruby_proxy_headers/httparty'
+
+RubyProxyHeaders::NetHTTP.patch!
+proxy = URI('http://user:pass@proxy.example.com:31280')
+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-Country' => 'US' },
+  connection_adapter: RubyProxyHeaders::ProxyHeadersConnectionAdapter
+)
+puts RubyProxyHeaders.proxy_connect_response_headers['X-ProxyMesh-IP']
+```
+
+Per-library pages: [Net::HTTP](net-http.md), [Faraday](faraday.md), [HTTParty](httparty.md), [HTTP.rb](http-gem.md), [Typhoeus](typhoeus.md), [RestClient](rest-client.md), [Excon](excon.md).

data/docs/http-gem.md

@@ -0,0 +1,126 @@
+# HTTP.rb
+
+[HTTP.rb](https://github.com/httprb/http) (the `http` gem) provides a simple Ruby DSL for making HTTP requests. The `RubyProxyHeaders::HTTPGem` module adds proxy header support.
+
+## Installation
+
+```ruby
+gem 'http'
+gem 'ruby-proxy-headers'
+```
+
+## Basic Usage
+
+### Using Client
+
+```ruby
+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 "Status: #{response.code}"
+puts "Body: #{response.body}"
+puts "Proxy IP: #{client.last_proxy_response_headers['x-proxymesh-ip']}"
+```
+
+### Standalone Methods
+
+```ruby
+require 'ruby_proxy_headers/http_gem'
+
+response = RubyProxyHeaders::HTTPGem.get(
+  'https://api.ipify.org?format=json',
+  proxy: 'http://user:pass@proxy.example.com:31280',
+  proxy_headers: { 'X-Country' => 'US' }
+)
+
+puts response.body
+```
+
+## API Reference
+
+### `RubyProxyHeaders::HTTPGem.create_client(options)`
+
+Create a client with proxy header support.
+
+**Parameters:**
+
+- `options` (Hash):
+  - `:proxy` (String) - Proxy URL (required)
+  - `:proxy_headers` (Hash) - Headers to send to proxy
+
+**Returns:** `ProxyClient`
+
+### `RubyProxyHeaders::HTTPGem.get(url, options)`
+
+Make a GET request.
+
+**Parameters:**
+
+- `url` (String) - Target URL
+- `options` (Hash) - Same as `create_client`
+
+**Returns:** Response object
+
+### `RubyProxyHeaders::HTTPGem.post(url, options)`
+
+Make a POST request.
+
+**Parameters:**
+
+- Same as `get`, plus:
+  - `:body` (String) - Request body
+
+## Client Methods
+
+The client supports standard HTTP methods:
+
+```ruby
+client = RubyProxyHeaders::HTTPGem.create_client(proxy: '...')
+
+client.get(url)
+client.post(url, body: data)
+client.put(url, body: data)
+client.delete(url)
+```
+
+## Accessing Proxy Headers
+
+```ruby
+client = RubyProxyHeaders::HTTPGem.create_client(
+  proxy: 'http://user:pass@proxy.example.com:31280',
+  proxy_headers: { 'X-Country' => 'US' }
+)
+
+response = client.get('https://example.com')
+
+# Access via client
+puts client.last_proxy_response_headers['x-proxymesh-ip']
+```
+
+## Example: Chained Requests
+
+```ruby
+require 'ruby_proxy_headers/http_gem'
+
+client = RubyProxyHeaders::HTTPGem.create_client(
+  proxy: ENV['PROXY_URL'],
+  proxy_headers: { 'X-ProxyMesh-Session' => 'chain-test' }
+)
+
+urls = [
+  'https://api.ipify.org?format=json',
+  'https://httpbin.org/ip',
+  'https://ifconfig.me/ip'
+]
+
+urls.each do |url|
+  response = client.get(url)
+  puts "#{url}: #{response.body.to_s.strip}"
+end
+```

data/docs/httparty.md

@@ -0,0 +1,35 @@
+# HTTParty
+
+[HTTParty](https://github.com/jnunemaker/httparty) uses Net::HTTP. Pass `RubyProxyHeaders::ProxyHeadersConnectionAdapter` and call `RubyProxyHeaders::NetHTTP.patch!` once. CONNECT response headers are on the thread afterward, not on the HTTParty response.
+
+Proxy header names are documented at <https://docs.proxymesh.com/>.
+
+## Installation
+
+```ruby
+gem 'httparty', '~> 0.24'
+gem 'ruby-proxy-headers'
+```
+
+## Usage
+
+```ruby
+require 'httparty'
+require 'ruby_proxy_headers/httparty'
+
+RubyProxyHeaders::NetHTTP.patch!
+
+proxy = URI('http://user:pass@proxy.example.com:31280')
+response = 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-Country' => 'US' },
+  connection_adapter: RubyProxyHeaders::ProxyHeadersConnectionAdapter
+)
+
+puts response.body
+puts RubyProxyHeaders.proxy_connect_response_headers['X-ProxyMesh-IP']
+```