vcr 2.0.0.rc1 → 2.0.0.rc2

data/lib/vcr/cassette/http_interaction_list.rb

@@ -1,27 +1,37 @@
 module VCR
   class Cassette
+    # @private
     class HTTPInteractionList
+      include Logger
+
+      # @private
       module NullList
         extend self
         def response_for(*a); nil; end
+        def has_interaction_matching?(*a); false; end
         def has_used_interaction_matching?(*a); false; end
         def remaining_unused_interaction_count(*a); 0; end
       end
 
       attr_reader :interactions, :request_matchers, :allow_playback_repeats, :parent_list
 
-      def initialize(interactions, request_matchers, allow_playback_repeats = false, parent_list = NullList)
+      def initialize(interactions, request_matchers, allow_playback_repeats = false, parent_list = NullList, log_prefix = '')
         @interactions           = interactions.dup
-        @request_matchers       = request_matchers.map { |m| VCR.request_matchers[m] }
+        @request_matchers       = request_matchers
         @allow_playback_repeats = allow_playback_repeats
         @parent_list            = parent_list
         @used_interactions      = []
+        @log_prefix             = log_prefix
+
+        interaction_summaries = interactions.map { |i| "#{request_summary(i.request)} => #{response_summary(i.response)}" }
+        log "Initialized HTTPInteractionList with request matchers #{request_matchers.inspect} and #{interactions.size} interaction(s): { #{interaction_summaries.join(', ')} }", 1
       end
 
       def response_for(request)
         if index = matching_interaction_index_for(request)
           interaction = @interactions.delete_at(index)
           @used_interactions.unshift interaction
+          log "Found matching interaction for #{request_summary(request)} at index #{index}: #{response_summary(interaction.response)}", 1
           interaction.response
         elsif interaction = matching_used_interaction_for(request)
           interaction.response
@@ -30,6 +40,12 @@ module VCR
         end
       end
 
+      def has_interaction_matching?(request)
+        !!matching_interaction_index_for(request) ||
+        !!matching_used_interaction_for(request) ||
+        @parent_list.has_interaction_matching?(request)
+      end
+
       def has_used_interaction_matching?(request)
         @used_interactions.any? { |i| interaction_matches_request?(request, i) }
       end
@@ -40,6 +56,10 @@ module VCR
 
     private
 
+      def request_summary(request)
+        super(request, @request_matchers)
+      end
+
       def matching_interaction_index_for(request)
         @interactions.index { |i| interaction_matches_request?(request, i) }
       end
@@ -50,10 +70,19 @@ module VCR
       end
 
       def interaction_matches_request?(request, interaction)
-        @request_matchers.all? do |matcher|
-          matcher.matches?(request, interaction.request)
+        log "Checking if #{request_summary(request)} matches #{request_summary(interaction.request)} using #{@request_matchers.inspect}", 1
+        @request_matchers.all? do |matcher_name|
+          matcher = VCR.request_matchers[matcher_name]
+          matcher.matches?(request, interaction.request).tap do |matched|
+            matched = matched ? 'matched' : 'did not match'
+            log "#{matcher_name} (#{matched}): current request #{request_summary(request)} vs #{request_summary(interaction.request)}", 2
+          end
         end
       end
+
+      def log_prefix
+        @log_prefix
+      end
     end
   end
 end

data/lib/vcr/cassette/migrator.rb

@@ -1,9 +1,8 @@
-require 'yaml'
-require 'vcr/structs'
-require 'uri'
+require 'vcr'
 
 module VCR
   class Cassette
+    # @private
     class Migrator
       def initialize(dir, out = $stdout)
         @dir, @out = dir, out

data/lib/vcr/cassette/reader.rb

@@ -1,5 +1,6 @@
 module VCR
   class Cassette
+    # @private
     class Reader
       def initialize(file_name, erb)
         @file_name, @erb = file_name, erb

data/lib/vcr/cassette/serializers.rb

@@ -1,15 +1,22 @@
 module VCR
   class Cassette
