vcr 2.0.0.rc1 → 2.0.0.rc2

data/lib/vcr/middleware/faraday.rb

@@ -5,19 +5,32 @@ require 'vcr/request_handler'
 VCR::VersionChecker.new('Faraday', Faraday::VERSION, '0.7.0', '0.7').check_version!
 
 module VCR
+  # Contains middlewares for use with different libraries.
   module Middleware
+    # Faraday middleware that VCR uses to record and replay HTTP requests made through
+    # Faraday.
+    #
+    # @note You can either insert this middleware into the Faraday middleware stack
+    #  yourself or configure {VCR::Configuration#hook_into} to hook into +:faraday+.
     class Faraday
       include VCR::Deprecations::Middleware::Faraday
 
+      # Constructs a new instance of the Faraday middleware.
+      #
+      # @param [#call] the faraday app
       def initialize(app)
         super
         @app = app
       end
 
+      # Handles the HTTP request being made through Faraday
+      #
+      # @param [Hash] env the Faraday request env hash
       def call(env)
         RequestHandler.new(@app, env).handle
       end
 
+      # @private
       class RequestHandler < ::VCR::RequestHandler
         attr_reader :app, :env
         def initialize(app, env)

data/lib/vcr/middleware/rack.rb

@@ -1,29 +1,64 @@
 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

data/lib/vcr/request_handler.rb

@@ -1,23 +1,53 @@
 module VCR
+  # @private
   class RequestHandler
+    include Logger
+
     def handle
+      log "Handling request: #{request_summary} (disabled: #{disabled?})"
       invoke_before_request_hook
-      return on_ignored_request    if should_ignore?
-      return on_stubbed_request    if stubbed_response
-      return on_recordable_request if VCR.real_http_connections_allowed?
-      on_connection_not_allowed
+
+      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 an modify what
+      # #request_type would return (i.e. when a response stub is
+      # used), so we need to store the request type for the
+      # 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 should_ignore?                     then :ignored
+        when has_response_stub?(consume_stub)   then :stubbed
+        when VCR.real_http_connections_allowed? then :recordable
+        else                                         :unhandled
+      end
+    end
+
     def invoke_before_request_hook
-      return if disabled?
-      VCR.configuration.invoke_hook(:before_http_request, vcr_request)
+      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, vcr_request, vcr_response)
+      VCR.configuration.invoke_hook(:after_http_request, @after_hook_typed_request, vcr_response)
     end
 
     def should_ignore?
@@ -28,6 +58,14 @@ module VCR
       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
@@ -47,8 +85,22 @@ module VCR
     def on_recordable_request
     end
 
-    def on_connection_not_allowed
+    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

@@ -3,6 +3,7 @@ require 'set'
 require 'vcr/util/hooks'
 
 module VCR
+  # @private
   class RequestIgnorer
     include VCR::Hooks
 

data/lib/vcr/request_matcher_registry.rb

@@ -1,15 +1,21 @@
 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)
         URI(request.uri).tap do |uri|
@@ -37,11 +43,13 @@ module VCR
       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."
@@ -50,6 +58,7 @@ module VCR
       @registry[name] = Matcher.new(block)
     end
 
+    # @private
     def [](matcher)
       @registry.fetch(matcher) do
         matcher.respond_to?(:call) ?
@@ -58,6 +67,25 @@ module VCR
       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

data/lib/vcr/structs.rb

@@ -1,9 +1,57 @@
+require 'base64'
+require 'delegate'
 require 'time'
-require 'forwardable'
 
 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 string.encoding.name == encoding
+            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
         # Ensure that the body is a raw string, in case the string instance
@@ -13,8 +61,29 @@ module VCR
         # http://github.com/myronmarston/vcr/issues/4
         self.body = String.new(body.to_s)
       end
+
+    private
+
+      def serializable_body
+        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
@@ -56,6 +125,7 @@ module VCR
     end
   end
 
+  # @private
   module OrderedHashSerializer
     def each
       @ordered_keys.each do |key|
@@ -74,6 +144,12 @@ module VCR
     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
@@ -84,21 +160,30 @@ module VCR
       self.uri = without_standard_port(self.uri)
     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'    => body,
+        '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'],
-          hash['body'],
+          body_from(hash['body']),
           hash['headers']
     end
 
@@ -108,19 +193,75 @@ module VCR
       @@object_method.bind(self).call(*args)
     end
 
-    # transforms the request into a fiber aware one
-    def fiber_aware
-      extend FiberAware
+    # 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 will be stubbed
+      def stubbed?
+        type == :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
+
+      undef method
     end
 
-    module FiberAware
+    # 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
+
+    # Transforms the request into a fiber aware one by extending
+    # the {FiberAware} module onto the instance. Necessary for the
+    # {VCR::Configuration#around_http_request} hook.
+    #
+    # @return [Request] the request instance
+    def fiber_aware
+      extend FiberAware
     end
 
   private
@@ -134,16 +275,22 @@ module VCR
     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)
-    extend ::Forwardable
-    def_delegators :request, :uri, :method
-
     def initialize(*args)
-      @ignored = false
       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,
@@ -154,70 +301,117 @@ module VCR
       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
 
-    def ignore!
-      @ignored = true
+    # @return [HookAware] an instance with additional capabilities
+    #  suitable for use in `before_record` and `before_playback` hooks.
+    def hook_aware
+      HookAware.new(self)
     end
 
-    def ignored?
-      !!@ignored
-    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
 
-    def filter!(text, replacement_text)
-      return self if [text, replacement_text].any? { |t| t.to_s.empty? }
-      filter_object!(self, text, replacement_text)
-    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
 
-  private
+      # @return [Boolean] whether or not this HTTP interaction should be ignored.
+      # @see #ignore!
+      def ignored?
+        !!@ignored
+      end
 
-    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) }
+      # Replaces a string in any part of the HTTP interaction (headers, request body,
+      # response body, etc) with the given replacement text.
+      #
+      # @param [String] text the text to replace
+      # @param [String] replacement_text the text to put in its place
+      def filter!(text, replacement_text)
+        return self if [text, replacement_text].any? { |t| t.to_s.empty? }
+        filter_object!(self, text, replacement_text)
       end
 
-      object
-    end
+    private
 
-    def filter_hash!(hash, text, replacement_text)
-      filter_object!(hash.values, text, replacement_text)
+      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
 
-      hash.keys.each do |k|
-        new_key = filter_object!(k.dup, text, replacement_text)
-        hash[new_key] = hash.delete(k) unless k == new_key
+        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
 
+  # 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
   class Response < Struct.new(:status, :headers, :body, :http_version)
     include Normalizers::Header
     include Normalizers::Body
 
+    # 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'         => body,
+        'body'         => serializable_body,
         'http_version' => http_version
       }.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 [Response] the response
     def self.from_hash(hash)
       new ResponseStatus.from_hash(hash.fetch('status', {})),
           hash['headers'],
-          hash['body'],
+          body_from(hash['body']),
           hash['http_version']
     end
 
+    # Updates the Content-Length response header so that it is
+    # accurate for the response body.
     def update_content_length_header
       value = body ? body.bytesize.to_s : '0'
       key = %w[ Content-Length content-length ].find { |k| headers.has_key?(k) }
@@ -225,13 +419,26 @@ module VCR
     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