paul-resourceful 0.2.3

data/lib/resourceful/response.rb

@@ -0,0 +1,175 @@
+require 'net/http'
+require 'time'
+require 'rubygems'
+require 'facets/kernel/ergo'
+require 'zlib'
+
+module Resourceful
+  # Exception indicating that the server used a content coding scheme
+  # that Resourceful is unable to handle.
+  class UnsupportedContentCoding < Exception
+  end
+
+  class Response
+    REDIRECT_RESPONSE_CODES = [301,302,303,307]
+
+    attr_reader :uri, :code, :header, :body, :response_time
+    alias headers header
+
+    attr_accessor :authoritative, :request_time
+    alias authoritative? authoritative
+
+    def initialize(uri, code, header, body)
+      @uri, @code, @header, @body = uri, code, header, body
+      @response_time = Time.now
+    end
+
+    # Is the response code sucessful? True for only 2xx series
+    # response codes.
+    #
+    # @return true|false
+    def is_success?
+      @code.in? 200..299
+    end
+    alias was_successful? is_success?
+
+    # Is the response the result of a server error? True for
+    # 5xx series response codes
+    #
+    # @return true|false
+    def is_server_error?
+      @code.in? 500..599
+    end
+    alias was_server_error? is_server_error?
+
+    # Is the response the result of a client error? True for
+    # 4xx series response codes
+    #
+    # @return true|false
+    def is_client_error?
+      @code.in? 400..499
+    end
+    alias was_client_error? is_client_error?
+
+    # Is the response the result of any kind of error? True for
+    # 4xx and 5xx series response codes
+    #
+    # @return true|false
+    def is_error?
+      is_server_error? || is_client_error?
+    end
+    alias was_error? is_error?
+
+    # Is the response not a success? True for
+    # 3xx, 4xx and 5xx series response codes
+    #
+    # @return true|false
+    def is_unsuccesful?
+      is_error? || is_redirect?
+    end
+    alias was_unsuccessful? is_unsuccesful?
+
+    # Is the response a redirect response code? True for
+    # 3xx codes that are redirects (301, 302, 303, 307)
+    #
+    # @return true|false
+    def is_redirect?
+      @code.in? REDIRECT_RESPONSE_CODES
+    end
+    alias was_redirect? is_redirect?
+
+    # Is the response a Permanent Redirect (301) ?
+    #
+    # @return true|false
+    def is_permanent_redirect?
+      @code == 301
+    end
+
+    # Is the response a Temporary Redirect (anything but 301) ?
+    #
+    # @return true|false
+    def is_temporary_redirect?
+      is_redirect? and not is_permanent_redirect?
+    end
+
+    # Is the response a client error of Not Authorized (401) ?
+    #
+    # @return true|false
+    def is_not_authorized?
+      @code == 401
+    end
+
+    # Is the response not modified (304) ?
+    #
+    # @return true|false
+    def is_not_modified?
+      @code == 304
+    end
+  
+    # Is this a cached response that has expired?
+    #
+    # @return true|false
+    def expired?
+      if header['Expire']
+        return true if Time.httpdate(header['Expire'].first) < Time.now
+      end
+      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
+
+      false
+    end
+
+    # Is this a cached response that is stale?
+    #
+    # @return true|false
+    def stale?
+      return true if expired?
+      if header['Cache-Control']
+        return true if header['Cache-Control'].include?('must-revalidate')
+        return true if header['Cache-Control'].include?('no-cache')
+      end
+
+      false
+    end
+
+    # Is this response cachable?
+    #
+    # @return true|false
+    def cachable?
+      return false if header['Vary'] and header['Vary'].include?('*')
+      return false if header['Cache-Control'] and header['Cache-Control'].include?('no-store')
+
+      true
+    end
+
+    # Algorithm taken from RCF2616#13.2.3
+    def current_age
+      age_value   = Time.httpdate(header['Age'].first) if header['Age']
+      date_value  = Time.httpdate(header['Date'].first)
+      now         = Time.now
+
+      apparent_age = [0, response_time - date_value].max
+      corrected_received_age = [apparent_age, age_value || 0].max
+      current_age = corrected_received_age + (response_time - request_time) + (now - response_time)
+    end
+
+    def body
+      case header['Content-Encoding'].ergo.first
+      when nil
+        # body is identity encoded; just return it
+        @body
+      when /^\s*gzip\s*$/i
+        gz_in = ::Zlib::GzipReader.new(StringIO.new(@body, 'r'))
+        @body = gz_in.read
+        gz_in.close
+        header.delete('Content-Encoding')
+        @body
+      else
+        raise UnsupportedContentCoding, "Resourceful does not support #{header['Content-Encoding'].ergo.first} content coding" 
+      end
+    end
+  end
+  
+end

