mustwin-vcr 2.9.3

data/lib/vcr/middleware/rack.rb

@@ -0,0 +1,79 @@
+module VCR
+  module Middleware
+    # Object yielded by VCR's {Rack} middleware that allows you to configure
+    # the cassette dynamically based on the rack env.
+    class CassetteArguments
+      # @private
+      def initialize
+        @name    = nil
+        @options = {}
+      end
+
+      # Sets (and gets) the cassette name.
+      #
+      # @param [#to_s] name the cassette name
+      # @return [#to_s] the cassette name
+      def name(name = nil)
+        @name = name if name
+        @name
+      end
+
+      # Sets (and gets) the cassette options.
+      #
+      # @param [Hash] options the cassette options
+      # @return [Hash] the cassette options
+      def options(options = {})
+        @options.merge!(options)
+      end
+    end
+
+    # Rack middleware that uses a VCR cassette for each incoming HTTP request.
+    #
+    # @example
+    #   app = Rack::Builder.new do
+    #     use VCR::Middleware::Rack do |cassette, env|
+    #       cassette.name "rack/#{env['SERVER_NAME']}"
+    #       cassette.options :record => :new_episodes
+    #     end
+    #
+    #     run MyRackApp
+    #   end
+    #
+    # @note This will record/replay _outbound_ HTTP requests made by your rack app.
+    class Rack
+      include VCR::VariableArgsBlockCaller
+
+      # Constructs a new instance of VCR's rack middleware.
+      #
+      # @param [#call] app the rack app
+      # @yield the cassette configuration block
+      # @yieldparam [CassetteArguments] cassette the cassette configuration object
+      # @yieldparam [(optional) Hash] env the rack env hash
+      # @raise [ArgumentError] if no configuration block is provided
+      def initialize(app, &block)
+        raise ArgumentError.new("You must provide a block to set the cassette options") unless block
+        @app, @cassette_arguments_block, @mutex = app, block, Mutex.new
+      end
+
+      # Implements the rack middleware interface.
+      #
+      # @param [Hash] env the rack env hash
+      # @return [Array(Integer, Hash, #each)] the rack response
+      def call(env)
+        @mutex.synchronize do
+          VCR.use_cassette(*cassette_arguments(env)) do
+            @app.call(env)
+          end
+        end
+      end
+
+    private
+
+      def cassette_arguments(env)
+        arguments = CassetteArguments.new
+        call_block(@cassette_arguments_block, arguments, env)
+        [arguments.name, arguments.options]
+      end
+    end
+  end
+end

data/lib/vcr/request_handler.rb

@@ -0,0 +1,114 @@
+module VCR
+  # @private
+  class RequestHandler
+    include Logger::Mixin
+
+    def handle
+      log "Handling request: #{request_summary} (disabled: #{disabled?})"
+      invoke_before_request_hook
+
+      req_type = request_type(:consume_stub)
+
+      log "Identified request type (#{req_type}) for #{request_summary}"
+
+      # The before_request hook can change the type of request
+      # (i.e. by inserting a cassette), so we need to query the
+      # request type again.
+      #
+      # Likewise, the main handler logic can modify what
+      # #request_type would return (i.e. when a response stub is
+      # used), so we need to store the request type for the
+      # after_request hook.
+      set_typed_request_for_after_hook(req_type)
+
+      send "on_#{req_type}_request"
+    end
+
+  private
+
+    def set_typed_request_for_after_hook(request_type)
+      @after_hook_typed_request = Request::Typed.new(vcr_request, request_type)
+    end
+
+    def request_type(consume_stub = false)
+      case
+        when externally_stubbed?                then :externally_stubbed
+        when should_ignore?                     then :ignored
+        when has_response_stub?(consume_stub)   then :stubbed_by_vcr
+        when VCR.real_http_connections_allowed? then :recordable
+        else                                         :unhandled
+      end
+    end
+
+    def invoke_before_request_hook
+      return if disabled? || !VCR.configuration.has_hooks_for?(:before_http_request)
+      typed_request = Request::Typed.new(vcr_request, request_type)
+      VCR.configuration.invoke_hook(:before_http_request, typed_request)
+    end
+
+    def invoke_after_request_hook(vcr_response)
+      return if disabled?
+      VCR.configuration.invoke_hook(:after_http_request, @after_hook_typed_request, vcr_response)
+    end
+
+    def externally_stubbed?
+      false
+    end
+
+    def should_ignore?
+      disabled? || VCR.request_ignorer.ignore?(vcr_request)
+    end
+
+    def disabled?
+      VCR.library_hooks.disabled?(library_name)
+    end
+
+    def has_response_stub?(consume_stub)
+      if consume_stub
+        stubbed_response
+      else
+        VCR.http_interactions.has_interaction_matching?(vcr_request)
+      end
+    end
+
+    def stubbed_response
+      @stubbed_response ||= VCR.http_interactions.response_for(vcr_request)
+    end
+
+    def library_name
+      # extracts `:typhoeus` from `VCR::LibraryHooks::Typhoeus::RequestHandler`
+      @library_name ||= self.class.name.split('::')[-2].downcase.to_sym
+    end
+
+    # Subclasses can implement these
+    def on_externally_stubbed_request
+    end
+
+    def on_ignored_request
+    end
+
+    def on_stubbed_by_vcr_request
+    end
+
+    def on_recordable_request
+    end
+
+    def on_unhandled_request
+      raise VCR::Errors::UnhandledHTTPRequestError.new(vcr_request)
+    end
+
+    def request_summary
+      request_matchers = if cass = VCR.current_cassette
+        cass.match_requests_on
+      else
+        VCR.configuration.default_cassette_options[:match_requests_on]
+      end
+
+      super(vcr_request, request_matchers)
+    end
+
+    def log_prefix
+      "[#{library_name}] "
+    end
+  end
+end

