resourceful 0.2.1 → 0.3.0

data/lib/resourceful/http_accessor.rb

@@ -37,16 +37,17 @@ module Resourceful
     #
     # Errors will not be logged.  Instead an exception will be raised
     # and the application code should log it if appropriate.
-    attr_accessor :logger
-    
-    attr_reader :auth_manager, :cache_manager
+    attr_accessor :logger, :cache_manager
     
+    attr_reader :auth_manager
     attr_reader :user_agent_tokens  
     
     INIT_OPTIONS = OptionsInterpreter.new do 
       option(:logger, :default => Resourceful::BitBucketLogger.new)
       option(:user_agent, :default => []) {|ua| [ua].flatten}
       option(:cache_manager, :default => NullCacheManager.new)
+      option(:authenticator)
+      option(:authenticators, :default => [])
     end
     
     # Initializes a new HttpAccessor.  Valid options:
@@ -56,6 +57,13 @@ module Resourceful
     #
     #  +:user_agent+:: One or more additional user agent tokens to
     #    added to the user agent string.
+    #
+    #  +:cache_manager+:: The cache manager this accessor should use.
+    #
+    #  +:authenticator+:: Add a single authenticator for this accessor.
+    #
+    #  +:authenticators+:: Enumerable of the authenticators for this
+    #    accessor.
     def initialize(options = {})
       @user_agent_tokens = [RESOURCEFUL_USER_AGENT_TOKEN]
       
@@ -64,6 +72,9 @@ module Resourceful
         self.logger = opts[:logger]
         @auth_manager = AuthenticationManager.new()
         @cache_manager = opts[:cache_manager]
+        
+        add_authenticator(opts[:authenticator]) if opts[:authenticator]
+        opts[:authenticators].each { |a| add_authenticator(a) }
       end     
     end
     
@@ -76,10 +87,14 @@ module Resourceful
     
     # Returns a resource object representing the resource indicated
     # by the specified URI.  A resource object will be created if necessary.
-    def resource(uri)
-      resource = Resource.new(self, uri)
+    def resource(uri, opts = {})
+      resource = Resource.new(self, uri, opts)
     end
     alias [] resource
 
+    # Adds an Authenticator to the set used by the accessor.
+    def add_authenticator(an_authenticator)
+      auth_manager.add_auth_handler(an_authenticator)
+    end
   end
 end

data/lib/resourceful/memcache_cache_manager.rb

@@ -0,0 +1,85 @@
+require File.dirname(__FILE__) + "/cache_manager"
+
+require 'memcache'
+require 'facets/kernel/returning'
+
+module Resourceful
+  class MemcacheCacheManager < AbstractCacheManager
+  
+    # Create a new Memcached backed cache manager
+    #
+    # @param [*String] memcache_servers  
+    #   list of all Memcached servers this cache manager should use.
+    def initialize(*memcache_servers)
+      @memcache = MemCache.new(memcache_servers, :multithread => true)
+    end
+
+    # Finds a previously cached response to the provided request.  The
+    # response returned may be stale.
+    #
+    # @param [Resourceful::Request] request
+    #   The request for which we are looking for a response.
+    #
+    # @return [Resourceful::Response, nil] 
+    #   A (possibly stale) response for the request provided or nil if 
+    #   no matching response is found.
+    def lookup(request)
+      resp = cache_entries_for(request)[request]
+      return if resp.nil?
+
+      resp.authoritative = false
+
+      resp
+    end
+
+    # Store a response in the cache. 
+    #
+    # This method is smart enough to not store responses that cannot be 
+    # cached (Vary: * or Cache-Control: no-cache, private, ...)
+    #
+    # @param [Resourceful::Request] request
+    #   The request used to obtain the response. This is needed so the 
+    #   values from the response's Vary header can be stored.
+    # @param [Resourceful::Response] response
+    #   The response to be stored.
+    def store(request, response)
+      return unless response.cachable?
+
+      @memcache[request.to_mc_key] = returning(cache_entries_for(request)) do |entries|
+        entries[request] = response
+      end
+    end
+
+    # Invalidates a all cached entries for a uri. 
+    #
+    # This is used, for example, to invalidate the cache for a resource 
+    # that gets POSTed to.
+    #
+    # @param [String] uri
+    #   The uri of the resource to be invalidated
+    def invalidate(uri)
+      @memcache.delete(Digest::MD5.hexdigest(uri))
+    end
+
+
+    private 
+
+    ##
+    # The memcache proxy.
+    attr_reader :memcache
+
+    def cache_entries_for(a_request)
+      @memcache.get(a_request.to_mc_key) || Resourceful::CacheEntryCollection.new
+    end
+  end
+  
+  module MemCacheKey
+    def to_mc_key
+      Digest::MD5.hexdigest(uri)
+    end
+  end
+
+  class Request
+    include MemCacheKey
+  end
+end