+    # Keeps track of the cassette serializers in a hash-like object.
     class Serializers
       autoload :YAML,  'vcr/cassette/serializers/yaml'
       autoload :Syck,  'vcr/cassette/serializers/syck'
       autoload :Psych, 'vcr/cassette/serializers/psych'
       autoload :JSON,  'vcr/cassette/serializers/json'
 
+      # @private
       def initialize
         @serializers = {}
       end
 
+      # Gets the named serializer.
+      #
+      # @param name [Symbol] the name of the serializer
+      # @return the named serializer
+      # @raise [ArgumentError] if there is not a serializer for the given name
       def [](name)
         @serializers.fetch(name) do |_|
           @serializers[name] = case name
@@ -22,6 +29,11 @@ module VCR
         end
       end
 
+      # Registers a serializer.
+      #
+      # @param name [Symbol] the name of the serializer
+      # @param value [#file_extension, #serialize, #deserialize] the serializer object. It must implement
+      #  +file_extension()+, +serialize(Hash)+ and +deserialize(String)+.
       def []=(name, value)
         if @serializers.has_key?(name)
           warn "WARNING: There is already a VCR cassette serializer registered for #{name.inspect}. Overriding it."
@@ -30,6 +42,16 @@ module VCR
         @serializers[name] = value
       end
     end
+
+    # @private
+    module EncodingErrorHandling
+      def handle_encoding_errors
+        yield
+      rescue *self::ENCODING_ERRORS => e
+        e.message << "\nNote: Using VCR's `:preserve_exact_body_bytes` option may help prevent this error in the future."
+        raise
+      end
+    end
   end
 end
 

data/lib/vcr/cassette/serializers/json.rb

@@ -3,19 +3,44 @@ require 'multi_json'
 module VCR
   class Cassette
     class Serializers
+      # The JSON serializer. Uses `MultiJson` under the covers.
+      #
+      # @see Psych
+      # @see Syck
+      # @see YAML
       module JSON
         extend self
+        extend EncodingErrorHandling
 
+        # @private
+        ENCODING_ERRORS = [MultiJson::DecodeError]
+        ENCODING_ERRORS << EncodingError if defined?(EncodingError)
+
+        # The file extension to use for this serializer.
+        #
+        # @return [String] "json"
         def file_extension
           "json"
         end
 
+        # Serializes the given hash using `MultiJson`.
+        #
+        # @param [Hash] hash the object to serialize
+        # @return [String] the JSON string
         def serialize(hash)
-          MultiJson.encode(hash)
+          handle_encoding_errors do
+            MultiJson.encode(hash)
+          end
         end
 
+        # Deserializes the given string using `MultiJson`.
+        #
+        # @param [String] string the JSON string
+        # @param [Hash] hash the deserialized object
         def deserialize(string)
-          MultiJson.decode(string)
+          handle_encoding_errors do
+            MultiJson.decode(string)
+          end
         end
       end
     end

data/lib/vcr/cassette/serializers/psych.rb

@@ -3,19 +3,43 @@ require 'psych'
 module VCR
   class Cassette
     class Serializers
+      # The Psych serializer. Psych is the new YAML engine in ruby 1.9.
+      #
+      # @see JSON
+      # @see Syck
+      # @see YAML
       module Psych
         extend self
+        extend EncodingErrorHandling
 
+        # @private
+        ENCODING_ERRORS = [ArgumentError]
+
+        # The file extension to use for this serializer.
+        #
+        # @return [String] "yml"
         def file_extension
           "yml"
         end
 
+        # Serializes the given hash using Psych.
+        #
+        # @param [Hash] hash the object to serialize
+        # @return [String] the YAML string
         def serialize(hash)
-          ::Psych.dump(hash)
+          handle_encoding_errors do
+            ::Psych.dump(hash)
+          end
         end
 
+        # Deserializes the given string using Psych.
+        #
+        # @param [String] string the YAML string
+        # @param [Hash] hash the deserialized object
         def deserialize(string)
-          ::Psych.load(string)
+          handle_encoding_errors do
+            ::Psych.load(string)
+          end
         end
       end
     end

data/lib/vcr/cassette/serializers/syck.rb

@@ -3,21 +3,47 @@ require 'yaml'
 module VCR
   class Cassette
     class Serializers
