resourceful 0.2.1 → 0.3.0

data/Manifest

@@ -0,0 +1,34 @@
+lib/resourceful.rb
+lib/resourceful/authentication_manager.rb
+lib/resourceful/util.rb
+lib/resourceful/resource.rb
+lib/resourceful/memcache_cache_manager.rb
+lib/resourceful/net_http_adapter.rb
+lib/resourceful/http_accessor.rb
+lib/resourceful/stubbed_resource_proxy.rb
+lib/resourceful/header.rb
+lib/resourceful/cache_manager.rb
+lib/resourceful/options_interpreter.rb
+lib/resourceful/response.rb
+lib/resourceful/request.rb
+spec/acceptance_shared_specs.rb
+spec/spec.opts
+spec/acceptance_spec.rb
+spec/simple_http_server_shared_spec_spec.rb
+spec/spec_helper.rb
+spec/resourceful/header_spec.rb
+spec/resourceful/authentication_manager_spec.rb
+spec/resourceful/memcache_cache_manager_spec.rb
+spec/resourceful/response_spec.rb
+spec/resourceful/options_interpreter_spec.rb
+spec/resourceful/http_accessor_spec.rb
+spec/resourceful/stubbed_resource_proxy_spec.rb
+spec/resourceful/request_spec.rb
+spec/resourceful/resource_spec.rb
+spec/resourceful/cache_manager_spec.rb
+spec/resourceful/net_http_adapter_spec.rb
+spec/simple_http_server_shared_spec.rb
+Manifest
+Rakefile
+README.markdown
+MIT-LICENSE

data/README.markdown

@@ -37,8 +37,8 @@ Simplest example
 Get a page requiring HTTP Authentication
 ----------------------------------------
 
-    basic_handler = Resourceful::BasicAuthenticator.new('My Realm', 'admin', 'secret')
-    http.auth_manager.add_auth_hander(basic_handler)
+    my_realm_authenticator = Resourceful::BasicAuthenticator.new('My Realm', 'admin', 'secret')
+    http = Resourceful::HttpAccessor.new(:authenticator => my_realm_authenticator)
     resp = http.resource('http://example.com/').get
     puts resp.body
 
@@ -53,8 +53,6 @@ callback. If the callback evaluates to true, it will follow the redirect.
     resource.on_redirect { |req, resp| resp.header['Location'] =~ /example.com/ }
     resource.get  # Will only follow the redirect if the new location is example.com
 
-
-
 Post a URL encoded form
 -----------------------
 
@@ -82,5 +80,5 @@ Delete a resource
 Copyright
 ---------
 
-Copyright (c) 2008 Absolute Performance, Inc, Peter Williams; released under the MIT License.
+Copyright (c) 2008 Absolute Performance, Inc, Peter Williams.  Released under the MIT License.
 

data/Rakefile

@@ -1,93 +1,41 @@
 require 'rubygems'
 require 'rake'
-require 'rake/gempackagetask'
-require 'rake/rdoctask'
-require 'spec/rake/spectask'
+require 'echoe'
 
-desc 'Default: run unit tests.'
-task :default => :spec
+Echoe.new('resourceful', '0.3.0') do |p|
+  p.description     = "An HTTP library for Ruby that takes advantage of everything HTTP has to offer."
+  p.url             = "http://github.com/paul/resourceful"
+  p.author          = "Paul Sadauskas"
+  p.email           = "psadauskas@gmail.com"
 
-desc "Run all tests"
-task :test => :spec
+  p.ignore_pattern  = ["pkg/*", "tmp/*"]
+  p.dependencies    = ['addressable', 'httpauth', 'rspec', 'facets', 'andand']
+  p.development_dependencies = ['thin', 'yard']
+end
+
+require 'spec/rake/spectask'
 
-desc "Verify Resourceful against it's specs"
+desc 'Run all specs'
 Spec::Rake::SpecTask.new(:spec) do |t|
   t.spec_opts << '--options' << 'spec/spec.opts' if File.exists?('spec/spec.opts')
   t.libs << 'lib'
