http_decoy 0.1.0

data/lib/httpfake/router.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module HttpFake
+  # Matches an incoming (method, path) pair against a list of Route objects.
+  # Supports :param segments in patterns, e.g. "/v1/charges/:id".
+  class Router
+    Match = Struct.new(:route, :params, keyword_init: true)
+
+    def initialize(routes)
+      @routes = routes
+    end
+
+    # Returns a Match or nil.
+    def match(method, path, scenario: nil)
+      http_method = method.to_s.upcase
+      @routes.each do |route|
+        next unless route.method == http_method
+        next unless route.scenario == scenario
+
+        captures = extract_params(route.pattern, path)
+        next if captures.nil?
+
+        return Match.new(route: route, params: captures)
+      end
+      nil
+    end
+
+    private
+
+    def extract_params(pattern, path)
+      regex = pattern_to_regex(pattern)
+      m = path.match(regex)
+      return nil unless m
+
+      m.named_captures.transform_keys(&:to_sym)
+    end
+
+    def pattern_to_regex(pattern)
+      escaped = pattern.gsub(/:([a-zA-Z_][a-zA-Z0-9_]*)/) { "(?<#{Regexp.last_match(1)}>[^/]+)" }
+      /\A#{escaped}\z/
+    end
+  end
+end

data/lib/httpfake/rspec.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require_relative "route_map"
+require_relative "server"
+require_relative "webmock_integration"
+
+module HttpFake
+  # RSpec integration.
+  #
+  # Two equivalent usage patterns:
+  #
+  # Pattern A — inline (per describe block):
+  #
+  #   RSpec.describe MyService do
+  #     include HttpFake::RSpec
+  #
+  #     fake_server(:payments) do
+  #       post "/charges" do
+  #         respond 201, json: { id: "ch_abc" }
+  #       end
+  #     end
+  #
+  #     it "creates a charge" do
+  #       MyService.charge(100)
+  #       expect(fake_server(:payments)).to have_received_request(:post, "/charges").once
+  #     end
+  #   end
+  #
+  # Pattern B — suite-wide definition (most common):
+  #
+  #   FakeStripe = HttpFake.define(:stripe) do
+  #     base_url "https://api.stripe.com"
+  #     post "/v1/charges" do
+  #       respond 200, json: { id: "ch_123" }
+  #     end
+  #   end
+  #
+  #   RSpec.configure { |c| c.include FakeStripe.rspec_helpers }
+  #
+  #   it "charges the card" do
+  #     StripeService.charge(500)
+  #     expect(fake_server(:stripe)).to have_received_request(:post, "/v1/charges").once
+  #   end
+  #
+  module RSpec
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Class-level macro. Evaluates the block into a RouteMap once at class-load
+      # time, then registers before/after hooks for per-example server lifecycle.
+      def fake_server(name, &)
+        route_map = RouteMap.new
+        route_map.instance_eval(&)
+        _httpfake_register(name, route_map)
+      end
+
+      # Internal: register before/after hooks for a pre-built RouteMap.
+      # Called by both the inline macro and Definition#rspec_helpers.
+      def _httpfake_register(name, route_map)
+        before(:each) do
+          server = Server.new(route_map)
+          server.start
+          stub = WebMockIntegration.setup(server)
+
+          @_httpfake_servers       ||= {}
+          @_httpfake_webmock_stubs ||= {}
+          @_httpfake_servers[name]       = server
+          @_httpfake_webmock_stubs[name] = stub
+        end
+
+        after(:each) do
+          server = @_httpfake_servers&.[](name)
+          stub   = @_httpfake_webmock_stubs&.[](name)
+          WebMockIntegration.teardown(stub)
+          server&.stop
+        end
+      end
+    end
+
+    # Instance-level accessor — returns the live Server for this example.
+    def fake_server(name)
+      @_httpfake_servers[name]
+    end
+
+    # Run a block with a named scenario active.
+    # server_name defaults to the only server if exactly one is registered.
+    def with_scenario(scenario_name, server_name = nil, &)
+      name = server_name || begin
+        servers = @_httpfake_servers || {}
+        raise ArgumentError, "server_name required when multiple fake servers are active" if servers.size > 1
+        raise ArgumentError, "No fake servers are active" if servers.empty?
+
+        servers.keys.first
+      end
+
+      server = @_httpfake_servers[name]
+      raise ArgumentError, "No fake server named #{name.inspect}" unless server
+
+      server.with_scenario(scenario_name, &)
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # RSpec matchers
+  # ---------------------------------------------------------------------------
+
+  ::RSpec::Matchers.define :have_received_request do |method, path|
+    match do |server|
+      entries = server.request_log.for(method, path)
+      next false if entries.empty?
+      next false if @times && entries.count != @times
+      next false if @body_matcher && entries.none? { |e| body_matches?(e.body, @body_matcher) }
+
+      true
+    end
+
+    chain :once do
+      @times = 1
+    end
+    chain :twice do
+      @times = 2
+    end
+    chain :times do |n|
+      @times = n
+    end
+
+    chain :with do |body: nil|
+      @body_matcher = body
+    end
+
+    failure_message do |server|
+      entries = server.request_log.for(method, path)
+      if entries.empty?
+        "expected #{method.to_s.upcase} #{path} to have been received, but it was never called"
+      elsif @times && entries.count != @times
+        "expected #{method.to_s.upcase} #{path} to have been received #{@times} time(s), " \
+          "but it was received #{entries.count} time(s)"
+      else
+        "expected #{method.to_s.upcase} #{path} body to match #{@body_matcher.inspect}, " \
+          "but received: #{entries.map(&:body).inspect}"
+      end
+    end
+
+    failure_message_when_negated do |_server|
+      "expected #{method.to_s.upcase} #{path} not to have been received"
+    end
+
+    description do
+      desc = "have received #{method.to_s.upcase} #{path}"
+      desc += " #{@times} time(s)" if @times
+      desc += " with body matching #{@body_matcher.inspect}" if @body_matcher
+      desc
+    end
+
+    def body_matches?(actual, matcher)
+      case matcher
+      when Hash
+        actual.is_a?(Hash) && matcher.all? do |k, v|
+          actual_val = actual[k] || actual[k.to_s]
+          v === actual_val
+        end
+      else
+        matcher === actual
+      end
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Definition — returned by HttpFake.define
+  # ---------------------------------------------------------------------------
+
+  # Wraps a named RouteMap and generates an anonymous RSpec helper module.
+  class Definition
+    attr_reader :name, :route_map
+
+    def initialize(name, route_map)
+      @name      = name
+      @route_map = route_map
+    end
+
+    # Returns an anonymous module. Include it in RSpec.configure to register
+    # the server lifecycle for every example group in the suite.
+    #
+    #   RSpec.configure { |c| c.include FakeStripe.rspec_helpers }
+    #
+    def rspec_helpers
+      definition = self
+
+      Module.new do
+        include HttpFake::RSpec
+
+        # define_singleton_method closes over `definition` from the outer scope.
+        # `def self.included` would NOT — def never captures outer locals.
+        define_singleton_method(:included) do |base|
+          super(base)
+          base._httpfake_register(definition.name, definition.route_map)
+        end
+
+        define_method(:_httpfake_definition) { definition }
+      end
+    end
+  end
+end

