typhoeus 0.5.0.pre → 0.5.0.rc

data/lib/typhoeus/hydra/before.rb

@@ -0,0 +1,30 @@
+module Typhoeus
+  class Hydra
+
+    # This module provides a way to hook into before
+    # a request gets queued in hydra. This is very powerful
+    # and you should be careful because when you accidently
+    # return a falsy value the request won't be executed.
+    #
+    # @api private
+    module Before
+
+      # Overrride queue in order to execute callbacks in
+      # Typhoeus.before. Will break and return when a
+      # callback returns nil or false. Calls super
+      # otherwise.
+      #
+      # @example Queue the request.
+      #   hydra.queue(request)
+      def queue(request)
+        Typhoeus.before.each do |callback|
+          value = callback.call(request)
+          if value.nil? || value == false || value.is_a?(Response)
+            return value
+          end
+        end
+        super
+      end
+    end
+  end
+end

data/lib/typhoeus/hydra/block_connection.rb

@@ -0,0 +1,35 @@
+module Typhoeus
+  class Hydra
+
+    # This module handles the blocked connection request mode on
+    # the hydra side, where only stubbed requests
+    # are allowed.
+    # Connection blocking needs to be turned on:
+    #   Typhoeus.configure do |config|
+    #     config.block_connection = true
+    #   end
+    #
+    # When trying to do real requests a NoStub error
+    # is raised.
+    #
+    # @api private
+    module BlockConnection
+
+      # Overrides queue in order to check before if block connection
+      # is turned on. If thats the case a NoStub error is
+      # raised.
+      #
+      # @example Queue the request.
+      #   hydra.queue(request)
+      #
+      # @param [ Request ] request The request to enqueue.
+      def queue(request)
+        if request.blocked?
+          raise Typhoeus::Errors::NoStub.new(request)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/typhoeus/{hydras → hydra}/easy_factory.rb

@@ -1,17 +1,28 @@
 module Typhoeus
-  module Hydras
+  class Hydra
 
     # This is a Factory for easies to be used in the hydra.
     # Before an easy is ready to be added to a multi, it needs
     # to be prepared and the on_complete callback to be set.
     # This is done by this class.
+    #
+    # @api private
     class EasyFactory
-      attr_reader :request, :hydra
+
+      # Returns the request provided.
+      #
+      # @return [ Typhoeus::Request ]
+      attr_reader :request
+
+      # Returns the hydra provided.
+      #
+      # @return [ Typhoeus::Hydra ]
+      attr_reader :hydra
 
       # Create an easy factory.
       #
       # @example Create easy factory.
-      #   Typhoeus::Hydras::EasyFactory.new(request, hydra)
+      #   Typhoeus::Hydra::EasyFactory.new(request, hydra)
       #
       # @param [ Request ] request The request to build an easy for.
       # @param [ Hydra ] hydra The hydra to build an easy for.
@@ -47,6 +58,8 @@ module Typhoeus
         easy
       end
 
+      private
+
       # Sets on_complete callback on easy in order to be able to
       # track progress.
       #
@@ -56,10 +69,9 @@ module Typhoeus
       # @return [ Ethon::Easy ] The easy.
       def set_callback
         easy.on_complete do |easy|
-          request.response = Response.new(easy.to_hash)
+          request.finish(Response.new(easy.to_hash))
           hydra.release_easy(easy)
           hydra.queue(hydra.queued_requests.shift) unless hydra.queued_requests.empty?
-          request.complete
         end
       end
     end

data/lib/typhoeus/{hydras → hydra}/easy_pool.rb

@@ -1,9 +1,11 @@
 module Typhoeus
-  module Hydras
+  class Hydra
 
     # The easy pool stores already initialized
     # easy handles for future use. This is useful
     # because creating them is quite expensive.
+    #
+    # @api private
     module EasyPool
 
       # Return the easy pool.
@@ -11,7 +13,7 @@ module Typhoeus
       # @example Return easy pool.
       #   hydra.easy_pool
       #
-      # @return [ Array ] The easy pool.
+      # @return [ Array<Ethon::Easy> ] The easy pool.
       def easy_pool
         @easy_pool ||= []
       end

data/lib/typhoeus/{hydras → hydra}/memoizable.rb

@@ -1,12 +1,14 @@
 module Typhoeus
-  module Hydras
+  class Hydra
 
     # This module handles the GET request memoization
     # on the hydra side. Memoization needs to be turned
     # on:
-    #   Typhoeus.configre do |config|
+    #   Typhoeus.configure do |config|
     #     config.memoize = true
     #   end
+    #
+    # @api private
     module Memoizable
 
       # Return the memory.
@@ -32,14 +34,14 @@ module Typhoeus
       # @return [ Request ] The queued request.
       def queue(request)
         if request.memoizable? && memory.has_key?(request)
-          request.instance_variable_set(:@response, memory[request])
-          request.complete
+          response = memory[request]
+          request.finish(response, true)
         else
           super
         end
       end
 
-      # Overrides run to clear the memory is cleared after
+      # Overrides run to make sure the memory is cleared after
       # each run.
       #
       # @example Run hydra.

data/lib/typhoeus/{hydras → hydra}/queueable.rb

@@ -1,8 +1,10 @@
 module Typhoeus
-  module Hydras # :nodoc:
+  class Hydra
 
     # This module handles the request queueing on
     # hydra.
+    #
+    # @api private
     module Queueable
 
       # Return the queued requests.
@@ -10,7 +12,7 @@ module Typhoeus
       # @example Return queued requests.
       #  hydra.queued_requests
       #
-      # @return [ Array ] The queued requests.
+      # @return [ Array<Typhoeus::Request> ] The queued requests.
       def queued_requests
         @queued_requests ||= []
       end
@@ -36,7 +38,7 @@ module Typhoeus
       def queue(request)
         request.hydra = self
         if multi.easy_handles.size < max_concurrency
-          multi.add(Hydras::EasyFactory.new(request, self).get)
+          multi.add(Hydra::EasyFactory.new(request, self).get)
         else
           queued_requests << request
         end

data/lib/typhoeus/{hydras → hydra}/runnable.rb

@@ -1,7 +1,9 @@
 module Typhoeus
-  module Hydras
+  class Hydra
 
     # This module contains logic to run a hydra.
+    #
+    # @api private
     module Runnable
 
       # Start the hydra run.
@@ -11,6 +13,7 @@ module Typhoeus
       #
       # @return [ Symbol ] Return value from multi.perform.
       def run
+        multi.prepare
         multi.perform
       end
     end

data/lib/typhoeus/hydra/stubbable.rb

@@ -0,0 +1,26 @@
+module Typhoeus
+  class Hydra
+
+    # This module handles stubbing on the hydra side.
+    # It plays well with the block_connection configuration,
+    # which raises when you make a request which is not stubbed.
+    #
+    # @api private
+    module Stubbable
+
+      # Override queue in order to check for matching expecations.
+      # When an expecation is found, super is not called. Instead a
+      # canned response is assigned to the request.
+      #
+      # @example Queue the request.
+      #   hydra.queue(request)
+      def queue(request)
+        if expectation = Expectation.find_by(request)
+          request.finish(expectation.response)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/typhoeus/request.rb

@@ -1,42 +1,115 @@
-require 'typhoeus/requests/callbacks'
-require 'typhoeus/requests/actions'
-require 'typhoeus/requests/operations'
-require 'typhoeus/requests/marshal'
-require 'typhoeus/requests/responseable'
-require 'typhoeus/requests/memoizable'
+require 'typhoeus/request/actions'
+require 'typhoeus/request/before'
+require 'typhoeus/request/block_connection'
+require 'typhoeus/request/callbacks'
+require 'typhoeus/request/marshal'
+require 'typhoeus/request/memoizable'
+require 'typhoeus/request/operations'
+require 'typhoeus/request/responseable'
+require 'typhoeus/request/stubbable'
 
 module Typhoeus
 
   # This class represents a request.
+  #
+  # @example (see #initialize)
+  #
+  # @example Make a request with the shortcut.
+  #   response = Typhoeus.get("www.example.com")
+  #
+  # @see (see #initialize)
   class Request
-    include Requests::Callbacks
-    include Requests::Marshal
-    include Requests::Operations
-    extend  Requests::Actions
-    include Requests::Responseable
-    include Requests::Memoizable
+    extend  Request::Actions
+    include Request::Callbacks::Types
+    include Request::Callbacks
+    include Request::Marshal
+    include Request::Operations
+    include Request::Responseable
+    include Request::Memoizable
+    include Request::BlockConnection
+    include Request::Stubbable
+    include Request::Before
 
