rack-proxy 0.8.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47505271ab54cee7d324c7fdd22c22ba7edae1b99146ee081913668925ff61f4
-  data.tar.gz: 74afa4cf47b33eba1e12a8a4b5f8b499237fa6a6fabacbb46c0bc820e627b07b
+  metadata.gz: 1e04f14fa6327e4f329211d6ca95a1865b2e2db929c954c613cd3017f2d9a587
+  data.tar.gz: ca3a3bbc4451fbcc21495317889bdb2afc2b5c328e8a0b6561a82617f3871c0c
 SHA512:
-  metadata.gz: 0ea871048c9cd7ceff7b13c7e59caad7d393947a9909e5372031cc51c85879d2e297b57c6245ea56dc7c104da3c5ed3bc5688e2ce7a8c006f68cba52c0ee1696
-  data.tar.gz: 1c3ee10747af4bc06e9a270ec21d1854f1112b82127940a198e075ee044c7be6e6c43847b83d5cfd6facfadd90a32e4260a2e8731665ced34d46ec7ffd2febc1
+  metadata.gz: 37d457fb14f1cd3f48729b36db119b5d72585e85cad6f745d37c8a6857bddd6636e2ed8ad18f6d1975b61b184eb0cfb4b262d80b3304dfeebaa765c6bb273871
+  data.tar.gz: 1e2f04812c516b6ecaf1266b941bca1797fd72546217e506443b8e8a619617d77130684250ea343c19e90a686185a8f6cfd659970b9393d4378e7307bf26af2b

