http_decoy 0.1.0

data/README.md

@@ -0,0 +1,478 @@
+# httpfake
+
+**A real fake HTTP server. For real tests.**
+
+[![CI](https://github.com/jibranusman/httpfake/actions/workflows/ci.yml/badge.svg)](https://github.com/jibranusman/httpfake/actions)
+[![Gem Version](https://badge.fury.io/rb/httpfake.svg)](https://badge.fury.io/rb/httpfake)
+[![Downloads](https://img.shields.io/gem/dt/httpfake)](https://rubygems.org/gems/httpfake)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+Your WebMock stubs are lying to you.
+
+They test that your code constructs the right HTTP call. Not that the API would accept it. Not that the response shape matches what your code expects. Not that you haven't been sending a stale request format for six months while production quietly breaks.
+
+**httpfake spins up a real Rack server inside your tests** — one that validates incoming request contracts, computes dynamic responses from real inputs, and fails loudly the moment your code sends something wrong.
+
+No cassettes. No scattered stubs. No surprises on deploy day.
+
+---
+
+## The problem, illustrated
+
+Three tests. Same feature. Different levels of lying.
+
+### Test 1 — WebMock (stub at the adapter layer)
+
+```ruby
+stub_request(:post, "https://api.stripe.com/v1/charges")
+  .with(body: { amount: "2000", currency: "usd" })
+  .to_return(status: 200, body: '{"id":"ch_123","status":"succeeded"}')
+```
+
+This test passes even if:
+- Your code sends `paymet_method` instead of `payment_method` (typo, ships to prod)
+- Stripe adds a required field next week (stub keeps returning 200, forever)
+- The response shape changes (your parser breaks in prod, not in tests)
+- Your code sends `"2000"` as a string but Stripe requires an integer
+
+The stub doesn't know anything about Stripe. It just pattern-matches and returns JSON.
+
+### Test 2 — VCR (record once, replay forever)
+
+```ruby
+it "charges the customer", vcr: { cassette_name: "stripe/charge" } do
+  result = StripeService.charge(amount: 2000)
+  expect(result.status).to eq "succeeded"
+end
+```
+
+This test passes even if:
+- The cassette was recorded in 2022 and `payment_method` became required in 2023
+- The cassette contains your actual Stripe test key (committed to git, forever)
+- You need to test what happens when a card is declined (good luck editing cassette YAML)
+- CI has no network access for the initial recording run
+
+You end up with 50 YAML files nobody touches, all slowly diverging from reality.
+
+### Test 3 — httpfake (what tests should look like)
+
+```ruby
+FakeStripe = HttpFake.define(:stripe) do
+  base_url "https://api.stripe.com"
+
+  post "/v1/charges" do
+    requires_body :amount, :currency, :payment_method
+    validates :amount,   type: Integer, min: 50
+    validates :currency, inclusion: %w[usd gbp eur]
+
+    respond 200, json: {
+      id:       -> { "ch_#{SecureRandom.hex(8)}" },
+      status:   "succeeded",
+      amount:   -> { body[:amount] },
+      currency: -> { body[:currency] }
+    }
+  end
+
+  post "/v1/charges", scenario: :card_declined do
+    respond 402, json: { error: { code: "card_declined" } }
+  end
+end
+```
+
+Now your tests:
+- **Fail immediately** if your code sends a missing or invalid field
+- **Reflect real request data** back in responses — no frozen stubs
+- **Test failure paths** with one line: `with_scenario(:card_declined) { ... }`
+- **Work offline**, in CI, on a plane, in an airgapped environment
+- **Live in one place** — define once, use across every test in the suite
+
+---
+
+## Install
+
+```ruby
+# Gemfile
+group :test do
+  gem "httpfake"
+end
+```
+
+```bash
+bundle install
+```
+
+---
+
+## Quickstart (5 minutes)
+
+### 1. Define your fake service
+
+```ruby
+# spec/support/fakes/fake_stripe.rb
+FakeStripe = HttpFake.define(:stripe) do
+  base_url "https://api.stripe.com"
+
+  post "/v1/charges" do
+    requires_body :amount, :currency, :payment_method
+    validates :amount, type: Integer, min: 50
+
+    respond 200, json: {
+      id:     -> { "ch_#{SecureRandom.hex(8)}" },
+      status: "succeeded",
+      amount: -> { body[:amount] }
+    }
+  end
+
+  get "/v1/charges/:id" do
+    respond 200, json: {
+      id:     -> { path_params[:id] },
+      status: "succeeded"
+    }
+  end
+
+  post "/v1/charges", scenario: :card_declined do
+    respond 402, json: {
+      error: { code: "card_declined", message: "Your card was declined." }
+    }
+  end
+
+  post "/v1/charges", scenario: :network_error do
+    raise_error :timeout
+  end
+end
+```
+
+### 2. Load it in spec_helper
+
+```ruby
+# spec/spec_helper.rb
+require "httpfake"
+require "support/fakes/fake_stripe"
+
+RSpec.configure do |config|
+  config.include FakeStripe.rspec_helpers
+end
+```
+
+### 3. Write tests
+
+```ruby
+RSpec.describe StripeService do
+  describe "#charge" do
+    it "creates a charge and returns the id" do
+      result = StripeService.charge(amount: 2000, currency: "usd", payment_method: "pm_card_visa")
+      expect(result.id).to match(/\Ach_/)
+      expect(result.amount).to eq 2000
+    end
+
+    it "raises PaymentError on card decline" do
+      with_scenario(:card_declined) do
+        expect { StripeService.charge(amount: 2000, currency: "usd", payment_method: "pm_card_visa") }
+          .to raise_error(StripeService::PaymentError, /declined/)
+      end
+    end
+
+    it "raises NetworkError on timeout" do
+      with_scenario(:network_error) do
+        expect { StripeService.charge(amount: 2000, currency: "usd", payment_method: "pm_card_visa") }
+          .to raise_error(StripeService::NetworkError)
+      end
+    end
+
+    it "catches bad requests before they reach prod" do
+      # Missing payment_method — httpfake raises immediately with a descriptive error
+      expect { StripeService.charge(amount: 2000, currency: "usd") }
+        .to raise_error(HttpFake::HandlerContext::ContractError, /payment_method is required/)
+    end
+  end
+end
+```
+
+No setup per test. No per-test `stub_request`. No cassette files.
+
+---
+
+## DSL Reference
+
+### Defining a server
+
+```ruby
+MyFakeService = HttpFake.define(:my_service) do
+  base_url "https://api.example.com"   # intercepted via WebMock automatically
+  # ...routes
+end
+```
+
+### Routes
+
+```ruby
+get    "/path"
+post   "/path"
+put    "/path"
+patch  "/path"
+delete "/path"
+```
+
+Path parameters:
+
+```ruby
+get "/users/:id/posts/:post_id" do
+  respond 200, json: { user_id: path_params[:id], post_id: path_params[:post_id] }
+end
+```
+
+Query parameters:
+
+```ruby
+get "/search" do
+  respond 200, json: { results: [], query: query_params[:q] }
+end
+```
+
+### Request contract validation
+
+```ruby
+post "/orders" do
+  requires_body :item_id, :quantity              # presence check
+  validates :quantity, type: Integer, min: 1     # type + range
+  validates :status, inclusion: %w[pending paid] # enum
+
+  respond 201, json: { order_id: -> { SecureRandom.uuid } }
+end
+```
+
+When validation fails, httpfake raises `HttpFake::HandlerContext::ContractError` with a message naming the exact field and rule. Your test fails at the right place, with the right message.
+
+### Dynamic responses
+
+Use lambdas anywhere in the response body — evaluated at request time with access to the full request:
+
+```ruby
+post "/echo" do
+  respond 200, json: {
+    received_at: -> { Time.now.iso8601 },
+    you_sent:    -> { body },
+    your_ip:     -> { request.ip }
+  }
+end
+```
+
+### Scenarios (failure simulation)
+
+```ruby
+# Definition
+post "/payments", scenario: :rate_limited do
+  respond 429, json: { error: "Too many requests" }, headers: { "Retry-After" => "30" }
+end
+
+post "/payments", scenario: :timeout do
+  raise_error :timeout
+end
+
+# Usage in tests
+with_scenario(:rate_limited) do
+  expect { PaymentService.pay(100) }.to raise_error(PaymentService::RateLimitError)
+end
+```
+
+Available transport errors: `:timeout`, `:reset`, `:refused`.
+
+### Stateful sequences
+
+```ruby
+get "/account/balance" do
+  respond_sequence(
+    [200, { json: { balance: 1000, status: "active" } }],
+    [200, { json: { balance:    0, status: "active" } }],
+    [403, { json: { error: "Account suspended" } }]
+  )
+end
+```
+
+First call → 1000. Second call → 0. Third call → 403. Wraps automatically.
+
+### Request assertions
+
+```ruby
+it "sends the right payload" do
+  StripeService.charge(amount: 500, currency: "usd", payment_method: "pm_123")
+
+  expect(fake_server(:stripe)).to have_received_request(:post, "/v1/charges")
+    .once
+    .with(body: { amount: 500, currency: "usd" })
+end
+```
+
+Chains: `.once`, `.twice`, `.times(n)`, `.with(body: ...)`.
+
+---
+
+## RSpec integration
+
+Suite-wide (recommended):
+
+```ruby
+RSpec.configure do |config|
+  config.include FakeStripe.rspec_helpers
+  config.include FakeSendGrid.rspec_helpers
+end
+```
+
+Inline per describe block:
+
+```ruby
+RSpec.describe "degraded upstream" do
+  include HttpFake::RSpec
+
+  fake_server(:api) do
+    get "/status" do
+      respond 503, json: { status: "degraded" }
+    end
+  end
+
+  it "handles it gracefully" do
+    expect(MyApp.health_check).to eq :degraded
+  end
+end
+```
+
+---
+
+## Configuration
+
+```ruby
+# Opt out of WebMock auto-interception (e.g. if you manage stubs manually)
+HttpFake.configure do |config|
+  config.auto_intercept = false
+end
+```
+
+---
+
+## Why not WebMock / VCR? (honest comparison)
+
+| | WebMock | VCR | **httpfake** |
+|---|---|---|---|
+| Real server | No | No | **Yes** |
+| Request contract validation | No | No | **Yes** |
+| Dynamic responses | No | No | **Yes** |
+| Failure scenario testing | Verbose | Very hard | **One line** |
+| Works offline | Yes | First run: No | **Yes** |
+| Secrets in version control | No | **Risk** | No |
+| Cassettes to maintain | No | **Yes** | No |
+| Define once, use everywhere | Requires setup | Yes | **Yes** |
+| Catches API drift | No | No | **Yes** |
+
+httpfake uses WebMock internally to intercept requests — complementary, not a replacement.
+
+---
+
+## Real-world examples
+
+<details>
+<summary>Stripe (payments)</summary>
+
+```ruby
+FakeStripe = HttpFake.define(:stripe) do
+  base_url "https://api.stripe.com"
+
+  post "/v1/payment_intents" do
+    requires_body :amount, :currency, :payment_method
+    validates :amount, type: Integer, min: 50
+
+    respond 200, json: {
+      id:             -> { "pi_#{SecureRandom.hex(12)}" },
+      status:         "succeeded",
+      amount:         -> { body[:amount] },
+      currency:       -> { body[:currency] },
+      payment_method: -> { body[:payment_method] }
+    }
+  end
+
+  post "/v1/payment_intents", scenario: :insufficient_funds do
+    respond 402, json: {
+      error: { code: "insufficient_funds", decline_code: "insufficient_funds" }
+    }
+  end
+end
+```
+</details>
+
+<details>
+<summary>SendGrid (email)</summary>
+
+```ruby
+FakeSendGrid = HttpFake.define(:sendgrid) do
+  base_url "https://api.sendgrid.com"
+
+  post "/v3/mail/send" do
+    requires_body :to, :from, :subject, :content
+    respond 202, text: ""
+  end
+
+  post "/v3/mail/send", scenario: :invalid_email do
+    respond 400, json: { errors: [{ message: "Invalid email address" }] }
+  end
+end
+```
+</details>
+
+<details>
+<summary>Internal microservice</summary>
+
+```ruby
+FakeInventory = HttpFake.define(:inventory) do
+  base_url "https://inventory.internal"
+
+  get "/products/:sku/stock" do
+    respond 200, json: {
+      sku:   -> { path_params[:sku] },
+      stock: -> { rand(0..100) },
+      unit:  "each"
+    }
+  end
+
+  get "/products/:sku/stock", scenario: :out_of_stock do
+    respond 200, json: { sku: -> { path_params[:sku] }, stock: 0 }
+  end
+
+  get "/products/:sku/stock", scenario: :service_down do
+    respond 503, json: { error: "Inventory service is down" }
+  end
+end
+```
+</details>
+
+---
+
+## Requirements
+
+- Ruby 3.1+
+- Runtime dependencies: `webrick`, `rack` (both lightweight)
+- Optional: `webmock` for URL interception
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/jibranusman/httpfake
+cd httpfake
+bundle install
+bundle exec rspec      # run all tests
+bundle exec rubocop    # lint
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines. Good first issues are labeled [`good first issue`](https://github.com/jibranusman/httpfake/issues?q=label%3A%22good+first+issue%22).
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+*httpfake — stop testing your assumptions, start testing your contracts.*

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/httpfake/configuration.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module HttpFake
+  class Configuration
+    attr_accessor :auto_intercept
+
+    def initialize
+      @auto_intercept = true
+    end
+  end
+end

data/lib/httpfake/handler_context.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module HttpFake
+  # The `self` inside every route handler block.
+  # Provides the full DSL surface: respond, requires_body, validates,
+  # body, path_params, query_params, respond_sequence, raise_error.
+  class HandlerContext
+    class ContractError < StandardError
+    end
+
+    attr_reader :path_params, :query_params, :request
+
+    # call_index: how many prior requests to this same (method, path) have been logged.
+    # Used by respond_sequence to pick the right entry without storing mutable state.
+    def initialize(rack_request, path_params, call_index: 0)
+      @request     = rack_request
+      @path_params = path_params
+      @query_params = Rack::Utils.parse_nested_query(rack_request.query_string.to_s)
+        .transform_keys(&:to_sym)
+      @call_index  = call_index
+      @_body       = :unset
+      @_response   = nil
+    end
+
+    # Lazily parsed request body — memoized.
+    def body
+      return @_body unless @_body == :unset
+
+      raw = @request.body&.read || ""
+      @request.body&.rewind
+      content_type = @request.content_type.to_s
+
+      @_body = if content_type.include?("application/json")
+                 raw.empty? ? {} : JSON.parse(raw, symbolize_names: true)
+               elsif content_type.include?("application/x-www-form-urlencoded")
+                 Rack::Utils.parse_nested_query(raw).transform_keys(&:to_sym)
+               else
+                 raw
+               end
+    end
+
+    # Build and store the response tuple for this request.
+    def respond(status, json: nil, text: nil, headers: {})
+      body_str     = json ? JSON.generate(resolve(json)) : text.to_s
+      content_type = json ? "application/json" : "text/plain"
+      @_response   = [status.to_i, { "Content-Type" => content_type }.merge(headers), [body_str]]
+    end
+
+    # Stateful sequence: call_index picks which response to use.
+    # Each entry is [status, { json: ..., text: ..., headers: ... }].
+    # Wraps around if more calls are made than entries defined.
+    def respond_sequence(*responses)
+      entry  = responses[@call_index % responses.length]
+      status = entry[0]
+      opts   = entry[1] || {}
+      respond(status, **opts)
+    end
+
+    # Contract assertion: raises ContractError if any key is absent from body.
+    def requires_body(*keys)
+      keys.each do |key|
+        present = body.is_a?(Hash) && (body.key?(key) || body.key?(key.to_s))
+        raise ContractError, "#{key} is required in request body" unless present
+      end
+    end
+
+    # Type / range / enum validation on a body field.
+    def validates(key, type: nil, min: nil, max: nil, inclusion: nil)
+      value = body.is_a?(Hash) ? (body[key] || body[key.to_s]) : nil
+
+      raise ContractError, "#{key} must be a #{type}, got #{value.class}" if type && !value.is_a?(type)
+      raise ContractError, "#{key} must be >= #{min}, got #{value.inspect}" if min && value < min
+      raise ContractError, "#{key} must be <= #{max}, got #{value.inspect}" if max && value > max
+      return unless inclusion && !inclusion.include?(value)
+
+      raise ContractError, "#{key} must be one of #{inclusion.inspect}, got #{value.inspect}"
+    end
+
+    # Simulate transport-level failures.
+    def raise_error(type)
+      case type
+      when :timeout  then raise Timeout::Error, "httpfake simulated timeout"
+      when :reset    then raise Errno::ECONNRESET, "httpfake simulated connection reset"
+      when :refused  then raise Errno::ECONNREFUSED, "httpfake simulated connection refused"
+      else                raise type.is_a?(Class) ? type : RuntimeError, type.to_s
+      end
+    end
+
+    # Internal: the built response tuple, or nil if none was set.
+    def response
+      @_response
+    end
+
+    private
+
+    # Recursively resolve lambdas in response bodies so users can write:
+    #   respond 200, json: { id: -> { SecureRandom.uuid }, amount: -> { body[:amount] } }
+    def resolve(obj)
+      case obj
+      when Hash  then obj.transform_values { |v| resolve(v) }
+      when Array then obj.map { |v| resolve(v) }
+      when Proc  then resolve(instance_exec(&obj))
+      else            obj
+      end
+    end
+  end
+end

data/lib/httpfake/request_log.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module HttpFake
+  # Thread-safe store of every request received by the fake server.
+  # Cleared between examples via Server#stop → new Server per example.
+  class RequestLog
+    # Use http_method instead of method to avoid overriding Struct#method.
+    Entry = Struct.new(:http_method, :path, :body, :headers, :query_params, keyword_init: true)
+
+    def initialize
+      @entries = []
+      @mutex   = Mutex.new
+    end
+
+    def record(method:, path:, body:, headers:, query_params:)
+      @mutex.synchronize do
+        @entries << Entry.new(
+          http_method: method.to_s.upcase,
+          path: path,
+          body: body,
+          headers: headers,
+          query_params: query_params
+        )
+      end
+    end
+
+    def all
+      @mutex.synchronize { @entries.dup }
+    end
+
+    # Returns all entries matching the given HTTP method and exact path.
+    def for(method, path)
+      all.select { |e| e.http_method == method.to_s.upcase && e.path == path }
+    end
+
+    def clear
+      @mutex.synchronize { @entries.clear }
+    end
+
+    def count
+      @mutex.synchronize { @entries.size }
+    end
+  end
+end

data/lib/httpfake/route.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module HttpFake
+  # Represents a single declared route: method + path pattern + optional scenario.
+  class Route
+    attr_reader :method, :pattern, :scenario, :handler_block
+
+    def initialize(method, pattern, scenario: nil, &block)
+      @method       = method.to_s.upcase
+      @pattern      = pattern
+      @scenario     = scenario
+      @handler_block = block
+    end
+  end
+end

data/lib/httpfake/route_map.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "route"
+require_relative "router"
+
+module HttpFake
+  # DSL target for defining a set of routes.
+  # Instantiated once at class-load time; immutable after definition.
+  class RouteMap
+    attr_reader :declared_base_url
+
+    def initialize
+      @routes = []
+      @declared_base_url = nil
+    end
+
+    def base_url(url = nil)
+      url ? @declared_base_url = url : @declared_base_url
+    end
+
+    %i[get post put patch delete head options].each do |verb|
+      define_method(verb) do |pattern, scenario: nil, &block|
+        @routes << Route.new(verb, pattern, scenario: scenario, &block)
+      end
+    end
+
+    def routes
+      @routes.dup
+    end
+
+    def router
+      # Memoize — route list is never mutated after definition.
+      @router ||= Router.new(@routes)
+    end
+  end
+end