data/lib/vcr/request_ignorer.rb

@@ -0,0 +1,43 @@
+require 'set'
+require 'vcr/util/hooks'
+
+module VCR
+  # @private
+  class RequestIgnorer
+    include VCR::Hooks
+
+    define_hook :ignore_request
+
+    LOCALHOST_ALIASES = %w( localhost 127.0.0.1 0.0.0.0 )
+
+    def initialize
+      ignore_request do |request|
+        host = request.parsed_uri.host
+        ignored_hosts.include?(host)
+      end
+    end
+
+    def ignore_localhost=(value)
+      if value
+        ignore_hosts(*LOCALHOST_ALIASES)
+      else
+        ignored_hosts.reject! { |h| LOCALHOST_ALIASES.include?(h) }
+      end
+    end
+
+    def ignore_hosts(*hosts)
+      ignored_hosts.merge(hosts)
+    end
+
+    def ignore?(request)
+      invoke_hook(:ignore_request, request).any?
+    end
+
+  private
+
+    def ignored_hosts
+      @ignored_hosts ||= Set.new
+    end
+  end
+end
+

data/lib/vcr/request_matcher_registry.rb

@@ -0,0 +1,149 @@
+require 'vcr/errors'
+
+module VCR
+  # Keeps track of the different request matchers.
+  class RequestMatcherRegistry
+
+    # The default request matchers used for any cassette that does not
+    # specify request matchers.
+    DEFAULT_MATCHERS = [:method, :uri]
+
+    # @private
+    class Matcher < Struct.new(:callable)
+      def matches?(request_1, request_2)
+        callable.call(request_1, request_2)
+      end
+    end
+
+    # @private
+    class URIWithoutParamsMatcher < Struct.new(:params_to_ignore)
+      def partial_uri_from(request)
+        request.parsed_uri.tap do |uri|
+          return uri unless uri.query # ignore uris without params, e.g. "http://example.com/"
+
+          uri.query = uri.query.split('&').tap { |params|
+            params.map! do |p|
+              key, value = p.split('=')
+              key.gsub!(/\[\]\z/, '') # handle params like tag[]=
+              [key, value]
+            end
+
+            params.reject! { |p| params_to_ignore.include?(p.first) }
+            params.map!    { |p| p.join('=') }
+          }.join('&')
+
+          uri.query = nil if uri.query.empty?
+        end
+      end
+
+      def call(request_1, request_2)
+        partial_uri_from(request_1) == partial_uri_from(request_2)
+      end
+
+      def to_proc
+        lambda { |r1, r2| call(r1, r2) }
+      end
+    end
+
+    # @private
+    def initialize
+      @registry = {}
+      register_built_ins
+    end
+
+    # @private
+    def register(name, &block)
+      if @registry.has_key?(name)
+        warn "WARNING: There is already a VCR request matcher registered for #{name.inspect}. Overriding it."
+      end
+
+      @registry[name] = Matcher.new(block)
+    end
+
+    # @private
+    def [](matcher)
+      @registry.fetch(matcher) do
+        matcher.respond_to?(:call) ?
+          Matcher.new(matcher) :
+          raise_unregistered_matcher_error(matcher)
+      end
+    end
+
+    # Builds a dynamic request matcher that matches on a URI while ignoring the
+    # named query parameters. This is useful for dealing with non-deterministic
+    # URIs (i.e. that have a timestamp or request signature parameter).
+    #
+    # @example
+    #   without_timestamp = VCR.request_matchers.uri_without_param(:timestamp)
+    #
+    #   # use it directly...
+    #   VCR.use_cassette('example', :match_requests_on => [:method, without_timestamp]) { }
+    #
+    #   # ...or register it as a named matcher
+    #   VCR.configure do |c|
+    #     c.register_request_matcher(:uri_without_timestamp, &without_timestamp)
+    #   end
+    #
+    #   VCR.use_cassette('example', :match_requests_on => [:method, :uri_without_timestamp]) { }
+    #
+    # @param ignores [Array<#to_s>] The names of the query parameters to ignore
+    # @return [#call] the request matcher
+    def uri_without_params(*ignores)
+      uri_without_param_matchers[ignores]
+    end
+    alias uri_without_param uri_without_params
+
+  private
+
+    def uri_without_param_matchers
+      @uri_without_param_matchers ||= Hash.new do |hash, params|
+        params = params.map(&:to_s)
+        hash[params] = URIWithoutParamsMatcher.new(params)
+      end
+    end
+
+    def raise_unregistered_matcher_error(name)
+      raise Errors::UnregisteredMatcherError.new \
+        "There is no matcher registered for #{name.inspect}. " +
+        "Did you mean one of #{@registry.keys.map(&:inspect).join(', ')}?"
+    end
+
+    def register_built_ins
+      register(:method)  { |r1, r2| r2.method.is_a?(Regexp)  ? r1.method.match(r2.method)   : r1.method == r2.method }
+      register(:uri)     { |r1, r2| r2.uri.is_a?(Regexp)     ? r1.uri.match(r2.uri)         : r1.uri == r2.uri }
+      register(:body)    { |r1, r2| r2.body.is_a?(Regexp)    ? r1.body.match(r2.body)       : r1.body == r2.body }
+      register(:headers) { |r1, r2| r2.headers.is_a?(Regexp) ? r1.headers.match(r2.headers) : r1.headers == r2.headers }
+
+      register(:host) do |r1, r2|
+        r1.parsed_uri.host == r2.parsed_uri.host
+      end
+      register(:path) do |r1, r2|
+        r1.parsed_uri.path == r2.parsed_uri.path
+      end
+
+      register(:query) do |r1, r2|
+        VCR.configuration.query_parser.call(r1.parsed_uri.query.to_s) ==
+          VCR.configuration.query_parser.call(r2.parsed_uri.query.to_s)
+      end
+
+      try_to_register_body_as_json
+    end
+
+    def try_to_register_body_as_json
+      begin
+        require 'json'
+      rescue LoadError
+        return
+      end
+
+      register(:body_as_json) do |r1, r2|
+        begin
+          JSON.parse(r1.body) == JSON.parse(r2.body)
+        rescue JSON::ParserError
+          false
+        end
+      end
+    end
+  end
+end
+