+      # The Syck serializer. Syck is the legacy YAML engine in ruby 1.8 and 1.9.
+      #
+      # @see JSON
+      # @see Psych
+      # @see YAML
       module Syck
         extend self
+        extend EncodingErrorHandling
 
+        # @private
+        ENCODING_ERRORS = [ArgumentError]
+
+        # The file extension to use for this serializer.
+        #
+        # @return [String] "yml"
         def file_extension
           "yml"
         end
 
+        # Serializes the given hash using Syck.
+        #
+        # @param [Hash] hash the object to serialize
+        # @return [String] the YAML string
         def serialize(hash)
-          using_syck { ::YAML.dump(hash) }
+          handle_encoding_errors do
+            using_syck { ::YAML.dump(hash) }
+          end
         end
 
+        # Deserializes the given string using Syck.
+        #
+        # @param [String] string the YAML string
+        # @param [Hash] hash the deserialized object
         def deserialize(string)
-          using_syck { ::YAML.load(string) }
+          handle_encoding_errors do
+            using_syck { ::YAML.load(string) }
+          end
         end
 
+      private
+
         def using_syck
           return yield unless defined?(::YAML::ENGINE)
           original_engine = ::YAML::ENGINE.yamler

data/lib/vcr/cassette/serializers/yaml.rb

@@ -3,19 +3,45 @@ require 'yaml'
 module VCR
   class Cassette
     class Serializers
+      # The YAML serializer. This will use either Psych or Syck, which ever your
+      # ruby interpreter defaults to. You can also force VCR to use Psych or Syck by
+      # using one of those serializers.
+      #
+      # @see JSON
+      # @see Psych
+      # @see Syck
       module YAML
         extend self
+        extend EncodingErrorHandling
 
+        # @private
+        ENCODING_ERRORS = [ArgumentError]
+
+        # The file extension to use for this serializer.
+        #
+        # @return [String] "yml"
         def file_extension
           "yml"
         end
 
+        # Serializes the given hash using YAML.
+        #
+        # @param [Hash] hash the object to serialize
+        # @return [String] the YAML string
         def serialize(hash)
-          ::YAML.dump(hash)
+          handle_encoding_errors do
+            ::YAML.dump(hash)
+          end
         end
 
+        # Deserializes the given string using YAML.
+        #
+        # @param [String] string the YAML string
+        # @param [Hash] hash the deserialized object
         def deserialize(string)
-          ::YAML.load(string)
+          handle_encoding_errors do
+            ::YAML.load(string)
+          end
         end
       end
     end

data/lib/vcr/configuration.rb

@@ -2,16 +2,109 @@ require 'fileutils'
 require 'vcr/util/hooks'
 
 module VCR
+  # Stores the VCR configuration.
   class Configuration
     include VCR::Hooks
     include VCR::VariableArgsBlockCaller
 
+    # Adds a callback that will be called before the recorded HTTP interactions
+    # are serialized and written to disk.
+    #
+    # @example
+    #  VCR.configure do |c|
+    #    # Don't record transient 5xx errors
+    #    c.before_record do |interaction|
+    #      interaction.ignore! if interaction.response.status.code >= 500
+    #    end
+    #
+    #    # Modify the response body for cassettes tagged with :twilio
+    #    c.before_record(:twilio) do |interaction|
+    #      interaction.response.body.downcase!
+    #    end
+    #  end
+    #
+    # @param tag [(optional) Symbol] Used to apply this hook to only cassettes that match
+    #  the given tag.
+    # @yield the callback
+    # @yieldparam interaction [VCR::HTTPInteraction::HookAware] The interaction that will be
+    #  serialized and written to disk.
+    # @yieldparam cassette [(optional) VCR::Cassette] The current cassette.
+    # @see #before_playback
     define_hook :before_record
