resourceful 0.2

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2008 Absolute-Performance, Inc
+Copyright (c) 2008 Peter Williams
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,86 @@
+Resourceful
+===========
+
+Resourceful provides a convenient Ruby API for making HTTP requests.
+
+Features:
+
+ * GET, PUT, POST and DELETE HTTP requests
+ * HTTP Basic and Digest authentication
+ * HTTP Caching with pluggable backends
+ * Follow redirects based on the results of a callback
+
+More Info
+=========
+ 
+ * Source: [Github](http://github.com/paul/resourceful/tree/master)
+ * Bug Tracking: [Lighthouse](http://resourceful.lighthouseapp.com)
+ * Project Page: [Rubyforge](http://rubyforge.org/projects/resourceful/)
+ * Documentation: [API Docs](http://resourceful.rubyforge.org)
+
+Examples
+========
+
+Getting started
+---------------
+
+    gem install resourceful
+
+Simplest example
+---------------
+
+    require 'resourceful'
+    http = Resourceful::HttpAccessor.new
+    resp = http.resource('http://rubyforge.org').get
+    puts resp.body
+
+Get a page requiring HTTP Authentication
+----------------------------------------
+
+    basic_handler = Resourceful::BasicAuthenticator.new('My Realm', 'admin', 'secret')
+    http.auth_manager.add_auth_hander(basic_handler)
+    resp = http.resource('http://example.com/').get
+    puts resp.body
+
+Redirection based on callback results
+-------------------------------------
+
+Resourceful will by default follow redirects on read requests (GET and HEAD), but not for 
+POST, etc. If you want to follow a redirect after a post, you will need to set the resource#on_redirect
+callback. If the callback evaluates to true, it will follow the redirect.
+
+    resource = http.resource('http://example.com/redirect_me')
+    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
+-----------------------
+
+     require 'resourceful'
+     http = Resourceful::HttpAccessor.new
+     resp = http.resource('http://mysite.example/service').
+              post('hostname=test&level=super', :content_type => 'application/x-www-form-urlencoded')
+
+Put an XML document
+-------------------
+
+     require 'resourceful'
+     http = Resourceful::HttpAccessor.new
+     resp = http.resource('http://mysite.example/service').
+              put('<?xml version="1.0"?><test/>', :content_type => 'application/xml')
+    
+Delete a resource
+-----------------
+
+     require 'resourceful'
+     http = Resourceful::HttpAccessor.new
+     resp = http.resource('http://mysite.example/service').delete
+
+
+Copyright
+---------
+
+Copyright (c) 2008 Absolute Performance, Inc, Peter Williams; released under the MIT License.
+

data/Rakefile

@@ -0,0 +1,89 @@
+require 'rubygems'
+require 'rake'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+desc 'Default: run unit tests.'
+task :default => :spec
+
+desc "Run all tests"
+task :test => :spec
+
+desc "Verify Resourceful against it's specs"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  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"
+
+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 "thin"
+  s.add_dependency "facets"
+
+  s.required_ruby_version = ">= 1.8.6"
+end
+
+Rake::GemPackageTask.new(spec) do |package|
+  package.gem_spec = spec
+end
+
+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 :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
+
+desc "Run :clean and uninstall the .gem"
+task :uninstall => :clean do
+  sh %{#{SUDO} gem uninstall resourceful}
+end
+

data/lib/resourceful.rb

@@ -0,0 +1,28 @@
+require 'resourceful/http_accessor'
+
+require 'resourceful/util'
+
+# Resourceful is a library that provides a high level HTTP interface.
+module Resourceful
+
+  HOP_BY_HOP_HEADERS = %w{
+    Connection
+    Keep-Alive
+    Proxy-Authenticate
+    Proxy-Authorization
+    TE
+    Trailers
+    Transfer-Encoding
+    Upgrade
+  }
+
+  NON_MODIFIABLE_HEADERS = %w{
+    Content-Location
+    Content-MD5
+    ETag
+    Last-Modified
+    Expires
+  }
+
+
+end

data/lib/resourceful/authentication_manager.rb

@@ -0,0 +1,85 @@
+require 'rubygems'
+require 'httpauth'
+require 'addressable/uri'
+
+module Resourceful
+
+  class AuthenticationManager
+    def initialize
+      @authenticators = []
+    end
+
+    def add_auth_handler(authenticator)
+      @authenticators << authenticator
+    end
+
+    def associate_auth_info(challenge)
+      @authenticators.each do |authenticator|
+        authenticator.update_credentials(challenge) if authenticator.valid_for?(challenge)
+      end
+    end
+
+    def add_credentials(request)
+      authenticator = @authenticators.find { |authenticator| authenticator.can_handle?(request) }
+      authenticator.add_credentials_to(request) if authenticator
+    end
+
+  end
+
+  class BasicAuthenticator
+
+    def initialize(realm, username, password)
+      @realm, @username, @password = realm, username, password
+      @domain = nil
+    end
+
+    def valid_for?(challenge_response)
+      return false unless challenge_response.header['WWW-Authenticate']
+
+      !challenge_response.header['WWW-Authenticate'].grep(/^\s*basic/i).find do |a_challenge|
+        @realm.downcase == /realm="([^"]+)"/i.match(a_challenge)[1].downcase
+      end.nil?
+    end
+
+    def update_credentials(challenge)
+      @domain = Addressable::URI.parse(challenge.uri).host
+    end
+
+    def can_handle?(request)
+      Addressable::URI.parse(request.uri).host == @domain
+    end
+
+    def add_credentials_to(request)
+      request.header['Authorization'] = credentials
+    end
+
+    def credentials
+      HTTPAuth::Basic.pack_authorization(@username, @password)
+    end
+
+  end
+
+  class DigestAuthenticator
+
+    def initialize(realm, username, password)
+      @realm, @username, @password = realm, username, password
+      @domain = nil
+    end
+
+    def valid_for?(challenge_response)
+      return false unless challenge = challenge_response.header['WWW-Authenticate']
+      begin
+        challenge = HTTPAuth::Digest::Challenge.from_header(challenge.first)
+      rescue HTTPAuth::UnwellformedHeader
+        return false
+      end
+      challenge.realm == @realm
+    end
+
+
+
+  end
+
+
+end
+

data/lib/resourceful/cache_manager.rb

@@ -0,0 +1,160 @@
+require 'resourceful/header'
+
+module Resourceful
+
+  class CacheManager
+    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.
+    #
+    # @param request<Resourceful::Request>
+    #   The request to use for searching.
+    def lookup(request); 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 request<Resourceful::Request>
+    #   The request used to obtain the response. This is needed so the 
+    #   values from the response's Vary header can be stored.
+    # @param response<Resourceful::Response>
+    #   The response to be stored.
+    def store(request, 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 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'].each do |name|
+        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
+    def initialize; end
+
+    def lookup(request)
+      nil
+    end
+
+    def store(request, response); end
+  end
+
+  # 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
+
+    def initialize
+      @collection = Hash.new(CacheEntryCollection.new)
+    end
+
+    def lookup(request)
+      entry = @collection[request.resource.uri][request]
+      response = entry.response if entry
+      response.authoritative = false if response
+
+      response      
+    end
+
+    def store(request, response)
+      return unless response.cachable?
+
+      entry = CacheEntry.new(request.request_time, 
+                             select_request_headers(request, response), 
+                             response)
+      
+      @collection[request.resource.uri][request] = entry
+    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
+
+    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
+
+      # 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
+
+    end # class CacheEntry
+
+  end # class InMemoryCacheManager
+
+end