data/lib/httpfake/server.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "webrick"
+require "rack"
+require "stringio"
+require "json"
+require_relative "request_log"
+require_relative "handler_context"
+
+module HttpFake
+  # A real WEBrick HTTP server that runs in a background thread.
+  #
+  # Uses WEBrick directly (no Rack::Handler) so it works with both
+  # Rack 2.x and Rack 3.x without the rackup gem.
+  #
+  # Port 0 lets the OS pick a free port atomically — parallel test
+  # runners never collide.
+  class Server
+    attr_reader :route_map, :request_log, :port
+
+    def initialize(route_map)
+      @route_map   = route_map
+      @request_log = RequestLog.new
+      @webrick     = nil
+      @thread      = nil
+      @port        = nil
+      @scenario    = nil
+      @scenario_mu = Mutex.new
+    end
+
+    def start
+      rack_app = build_rack_app
+
+      # WEBrick binds to the OS-assigned port during initialization.
+      @webrick = WEBrick::HTTPServer.new(
+        Port: 0,
+        Logger: WEBrick::Log.new(File::NULL),
+        AccessLog: []
+      )
+      @port = @webrick.config[:Port]
+
+      @webrick.mount_proc("/") do |req, res|
+        status, headers, body = rack_app.call(rack_env_from(req))
+        res.status = status.to_i
+        headers.each { |k, v| res[k] = v }
+        res.body = Array(body).join
+      rescue StandardError => e
+        res.status = 500
+        res["Content-Type"] = "application/json"
+        res.body = JSON.generate(error: "#{e.class}: #{e.message}")
+      end
+
+      @thread = Thread.new { @webrick.start }
+      @thread.abort_on_exception = true
+
+      # Poll until WEBrick enters its accept loop.
+      deadline = Time.now + 5
+      sleep(0.005) until @webrick.status == :Running || Time.now > deadline
+      raise "httpfake: server failed to start within 5 seconds" unless @webrick.status == :Running
+
+      self
+    end
+
+    def stop
+      @webrick&.shutdown
+      @thread&.join(3)
+      @thread  = nil
+      @webrick = nil
+    end
+
+    def base_url = "http://127.0.0.1:#{@port}"
+
+    # The Rack app is also exposed for WebMock's to_rack() interception.
+    def rack_app
+      @rack_app ||= build_rack_app
+    end
+
+    def with_scenario(name)
+      @scenario_mu.synchronize { @scenario = name }
+      yield
+    ensure
+      @scenario_mu.synchronize { @scenario = nil }
+    end
+
+    def current_scenario
+      @scenario_mu.synchronize { @scenario }
+    end
+
+    private
+
+    def build_rack_app
+      route_map   = @route_map
+      request_log = @request_log
+      server      = self
+
+      lambda do |env|
+        req      = Rack::Request.new(env)
+        method   = req.request_method
+        path     = req.path_info
+        scenario = server.current_scenario
+
+        result   = route_map.router.match(method, path, scenario: scenario)
+        result ||= route_map.router.match(method, path, scenario: nil) if scenario
+
+        return json_response(404, error: "No route matches #{method} #{path}") unless result
+
+        call_index = request_log.for(method, path).count
+        ctx        = HandlerContext.new(req, result.params, call_index: call_index)
+
+        begin
+          ctx.instance_eval(&result.route.handler_block)
+        rescue HandlerContext::ContractError => e
+          return json_response(422, error: e.message)
+        end
+
+        request_log.record(
+          method: method,
+          path: path,
+          body: ctx.body,
+          headers: env.select { |k, _| k.start_with?("HTTP_") },
+          query_params: ctx.query_params
+        )
+
+        ctx.response || json_response(200, status: "ok")
+      end
+    end
+
+    # Convert a WEBrick::HTTPRequest into a Rack-compatible env hash.
+    # Uses req.header (a Hash with lowercase keys) rather than each_header,
+    # which does not exist on WEBrick::HTTPRequest.
+    def rack_env_from(req)
+      body_str = req.body || ""
+
+      env = {
+        "REQUEST_METHOD" => req.request_method,
+        "SCRIPT_NAME" => "",
+        "PATH_INFO" => req.path,
+        "QUERY_STRING" => req.query_string || "",
+        "SERVER_NAME" => "127.0.0.1",
+        "SERVER_PORT" => @port.to_s,
+        "CONTENT_TYPE" => req.content_type || "",
+        "CONTENT_LENGTH" => body_str.bytesize.to_s,
+        "rack.input" => StringIO.new(body_str),
+        "rack.errors" => $stderr,
+        "rack.multithread" => true,
+        "rack.multiprocess" => false,
+        "rack.run_once" => false,
+        "rack.url_scheme" => "http"
+      }
+
+      # req.header is a Hash of { "lowercase-name" => ["value"] }
+      req.header.each do |key, values|
+        rack_key = key.upcase.tr("-", "_")
+        next if %w[CONTENT_TYPE CONTENT_LENGTH].include?(rack_key)
+
+        env["HTTP_#{rack_key}"] = Array(values).join(", ")
+      end
+
+      env
+    end
+
+    def json_response(status, payload)
+      [status.to_i, { "Content-Type" => "application/json" }, [JSON.generate(payload)]]
+    end
+  end
+end

