openlogic-resourceful 1.2.0

data/History.txt

@@ -0,0 +1,45 @@
+Version NEXT
+============
+ * Added PromiscuousBasicAuthenticator to support basic authentication
+   with servers that do not return challenge headers.
+
+
+Version 1.0.0
+============
+ * Added .request() convenience method to Resourceful module.
+ * Added .get(), .post(), .put(), .delete() and .head() convenience method to Resourceful module
+
+Version 0.7.0
+=============
+ * Multiple values in a single header field are treated the same as repeated header fields. (Peter Williams)
+
+Compatibility issues
+--------------------
+
+ * The semantics of the Resourceful::Header API have changed slightly.
+   Previously multiple values in a single header field 
+   (e.g. `Accept: application/xml, application/json`) where treated 
+   differently from multiple values occurring in multiple fields (e.g 
+   `Accept: application/xml\n\rAccept: application/json`).  This lead 
+   to some unfortunate complexity when interacting with multi-valued 
+   fields.
+
+
+Version 0.6.0
+=============
+
+ * Improved support for multi-valued header fields. (Peter Williams)
+ * Added convenience mechanisms for making URL encoded and multipart form data requests. (Peter Williams)
+ * Ruby 1.9 support (Peter Williams)
+
+Compatibility issues
+--------------------
+
+ * The semantics of the Resourceful::Header API have changed slightly.
+   Previously, any header might return a string or an array.  Now
+   fields are either "single-value" and always return a string, or
+   "multi-value" and always return an array.  See API doc for more
+   details.
+
+
+

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/Manifest

@@ -0,0 +1,46 @@
+History.txt
+MIT-LICENSE
+Manifest
+README.markdown
+Rakefile
+lib/resourceful.rb
+lib/resourceful/abstract_form_data.rb
+lib/resourceful/authentication_manager.rb
+lib/resourceful/cache_manager.rb
+lib/resourceful/exceptions.rb
+lib/resourceful/header.rb
+lib/resourceful/http_accessor.rb
+lib/resourceful/memcache_cache_manager.rb
+lib/resourceful/multipart_form_data.rb
+lib/resourceful/net_http_adapter.rb
+lib/resourceful/promiscuous_basic_authenticator.rb
+lib/resourceful/request.rb
+lib/resourceful/resource.rb
+lib/resourceful/response.rb
+lib/resourceful/simple.rb
+lib/resourceful/stubbed_resource_proxy.rb
+lib/resourceful/urlencoded_form_data.rb
+lib/resourceful/util.rb
+openlogic-resourceful.gemspec
+resourceful.gemspec
+spec/acceptance/authorization_spec.rb
+spec/acceptance/caching_spec.rb
+spec/acceptance/header_spec.rb
+spec/acceptance/redirecting_spec.rb
+spec/acceptance/resource_spec.rb
+spec/acceptance/resourceful_spec.rb
+spec/acceptance_shared_specs.rb
+spec/caching_spec.rb
+spec/old_acceptance_specs.rb
+spec/resourceful/header_spec.rb
+spec/resourceful/http_accessor_spec.rb
+spec/resourceful/multipart_form_data_spec.rb
+spec/resourceful/promiscuous_basic_authenticator_spec.rb
+spec/resourceful/resource_spec.rb
+spec/resourceful/response_spec.rb
+spec/resourceful/urlencoded_form_data_spec.rb
+spec/resourceful_spec.rb
+spec/simple_sinatra_server.rb
+spec/simple_sinatra_server_spec.rb
+spec/spec.opts
+spec/spec_helper.rb

data/README.markdown