data/lib/resourceful/stubbed_resource_proxy.rb

@@ -0,0 +1,47 @@
+require 'resourceful/resource'
+  
+module Resourceful
+  class StubbedResourceProxy
+    def initialize(resource, canned_responses)
+      @resource = resource
+      
+      @canned_responses = {}
+      
+      canned_responses.each do |cr| 
+        mime_type = cr[:mime_type]
+        @canned_responses[mime_type] = resp = Net::HTTPOK.new('1.1', '200', 'OK')
+        resp['content-type'] = mime_type.to_str
+        resp.instance_variable_set(:@read, true)
+        resp.instance_variable_set(:@body, cr[:body])
+
+      end
+    end
+
+    def get_body(*args)
+      get(*args).body
+    end
+    
+    def get(*args)
+      options = args.last.is_a?(Hash) ? args.last : {}
+      
+      if accept = [(options[:accept] || '*/*')].flatten.compact
+        accept.each do |mt|
+          return canned_response(mt) || next
+        end
+        @resource.get(*args)
+       end
+    end
+
+    def method_missing(method, *args)
+      @resource.send(method, *args)
+    end
+    
+    protected
+    
+    def canned_response(mime_type)
+      mime_type = @canned_responses.keys.first if mime_type == '*/*'
+      @canned_responses[mime_type]
+    end
+    
+  end
+end

data/lib/resourceful/util.rb

@@ -0,0 +1,6 @@
+
+class Object
+  def in?(arr)
+    arr.include?(self)
+  end
+end

data/lib/resourceful/version.rb

@@ -0,0 +1 @@
+RESOURCEFUL_VERSION = '0.2'

data/resourceful.gemspec

@@ -0,0 +1,30 @@
+Gem::Specification.new do |s|
+  s.name = %q{resourceful}
+  s.version = "0.2.3"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Paul Sadauskas", "Peter Williams"]
+  s.date = %q{2008-11-22}
+  s.email = ["psadauskas@gmail.com", "pezra@barelyenough.org"]
+  s.extra_rdoc_files = ["Manifest.txt"]
+  s.files = ["MIT-LICENSE", "Manifest.txt", "README.markdown", "Rakefile", "lib/resourceful.rb", "lib/resourceful/authentication_manager.rb", "lib/resourceful/cache_manager.rb", "lib/resourceful/header.rb", "lib/resourceful/http_accessor.rb", "lib/resourceful/net_http_adapter.rb", "lib/resourceful/options_interpreter.rb", "lib/resourceful/request.rb", "lib/resourceful/resource.rb", "lib/resourceful/response.rb", "lib/resourceful/stubbed_resource_proxy.rb", "lib/resourceful/util.rb", "lib/resourceful/version.rb", "resourceful.gemspec", "spec/acceptance_shared_specs.rb", "spec/acceptance_spec.rb", "spec/resourceful/authentication_manager_spec.rb", "spec/resourceful/cache_manager_spec.rb", "spec/resourceful/header_spec.rb", "spec/resourceful/http_accessor_spec.rb", "spec/resourceful/net_http_adapter_spec.rb", "spec/resourceful/options_interpreter_spec.rb", "spec/resourceful/request_spec.rb", "spec/resourceful/resource_spec.rb", "spec/resourceful/response_spec.rb", "spec/resourceful/stubbed_resource_proxy_spec.rb", "spec/simple_http_server_shared_spec.rb", "spec/simple_http_server_shared_spec_spec.rb", "spec/spec.opts", "spec/spec_helper.rb"]
+  s.has_rdoc = true
+  s.rdoc_options = ["--main", "README.txt"]
+  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_development_dependency(%q<hoe>, [">= 1.8.2"])
+    else
+      s.add_dependency(%q<hoe>, [">= 1.8.2"])
+    end
+  else
+    s.add_dependency(%q<hoe>, [">= 1.8.2"])
+  end
+end

data/spec/acceptance_shared_specs.rb