data/lib/resourceful/net_http_adapter.rb

@@ -47,6 +47,7 @@ module Resourceful
     def self.net_http_request_class(method)
       case method
       when :get     then Net::HTTP::Get
+      when :head    then Net::HTTP::Head
       when :post    then Net::HTTP::Post
       when :put     then Net::HTTP::Put
       when :delete  then Net::HTTP::Delete

data/lib/resourceful/request.rb

@@ -12,11 +12,21 @@ module Resourceful
     attr_accessor :method, :resource, :body, :header
     attr_reader   :request_time
 
+    # @param [Symbol] http_method
+    #   :get, :put, :post, :delete or :head
+    # @param [Resourceful::Resource] resource
+    # @param [String] body
+    # @param [Resourceful::Header, Hash] header
     def initialize(http_method, resource, body = nil, header = nil)
       @method, @resource, @body = http_method, resource, body
       @header = header.is_a?(Resourceful::Header) ? header : Resourceful::Header.new(header || {})
 
       @header['Accept-Encoding'] = 'gzip, identity'
+      # 'Host' is a required HTTP/1.1 header, so set it if it isn't already
+      @header['Host'] ||= Addressable::URI.parse(resource.uri).host
+
+      # Setting the date isn't a bad idea, either
+      @header['Date'] ||= Time.now.httpdate
     end
 
     def response
@@ -24,6 +34,7 @@ module Resourceful
 
       http_resp = NetHttpAdapter.make_request(@method, @resource.uri, @body, @header)
       response = Resourceful::Response.new(uri, *http_resp)
+      response.request_time = @request_time
 
       response.authoritative = true
       response
@@ -44,6 +55,7 @@ module Resourceful
       @header['Cache-Control'] = 'max-age=0' if response.header.has_key?('Cache-Control') and response.header['Cache-Control'].include?('must-revalidate')
     end
 
+    # @return [String]   The URI against which this request will be, or was, made.
     def uri
       resource.uri
     end

data/lib/resourceful/resource.rb

@@ -10,8 +10,6 @@ module Resourceful
     attr_reader :http_response, :http_request
  
     # Initialize new error from the HTTP request and response attributes.
-    #--
-    # @private
     def initialize(http_request, http_response)
       super("#{http_request.method} request to <#{http_request.uri}> failed with code #{http_response.code}")
       @http_request = http_request
@@ -21,6 +19,7 @@ module Resourceful
 
   class Resource
     attr_reader :accessor
+    attr_accessor :default_options
 
     # Build a new resource for a uri
     #
@@ -28,8 +27,9 @@ module Resourceful
     #   The parent http accessor
     # @param uri<String, Addressable::URI> 
     #   The uri for the location of the resource
-    def initialize(accessor, uri)
+    def initialize(accessor, uri, options = {})
       @accessor, @uris = accessor, [uri]
+      @default_options = options
       @on_redirect = nil
     end
 
@@ -153,17 +153,17 @@ module Resourceful
     #   success, ie the final request returned a 2xx response code
     #
     def do_read_request(method, header = {})
-      request = Resourceful::Request.new(method, self, nil, header)
+      request = Resourceful::Request.new(method, self, nil, default_options.merge(header))
       accessor.auth_manager.add_credentials(request)
 
       cached_response = accessor.cache_manager.lookup(request)
       if cached_response
-        logger.debug("    Retrieved from cache")
+        logger.info("    Retrieved from cache")
         if not cached_response.stale?
           # We're done!
           return cached_response
         else
-          logger.debug("    Cache entry is stale")
+          logger.info("    Cache entry is stale")
           request.set_validation_headers(cached_response)
         end
       end
@@ -171,7 +171,9 @@ module Resourceful
       response = request.response
 
       if response.is_not_modified?
-        cached_response.header.merge(response.header)
+        logger.info("    Resource not modified")
+        cached_response.header.merge!(response.header)
+        cached_response.request_time = response.request_time
         response = cached_response
         response.authoritative = true
       end
@@ -179,9 +181,11 @@ module Resourceful
       if response.is_redirect? and request.should_be_redirected?
         if response.is_permanent_redirect?
           @uris.unshift response.header['Location'].first