@@ -0,0 +1,92 @@
+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'
+    resp = Resourceful.get('http://rubyforge.org')
+    puts resp.body
+
+Get a page requiring HTTP Authentication
+----------------------------------------
+
+    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
+
+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(Resourceful::UrlencodedFormData.new(:hostname => 'test', :level => 'super'))
+
+Post a Mulitpart form with a file
+-----------------------
+
+     require 'resourceful'
+     http = Resourceful::HttpAccessor.new
+     form_data = Resourceful::MultipartFormData.new(:username => 'me')
+     form_data.add_file('avatar', '/tmp/my_avatar.png', 'image/png')
+     resp = http.resource('http://mysite.example/service').post(form_data)
+
+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,91 @@
+require 'rubygems'
+require 'rake'
+require 'lib/resourceful'
+
+begin
+  require 'echoe'
+
+  Echoe.new('openlogic-resourceful', Resourceful::VERSION) 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          = "OpenLogic"
+    p.email           = "engteam@openlogic.com"
+
+    p.ignore_pattern  = ["pkg/*", "tmp/*"]
+    p.dependencies    = [['addressable', '>= 2.1.0'], 'httpauth', ['options', '>= 2.1.1']]
+    p.development_dependencies = ['thin', 'yard', 'sinatra', 'rspec']
+    p.retain_gemspec  = true
+  end
+rescue LoadError => e
+  puts "install 'echoe' gem to be able to build the gem"
+end
+
+require 'spec/rake/spectask'
+
+desc 'Run all acceptance 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.spec_files = FileList['spec/**/*_spec.rb'] 
+end
+
+namespace :spec do 
+  desc 'Run all acceptance specs'
+  Spec::Rake::SpecTask.new(:acceptance) do |t|
+    t.spec_opts << '--options' << 'spec/spec.opts' if File.exists?('spec/spec.opts')
+    t.libs << 'lib'
+    t.spec_files = FileList['spec/acceptance/*_spec.rb'] 
+  end
+
+  desc 'Run all unit specs'
+  Spec::Rake::SpecTask.new(:unit) do |t|
+    t.spec_opts << '--options' << 'spec/spec.opts' if File.exists?('spec/spec.opts')
+    t.libs << 'lib'
+    t.spec_files = FileList['spec/**/*_spec.rb'] - (FileList['spec/acceptance/*_spec.rb'] + FileList['spec/simple_sinatra_server_spec.rb'] )
+  end
+  
+  desc 'Run the specs for the server'
+  Spec::Rake::SpecTask.new('server') do |t|
+    t.spec_opts << '--options' << 'spec/spec.opts' if File.exists?('spec/spec.opts')
+    t.libs << 'lib'
+    t.spec_files = FileList['spec/simple_sinatra_server_spec.rb'] 
+  end
+end
+
+task :server do 
+  begin 
+    require 'spec/simple_sinatra_server'
+    desc "Run the sinatra echo server, with loggin" 
+    task :server do
+      Sinatra::Default.set(
+                           :run => true,
+                           :logging => true
+                           )
+    end
+  rescue LoadError => e
+    puts "Install 'sinatra' gem to run the server"
+  end
+end
+
+desc 'Default: Run Specs'
+task :default => :spec
+
+desc 'Run all tests'
+task :test => :spec
+
+begin
+  require 'yard'
+
+  desc "Generate Yardoc"
+  YARD::Rake::YardocTask.new do |t|
+    t.files = ['lib/**/*.rb', 'README.markdown']
+  end
+rescue LoadError => e
+  puts "Install 'yard' gem to generate docs"
+end
+
+desc "Update rubyforge documentation"
+task :update_docs => :yardoc do
+  puts %x{rsync -aPz doc/* psadauskas@resourceful.rubyforge.org:/var/www/gforge-projects/resourceful/}
+end

data/lib/resourceful.rb

@@ -0,0 +1,27 @@
+
+__DIR__ = File.dirname(__FILE__)
+
+$LOAD_PATH.unshift __DIR__ unless
+  $LOAD_PATH.include?(__DIR__) ||
+  $LOAD_PATH.include?(File.expand_path(__DIR__))
+
+require 'resourceful/util'
+
+require 'resourceful/header'
+require 'resourceful/http_accessor'
+require 'resourceful/simple'
+
+module Resourceful
+  autoload :MultipartFormData, 'resourceful/multipart_form_data'
+  autoload :UrlencodedFormData, 'resourceful/urlencoded_form_data'
+  autoload :StubbedResourceProxy, 'resourceful/stubbed_resource_proxy'
+  autoload :PromiscuousBasicAuthenticator, 'resourceful/promiscuous_basic_authenticator'
+
+  extend Simple
+end
+
+# Resourceful is a library that provides a high level HTTP interface.
+module Resourceful
+  VERSION = "1.2.0"
+  RESOURCEFUL_USER_AGENT_TOKEN = "openlogic-Resourceful/#{VERSION}(Ruby/#{RUBY_VERSION})"
+end

data/lib/resourceful/abstract_form_data.rb

@@ -0,0 +1,30 @@
+module Resourceful
+  class AbstractFormData
+    def initialize(contents = {})
+      @form_data = []
+      
+      contents.each do |k,v|
+        add(k, v)
+      end
+    end
+
+    # Add a name-value pair to this form data representation.
+    #
+    # @param [#to_s] name The name of the new name-value pair.
+    # @param [#to_s] value The value of the new name-value pair.
+    def add(name, value)
+      form_data << [name.to_s, value]
+    end
+
+    # Resets representation so that #read can be called again.
+    #
+    # ----
+    #
+    # Form data representations do not need to be rewound so this is a no-op.
+    def rewind
+    end
+
+    protected
+    attr_reader :form_data
+  end
+end

data/lib/resourceful/authentication_manager.rb

@@ -0,0 +1,107 @@
+#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)
+      @authenticators.each do |authenticator|
+        authenticator.add_credentials_to(request) if authenticator.can_handle?(request)
+      end
+    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
+
+    attr_reader :username, :password, :realm, :domain, :challenge
+
+    def initialize(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_header = challenge_response.header['WWW-Authenticate']
+      begin
+        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
+
+
+end
+