@@ -0,0 +1,49 @@
+describe 'redirect', :shared => true do
+  it 'should be followed by default on GET' do
+    resp = @resource.get
+    resp.should be_instance_of(Resourceful::Response)
+    resp.code.should == 200
+    resp.header['Content-Type'].should == ['text/plain']
+  end
+
+  %w{PUT POST}.each do |method|
+    it "should not be followed by default on #{method}" do
+      lambda {
+        @resource.send(method.downcase.intern, nil, :content_type => 'text/plain' )
+      }.should raise_error(Resourceful::UnsuccessfulHttpRequestError)
+    end
+
+    it "should redirect on #{method.to_s.upcase} if the redirection callback returns true" do
+      @resource.on_redirect { true }
+      resp = @resource.send(method.downcase.intern, nil, :content_type => 'text/plain' )
+      resp.code.should == 200
+    end
+
+    it "should not redirect on #{method.to_s.upcase} if the redirection callback returns false" do
+      @resource.on_redirect { false }
+      lambda {
+        @resource.send(method.downcase.intern, nil, :content_type => 'text/plain' )
+      }.should raise_error(Resourceful::UnsuccessfulHttpRequestError)
+    end
+  end
+
+  it "should not be followed by default on DELETE" do
+    lambda {
+      @resource.delete
+    }.should raise_error(Resourceful::UnsuccessfulHttpRequestError)
+  end
+
+  it "should redirect on DELETE if vthe redirection callback returns true" do
+    @resource.on_redirect { true }
+    resp = @resource.delete
+    resp.code.should == 200
+  end
+
+  it "should not redirect on DELETE if the redirection callback returns false" do
+    @resource.on_redirect { false }
+    lambda {
+      @resource.delete
+    }.should raise_error(Resourceful::UnsuccessfulHttpRequestError)
+  end
+end
+

data/spec/acceptance_spec.rb