data/lib/httpfake/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HttpFake
+  VERSION = "0.1.0"
+end

data/lib/httpfake/webmock_integration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module HttpFake
+  # Manages the WebMock stub that routes a declared base_url to the server's Rack app.
+  #
+  # Auto-detect: if WebMock is loaded and HttpFake.configuration.auto_intercept is true,
+  # requests to the declared base_url are intercepted transparently.
+  #
+  # Teardown removes only the stub httpfake created — never calls WebMock.reset!.
+  # If WebMock/RSpec has already cleared the registry (its own after(:each) hook),
+  # we rescue silently rather than crashing.
+  module WebMockIntegration
+    class << self
+      def available?
+        defined?(WebMock) && WebMock.respond_to?(:stub_request)
+      end
+
+      # Install an interception stub for the given server.
+      # Returns the stub object so it can be removed precisely during teardown.
+      def setup(server)
+        return nil unless available? && HttpFake.configuration.auto_intercept
+        return nil unless server.route_map.declared_base_url
+
+        # Match the full base URL (scheme + host) so the regex anchors correctly.
+        # e.g. "https://api.stripe.com" → /\Ahttps:\/\/api\.stripe\.com/
+        base    = server.route_map.declared_base_url.chomp("/")
+        pattern = /\A#{Regexp.escape(base)}/
+
+        WebMock.stub_request(:any, pattern).to_rack(server.rack_app)
+      end
+
+      # Remove only the stub we created.
+      # Rescues silently if webmock/rspec already cleared the registry between examples.
+      def teardown(stub)
+        return unless stub && available?
+
+        WebMock::StubRegistry.instance.remove_request_stub(stub)
+      rescue RuntimeError
+        # Already removed by WebMock.reset! (e.g. webmock/rspec after(:each) hook). Fine.
+      end
+    end
+  end
+end