+    def before_record(tag = nil, &block)
+      super(filter_from(tag), &block)
+    end
+
+    # Adds a callback that will be called before a previously recorded
+    # HTTP interaction is loaded for playback.
+    #
+    # @example
+    #  VCR.configure do |c|
+    #    # Don't playback transient 5xx errors
+    #    c.before_playback do |interaction|
+    #      interaction.ignore! if interaction.response.status.code >= 500
+    #    end
+    #
+    #    # Change a response header for playback
+    #    c.before_playback(:twilio) do |interaction|
+    #      interaction.response.headers['X-Foo-Bar'] = 'Bazz'
+    #    end
+    #  end
+    #
+    # @param tag [(optional) Symbol] Used to apply this hook to only cassettes that match
+    #  the given tag.
+    # @yield the callback
+    # @yieldparam interaction [VCR::HTTPInteraction::HookAware] The interaction that is being
+    #  loaded.
+    # @yieldparam cassette [(optional) VCR::Cassette] The current cassette.
+    # @see #before_record
     define_hook :before_playback
+    def before_playback(tag = nil, &block)
+      super(filter_from(tag), &block)
+    end
+
+    # @private
     define_hook :after_library_hooks_loaded
+
+    # Adds a callback that will be called with each HTTP request before it is made.
+    #
+    # @example
+    #  VCR.configure do |c|
+    #    c.before_http_request(:real?) do |request|
+    #      puts "Request: #{request.method} #{request.uri}"
+    #    end
+    #  end
+    #
+    # @param filters [optional splat of #to_proc] one or more filters to apply.
+    #   The objects provided will be converted to procs using `#to_proc`. If provided,
+    #   the callback will only be invoked if these procs all return `true`.
+    # @yield the callback
+    # @yieldparam request [VCR::Request::Typed] the request that is being made
+    # @see #after_http_request
+    # @see #around_http_request
     define_hook :before_http_request
+
+    # Adds a callback that will be called with each HTTP request after it is complete.
+    #
+    # @example
+    #  VCR.configure do |c|
+    #    c.after_http_request(:ignored?) do |request, response|
+    #      puts "Request: #{request.method} #{request.uri}"
+    #      puts "Response: #{response.status.code}"
+    #    end
+    #  end
+    #
+    # @param filters [optional splat of #to_proc] one or more filters to apply.
+    #   The objects provided will be converted to procs using `#to_proc`. If provided,
+    #   the callback will only be invoked if these procs all return `true`.
+    # @yield the callback
+    # @yieldparam request [VCR::Request::Typed] the request that is being made
+    # @yieldparam response [VCR::Response] the response from the request
+    # @see #before_http_request
+    # @see #around_http_request
     define_hook :after_http_request, :prepend
 
+    # @private
     def initialize
       @allow_http_connections_when_no_cassette = nil
       @default_cassette_options = {
@@ -19,47 +112,172 @@ module VCR
         :match_requests_on => RequestMatcherRegistry::DEFAULT_MATCHERS,
         :serialize_with    => :yaml
       }
+
+      self.debug_logger = NullDebugLogger
+
+      register_built_in_hooks
     end
 
+    # The directory to read cassettes from and write cassettes to.
+    #
+    # @overload cassette_library_dir
+    #   @return [String] the directory to read cassettes from and write cassettes to
+    # @overload cassette_library_dir=(dir)
+    #   @param dir [String] the directory to read cassettes from and write cassettes to
+    #   @return [void]
+    # @example
+    #   VCR.configure do |c|
+    #     c.cassette_library_dir = 'spec/cassettes'
+    #   end
     attr_reader :cassette_library_dir
+
+    # Sets the directory to read cassettes from and write cassettes to.
     def cassette_library_dir=(cassette_library_dir)
-      @cassette_library_dir = cassette_library_dir
       FileUtils.mkdir_p(cassette_library_dir) if cassette_library_dir
+      @cassette_library_dir = cassette_library_dir ? absolute_path_for(cassette_library_dir) : nil
     end
 
+    # Default options to apply to every cassette.
+    #
+    # @overload default_cassette_options
+    #   @return [Hash] default options to apply to every cassette
+    # @overload default_cassette_options=(options)
+    #   @param options [Hash] default options to apply to every cassette
+    #   @return [void]
+    # @example
+    #   VCR.configure do |c|
+    #     c.default_cassette_options = { :record => :new_episodes }
+    #   end
+    # @note {VCR#insert_cassette} for the list of valid options.
     attr_reader :default_cassette_options