@@ -0,0 +1,408 @@
+require 'pathname'
+require Pathname(__FILE__).dirname + 'spec_helper'
+require 'resourceful'
+
+require Pathname(__FILE__).dirname + 'acceptance_shared_specs'
+
+
+describe Resourceful do
+  it_should_behave_like 'simple http server'
+
+  describe 'working with a resource' do
+    before do
+      @accessor = Resourceful::HttpAccessor.new
+    end
+
+    it 'should #get a resource, and return a response object' do
+      resource = @accessor.resource('http://localhost:3000/get')
+      resp = resource.get
+      resp.should be_instance_of(Resourceful::Response)
+      resp.code.should == 200
+      resp.body.should == 'Hello, world!'
+      resp.header.should be_instance_of(Resourceful::Header)
+      resp.header['Content-Type'].should == ['text/plain']
+    end
+
+    it 'should set additional headers on the #get' do
+      resource = @accessor.resource('http://localhost:3000/echo_header')
+      resp = resource.get(:foo => :bar)
+      resp.should be_instance_of(Resourceful::Response)
+      resp.code.should == 200
+      resp.body.should =~ /"HTTP_FOO"=>"bar"/
+    end
+
+    it 'should #post a resource, and return the response' do
+      resource = @accessor.resource('http://localhost:3000/post')
+      resp = resource.post('Hello world from POST', :content_type => 'text/plain')
+      resp.should be_instance_of(Resourceful::Response)
+      resp.code.should == 201
+      resp.body.should == 'Hello world from POST'
+      resp.header.should be_instance_of(Resourceful::Header)
+      resp.header['Content-Type'].should == ['text/plain']
+    end
+
+    it 'should #put a resource, and return the response' do
+      resource = @accessor.resource('http://localhost:3000/put')
+      resp = resource.put('Hello world from PUT', :content_type => 'text/plain')
+      resp.should be_instance_of(Resourceful::Response)
+      resp.code.should == 200
+      resp.body.should == 'Hello world from PUT'
+      resp.header.should be_instance_of(Resourceful::Header)
+      resp.header['Content-Type'].should == ['text/plain']
+    end
+
+    it 'should #delete a resource, and return a response' do
+      resource = @accessor.resource('http://localhost:3000/delete')
+      resp = resource.delete
+      resp.should be_instance_of(Resourceful::Response)
+      resp.code.should == 200
+      resp.body.should == 'KABOOM!'
+      resp.header.should be_instance_of(Resourceful::Header)
+      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
+        before do
+          @resource = @accessor.resource('http://localhost:3000/redirect/301?http://localhost:3000/get')
+          @callback = mock('callback')
+          @callback.stub!(:call).and_return(true)
+
+          @resource.on_redirect { @callback.call }
+        end
+
+        it 'should allow a callback to be registered' do
+          @resource.should respond_to(:on_redirect)
+        end
+
+        it 'should perform a registered callback on redirect' do
+          @callback.should_receive(:call).and_return(true)
+          @resource.get
+        end
+
+        it 'should not perform the redirect if the callback returns false' do
+          @callback.should_receive(:call).and_return(false)
+          lambda {
+            @resource.get
+          }.should raise_error(Resourceful::UnsuccessfulHttpRequestError)
+        end
+      end
+
+      describe 'permanent redirect' do
+        before do
+          @redirect_code = 301
+          @resource = @accessor.resource('http://localhost:3000/redirect/301?http://localhost:3000/get')
+        end
+
+        it_should_behave_like 'redirect'
+
+        it 'should change the effective uri of the resource' do
+          @resource.get
+          @resource.effective_uri.should == 'http://localhost:3000/get'
+        end
+      end
+
+      describe 'temporary redirect' do
+        before do
+          @redirect_code = 302
+          @resource = @accessor.resource('http://localhost:3000/redirect/302?http://localhost:3000/get')
+        end
+
+        it_should_behave_like 'redirect'
+
+        it 'should not change the effective uri of the resource' do
+          @resource.get
+          @resource.effective_uri.should == 'http://localhost:3000/redirect/302?http://localhost:3000/get'
+        end
+
+        describe '303 See Other' do
+          before do
+            @redirect_code = 303
+            @resource = @accessor.resource('http://localhost:3000/redirect/303?http://localhost:3000/method')
+            @resource.on_redirect { true }
+          end
+
+          it 'should GET the redirected resource, regardless of the initial method' do
+            resp = @resource.delete
+            resp.code.should == 200
+            resp.body.should == 'GET'
+          end
+        end
+      end
+
+    end
+
+    describe 'caching' do
+      before do
+        @accessor = Resourceful::HttpAccessor.new(:cache_manager => Resourceful::InMemoryCacheManager.new)
+      end
+
+      it 'should use the cached response' do
+        resource = @accessor.resource('http://localhost:3000/get')
+        resp = resource.get
+        resp.authoritative?.should be_true
+
+        resp2 = resource.get
+        resp2.authoritative?.should be_false
+
+        resp2.should == resp
+      end
+      
+      it 'should not store the representation if the server says not to' do
+        resource = @accessor.resource('http://localhost:3000/header?{Vary:%20*}')
+        resp = resource.get
+        resp.authoritative?.should be_true
+        resp.should_not be_cachable
+
+        resp2 = resource.get
+        resp2.should_not == resp
+      end
+
+      it 'should use the cached version of the representation if it has not expired' do
+        in_an_hour = (Time.now + (60*60)).httpdate
+        uri = URI.escape("http://localhost:3000/header?{Expire: \"#{in_an_hour}\"}")
+
+        resource = @accessor.resource(uri)
+        resp = resource.get
+        resp.should be_authoritative
+
+        resp2 = resource.get
+        resp2.should_not be_authoritative
+        resp2.should == resp
+      end
+
+      it 'should revalidate the cached response if it has expired' do
+        an_hour_ago = (Time.now - (60*60)).httpdate
+        uri = URI.escape("http://localhost:3000/header?{Expire: \"#{an_hour_ago}\"}")
+
+        resource = @accessor.resource(uri)
+        resp = resource.get
+        resp.should be_authoritative
+        resp.should be_expired
+
+        resp2 = resource.get
+        resp2.should be_authoritative
+      end
+
+      it 'should provide the cached version if the server responds with a 304 not modified' do
+        in_an_hour = (Time.now + (60*60)).httpdate
+        uri = URI.escape("http://localhost:3000/modified?#{in_an_hour}")
+
+        resource = @accessor.resource(uri)
+        resp = resource.get
+        resp.should be_authoritative
+        resp.header['Cache-Control'].should include('must-revalidate')
+
+        resp2 = resource.get
+        resp2.should be_authoritative
+        resp2.should == resp
+      end
+
+      it 'should not use a cached document for a resource that has been posted to' do
+        resource = @accessor.resource('http://localhost:3000/get')
+        resp = resource.get
+        resp.authoritative?.should be_true
+
+        resource.post("foo", :content_type => 'text/plain')
+
+        resp2 = resource.get
+        resp2.should_not == resp
+      end
+
+      describe 'Cache-Control' do
+
+        it 'should cache anything with "Cache-Control: public"' do
+          uri = URI.escape('http://localhost:3000/header?{Cache-Control: public}')
+          resource = @accessor.resource(uri)
+          resp = resource.get
+          resp.authoritative?.should be_true
+
+          resp2 = resource.get
+          resp2.authoritative?.should be_false
+
+          resp2.should == resp
+        end
+
+        it 'should cache anything with "Cache-Control: private"' do
+          uri = URI.escape('http://localhost:3000/header?{Cache-Control: private}')
+          resource = @accessor.resource(uri)
+          resp = resource.get
+          resp.authoritative?.should be_true
+
+          resp2 = resource.get
+          resp2.authoritative?.should be_false
+
+          resp2.should == resp
+        end
+
+        it 'should cache but revalidate anything with "Cache-Control: no-cache"' do
+          uri = URI.escape('http://localhost:3000/header?{Cache-Control: no-cache}')
+          resource = @accessor.resource(uri)
+          resp = resource.get
+          resp.authoritative?.should be_true
+
+          resp2 = resource.get
+          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)
+          resp = resource.get
+          resp.authoritative?.should be_true
+
+          resp2 = resource.get
+          resp2.authoritative?.should be_true
+        end
+
+        it 'should not cache anything with "Cache-Control: no-store"' do
+          uri = URI.escape('http://localhost:3000/header?{Cache-Control: no-store}')
+          resource = @accessor.resource(uri)
+          resp = resource.get
+          resp.authoritative?.should be_true
+
+          resp2 = resource.get
+          resp2.authoritative?.should be_true
+        end
+
+
+      end
+
+    end
+
+    describe 'authorization' do
+      before do
+        @uri = 'http://localhost:3000/auth?basic'
+      end
+
+      it 'should automatically add authorization info to the request if its available'
+
+      it 'should not authenticate if no auth handlers are set' do
+        resource = @accessor.resource(@uri)
+        lambda {
+          resource.get
+        }.should raise_error(Resourceful::UnsuccessfulHttpRequestError)
+      end
+
+      it 'should not authenticate if no valid auth handlers are available' do
+        basic_handler = Resourceful::BasicAuthenticator.new('Not Test Auth', 'admin', 'secret')
+        @accessor.auth_manager.add_auth_handler(basic_handler)
+        resource = @accessor.resource(@uri)
+        lambda {
+          resource.get
+        }.should raise_error(Resourceful::UnsuccessfulHttpRequestError)
+      end
+
+      describe 'basic' do
+        before do
+          @uri = 'http://localhost:3000/auth?basic'
+        end
+
+        it 'should be able to authenticate basic auth' do
+          basic_handler = Resourceful::BasicAuthenticator.new('Test Auth', 'admin', 'secret')
+          @accessor.auth_manager.add_auth_handler(basic_handler)
+          resource = @accessor.resource(@uri)
+          resp = resource.get
+
+          resp.code.should == 200
+        end
+
+        it 'should not keep trying to authenticate with incorrect credentials' do
+          basic_handler = Resourceful::BasicAuthenticator.new('Test Auth', 'admin', 'well-known')
+          @accessor.auth_manager.add_auth_handler(basic_handler)
+          resource = @accessor.resource(@uri)
+
+          lambda {
+            resource.get
+          }.should raise_error(Resourceful::UnsuccessfulHttpRequestError)
+        end
+
+      end
+
+      describe 'digest' do
+        before do
+          @uri = 'http://localhost:3000/auth/digest'
+        end
+
+        it 'should be able to authenticate digest auth' do
+          pending
+          digest_handler = Resourceful::DigestAuthenticator.new('Test Auth', 'admin', 'secret')
+          @accessor.auth_manager.add_auth_handler(digest_handler)
+          resource = @accessor.resource(@uri)
+          resp = resource.get
+
+          resp.code.should == 200
+        end
+
+      end
+
+    end
+
+    describe 'error checking' do
+
+      it 'should raise InvalidResponse when response code is invalid'
+
+      describe 'client errors' do
+
+        it 'should raise when there is one'
+
+      end
+
+      describe 'server errors' do
+
+        it 'should raise when there is one'
+
+      end
+
+    end
+
+  end
+
+end
+