-  t.pattern = 'spec/**/*_spec.rb'
-end
-
-begin
-  gem 'yard', '>=0.2.3'
-  require 'yard'
-  desc 'Generate documentation for Resourceful.'
-  YARD::Rake::YardocTask.new do |t|
-    t.files   = ['lib/**/*.rb', 'README']
-  end
-rescue Exception
-  # install YARD to generate documentation
-end
-
-desc 'Removes all temporary files'
-task :clean
-
-##############################################################################
-# Packaging & Installation
-##############################################################################
-
-RESOURCEFUL_VERSION = "0.2.1"
-
-windows = (PLATFORM =~ /win32|cygwin/) rescue nil
-
-SUDO = windows ? "" : "sudo"
-
-task :resourceful => [:clean, :rdoc, :package]
-
-spec = Gem::Specification.new do |s|
-  s.name         = "resourceful"
-  s.version      = RESOURCEFUL_VERSION
-  s.platform     = Gem::Platform::RUBY
-  s.author       = "Paul Sadauskas & Peter Williams"
-  s.email        = "psadauskas@gmail.com"
-  s.homepage     = "https://github.com/paul/resourceful/tree/master"
-  s.summary      = "Resourceful provides a convenient Ruby API for making HTTP requests."
-  s.description  = s.summary
-  s.rubyforge_project = 'resourceful'
-  s.require_path = "lib"
-  s.files        = %w( MIT-LICENSE README.markdown Rakefile ) + Dir["{spec,lib}/**/*"]
-
-  # rdoc
-  s.has_rdoc         = false
-
-  # Dependencies
-  s.add_dependency "addressable"
-  s.add_dependency "httpauth"
-  s.add_dependency "rspec"
-  s.add_dependency "facets"
-
-  s.required_ruby_version = ">= 1.8.6"
+  t.spec_files = FileList['spec/**/*_spec.rb']
 end
 
-Rake::GemPackageTask.new(spec) do |package|
-  package.gem_spec = spec
-end
+desc 'Default: Run Specs'
+task :default => :spec
 
