rack-proxy: Instructions file for Claude Code

Working in this repo (for AI agents and new contributors)

rack-proxy is a small, security-sensitive Rack middleware/app that proxies HTTP requests to a backend and lets you rewrite the request and response. It is a library that other apps mount — so the bar is: safe defaults, no surprises, and never regress the security behavior below. Read this before changing code.

Commands

bundle install
bundle exec rake test        # full suite, fully OFFLINE, ~2-3s
LIVE=1 bundle exec rake test  # additionally runs real-internet smoke tests
bundle exec standardrb       # style check, CI-blocking (--fix to autofix)
COVERAGE=1 bundle exec rake test  # SimpleCov, ratcheted floor (CI-enforced)

# Run the suite against a specific Rack major (CI does both):
BUNDLE_GEMFILE=gemfiles/rack_3.gemfile bundle exec rake test
BUNDLE_GEMFILE=gemfiles/rack_2.gemfile bundle exec rake test

The default suite must never touch the network. CI (.github/workflows/ci.yml) runs the matrix Ruby 3.1–3.4 × Rack 2/3, a ruby head canary, a gem-build smoke test, and a blocking lint job (standardrb + coverage floor + bundler-audit).

Architecture (two core files, ~460 lines)

• lib/rack/proxy.rb — Rack::Proxy. The entry point: call → rewrite_env → perform_request → rewrite_response. perform_request extracts/forwards request headers, picks the backend, and has two distinct network paths that must stay behaviorally identical: streaming (default) and non-streaming (streaming: false). Subclasses override rewrite_env / rewrite_response (and sometimes perform_request); see examples/ (copy-paste snippets, not shipped in the gem).
• lib/rack/http_streaming_response.rb — HttpStreamingResponse, the lazy Rack body used by the streaming path. It runs the public block form of Net::HTTP#request inside a Fiber: the Fiber pauses once the status and headers are in, and #each resumes it to pull body chunks; #each/#close tear the connection down (early termination unwinds the Fiber via Fiber#raise).
• lib/net_http_hacked.rb — the former streaming engine (a monkey-patch of private Net::HTTP internals) — was deleted in 1.0. Do not reintroduce it or anything like it; a subprocess test asserts the library loads without defining the old hacked methods.