+
+    # Sets the default options that apply to every cassette.
     def default_cassette_options=(overrides)
       @default_cassette_options.merge!(overrides)
     end
 
+    # Configures which libraries VCR will hook into to intercept HTTP requests.
+    #
+    # @example
+    #   VCR.configure do |c|
+    #     c.hook_into :fakeweb, :typhoeus
+    #   end
+    #
+    # @param hooks [Array<Symbol>] List of libraries. Valid values are
+    #  `:fakeweb`, `:webmock`, `:typhoeus`, `:excon` and `:faraday`.
+    # @raise [ArgumentError] when given an unsupported library name.
+    # @raise [VCR::Errors::LibraryVersionTooLowError] when the version
+    #  of a library you are using is too low for VCR to support.
+    # @note `:fakeweb` and `:webmock` cannot both be used since they both monkey patch
+    #  `Net::HTTP`. Otherwise, you can use any combination of these.
     def hook_into(*hooks)
       hooks.each { |a| load_library_hook(a) }
       invoke_hook(:after_library_hooks_loaded)
     end
 
+    # Registers a request matcher for later use.
+    #
+    # @example
+    #  VCR.configure do |c|
+    #    c.register_request_matcher :port do |request_1, request_2|
+    #      URI(request_1.uri).port == URI(request_2.uri).port
+    #    end
+    #  end
+    #
+    #  VCR.use_cassette("my_cassette", :match_requests_on => [:method, :host, :port]) do
+    #    # ...
+    #  end
+    #
+    # @param name [Symbol] the name of the request matcher
+    # @yield the request matcher
+    # @yieldparam request_1 [VCR::Request] One request
+    # @yieldparam request_2 [VCR::Request] The other request
+    # @yieldreturn [Boolean] whether or not these two requests should be considered
+    #  equivalent
     def register_request_matcher(name, &block)
       VCR.request_matchers.register(name, &block)
     end
 
+    # Specifies host(s) that VCR should ignore.
+    #
+    # @param hosts [Array<String>] List of hosts to ignore
+    # @see #ignore_localhost=
+    # @see #ignore_request
     def ignore_hosts(*hosts)
       VCR.request_ignorer.ignore_hosts(*hosts)
     end
     alias ignore_host ignore_hosts
 
+    # Sets whether or not VCR should ignore localhost requests.
+    #
+    # @param value [Boolean] the value to set
+    # @see #ignore_hosts
+    # @see #ignore_request
     def ignore_localhost=(value)
       VCR.request_ignorer.ignore_localhost = value
     end
 
+    # Defines what requests to ignore using a block.
+    #
+    # @example
+    #   VCR.configure do |c|
+    #     c.ignore_request do |request|
+    #       uri = URI(request.uri)
+    #       # ignore only localhost requests to port 7500
+    #       uri.host == 'localhost' && uri.port == 7500
+    #     end
+    #   end
+    #
+    # @yield the callback
+    # @yieldparam request [VCR::Request] the HTTP request
+    # @yieldreturn [Boolean] whether or not to ignore the request
     def ignore_request(&block)
       VCR.request_ignorer.ignore_request(&block)
     end
 
+    # Determines how VCR treats HTTP requests that are made when
+    # no VCR cassette is in use. When set to `true`, requests made
+    # when there is no VCR cassette in use will be allowed. When set
+    # to `false` (the default), an {VCR::Errors::UnhandledHTTPRequestError}
+    # will be raised for any HTTP request made when there is no
+    # cassette in use.
+    #
+    # @overload allow_http_connections_when_no_cassette?
+    #   @return [Boolean] whether or not HTTP connections are allowed
+    #    when there is no cassette.
+    # @overload allow_http_connections_when_no_cassette=
+    #   @param value [Boolean] sets whether or not to allow HTTP
+    #    connections when there is no cassette.
     attr_writer :allow_http_connections_when_no_cassette
+    # @private (documented above)
     def allow_http_connections_when_no_cassette?
       !!@allow_http_connections_when_no_cassette
     end
 