+          logger.info("    Permanently redirected to #{uri} - Storing new location.")
           response = do_read_request(method, header)
         else
           redirected_resource = Resourceful::Resource.new(self.accessor, response.header['Location'].first)
+          logger.info("    Redirected to #{redirected_resource.uri} - Storing new location.")
           response = redirected_resource.do_read_request(method, header)
         end
       end
@@ -189,7 +193,7 @@ module Resourceful
       if response.is_not_authorized? && !@already_tried_with_auth
         @already_tried_with_auth = true
         accessor.auth_manager.associate_auth_info(response)
-        logger.debug("Authentication Required. Retrying with auth info")
+        logger.info("Authentication Required. Retrying with auth info")
         response = do_read_request(method, header)
       end
 
@@ -214,7 +218,7 @@ module Resourceful
     # @raise [UnsuccessfulHttpRequestError] unless the request is a
     #   success, ie the final request returned a 2xx response code
     def do_write_request(method, data = nil, header = {})
-      request = Resourceful::Request.new(method, self, data, header)
+      request = Resourceful::Request.new(method, self, data, default_options.merge(header))
       accessor.auth_manager.add_credentials(request)
 
       response = request.response

data/lib/resourceful/response.rb

@@ -113,7 +113,8 @@ module Resourceful
       if header['Expire']
         return true if Time.httpdate(header['Expire'].first) < Time.now
       end
-      if header['Cache-Control'] and header['Cache-Control'].include?('max-age')
+      if header['Cache-Control'] and header['Cache-Control'].first.include?('max-age')
+        max_age = header['Cache-Control'].first.split(',').grep(/max-age/).first.split('=').last.to_i
         return true if current_age > max_age
       end
 

data/resourceful.gemspec