-desc "Run :package and install the resulting .gem"
-task :install => :package do
-  sh %{#{SUDO} gem install --local pkg/resourceful-#{RESOURCEFUL_VERSION}.gem --no-rdoc --no-ri}
-end
+desc 'Run all tests'
+task :test => :spec
 
-desc "Run :package and install the resulting .gem with jruby"
-task :jinstall => :package do
-  sh %{#{SUDO} jruby -S gem install pkg/resourceful-#{RESOURCEFUL_VERSION}.gem --no-rdoc --no-ri}
-end
+require 'yard'
 
-desc "Run :clean and uninstall the .gem"
-task :uninstall => :clean do
-  sh %{#{SUDO} gem uninstall resourceful}
+desc "Generate Yardoc"
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb', 'README.markdown']
 end
 
 desc "Update rubyforge documentation"
-task :update_docs do
+task :update_docs => :yardoc do
   puts %x{rsync -aPz doc/* psadauskas@resourceful.rubyforge.org:/var/www/gforge-projects/resourceful/}
 end

data/lib/resourceful/authentication_manager.rb

@@ -61,22 +61,44 @@ module Resourceful
 
   class DigestAuthenticator
 
+    attr_reader :username, :password, :realm, :domain, :challenge
+
     def initialize(realm, username, password)
-      @realm, @username, @password = realm, username, password
+      @realm = realm
+      @username, @password = username, password
       @domain = nil
     end
 
+    def update_credentials(challenge_response)
+      @domain = Addressable::URI.parse(challenge_response.uri).host
+      @challenge = HTTPAuth::Digest::Challenge.from_header(challenge_response.header['WWW-Authenticate'].first)
+    end
+
     def valid_for?(challenge_response)
-      return false unless challenge = challenge_response.header['WWW-Authenticate']
+      return false unless challenge_header = challenge_response.header['WWW-Authenticate']
       begin
-        challenge = HTTPAuth::Digest::Challenge.from_header(challenge.first)
+        challenge = HTTPAuth::Digest::Challenge.from_header(challenge_header.first)
       rescue HTTPAuth::UnwellformedHeader
         return false
       end
       challenge.realm == @realm
     end
 
+    def can_handle?(request)
+      Addressable::URI.parse(request.uri).host == @domain
+    end
 
+    def add_credentials_to(request)
+      request.header['Authorization'] = credentials_for(request)
+    end
+
+    def credentials_for(request)
+      HTTPAuth::Digest::Credentials.from_challenge(@challenge, 
+                                                   :username => @username,
+                                                   :password => @password,
+                                                   :method   => request.method.to_s.upcase,
+                                                   :uri      => Addressable::URI.parse(request.uri).path).to_header
+    end
 
   end
 

data/lib/resourceful/cache_manager.rb

@@ -1,20 +1,24 @@
 require 'resourceful/header'
+require 'andand'
 
 module Resourceful
 
-  class CacheManager
+  class AbstractCacheManager
     def initialize
       raise NotImplementedError,
         "Use one of CacheManager's child classes instead. Try NullCacheManager if you don't want any caching at all."
     end
 
-    # Search for a cached representation that can be used to fulfill the
-    # the given request. If none are found, returns nil.
+    # Finds a previously cached response to the provided request.  The
+    # response returned may be stale.
     #
-    # @param request<Resourceful::Request>
-    #   The request to use for searching.
+    # @param [Resourceful::Request] request 
+    #   The request for which we are looking for a response.
+    #
+    # @return [Resourceful::Response] 
+    #   A (possibly stale) response for the request provided.
     def lookup(request); end
-
+    
     # Store a response in the cache. 
     #
     # This method is smart enough to not store responses that cannot be 
@@ -35,29 +39,11 @@ module Resourceful
     # @param uri<String>
     #   The uri of the resource to be invalidated
     def invalidate(uri); end
-
-    # Selects the headers from the request named by the response's Vary header
-    # http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.5.6
-    #
-    # @param request<Resourceful::Request>
-    #   The request used to obtain the response.
-    # @param response<Resourceful::Response>
-    #   The response obtained from the request.
-    def select_request_headers(request, response)
-      header = Resourceful::Header.new
-
-      response.header['Vary'].first.split(',').each do |name|
-        name.strip!
-        header[name] = request.header[name]
-      end if response.header['Vary']
-
-      header
-    end
   end
 
   # This is the default cache, and does not do any caching. All lookups
   # result in nil, and all attempts to store a response are a no-op.
-  class NullCacheManager < CacheManager
+  class NullCacheManager < AbstractCacheManager
     def initialize; end
 
     def lookup(request)
@@ -70,105 +56,128 @@ module Resourceful
   # This is a nieve implementation of caching. Unused entries are never
   # removed, and this may eventually eat up all your memory and cause your
   # machine to explode.
-  class InMemoryCacheManager < CacheManager
+  class InMemoryCacheManager < AbstractCacheManager
 
     def initialize
       @collection = Hash.new{ |h,k| h[k] = CacheEntryCollection.new}
     end
 
     def lookup(request)
-      entry = @collection[request.uri.to_s][request]
-      response = entry.response if entry
-      response.authoritative = false if response
-
-      response      
+      returning(@collection[request.uri.to_s][request]) do |response|
+        response.authoritative = false if response
+      end
     end
 
     def store(request, response)
       return unless response.cachable?
 
-      entry = CacheEntry.new(request.request_time, 
-                             select_request_headers(request, response), 
-                             response)
-      
-      @collection[request.uri.to_s][request] = entry
+      @collection[request.uri.to_s][request] = response
     end
 
     def invalidate(uri)
       @collection.delete(uri)
     end
+  end  # class InMemoryCacheManager
+
+  # The collection of cached entries.  Nominally all the entry in a
+  # collection of this sort will be for the same resource but that is
+  # not required to be true.
+  class CacheEntryCollection
+    include Enumerable
+    
+    def initialize
+      @entries = []
+    end
+    
+    # Iterates over the entries. Needed for Enumerable
+    def each(&block)
+      @entries.each(&block)
+    end
+    
+    # Looks of a Entry that could fullfil the request. Returns nil if none
+    # was found.
+    #
+    # @param [Resourceful::Request] request
+    #   The request to use for the lookup.
+    #
+    # @return [Resourceful::Response] 
+    #   The cached response for the specified request if one is available.
+    def [](request)
+      find { |an_entry| an_entry.valid_for?(request) }.andand.response 
+    end
+    
+    # Saves an entry into the collection. Replaces any existing ones that could 
+    # be used with the updated response.
+    #
+    # @param [Resourceful::Request] request
+    #   The request that was used to obtain the response
+    # @param [Resourceful::Response] response
+    #   The cache_entry generated from response that was obtained.
+    def []=(request, response)
+      @entries.delete_if { |e| e.valid_for?(request) }
+      @entries << CacheEntry.new(request, response)
+
+      response
+    end
+  end # class CacheEntryCollection
+
+  # Represents a previous request and cached response with enough
+  # detail to determine construct a cached response to a matching
+  # request in the future.  It also understands what a matching
+  # request means.
+  class CacheEntry
+    # request_vary_headers is a HttpHeader with keys from the Vary
+    # header of the response, plus the values from the matching fields
+    # in the request
+    attr_reader :request_vary_headers
+    
+    # The time at which the client believes the request was made.
+    attr_reader :request_time
+
+    # The URI of the request
+    attr_reader :request_uri
+
+    # The response to that we are caching
+    attr_reader :response
+
+    # @param [Resourceful::Request] request
+    #   The request whose response we are storing in the cache.
+    # @param response<Resourceful::Response>
+    #   The Response obhect to be stored.
+    def initialize(request, response)
+      @request_uri = request.uri
+      @request_time = request.request_time
+      @request_vary_headers = select_request_headers(request, response)
+      @response = response
+    end
 
-    # The collection of all cached entries for a single resource (uri). 
-    class CacheEntryCollection
-      include Enumerable
-
-      def initialize
-        @entries = []
-      end
-
-      # Iterates over the entries. Needed for Enumerable
-      def each(&block)
-        @entries.each(&block)
-      end
-
-      # Looks of a Entry that could fullfil the request. Returns nil if none
-      # was found.
-      #
-      # @param request<Resourceful::Request>
-      #   The request to use for the lookup.
-      def [](request)
-        self.each do |entry|
-          return entry if entry.valid_for?(request)
-        end
-        return nil
-      end
-
-      # Saves an entry into the collection. Replaces any existing ones that could 
-      # be used with the updated response.
-      #
-      # @param request<Resourceful::Request>
-      #   The request that was used to obtain the response
-      # @param cache_entry<CacheEntry>
-      #   The cache_entry generated from response that was obtained.
-      def []=(request, cache_entry)
-        @entries.delete_if { |e| e.valid_for?(request) }
-        @entries.unshift cache_entry
-      end
+    # Returns true if this entry may be used to fullfil the given request, 
+    # according to the vary headers.
+    #
+    # @param request<Resourceful::Request>
+    #   The request to do the lookup on. 
+    def valid_for?(request)
+      request.uri == @request_uri and 
+        @request_vary_headers.all? {|key, value| request.header[key] == value}
+    end
 
-    end # class CacheEntryCollection
-
-    # Contains everything we need to know to build a response for a request using the
-    # stored request.
-    class CacheEntry
-      # request_vary_headers is a HttpHeader with keys from the 
-      # Vary header of the response, plus the values from the matching
-      # fields in the request
-      attr_accessor :request_time, :request_vary_headers, :response
-
-      # @param request_time<Time>
-      #   Client-generated timestamp for when the request was made
-      # @param request_vary_headers<Resourceful::HttpHeader>
-      #   A HttpHeader constructed from the keys listed in the vary headers
-      #   of the response, and values obtained from those headers in the request
-      # @param response<Resourceful::Response>
-      #   The Response obhect to be stored.
-      def initialize(request_time, request_vary_headers, response)
-        @request_time, @request_vary_headers, @response = request_time, request_vary_headers, response
-      end
+    # Selects the headers from the request named by the response's Vary header
+    # http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.5.6
+    #
+    # @param [Resourceful::Request] request
+    #   The request used to obtain the response.
+    # @param [Resourceful::Response] response
+    #   The response obtained from the request.
+    def select_request_headers(request, response)
+      header = Resourceful::Header.new
 
-      # Returns true if this entry may be used to fullfil the given request, 
-      # according to the vary headers.
-      #
-      # @param request<Resourceful::Request>
-      #   The request to do the lookup on. 
-      def valid_for?(request)
-        @request_vary_headers.all? do |key, value|
-          request.header[key] == value
-        end
-      end
+      response.header['Vary'].each do |name|
+        header[name] = request.header[name]
+      end if response.header['Vary']
 
-    end # class CacheEntry
+      header
+    end
 
-  end # class InMemoryCacheManager
+  end # class CacheEntry
 
 end