-    def filter_sensitive_data(placeholder, tag = nil, &block)
+    # Sets up a {#before_record} and a {#before_playback} hook that will
+    # insert a placeholder string in the cassette in place of another string.
+    # You can use this as a generic way to interpolate a variable into the
+    # cassette for a unique string. It's particularly useful for unique
+    # sensitive strings like API keys and passwords.
+    #
+    # @example
+    #   VCR.configure do |c|
+    #     # Put "<GITHUB_API_KEY>" in place of the actual API key in
+    #     # our cassettes so we don't have to commit to source control.
+    #     c.filter_sensitive_data('<GITHUB_API_KEY>') { GithubClient.api_key }
+    #
+    #     # Put a "<USER_ID>" placeholder variable in our cassettes tagged with
+    #     # :user_cassette since it can be different for different test runs.
+    #     c.define_cassette_placeholder('<USER_ID>', :user_cassette) { User.last.id }
+    #   end
+    #
+    # @param placeholder [String] The placeholder string.
+    # @param tag [Symbol] Set this apply this to only to cassettes
+    #  with a matching tag; otherwise it will apply to every cassette.
+    # @yield block that determines what string to replace
+    # @yieldparam interaction [(optional) VCR::HTTPInteraction::HookAware] the HTTP interaction
+    # @yieldreturn the string to replace
+    def define_cassette_placeholder(placeholder, tag = nil, &block)
       before_record(tag) do |interaction|
         interaction.filter!(call_block(block, interaction), placeholder)
       end
@@ -68,28 +286,123 @@ module VCR
         interaction.filter!(placeholder, call_block(block, interaction))
       end
     end
-    alias define_cassette_placeholder filter_sensitive_data
+    alias filter_sensitive_data define_cassette_placeholder
 
+    # Gets the registry of cassette serializers. Use it to register a custom serializer.
+    #
+    # @example
+    #   VCR.configure do |c|
+    #     c.cassette_serializers[:my_custom_serializer] = my_custom_serializer
+    #   end
+    #
+    # @return [VCR::Cassette::Serializers] the cassette serializer registry object.
+    # @note Custom serializers must implement the following interface:
+    #
+    #   * `file_extension      # => String`
+    #   * `serialize(Hash)     # => String`
+    #   * `deserialize(String) # => Hash`
     def cassette_serializers
       VCR.cassette_serializers
     end
 
-    def around_http_request(&block)
+    # Adds a callback that will be executed around each HTTP request.
+    #
+    # @example
+    #  VCR.configure do |c|
+    #    c.around_http_request(lambda {|r| r.uri =~ /api.geocoder.com/}) do |request|
+    #      # extract an address like "1700 E Pine St, Seattle, WA"
+    #      # from a query like "address=1700+E+Pine+St%2C+Seattle%2C+WA"
+    #      address = CGI.unescape(URI(request.uri).query.split('=').last)
+    #      VCR.use_cassette("geocoding/#{address}", &request)
+    #    end
+    #  end
+    #
+    # @yield the callback
+    # @yieldparam request [VCR::Request::FiberAware] the request that is being made
+    # @raise [VCR::Errors::NotSupportedError] if the fiber library cannot be loaded.
+    # @param filters [optional splat of #to_proc] one or more filters to apply.
+    #   The objects provided will be converted to procs using `#to_proc`. If provided,
+    #   the callback will only be invoked if these procs all return `true`.
+    # @note This method can only be used on ruby interpreters that support
+    #  fibers (i.e. 1.9+). On 1.8 you can use separate `before_http_request` and
+    #  `after_http_request` hooks.
+    # @note You _must_ call `request.proceed` or pass the request as a proc on to a
+    #  method that yields to a block (i.e. `some_method(&request)`).
+    # @see #before_http_request
+    # @see #after_http_request
+    def around_http_request(*filters, &block)
       require 'fiber'
     rescue LoadError
       raise Errors::NotSupportedError.new \
         "VCR::Configuration#around_http_request requires fibers, " +
         "which are not available on your ruby intepreter."
     else