@@ -0,0 +1,52 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{resourceful}
+  s.version = "0.3.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Paul Sadauskas"]
+  s.date = %q{2008-12-05}
+  s.description = %q{An HTTP library for Ruby that takes advantage of everything HTTP has to offer.}
+  s.email = %q{psadauskas@gmail.com}
+  s.extra_rdoc_files = ["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", "README.markdown"]
+  s.files = ["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", "resourceful.gemspec"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/paul/resourceful}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Resourceful", "--main", "README.markdown"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{resourceful}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{An HTTP library for Ruby that takes advantage of everything HTTP has to offer.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<addressable>, [">= 0"])
+      s.add_runtime_dependency(%q<httpauth>, [">= 0"])
+      s.add_runtime_dependency(%q<rspec>, [">= 0"])
+      s.add_runtime_dependency(%q<facets>, [">= 0"])
+      s.add_runtime_dependency(%q<andand>, [">= 0"])
+      s.add_development_dependency(%q<thin>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+    else
+      s.add_dependency(%q<addressable>, [">= 0"])
+      s.add_dependency(%q<httpauth>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<facets>, [">= 0"])
+      s.add_dependency(%q<andand>, [">= 0"])
+      s.add_dependency(%q<thin>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<addressable>, [">= 0"])
+    s.add_dependency(%q<httpauth>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<facets>, [">= 0"])
+    s.add_dependency(%q<andand>, [">= 0"])
+    s.add_dependency(%q<thin>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
+  end
+end

data/spec/acceptance_spec.rb

@@ -8,7 +8,7 @@ require Pathname(__FILE__).dirname + 'acceptance_shared_specs'
 describe Resourceful do
   it_should_behave_like 'simple http server'
 
-  describe 'getting a resource' do
+  describe 'working with a resource' do
     before do
       @accessor = Resourceful::HttpAccessor.new
     end
@@ -61,6 +61,38 @@ describe Resourceful do
       resp.header['Content-Type'].should == ['text/plain']
     end
 
+    it 'should take an optional default header for reads' do
+      resource = @accessor.resource('http://localhost:3000/echo_header', :foo => :bar)
+      resp = resource.get
+      resp.should be_instance_of(Resourceful::Response)
+      resp.code.should == 200
+      resp.body.should =~ /"HTTP_FOO"=>"bar"/
+    end
+
+    it 'should take an optional default header for writes' do
+      resource = @accessor.resource('http://localhost:3000/echo_header', :foo => :bar)
+      resp = resource.post("data", :content_type => 'text/plain')
+      resp.should be_instance_of(Resourceful::Response)
+      resp.code.should == 200
+      resp.body.should =~ /"HTTP_FOO"=>"bar"/
+    end
+
+    it 'should override the default header with any set on a read action' do
+      resource = @accessor.resource('http://localhost:3000/echo_header', :foo => :bar)
+      resp = resource.get(:foo => :baz)
+      resp.should be_instance_of(Resourceful::Response)
+      resp.code.should == 200
+      resp.body.should =~ /"HTTP_FOO"=>"baz"/
+    end
+
+    it 'should override the default header with any set on a write action' do
+      resource = @accessor.resource('http://localhost:3000/echo_header', :foo => :bar)
+      resp = resource.post("data", :foo => :baz, :content_type => 'text/plain')
+      resp.should be_instance_of(Resourceful::Response)
+      resp.code.should == 200
+      resp.body.should =~ /"HTTP_FOO"=>"baz"/
+    end
+
     describe 'redirecting' do
 
       describe 'registering callback' do
@@ -246,6 +278,19 @@ describe Resourceful do
           resp2.authoritative?.should be_true
         end
 
+        it 'should revalidate anything that is older than "Cache-Control: max-age" value' do
+
+          uri = URI.escape('http://localhost:3000/header?{Cache-Control: max-age=1, Date: "Mon, 04 Aug 2008 18:00:00 GMT"}')
+          resource = @accessor.resource(uri)
+          resp = resource.get
+          resp.authoritative?.should be_true
+
+          resp.expired?.should be_true
+
+          resp2 = resource.get
+          resp2.authoritative?.should be_true
+        end
+
         it 'should cache but revalidate anything with "Cache-Control: must-revalidate"' do
           uri = URI.escape('http://localhost:3000/header?{Cache-Control: must-revalidate}')
           resource = @accessor.resource(uri)

data/spec/resourceful/authentication_manager_spec.rb

@@ -166,6 +166,14 @@ end
 describe Resourceful::DigestAuthenticator do
 
   before do 
+    @header = {'WWW-Authenticate' => ['Digest realm="Test Auth"']}
+    @chal = mock('response', :header => @header, :uri => 'http://example.com/foo/bar')
+
+    @req_header = {}
+    @req = mock('request', :header => @req_header, 
+                           :uri => 'http://example.com',
+                           :method => 'GET')
+
     @auth = Resourceful::DigestAuthenticator.new('Test Auth', 'admin', 'secret')
   end
 
@@ -175,12 +183,21 @@ describe Resourceful::DigestAuthenticator do
     end
   end
 
-  describe "Updating from a challenge response" do
-    before do
-      @header = {'WWW-Authenticate' => ['Digest realm="Test Auth"']}
-      @chal = mock('response', :header => @header, :uri => 'http://example.com/foo/bar')
+  describe "Updating credentials from a challenge response" do
+
+    it "should set the domain from the host part of the challenge response uri" do
+      @auth.update_credentials(@chal)
+      @auth.domain.should == 'example.com'
     end
 
+    it "should create an HTTPAuth Digest Challenge from the challenge response WWW-Authenticate header" do
+      HTTPAuth::Digest::Challenge.should_receive(:from_header).with(@header['WWW-Authenticate'].first)
+      @auth.update_credentials(@chal)
+    end
+
+  end
+
+  describe "Validating a challenge" do
     it 'should be valid for a challenge response with scheme "Digest" and the same realm' do
       @auth.valid_for?(@chal).should be_true
     end
@@ -201,4 +218,32 @@ describe Resourceful::DigestAuthenticator do
     end
   end
 
+  it "should be able to handle requests to the same domain" do
+    @auth.instance_variable_set("@domain", 'example.com')
+    @auth.can_handle?(@req).should be_true
+  end
+
+  it "should not handle requests to a different domain" do
+    @auth.instance_variable_set("@domain", 'example2.com')
+    @auth.can_handle?(@req).should be_false
+  end
+
+  it "should add credentials to a request" do
+    @auth.update_credentials(@chal)
+    @auth.add_credentials_to(@req)
+    @req_header.should have_key('Authorization')
+    @req_header['Authorization'].should_not be_blank
+  end
+
+  it "should have HTTPAuth::Digest generate the Authorization header" do
+    @auth.update_credentials(@chal)
+    cred = mock('digest_credentials', :to_header => nil)
+
+    HTTPAuth::Digest::Credentials.should_receive(:from_challenge).with(
+      @auth.challenge, :username => 'admin', :password => 'secret', :method => 'GET', :uri => ''
+    ).and_return(cred)
+
+    cred = @auth.credentials_for(@req)
+  end
+
 end