data/lib/httpfake.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "httpfake/version"
+require_relative "httpfake/configuration"
+require_relative "httpfake/route"
+require_relative "httpfake/route_map"
+require_relative "httpfake/router"
+require_relative "httpfake/request_log"
+require_relative "httpfake/handler_context"
+require_relative "httpfake/server"
+require_relative "httpfake/webmock_integration"
+
+module HttpFake
+  class << self
+    # Global configuration.
+    #
+    #   HttpFake.configure do |c|
+    #     c.auto_intercept = false   # opt out of WebMock auto-interception
+    #   end
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Define a named fake service.
+    #
+    #   FakeStripe = HttpFake.define(:stripe) do
+    #     base_url "https://api.stripe.com"
+    #
+    #     post "/v1/charges" do
+    #       requires_body :amount, :currency, :payment_method
+    #       respond 200, json: { id: -> { "ch_#{SecureRandom.hex(8)}" } }
+    #     end
+    #   end
+    #
+    #   RSpec.configure { |c| c.include FakeStripe.rspec_helpers }
+    #
+    def define(name = :default, &)
+      require_relative "httpfake/rspec"
+      route_map = RouteMap.new
+      route_map.instance_eval(&)
+      Definition.new(name, route_map)
+    end
+  end
+end

data/sig/httpfake.rbs

@@ -0,0 +1,4 @@
+module Httpfake
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: http_decoy
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jibran Usman
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: httpfake spins up a real Rack server inside your tests with a clean DSL.
+  Define routes, validate request contracts, return dynamic fixtures, and tear down
+  automatically. No VCR cassettes. No scattered WebMock stubs.
+email:
+- jibran.usman@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/httpfake.rb
+- lib/httpfake/configuration.rb
+- lib/httpfake/handler_context.rb
+- lib/httpfake/request_log.rb
+- lib/httpfake/route.rb
+- lib/httpfake/route_map.rb
+- lib/httpfake/router.rb
+- lib/httpfake/rspec.rb
+- lib/httpfake/server.rb
+- lib/httpfake/version.rb
+- lib/httpfake/webmock_integration.rb
+- sig/httpfake.rbs
+homepage: https://github.com/jibranusman95/httpfake
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jibranusman95/httpfake
+  source_code_uri: https://github.com/jibranusman95/httpfake
+  changelog_uri: https://github.com/jibranusman95/httpfake/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Declarative fake HTTP servers for RSpec. Real server. Real requests. Zero
+  cassettes.
+test_files: []