-      fiber, hook_decaration = nil, caller.first
-      before_http_request { |request| fiber = start_new_fiber_for(request, block) }
-      after_http_request  { |request| resume_fiber(fiber, hook_decaration) }
+      fiber, hook_allowed, hook_decaration = nil, false, caller.first
+      before_http_request(*filters) do |request|
+        hook_allowed = true
+        fiber = start_new_fiber_for(request, block)
+      end
+
+      after_http_request(lambda { hook_allowed }) do |request, response|
+        resume_fiber(fiber, response, hook_decaration)
+      end
     end
 
+    # Configures RSpec to use a VCR cassette for any example
+    # tagged with `:vcr`.
     def configure_rspec_metadata!
       VCR::RSpec::Metadata.configure!
     end
 
+    # An object to log debug output to.
+    #
+    # @overload debug_logger
+    #   @return [#puts] the logger
+    # @overload debug_logger=(logger)
+    #   @param logger [#puts] the logger
+    #   @return [void]
+    # @example
+    #   VCR.configure do |c|
+    #     c.debug_logger = $stderr
+    #   end
+    # @example
+    #   VCR.configure do |c|
+    #     c.debug_logger = File.open('vcr.log', 'w')
+    #   end
+    attr_accessor :debug_logger
+
+    # Sets a callback that determines whether or not to base64 encode
+    # the bytes of a request or response body during serialization in
+    # order to preserve them exactly.
+    #
+    # @example
+    #   VCR.configure do |c|
+    #     c.preserve_exact_body_bytes do |http_message|
+    #       http_message.body.encoding.name == 'ASCII-8BIT' ||
+    #       !http_message.body.valid_encoding?
+    #     end
+    #   end
+    #
+    # @yield the callback
+    # @yieldparam http_message [#body, #headers] the `VCR::Request` or `VCR::Response` object being serialized
+    # @yieldparam cassette [VCR::Cassette] the cassette the http message belongs to
+    # @yieldreturn [Boolean] whether or not to preserve the exact bytes for the body of the given HTTP message
+    # @return [void]
+    # @see #preserve_exact_body_bytes_for?
+    # @note This is usually only necessary when the HTTP server returns a response
+    #  with a non-standard encoding or with a body containing invalid bytes for the given
+    #  encoding. Note that when you set this, and the block returns true, you sacrifice
+    #  the human readability of the data in the cassette.
+    define_hook :preserve_exact_body_bytes
+
+    # @return [Boolean] whether or not the body of the given HTTP message should
+    #  be base64 encoded during serialization in order to preserve the bytes exactly.
+    # @param http_message [#body, #headers] the `VCR::Request` or `VCR::Response` object being serialized
+    # @see #preserve_exact_body_bytes
+    def preserve_exact_body_bytes_for?(http_message)
+      invoke_hook(:preserve_exact_body_bytes, http_message, VCR.current_cassette).any?
+    end
+
   private
 
     def load_library_hook(hook)
@@ -100,8 +413,8 @@ module VCR
       raise ArgumentError.new("#{hook.inspect} is not a supported VCR HTTP library hook.")
     end
 
-    def resume_fiber(fiber, hook_declaration)
-      fiber.resume
+    def resume_fiber(fiber, response, hook_declaration)
+      fiber.resume(response)
     rescue FiberError
       raise Errors::AroundHTTPRequestHookError.new \
         "Your around_http_request hook declared at #{hook_declaration}" +
@@ -110,9 +423,34 @@ module VCR
 
     def start_new_fiber_for(request, block)
       Fiber.new(&block).tap do |fiber|
-        fiber.resume(request.fiber_aware)
+        fiber.resume(Request::FiberAware.new(request))
+      end
+    end
+
+    def absolute_path_for(path)
+      Dir.chdir(path) { Dir.pwd }
+    end
+
+    def filter_from(tag)
+      return lambda { true } unless tag
+      lambda { |_, cassette| cassette.tags.include?(tag) }
+    end
+
+    def register_built_in_hooks
+      before_playback(:update_content_length_header) do |interaction|
+        interaction.response.update_content_length_header
+      end
+
+      preserve_exact_body_bytes do |http_message, cassette|
+        cassette && cassette.tags.include?(:preserve_exact_body_bytes)
       end
     end
   end
+
+  # @private
+  module NullDebugLogger
+    extend self
+    def puts(*); end
+  end
 end