data/CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project aims to
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [1.0.0] - 2026-07-18
+
+The 2026 modernization + security-hardening release (see
+`MODERNIZATION_PLAN.md`). From 1.0.0 on this project follows SemVer strictly:
+breaking changes only in majors.
+
+### Breaking changes
+
+Read this list before upgrading from 0.8.x; everything else below is additive
+or a compatible fix. See the README's "Upgrading" section for migration steps.
+
+- **Host-derived (dynamic) backends are refused by default.** With no
+  `:backend` and no `env["rack.backend"]`, requests now get `502` unless you
+  pass `allow_dynamic_backend: true`. A bare `Rack::Proxy.new` is no longer an
+  open proxy. Combine the opt-in with a `backend_allowed?` allowlist.
+- **`net_http_hacked` is gone** — the file, `require "net_http_hacked"`, and
+  the `begin_request_hacked`/`end_request_hacked` methods (see Removed).
+- **The bundled examples left the gem** — `require "rack_proxy_examples/..."`
+  raises `LoadError`; copy the snippets from `examples/` instead (see Removed).
+- **Backend failures no longer raise.** `OpenSSL::SSL::SSLError`, `EOFError`,
+  timeouts, resets, and malformed backend responses now become a `502` triplet
+  instead of an exception — `rescue`-based error handling around `proxy.call`
+  must inspect the status instead.
+- **Hop-by-hop request headers are no longer forwarded** (`Connection`, `TE`,
+  `Transfer-Encoding`, `Proxy-Authorization`, `Upgrade`, anything named by
+  `Connection`).
+- **gzip backend bodies are forwarded verbatim in `streaming: false` mode**
+  (previously they were transparently inflated); `rewrite_response` hooks that
+  read body text must inflate it themselves.
+- **Supported runtimes: Ruby >= 3.0 and Rack >= 2.0, < 4** (was Ruby >= 2.6,
+  rack unpinned).
+- Smaller wire/API changes: body-less POST/PUT sends `Content-Length: 0` on
+  the streaming path; the streaming body is thread-affine (iterate it on the
+  thread that called the app, as mainstream servers do); `HttpStreamingResponse`
+  raises `IOError` on use-after-close; early termination closes the backend
+  connection instead of draining it.
+
+### Security
+
+- Refuse Host-derived backends unless `allow_dynamic_backend: true` is set
+  (see Breaking changes) — closes the default open-proxy/SSRF pivot.
+- Strip hop-by-hop headers from the **forwarded request** (Connection, TE,
+  Transfer-Encoding, Proxy-Authorization, …, plus any header named by the inbound
+  `Connection` header), closing a Content-Length/Transfer-Encoding request-smuggling
+  surface. Hop-by-hop headers were previously stripped only from the response.
+- Add `backend_allowed?(backend)` — an overridable per-request allowlist hook,
+  consulted for every request (static backends included). A refused backend
+  responds `502`.
+- Add `:max_response_length` to cap the backend response size (bounds memory
+  against a hostile/huge backend). Enforced incrementally while streaming.
+- Add `:ca_file` / `:cert_store` so private-CA backends can be verified under the
+  default `VERIFY_PEER` instead of disabling verification.
+- Add `:open_timeout` / `:write_timeout` to bound connect and per-write stalls
+  (previously only `:read_timeout` was configurable).
+
+### Added
+
+- `:min_version` / `:max_version` TLS options (mapping to `Net::HTTP#min_version=`
+  / `#max_version=`). `:ssl_version` still works but is deprecated (it pins an
+  exact protocol and forbids TLS 1.3).
+- `HttpStreamingResponse#close` so Rack servers release the backend connection on
+  early termination (HEAD, 304, client disconnect) instead of leaking it until GC.
+- Opt-in request hardening: `strip_credentials: true` drops the client's
+  `Cookie`/`Authorization` headers from the forwarded request, and
+  `replace_x_forwarded_for: true` forwards only this hop's `REMOTE_ADDR`
+  instead of appending to the client-supplied `X-Forwarded-For` chain.
+- Project scaffolding: `SECURITY.md`, `CHANGELOG.md`, `CONTRIBUTING.md`,
+  `CLAUDE.md`/`AGENTS.md`, GitHub Actions CI (Ruby 3.1–3.4 × Rack 2/3),
+  Dependabot, issue/PR templates, SimpleCov with a ratcheted coverage floor
+  (`COVERAGE=1`), and Standard (`standardrb`) + `bundler-audit` enforced by a
+  CI lint job.
+
+### Changed
+
+- **The streaming path no longer monkey-patches `net/http`.**
+  `Rack::HttpStreamingResponse` now runs the public block form of
+  `Net::HTTP#request` inside a Fiber (pausing at the response head, resuming
+  per body chunk), replacing the 2010-era patch of private `net/http` internals
+  in `net_http_hacked.rb`. Behavioral notes: the streaming session sets
+  `max_retries = 0` so a transport error can never silently replay the request
+  mid-stream; early termination (client abort, HEAD, 204/304) now closes
+  the backend connection immediately instead of draining the remaining body;
+  and a body-less POST/PUT/PATCH on the streaming path now carries
+  `Content-Length: 0` (matching the non-streaming path and plain `Net::HTTP` —
+  the old patched path sent no `Content-Length` at all).
+- Backend and construction failures now map to status codes instead of raising a
+  `500`: `400` (malformed request URI), `501` (unknown HTTP method), `502`
+  (broadened backend-error set incl. `ECONNRESET`, `EPIPE`, read/write timeouts,
+  `EOFError`, `OpenSSL::SSL::SSLError`, protocol errors, and malformed backend
+  responses — `Net::HTTPBadResponse` / `Net::HTTPHeaderSyntaxError`).
+- gzip-encoded backend responses are forwarded verbatim (Content-Encoding and
+  Content-Length preserved) instead of being transparently inflated.
+- Skip all `1xx` interim responses (including `103 Early Hints`) on the streaming
+  path, so a backend's `103` is no longer mistaken for the final response.
+- `rack` dependency constrained to `>= 2.0, < 4`; the library now `require`s rack
+  itself.
+- Test suite is fully offline (local WEBrick server); the previous live-host
+  tests are gated behind `LIVE=1`.
+
+### Deprecated
+
+- `:ssl_version` — use `:min_version` / `:max_version`.
+
+### Removed
+
+- `lib/net_http_hacked.rb` — the 2010-era monkey-patch of private `Net::HTTP`
+  internals. The library stopped using it when streaming moved to the public
+  `Net::HTTP` API (see Changed); `require "net_http_hacked"` and the
+  `begin_request_hacked` / `end_request_hacked` methods are gone. If external
+  code still depends on them, vendor the file from a 0.8.x release — and plan
+  to migrate; it breaks under modern net/http refactors.
+
+- The bundled examples moved from the gem load path
+  (`lib/rack_proxy_examples/`) to [`examples/`](examples/) in the repository.
+  `require "rack_proxy_examples/..."` no longer works — copy the example class
+  into your app instead (they were never safe to require blindly: each one
+  installs itself into the Rails middleware stack when Rails is booted).
+
+## [0.8.3] - 2025
+
+### Fixed
+
+- Handle non-rewindable request body streams (Rack 3 input streams need not
+  respond to `#rewind`). (#128)
+
+## [0.8.2] - 2025
+
+### Fixed
+
+- Harden `build_header_hash` against a top-level `::Headers` constant defined by
+  the host app being picked up instead of `Rack::Headers`.
+
+## [0.8.1] - 2025
+
+### Added
+
+- `:logger` option, wired to `Net::HTTP#set_debug_output` for wire-level debug
+  output. (#80)
+
+## [0.8.0] - 2025
+
+### Changed
+
+- **BREAKING:** TLS certificate verification now defaults to `VERIFY_PEER`
+  (Ruby's `Net::HTTP` default). Previous versions silently used `VERIFY_NONE` for
+  HTTPS backends. Pass `ssl_verify_none: true` (or `verify_mode:`) to opt out. (#113)
+
+### Fixed
+
+- Return `502` on backend connection errors instead of raising; correct body
+  handling for empty responses and no-entity-body statuses (1xx/204/304). (#58, #122, #123)
+
+---
+
+Older releases (≤ 0.7.8) predate this changelog; see the git history and tags.
+
+[Unreleased]: https://github.com/ncr/rack-proxy/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/ncr/rack-proxy/compare/v0.8.3...v1.0.0
+[0.8.3]: https://github.com/ncr/rack-proxy/compare/v0.8.2...v0.8.3
+[0.8.2]: https://github.com/ncr/rack-proxy/compare/v0.8.1...v0.8.2
+[0.8.1]: https://github.com/ncr/rack-proxy/compare/v0.8.0...v0.8.1
+[0.8.0]: https://github.com/ncr/rack-proxy/compare/v0.7.8...v0.8.0

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013 Jacek Becela jacek.becela@gmail.com
+Copyright (c) 2010-2026 Jacek Becela and contributors jacek.becela@gmail.com
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,12 +1,25 @@
+# Rack::Proxy
+
 A request/response rewriting HTTP proxy. A Rack app. Subclass `Rack::Proxy` and provide your `rewrite_env` and `rewrite_response` methods.
 
+## Contents
+
+- [Installation](#installation)
+- [Use Cases](#use-cases)
+- [Options](#options)
+- [Security considerations](#security-considerations)
+- [Examples](#examples)
+- [Upgrading](#upgrading)
+- [A note on header keys](#a-note-on-header-keys-96)
+- [Compatibility notes](#compatibility-notes)
+
 Installation
 ----
 
 Add the following to your `Gemfile`:
 
 ```
-gem 'rack-proxy', '~> 0.8.0'
+gem 'rack-proxy', '~> 1.0'
 ```
 
 Or install:
@@ -36,14 +49,29 @@ Options
 
 Options can be set when initializing the middleware or overriding a method.
 
-
-* `:streaming` - defaults to `true`, but does not work on all Ruby versions, recommend to set to `false`
-* `:ssl_verify_none` - tell `Net::HTTP` to skip TLS certificate verification (defaults to verifying — see [Upgrading](#upgrading) for the 0.8 change)
-* `:verify_mode` - explicit `OpenSSL::SSL::VERIFY_*` constant; wins over `ssl_verify_none`
-* `:ssl_version` - tell `Net::HTTP` to set a specific `ssl_version`
-* `:backend` - the URI parseable format of host and port of the target proxy backend. If not set it will assume the backend target is the same as the source.
-* `:read_timeout` - set proxy timeout it defaults to 60 seconds
-* `:logger` - any object responding to `#<<` (e.g. `$stdout`, a `StringIO`, or a Ruby `Logger`). Wired through to `Net::HTTP#set_debug_output` so the full HTTP wire-level conversation is written to the sink. Useful for debugging.
+* `:streaming` - stream the backend response as it arrives (default `true`). Set to `false` to buffer the whole response before returning it (also recommended under `webmock`/`vcr` — see [Compatibility notes](#compatibility-notes)).
+* `:backend` - URI (or URI-parseable string) of the backend host/port/scheme to proxy to. If not set, the destination is derived from the incoming request's `Host` — which is **refused by default** since 1.0; see `:allow_dynamic_backend` and [Security considerations](#security-considerations).
+* `:allow_dynamic_backend` - opt in (`true`) to deriving the destination from the client-supplied `Host` header when no `:backend` is configured. Off by default (such requests get `502`), because a bare dynamic proxy is an open proxy. Combine with a `backend_allowed?` allowlist.
+* `:read_timeout` - per-read timeout in seconds (default `60`).
+* `:open_timeout` - connection-open timeout in seconds.
+* `:write_timeout` - per-write timeout in seconds.
+* `:ssl_verify_none` - skip TLS certificate verification. Verification is on by default (`VERIFY_PEER`) — see [Upgrading](#upgrading).
+* `:verify_mode` - explicit `OpenSSL::SSL::VERIFY_*` constant; wins over `ssl_verify_none`.
+* `:ca_file` - path to a PEM CA bundle used to verify the backend certificate (prefer this over disabling verification for private CAs).
+* `:cert_store` - an `OpenSSL::X509::Store` used to verify the backend certificate.
+* `:cert` / `:key` - client certificate and key for mutual TLS to the backend.
+* `:min_version` / `:max_version` - TLS protocol range (e.g. `:TLS1_2`), mapped to `Net::HTTP#min_version=` / `#max_version=`.
+* `:ssl_version` - **deprecated**; pins an exact protocol (forbids TLS 1.3). Use `:min_version` / `:max_version`.
+* `:max_response_length` - cap (in bytes) on the backend response size; a larger response is refused with `502` (streaming aborts once the cap is passed).
+* `:username` / `:password` - HTTP Basic credentials sent to the backend.
+* `:strip_credentials` - when `true`, drop the client's `Cookie` and `Authorization` headers instead of forwarding them — see [Security considerations](#security-considerations). The strip applies **after** `rewrite_env`, so a credential injected there is stripped too; attach a proxy-owned credential with `:username`/`:password` instead.
+* `:replace_x_forwarded_for` - when `true`, discard the client-supplied `X-Forwarded-For` chain and forward only this hop's `REMOTE_ADDR` (default appends to the chain) — see [Security considerations](#security-considerations).
+* `:logger` - any object responding to `#<<` (e.g. `$stdout`, a `StringIO`, or a Ruby `Logger`). Wired to `Net::HTTP#set_debug_output` so the HTTP wire-level conversation is written to the sink. Useful for debugging.
+
+Two request-scoped overrides can also be set in `env` (e.g. from `rewrite_env`):
+
+* `env['rack.backend']` - a URI overriding `:backend` for this request.
+* `env['http.read_timeout']` - override `:read_timeout` for this request.
 
 To pass in options, when you configure your middleware you can pass them in as an optional hash.
 
@@ -51,31 +79,62 @@ To pass in options, when you configure your middleware you can pass them in as a
 Rails.application.config.middleware.use ExampleServiceProxy, backend: 'http://guides.rubyonrails.org', streaming: false
 ```
 
+Security considerations
+----
+
+rack-proxy forwards attacker-influenced requests to a backend and relays the backend's response. Configure and subclass it with that in mind.
+
+* **SSRF / open proxy — safe by default since 1.0.** If you do **not** set `:backend`, the destination host/port/scheme would be derived from the incoming request's `Host` / `X-Forwarded-Host` header — meaning a client could steer the proxy at *any* host, including cloud metadata endpoints (`169.254.169.254`), loopback, and private ranges. Such requests are now refused with `502` unless you pass `allow_dynamic_backend: true`. When you do opt in, pin an allowlist on top by overriding `backend_allowed?(backend)` (consulted for every request, static backends included):
+
+    ```ruby
+    class MyProxy < Rack::Proxy
+      ALLOWED = %w[api.internal.example.com].freeze
+
+      def backend_allowed?(backend)
+        ALLOWED.include?(backend.host)
+      end
+    end
+
+    MyProxy.new(allow_dynamic_backend: true)
+    ```
+
+    A refused backend is answered with `502` (with a hint in the `:logger` output).
+
+* **Credential forwarding.** All incoming `HTTP_*` headers are forwarded, including `Authorization` and `Cookie`. Don't proxy to a different trust domain with credentials attached — pass `strip_credentials: true` to drop both (or do finer-grained filtering in `rewrite_env`). Over an `http://` backend these travel in cleartext.
+
+* **X-Forwarded-For.** rack-proxy appends `REMOTE_ADDR` to any inbound `X-Forwarded-For`. If your clients are not behind a trusted proxy, the inbound value is attacker-controlled; pass `replace_x_forwarded_for: true` to forward only the directly-connected peer's address when the backend trusts that header.
+
+* **TLS verification** defaults to `VERIFY_PEER`. For private-CA backends use `:ca_file` / `:cert_store` rather than `ssl_verify_none: true`.
+
+* **Resource limits.** Use `:max_response_length` plus `:open_timeout` / `:write_timeout` / `:read_timeout` to bound memory and stalls against a hostile or slow backend.
+
+* **Hop-by-hop headers** (Connection, TE, Transfer-Encoding, Proxy-Authorization, …) are stripped from both the forwarded request and the response.
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
 Examples
 ----
 
-See and run the examples below from `lib/rack_proxy_examples/`. To mount any example into an existing Rails app:
+The snippets below (also in [`examples/`](examples/) in the repository) are meant to be **copied into your app** — e.g. into `app/middleware/` or `lib/` — and adapted. They are not shipped in the gem and cannot be `require`d from it. To mount one in Rails, copy the class into your app and add it to the middleware stack in an initializer:
 
-1. create `config/initializers/proxy.rb`
-2. modify the file to require the example file
 ```ruby
-require 'rack_proxy_examples/forward_host'
+# config/initializers/proxy.rb
+Rails.application.config.middleware.use ForwardHost, backend: "http://example.com"
 ```
 
 ### Forward request to Host and Insert Header
 
-Test with `require 'rack_proxy_examples/forward_host'`
+From [`examples/forward_host.rb`](examples/forward_host.rb):
 
 ```ruby
 class ForwardHost < Rack::Proxy
-
   def rewrite_env(env)
     env["HTTP_HOST"] = "example.com"
     env
   end
 
   def rewrite_response(triplet)
-    status, headers, body = triplet
+    _, headers, _ = triplet
 
     # example of inserting an additional header
     headers["X-Foo"] = "Bar"
@@ -87,24 +146,22 @@ class ForwardHost < Rack::Proxy
 
     triplet
   end
-
 end
 ```
 
 ### Disable SSL session verification when proxying a server with e.g. self-signed SSL certs
 
-Test with `require 'rack_proxy_examples/trusting_proxy'`
+From [`examples/trusting_proxy.rb`](examples/trusting_proxy.rb):
 
 ```ruby
 class TrustingProxy < Rack::Proxy
-
   def rewrite_env(env)
     env["HTTP_HOST"] = "self-signed.badssl.com"
     env
   end
 
   def rewrite_response(triplet)
-    status, headers, body = triplet
+    _, headers, _ = triplet
 
     # if you rewrite env, it appears that content-length isn't calculated correctly
     # resulting in only partial responses being sent to users
@@ -113,16 +170,18 @@ class TrustingProxy < Rack::Proxy
 
     triplet
   end
-
 end
 
-# Pass ssl_verify_none: true to skip TLS certificate verification.
-Rack::Proxy.new(ssl_verify_none: true)
+# Mount it with an explicit backend (dynamic Host-derived backends are refused
+# by default since 1.0). Pass ssl_verify_none: true to skip TLS verification.
+Rails.application.config.middleware.use TrustingProxy,
+  backend: "https://self-signed.badssl.com",
+  ssl_verify_none: true
 ```
 
 ### Rails middleware example
 
-Test with `require 'rack_proxy_examples/example_service_proxy'`
+From [`examples/example_service_proxy.rb`](examples/example_service_proxy.rb):
 
 ```ruby
 ###
@@ -132,32 +191,32 @@ Test with `require 'rack_proxy_examples/example_service_proxy'`
 # 1. rails new test_app
 # 2. cd test_app
 # 3. install Rack-Proxy in `Gemfile`
-#    a. `gem 'rack-proxy', '~> 0.7.7'`
+#    a. `gem 'rack-proxy', '~> 1.0'`
 # 4. install gem: `bundle install`
-# 5. create `config/initializers/proxy.rb` adding this line `require 'rack_proxy_examples/example_service_proxy'`
+# 5. copy the class into your app and mount it from `config/initializers/proxy.rb`
 # 6. run: `SERVICE_URL=http://guides.rubyonrails.org rails server`
 # 7. open in browser: `http://localhost:3000/example_service`
 #
 ###
-ENV['SERVICE_URL'] ||= 'http://guides.rubyonrails.org'
+ENV["SERVICE_URL"] ||= "http://guides.rubyonrails.org"
 
 class ExampleServiceProxy < Rack::Proxy
   def perform_request(env)
     request = Rack::Request.new(env)
 
     # use rack proxy for anything hitting our host app at /example_service
-    if request.path =~ %r{^/example_service}
-        backend = URI(ENV['SERVICE_URL'])
-        # most backends required host set properly, but rack-proxy doesn't set this for you automatically
-        # even when a backend host is passed in via the options
-        env["HTTP_HOST"] = backend.host
-
-        # This is the only path that needs to be set currently on Rails 5 & greater
-        env['PATH_INFO'] = ENV['SERVICE_PATH'] || '/configuring.html'
-
-        # don't send your sites cookies to target service, unless it is a trusted internal service that can parse all your cookies
-        env['HTTP_COOKIE'] = ''
-        super(env)
+    if %r{^/example_service}.match?(request.path)
+      backend = URI(ENV["SERVICE_URL"])
+      # most backends required host set properly, but rack-proxy doesn't set this for you automatically
+      # even when a backend host is passed in via the options
+      env["HTTP_HOST"] = backend.host
+
+      # This is the only path that needs to be set currently on Rails 5 & greater
+      env["PATH_INFO"] = ENV["SERVICE_PATH"] || "/configuring.html"
+
+      # don't send your sites cookies to target service, unless it is a trusted internal service that can parse all your cookies
+      env["HTTP_COOKIE"] = ""
+      super
     else
       @app.call(env)
     end
@@ -167,7 +226,7 @@ end
 
 ### Using as middleware to forward only some extensions to another Application
 
-Test with `require 'rack_proxy_examples/rack_php_proxy'`
+From [`examples/rack_php_proxy.rb`](examples/rack_php_proxy.rb):
 
 Example: Proxying only requests that end with ".php" could be done like this:
 
@@ -176,28 +235,27 @@ Example: Proxying only requests that end with ".php" could be done like this:
 # Open http://localhost:3000/test.php to trigger proxy
 ###
 class RackPhpProxy < Rack::Proxy
-
   def perform_request(env)
     request = Rack::Request.new(env)
-    if request.path =~ %r{\.php}
+    if %r{\.php}.match?(request.path)
       env["HTTP_HOST"] = ENV["HTTP_HOST"] ? URI(ENV["HTTP_HOST"]).host : "localhost"
-      ENV["PHP_PATH"] ||= '/manual/en/tutorial.firstpage.php'
+      ENV["PHP_PATH"] ||= "/manual/en/tutorial.firstpage.php"
 
       # Rails 3 & 4
       env["REQUEST_PATH"] = ENV["PHP_PATH"] || "/php/#{request.fullpath}"
       # Rails 5 and above
-      env['PATH_INFO'] = ENV["PHP_PATH"] || "/php/#{request.fullpath}"
+      env["PATH_INFO"] = ENV["PHP_PATH"] || "/php/#{request.fullpath}"
 
-      env['content-length'] = nil
+      env["content-length"] = nil
 
-      super(env)
+      super
     else
       @app.call(env)
     end
   end
 
   def rewrite_response(triplet)
-    status, headers, body = triplet
+    _, headers, _ = triplet
 
     # if you proxy depending on the backend, it appears that content-length isn't calculated correctly
     # resulting in only partial responses being sent to users
@@ -214,14 +272,14 @@ To use the middleware, please consider the following:
 1) For Rails we could add a configuration in `config/application.rb`
 
 ```ruby
-  config.middleware.use RackPhpProxy, {ssl_verify_none: true}
+  config.middleware.use RackPhpProxy, backend: "http://php.net", ssl_verify_none: true
 ```
 
 2) For Sinatra or any Rack-based application:
 
 ```ruby
 class MyAwesomeSinatra < Sinatra::Base
-   use  RackPhpProxy, {ssl_verify_none: true}
+   use RackPhpProxy, backend: "http://php.net", ssl_verify_none: true
 end
 ```
 
@@ -307,7 +365,7 @@ key_raw = File.read('./certs/key.pem')
 cert = OpenSSL::X509::Certificate.new(cert_raw)
 key = OpenSSL::PKey.read(key_raw)
 
-use TLSProxy, cert: cert, key: key, use_ssl: true, verify_mode: OpenSSL::SSL::VERIFY_PEER, ssl_version: 'TLSv1_2'
+use TLSProxy, backend: "https://client-tls-auth-api.com", cert: cert, key: key, verify_mode: OpenSSL::SSL::VERIFY_PEER, min_version: :TLS1_2
 ```
 
 And rewrite host for example:
@@ -326,6 +384,32 @@ end
 Upgrading
 ----
 
+### 0.8.x → 1.0.0
+
+1.0.0 is a breaking release; the full list is in [CHANGELOG.md](CHANGELOG.md). The changes most likely to need action:
+
+**Host-derived backends now require an explicit opt-in.** If you rely on the destination being derived from the request's `Host` header (no `:backend` option — this includes every subclass that routes by rewriting `env["HTTP_HOST"]`), such requests now return `502`. Restore the behavior explicitly, ideally with an allowlist:
+
+```ruby
+class MyProxy < Rack::Proxy
+  def backend_allowed?(backend)
+    %w[api.internal.example.com].include?(backend.host)
+  end
+end
+
+MyProxy.new(allow_dynamic_backend: true)
+```
+
+Deployments with a fixed `:backend` (or that set `env["rack.backend"]` in `rewrite_env`) need no change.
+
+**Backend failures return `502` instead of raising.** If you rescued `OpenSSL::SSL::SSLError`, `Errno::ECONNREFUSED`, timeouts, etc. around the proxy, inspect the response status instead. Malformed request URIs map to `400` and unknown HTTP methods to `501`.
+
+**`require "rack_proxy_examples/..."` is gone.** The examples are copy-paste snippets in [`examples/`](examples/) now — copy the class into your app and mount it yourself.
+
+**`net_http_hacked` is gone.** The library streams via the public `Net::HTTP` API; if external code called `begin_request_hacked`/`end_request_hacked`, vendor the old file from a 0.8.x release and plan a migration.
+
+**Other behavior changes to be aware of:** hop-by-hop request headers (including `Proxy-Authorization`) are no longer forwarded; gzip bodies are forwarded still-compressed in `streaming: false` mode (inflate in `rewrite_response` if you inspect body text); body-less POST/PUT sends `Content-Length: 0`; Ruby >= 3.0 and Rack 2.x–3.x are required.
+
 ### 0.7.x → 0.8.0
 
 **TLS certificate verification is now on by default.** Prior versions silently used `OpenSSL::SSL::VERIFY_NONE` whenever the backend was HTTPS, which disabled certificate checks. 0.8.0 defaults to `VERIFY_PEER` to match Ruby's `Net::HTTP`.
@@ -346,14 +430,7 @@ Per the standard Rack/CGI convention, header names received by your proxy are ex
 
 If you need underscore-style headers preserved end-to-end, configure your fronting web server (e.g. `underscores_in_headers on;` in nginx, or `HTTPProtocolOptions` in Apache) — rack-proxy is not the right layer to fix this.
 
-WARNING
-----
-
-Doesn't work with `fakeweb`/`webmock`. Both libraries monkey-patch net/http code.
-
-Todos
+Compatibility notes
 ----
 
-* Make the docs up to date with the current use case for this code: everything except streaming which involved a rather ugly monkey patch and only worked in 1.8, but does not work now.
-* Improve and validate requirements for Host and Path rewrite rules
-* Ability to inject logger and set log level
+The streaming response path (the default) streams straight off the backend socket via `Net::HTTP`. Historically it relied on private `net/http` internals and did not work at all under `webmock`, `vcr`, or `fakeweb`; it now uses only the public `Net::HTTP#request` API, but those libraries still replace the real network layer, so behavior under them is not guaranteed. In tests that stub HTTP, prefer `streaming: false`.

data/SECURITY.md

@@ -0,0 +1,52 @@
+# Security Policy
+
+`rack-proxy` is a request/response-rewriting HTTP proxy. Because it forwards
+attacker-influenced requests to a backend and relays the backend's response, how
+you configure and subclass it has direct security consequences. Please read the
+threat model below alongside the "Security considerations" section of the README.
+
+## Supported versions
+
+Security fixes are released for the latest major series. The last `0.x` series
+receives fixes for critical issues only, for a transition period — please
+upgrade to `1.x`.
+
+| Version | Supported |
+| ------- | --------- |
+| 1.0.x   | ✅        |
+| 0.8.x   | critical fixes only |
+| < 0.8   | ❌        |
+
+## Reporting a vulnerability
+
+**Please do not open a public issue for security problems.**
+
+Report privately through GitHub's **Report a vulnerability** button under the
+repository's *Security* tab (Private Vulnerability Reporting). If that is
+unavailable to you, email the maintainer at **jacek.becela@gmail.com** with
+`[rack-proxy security]` in the subject.
+
+Please include:
+
+- the rack-proxy, Rack, and Ruby versions,
+- whether you run in streaming (`streaming: true`, the default) or non-streaming mode,
+- a minimal `config.ru` / subclass that reproduces the issue,
+- the impact you observed.
+
+We aim to acknowledge a report within **5 business days** and to agree on a
+disclosure timeline from there. We are grateful for responsible disclosure and
+will credit reporters who want it.
+
+## Scope
+
+In scope: defects in the library itself — for example, credentials or hop-by-hop
+headers being forwarded when they should not be, request/response smuggling,
+verification defaults that are weaker than documented, or a crash/`500` where a
+`4xx`/`5xx` mapping is expected.
+
+Out of scope: insecure **configuration or subclassing** of the library. Since
+1.0, deriving the backend from the client-controlled `Host` header requires an
+explicit `allow_dynamic_backend: true`; opting in without a `backend_allowed?`
+allowlist is an SSRF/open-proxy risk that is the deployer's responsibility —
+see the README "Security considerations". If the documentation is what led you
+astray, that is in scope: tell us and we will fix the docs.