data/lib/vcr/structs.rb

@@ -0,0 +1,578 @@
+require 'base64'
+require 'delegate'
+require 'time'
+
+module VCR
+  # @private
+  module Normalizers
+    # @private
+    module Body
+      def self.included(klass)
+        klass.extend ClassMethods
+      end
+
+      # @private
+      module ClassMethods
+        def body_from(hash_or_string)
+          return hash_or_string unless hash_or_string.is_a?(Hash)
+          hash = hash_or_string
+
+          if hash.has_key?('base64_string')
+            string = Base64.decode64(hash['base64_string'])
+            force_encode_string(string, hash['encoding'])
+          else
+            try_encode_string(hash['string'], hash['encoding'])
+          end
+        end
+
+        if "".respond_to?(:encoding)
+          def force_encode_string(string, encoding)
+            return string unless encoding
+            string.force_encoding(encoding)
+          end
+
+          def try_encode_string(string, encoding)
+            return string if encoding.nil? || string.encoding.name == encoding
+
+            # ASCII-8BIT just means binary, so encoding to it is nonsensical
+            # and yet "\u00f6".encode("ASCII-8BIT") raises an error.
+            # Instead, we'll force encode it (essentially just tagging it as binary)
+            return string.force_encoding(encoding) if encoding == "ASCII-8BIT"
+
+            string.encode(encoding)
+          rescue EncodingError => e
+            struct_type = name.split('::').last.downcase
+            warn "VCR: got `#{e.class.name}: #{e.message}` while trying to encode the #{string.encoding.name} " +
+                 "#{struct_type} body to the original body encoding (#{encoding}). Consider using the " +
+                 "`:preserve_exact_body_bytes` option to work around this."
+            return string
+          end
+        else
+          def force_encode_string(string, encoding)
+            string
+          end
+
+          def try_encode_string(string, encoding)
+            string
+          end
+        end
+      end
+
+      def initialize(*args)
+        super
+
+        if body && !body.is_a?(String)
+          raise ArgumentError, "#{self.class} initialized with an invalid body: #{body.inspect}."
+        end
+
+        # Ensure that the body is a raw string, in case the string instance
+        # has been subclassed or extended with additional instance variables
+        # or attributes, so that it is serialized to YAML as a raw string.
+        # This is needed for rest-client.  See this ticket for more info:
+        # http://github.com/myronmarston/vcr/issues/4
+        self.body = String.new(body.to_s)
+      end
+
+    private
+
+      def serializable_body
+        # Ensure it's just a string, and not a string with some
+        # extra state, as such strings serialize to YAML with
+        # all the extra state.
+        body = String.new(self.body.to_s)
+
+        if VCR.configuration.preserve_exact_body_bytes_for?(self)
+          base_body_hash(body).merge('base64_string' => Base64.encode64(body))
+        else
+          base_body_hash(body).merge('string' => body)
+        end
+      end
+
+      if ''.respond_to?(:encoding)
+        def base_body_hash(body)
+          { 'encoding' => body.encoding.name }
+        end
+      else
+        def base_body_hash(body)
+          { }
+        end
+      end
+    end
+
+    # @private
+    module Header
+      def initialize(*args)
+        super
+        normalize_headers
+      end
+
+    private
+
+      def normalize_headers
+        new_headers = {}
+        @normalized_header_keys = Hash.new {|h,k| k }
+
+        headers.each do |k, v|
+          val_array = case v
+            when Array then v
+            when nil then []
+            else [v]
+          end
+
+          new_headers[String.new(k)] = convert_to_raw_strings(val_array)
+          @normalized_header_keys[k.downcase] = k
+        end if headers
+
+        self.headers = new_headers
+      end
+
+      def header_key(key)
+        key = @normalized_header_keys[key.downcase]
+        key if headers.has_key? key
+      end
+
+      def get_header(key)
+        key = header_key(key)
+        headers[key] if key
+      end
+
+      def edit_header(key, value = nil)
+        if key = header_key(key)
+          value ||= yield headers[key]
+          headers[key] = Array(value)
+        end
+      end
+
+      def delete_header(key)
+        if key = header_key(key)
+          @normalized_header_keys.delete key.downcase
+          headers.delete key
+        end
+      end
+
+      def convert_to_raw_strings(array)
+        # Ensure the values are raw strings.
+        # Apparently for Paperclip uploads to S3, headers
+        # get serialized with some extra stuff which leads
+        # to a seg fault. See this issue for more info:
+        # https://github.com/myronmarston/vcr/issues#issue/39
+        array.map do |v|
+          case v
+            when String; String.new(v)
+            when Array; convert_to_raw_strings(v)
+            else v
+          end
+        end
+      end
+    end
+  end
+
+  # @private
+  module OrderedHashSerializer
+    def each
+      @ordered_keys.each do |key|
+        yield key, self[key] if has_key?(key)
+      end
+    end
+
+    if RUBY_VERSION.to_f > 1.8
+      # 1.9+ hashes are already ordered.
+      def self.apply_to(*args); end
+    else
+      def self.apply_to(hash, keys)
+        hash.instance_variable_set(:@ordered_keys, keys)
+        hash.extend self
+      end
+    end
+  end
+
+  # The request of an {HTTPInteraction}.
+  #
+  # @attr [Symbol] method the HTTP method (i.e. :head, :options, :get, :post, :put, :patch or :delete)
+  # @attr [String] uri the request URI
+  # @attr [String, nil] body the request body
+  # @attr [Hash{String => Array<String>}] headers the request headers
+  class Request < Struct.new(:method, :uri, :body, :headers)
+    include Normalizers::Header
+    include Normalizers::Body
+
+    def initialize(*args)
+      skip_port_stripping = false
+      if args.last == :skip_port_stripping
+        skip_port_stripping = true
+        args.pop
+      end
+
+      super(*args)
+      self.method = self.method.to_s.downcase.to_sym if self.method
+      self.uri = without_standard_port(self.uri) unless skip_port_stripping
+    end
+
+    # Builds a serializable hash from the request data.
+    #
+    # @return [Hash] hash that represents this request and can be easily
+    #  serialized.
+    # @see Request.from_hash
+    def to_hash
+      {
+        'method'  => method.to_s,
+        'uri'     => uri,
+        'body'    => serializable_body,
+        'headers' => headers
+      }.tap { |h| OrderedHashSerializer.apply_to(h, members) }
+    end
+
+    # Constructs a new instance from a hash.
+    #
+    # @param [Hash] hash the hash to use to construct the instance.
+    # @return [Request] the request
+    def self.from_hash(hash)
+      method = hash['method']
+      method &&= method.to_sym
+      new method,
+          hash['uri'],
+          body_from(hash['body']),
+          hash['headers'],
+          :skip_port_stripping
+    end
+
+    # Parses the URI using the configured `uri_parser`.
+    #
+    # @return [#schema, #host, #port, #path, #query] A parsed URI object.
+    def parsed_uri
+      VCR.configuration.uri_parser.parse(uri)
+    end
+
+    @@object_method = Object.instance_method(:method)
+    def method(*args)
+      return super if args.empty?
+      @@object_method.bind(self).call(*args)
+    end
+
+    # Decorates a {Request} with its current type.
+    class Typed < DelegateClass(self)
+      # @return [Symbol] One of `:ignored`, `:stubbed`, `:recordable` or `:unhandled`.
+      attr_reader :type
+
+      # @param [Request] request the request
+      # @param [Symbol] type the type. Should be one of `:ignored`, `:stubbed`, `:recordable` or `:unhandled`.
+      def initialize(request, type)
+        @type = type
+        super(request)
+      end
+
+      # @return [Boolean] whether or not this request is being ignored
+      def ignored?
+        type == :ignored
+      end
+
+      # @return [Boolean] whether or not this request is being stubbed by VCR
+      # @see #externally_stubbed?
+      # @see #stubbed?
+      def stubbed_by_vcr?
+        type == :stubbed_by_vcr
+      end
+
+      # @return [Boolean] whether or not this request is being stubbed by an
+      #  external library (such as WebMock or FakeWeb).
+      # @see #stubbed_by_vcr?
+      # @see #stubbed?
+      def externally_stubbed?
+        type == :externally_stubbed
+      end
+
+      # @return [Boolean] whether or not this request will be recorded.
+      def recordable?
+        type == :recordable
+      end
+
+      # @return [Boolean] whether or not VCR knows how to handle this request.
+      def unhandled?
+        type == :unhandled
+      end
+
+      # @return [Boolean] whether or not this request will be made for real.
+      # @note VCR allows `:ignored` and `:recordable` requests to be made for real.
+      def real?
+        ignored? || recordable?
+      end
+
+      # @return [Boolean] whether or not this request will be stubbed.
+      #  It may be stubbed by an external library or by VCR.
+      # @see #stubbed_by_vcr?
+      # @see #externally_stubbed?
+      def stubbed?
+        stubbed_by_vcr? || externally_stubbed?
+      end
+
+      undef method
+    end
+
+    # Provides fiber-awareness for the {VCR::Configuration#around_http_request} hook.
+    class FiberAware < DelegateClass(Typed)
+      # Yields the fiber so the request can proceed.
+      #
+      # @return [VCR::Response] the response from the request
+      def proceed
+        Fiber.yield
+      end
+
+      # Builds a proc that allows the request to proceed when called.
+      # This allows you to treat the request as a proc and pass it on
+      # to a method that yields (at which point the request will proceed).
+      #
+      # @return [Proc] the proc
+      def to_proc
+        lambda { proceed }
+      end
+
+      undef method
+    end
+
+  private
+
+    def without_standard_port(uri)
+      return uri if uri.nil?
+      u = parsed_uri
+      return uri unless [['http', 80], ['https', 443]].include?([u.scheme, u.port])
+      u.port = nil
+      u.to_s
+    end
+  end
+
+  # The response of an {HTTPInteraction}.
+  #
+  # @attr [ResponseStatus] status the status of the response
+  # @attr [Hash{String => Array<String>}] headers the response headers
+  # @attr [String] body the response body
+  # @attr [nil, String] http_version the HTTP version
+  # @attr [Hash] adapter_metadata Additional metadata used by a specific VCR adapter.
+  class Response < Struct.new(:status, :headers, :body, :http_version, :adapter_metadata)
+    include Normalizers::Header
+    include Normalizers::Body
+
+    def initialize(*args)
+      super(*args)
+      self.adapter_metadata ||= {}
+    end
+
+    # Builds a serializable hash from the response data.
+    #
+    # @return [Hash] hash that represents this response
+    #  and can be easily serialized.
+    # @see Response.from_hash
+    def to_hash
+      {
+        'status'       => status.to_hash,
+        'headers'      => headers,
+        'body'         => serializable_body,
+        'http_version' => http_version
+      }.tap do |hash|
+        hash['adapter_metadata'] = adapter_metadata unless adapter_metadata.empty?
+        OrderedHashSerializer.apply_to(hash, members)
+      end
+    end
+
+    # Constructs a new instance from a hash.
+    #
+    # @param [Hash] hash the hash to use to construct the instance.
+    # @return [Response] the response
+    def self.from_hash(hash)
+      new ResponseStatus.from_hash(hash.fetch('status', {})),
+          hash['headers'],
+          body_from(hash['body']),
+          hash['http_version'],
+          hash['adapter_metadata']
+    end
+
+    # Updates the Content-Length response header so that it is
+    # accurate for the response body.
+    def update_content_length_header
+      edit_header('Content-Length') { body ? body.bytesize.to_s : '0' }
+    end
+
+    # The type of encoding.
+    #
+    # @return [String] encoding type
+    def content_encoding
+      enc = get_header('Content-Encoding') and enc.first
+    end
+
+    # Checks if the type of encoding is one of "gzip" or "deflate".
+    def compressed?
+      %w[ gzip deflate ].include? content_encoding
+    end
+
+    # Decodes the compressed body and deletes evidence that it was ever compressed.
+    #
+    # @return self
+    # @raise [VCR::Errors::UnknownContentEncodingError] if the content encoding
+    #  is not a known encoding.
+    def decompress
+      self.class.decompress(body, content_encoding) { |new_body|
+        self.body = new_body
+        update_content_length_header
+        delete_header('Content-Encoding')
+      }
+      return self
+    end
+
+    begin
+      require 'zlib'
+      require 'stringio'
+      HAVE_ZLIB = true
+    rescue LoadError
+      HAVE_ZLIB = false
+    end
+
+    # Decode string compressed with gzip or deflate
+    #
+    # @raise [VCR::Errors::UnknownContentEncodingError] if the content encoding
+    #  is not a known encoding.
+    def self.decompress(body, type)
+      unless HAVE_ZLIB
+        warn "VCR: cannot decompress response; Zlib not available"
+        return
+      end
+
+      case type
+      when 'gzip'
+        args = [StringIO.new(body)]
+        args << { :encoding => 'ASCII-8BIT' } if ''.respond_to?(:encoding)
+        yield Zlib::GzipReader.new(*args).read
+      when 'deflate'
+        yield Zlib::Inflate.inflate(body)
+      when 'identity', NilClass
+        return
+      else
+        raise Errors::UnknownContentEncodingError, "unknown content encoding: #{type}"
+      end
+    end
+  end
+
+  # The response status of an {HTTPInteraction}.
+  #
+  # @attr [Integer] code the HTTP status code
+  # @attr [String] message the HTTP status message (e.g. "OK" for a status of 200)
+  class ResponseStatus < Struct.new(:code, :message)
+    # Builds a serializable hash from the response status data.
+    #
+    # @return [Hash] hash that represents this response status
+    #  and can be easily serialized.
+    # @see ResponseStatus.from_hash
+    def to_hash
+      {
+        'code' => code, 'message' => message
+      }.tap { |h| OrderedHashSerializer.apply_to(h, members) }
+    end
+
+    # Constructs a new instance from a hash.
+    #
+    # @param [Hash] hash the hash to use to construct the instance.
+    # @return [ResponseStatus] the response status
+    def self.from_hash(hash)
+      new hash['code'], hash['message']
+    end
+  end
+
+  # Represents a single interaction over HTTP, containing a request and a response.
+  #
+  # @attr [Request] request the request
+  # @attr [Response] response the response
+  # @attr [Time] recorded_at when this HTTP interaction was recorded
+  class HTTPInteraction < Struct.new(:request, :response, :recorded_at)
+    def initialize(*args)
+      super
+      self.recorded_at ||= Time.now
+    end
+
+    # Builds a serializable hash from the HTTP interaction data.
+    #
+    # @return [Hash] hash that represents this HTTP interaction
+    #  and can be easily serialized.
+    # @see HTTPInteraction.from_hash
+    def to_hash
+      {
+        'request'     => request.to_hash,
+        'response'    => response.to_hash,
+        'recorded_at' => recorded_at.httpdate
+      }.tap do |hash|
+        OrderedHashSerializer.apply_to(hash, members)
+      end
+    end
+
+    # Constructs a new instance from a hash.
+    #
+    # @param [Hash] hash the hash to use to construct the instance.
+    # @return [HTTPInteraction] the HTTP interaction
+    def self.from_hash(hash)
+      new Request.from_hash(hash.fetch('request', {})),
+          Response.from_hash(hash.fetch('response', {})),
+          Time.httpdate(hash.fetch('recorded_at'))
+    end
+
+    # @return [HookAware] an instance with additional capabilities
+    #  suitable for use in `before_record` and `before_playback` hooks.
+    def hook_aware
+      HookAware.new(self)
+    end
+
+    # Decorates an {HTTPInteraction} with additional methods useful
+    # for a `before_record` or `before_playback` hook.
+    class HookAware < DelegateClass(HTTPInteraction)
+      def initialize(http_interaction)
+        @ignored = false
+        super
+      end
+
+      # Flags the HTTP interaction so that VCR ignores it. This is useful in
+      # a {VCR::Configuration#before_record} or {VCR::Configuration#before_playback}
+      # hook so that VCR does not record or play it back.
+      # @see #ignored?
+      def ignore!
+        @ignored = true
+      end
+
+      # @return [Boolean] whether or not this HTTP interaction should be ignored.
+      # @see #ignore!
+      def ignored?
+        !!@ignored
+      end
+
+      # Replaces a string in any part of the HTTP interaction (headers, request body,
+      # response body, etc) with the given replacement text.
+      #
+      # @param [#to_s] text the text to replace
+      # @param [#to_s] replacement_text the text to put in its place
+      def filter!(text, replacement_text)
+        text, replacement_text = text.to_s, replacement_text.to_s
+        return self if [text, replacement_text].any? { |t| t.empty? }
+        filter_object!(self, text, replacement_text)
+      end
+
+    private
+
+      def filter_object!(object, text, replacement_text)
+        if object.respond_to?(:gsub)
+          object.gsub!(text, replacement_text) if object.include?(text)
+        elsif Hash === object
+          filter_hash!(object, text, replacement_text)
+        elsif object.respond_to?(:each)
+          # This handles nested arrays and structs
+          object.each { |o| filter_object!(o, text, replacement_text) }
+        end
+
+        object
+      end
+
+      def filter_hash!(hash, text, replacement_text)
+        filter_object!(hash.values, text, replacement_text)
+
+        hash.keys.each do |k|
+          new_key = filter_object!(k.dup, text, replacement_text)
+          hash[new_key] = hash.delete(k) unless k == new_key
+        end
+      end
+    end
+  end
+end