ruby-proxy-headers 0.2.2 → 0.3.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-proxy-headers
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - ProxyMesh
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.50'
+        version: '1.92'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.50'
+        version: '1.92'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -121,6 +121,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: httparty
   requirement: !ruby/object:Gem::Requirement
@@ -149,20 +163,54 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: ethon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.19.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.19.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.20'
 - !ruby/object:Gem::Dependency
   name: typhoeus
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -186,11 +234,20 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".yardopts"
-- DEFERRED.md
-- IMPLEMENTATION_PRIORITY.md
-- LIBRARY_RESEARCH.md
+- CHANGELOG.md
 - LICENSE
 - README.md
+- docs/core-api.md
+- docs/excon.md
+- docs/faraday.md
+- docs/getting-started.md
+- docs/http-gem.md
+- docs/httparty.md
+- docs/index.md
+- docs/net-http.md
+- docs/rest-client.md
+- docs/testing.md
+- docs/typhoeus.md
 - lib/ruby_proxy_headers.rb
 - lib/ruby_proxy_headers/connection.rb
 - lib/ruby_proxy_headers/excon.rb
@@ -207,6 +264,9 @@ licenses:
 metadata:
   source_code_uri: https://github.com/proxymesh/ruby-proxy-headers
   documentation_uri: https://rubydoc.info/gems/ruby-proxy-headers
+  homepage_uri: https://github.com/proxymesh/ruby-proxy-headers
+  changelog_uri: https://github.com/proxymesh/ruby-proxy-headers/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/proxymesh/ruby-proxy-headers/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -214,14 +274,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Custom proxy CONNECT headers for Ruby HTTP clients (ProxyMesh, etc.)
 test_files: []

data/DEFERRED.md

@@ -1,29 +0,0 @@
-# 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

@@ -1,72 +0,0 @@
-# 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

@@ -1,71 +0,0 @@
-# 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*