-    attr_accessor :options, :url, :hydra
+    # Returns the provided url.
+    #
+    # @return [ String ]
+    attr_accessor :url
+
+    # Returns options, which includes default parameters.
+    #
+    # @return [ Hash ]
+    attr_accessor :options
+
+    # Returns the hydra the request ran into if any.
+    #
+    # @return [ Typhoeus::Hydra ]
+    #
+    # @api private
+    attr_accessor :hydra
+
+    # Returns the original options provided.
+    #
+    # @return [ Hash ]
+    #
+    # @api private
+    attr_accessor :original_options
+
+    # @return [ Boolean ]
+    #
+    # @api private
+    attr_accessor :block_connection
 
     # Create a new request.
     #
-    # @example Create a request.
-    #   Request.new("www.example.com")
+    # @example Simplest request.
+    #   response = Typhoeus::Request.new("www.example.com").run
+    #
+    # @example Request with url parameters.
+    #   response = Typhoeus::Request.new(
+    #     "www.example.com",
+    #     :params => {:a => 1}
+    #   ).run
+    #
+    # @example Request with a body.
+    #   response = Typhoeus::Request.new(
+    #     "www.example.com",
+    #     :body => {:b => 2}
+    #   ).run
+    #
+    # @example Request with parameters and body.
+    #   response = Typhoeus::Request.new(
+    #     "www.example.com",
+    #     :params => {:a => 1},
+    #     :body => {:b => 2}
+    #   ).run
+    #
+    # @example Create a request and allow follow redirections.
+    #   response = Typhoeus::Request.new(
+    #     "www.example.com",
+    #     :followlocation => true
+    #   ).run
     #
     # @param [ String ] url The url to request.
-    # @param [ Hash ] options The options.
+    # @param [ options ] options The options.
+    #
+    # @option options [ Hash ] :params Translated
+    #   into url parameters.
+    # @option options [ Hash ] :body Translated
+    #   into HTTP POST request body.
     #
-    # #return [ Request ] The new request.
+    # @return [ Typhoeus::Request ] The request.
+    #
+    # @note See {Ethon::Easy#initialize} for more options.
+    #
+    # @see Typhoeus::Hydra
+    # @see Typhoeus::Response
+    # @see Typhoeus::Request::Actions
     def initialize(url, options = {})
       @url = url
+      @original_options = options
       @options = options.dup
 
-      if @options[:headers]
-        @options[:headers] = {'User-Agent' => Typhoeus::USER_AGENT}.merge(options[:headers])
-      else
-        @options[:headers] = {'User-Agent' => Typhoeus::USER_AGENT}
-      end
-      @options[:verbose] = Typhoeus::Config.verbose unless @options[:verbose]
+      set_defaults
     end
 
     # Returns wether other is equal to self.
@@ -47,6 +120,8 @@ module Typhoeus
     # @param [ Object ] other The object to check.
     #
     # @return [ Boolean ] Returns true if equals, else false.
+    #
+    # @api private
     def eql?(other)
       self.class == other.class &&
         self.url == other.url &&
@@ -56,19 +131,23 @@ module Typhoeus
     # Overrides Object#hash.
     #
     # @return [ Integer ] The integer representing the request.
+    #
+    # @api private
     def hash
       [ self.class, self.url, self.options ].hash
     end
 
-    protected
+    private
 
-    # Checks if two hashes are equal or not, discarding first-level hash order
+    # Checks if two hashes are equal or not, discarding
+    # first-level hash order.
     #
-    # @param [ Hash ] hash
-    # @param [ Hash ] other hash to check for equality
+    # @param [ Hash ] left
+    # @param [ Hash ] right hash to check for equality
     #
-    # @return [ Boolean ] Returns true if hashes have same values for same keys and same length,
-    #     even if the keys are given in a different order.
+    # @return [ Boolean ] Returns true if hashes have
+    #   same values for same keys and same length,
+    #   even if the keys are given in a different order.
     def fuzzy_hash_eql?(left, right)
       return true if (left == right)
 
@@ -77,5 +156,14 @@ module Typhoeus
       end
     end
 
+    # Sets default header and verbose when turned on.
+    def set_defaults
+      if @options[:headers]
+        @options[:headers] = {'User-Agent' => Typhoeus::USER_AGENT}.merge(options[:headers])
+      else
+        @options[:headers] = {'User-Agent' => Typhoeus::USER_AGENT}
+      end
+      @options[:verbose] = Typhoeus::Config.verbose if @options[:verbose].nil? && !Typhoeus::Config.verbose.nil?
+    end
   end
 end