paul-resourceful 0.5.4 → 0.6.0

data/History.txt

@@ -0,0 +1,18 @@
+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/Manifest

@@ -1,17 +1,22 @@
 lib/resourceful.rb
 lib/resourceful/net_http_adapter.rb
+lib/resourceful/options_interpretation.rb
 lib/resourceful/stubbed_resource_proxy.rb
+lib/resourceful/urlencoded_form_data.rb
 lib/resourceful/header.rb
 lib/resourceful/memcache_cache_manager.rb
 lib/resourceful/response.rb
 lib/resourceful/util.rb
-lib/resourceful/options_interpreter.rb
+lib/resourceful/abstract_form_data.rb
 lib/resourceful/cache_manager.rb
 lib/resourceful/request.rb
 lib/resourceful/resource.rb
 lib/resourceful/exceptions.rb
+lib/resourceful/multipart_form_data.rb
 lib/resourceful/http_accessor.rb
 lib/resourceful/authentication_manager.rb
+History.txt
+resourceful.gemspec
 README.markdown
 MIT-LICENSE
 Rakefile
@@ -26,4 +31,9 @@ spec/acceptance/header_spec.rb
 spec/acceptance/resource_spec.rb
 spec/acceptance/caching_spec.rb
 spec/acceptance/redirecting_spec.rb
+spec/resourceful/multipart_form_data_spec.rb
+spec/resourceful/header_spec.rb
+spec/resourceful/resource_spec.rb
+spec/resourceful/urlencoded_form_data_spec.rb
+spec/caching_spec.rb
 spec/spec.opts

data/README.markdown

@@ -58,8 +58,17 @@ 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')
+     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
 -------------------

data/Rakefile

@@ -12,8 +12,9 @@ begin
     p.email           = "psadauskas@gmail.com"
 
     p.ignore_pattern  = ["pkg/*", "tmp/*"]
-    p.dependencies    = ['addressable', 'httpauth']
+    p.dependencies    = [['addressable', '>= 2.1.0'], 'httpauth']
     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"
@@ -21,31 +22,50 @@ end
 
 require 'spec/rake/spectask'
 
-desc 'Run all specs'
+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/acceptance/*_spec.rb'] 
+  t.spec_files = FileList['spec/**/*_spec.rb'] 
 end
 
-desc 'Run the specs for the server'
-Spec::Rake::SpecTask.new('spec: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'] 
+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
 
-begin 
-  require 'spec/simple_sinatra_server'
-  desc "Run the sinatra echo server, with loggin" 
-  task :server do
-    Sinatra::Default.set(
-      :run => true,
-      :logging => true
-    )
+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
-rescue LoadError => e
-  puts "Install 'sinatra' gem to run the server"
 end
 
 desc 'Default: Run Specs'

data/lib/resourceful/abstract_form_data.rb

@@ -0,0 +1,18 @@
+module Resourceful
+  class AbstractFormData
+    def initialize(contents = {})
+      @form_data = []
+      
+      contents.each do |k,v|
+        add(k, v)
+      end
+    end
+
+    def add(name, value)
+      form_data << [name.to_s, value]
+    end
+
+    protected
+    attr_reader :form_data
+  end
+end

data/lib/resourceful/header.rb

@@ -1,125 +1,256 @@
-# A case-normalizing Hash, adjusting on [] and []=.
-# Shamelessly swiped from Rack
+require 'resourceful/options_interpretation'
+require 'set'
+
+# Represents the header fields of an HTTP message.  To access a field
+# you can use `#[]` and `#[]=`.  For example, to get the content type
+# of a response you can do
+# 
+#     response.header['Content-Type']  # => "application/xml"
+#
+# Lookups and modifications done in this way are case insensitive, so
+# 'Content-Type', 'content-type' and :content_type are all equivalent.
+#
+# Multi-valued fields
+# -------------------
+#
+# Multi-value fields (e.g. Accept) are always returned as an Array
+# regardless of the number of values, if the field is present.
+# Single-value fields (e.g. Content-Type) are always returned as
+# strings. The multi/single valueness of a header field is determined
+# by the way it is defined in the HTTP spec.  Unknown fields are
+# treated as multi-valued.
+#
+# (This behavior is new in 0.6 and may be slightly incompatible with
+# the way previous versions worked in some situations.)
+#
+# For example
+#
+#     h = Resourceful::Header.new
+#     h['Accept'] = "application/xml"
+#     h['Accept']                      # => ["application/xml"]
+#
 module Resourceful
-  class Header < Hash
+  class Header
+    include Enumerable
+    
     def initialize(hash={})
+      @raw_fields = {}
       hash.each { |k, v| self[k] = v }
     end
 
     def to_hash
-      {}.replace(self)
+      @raw_fields.dup
     end
 
     def [](k)
-      super capitalize(k)
+      field_def(k).get_from(@raw_fields)
     end
 
     def []=(k, v)
-      super capitalize(k), v
+      field_def(k).set_to(v, @raw_fields)
     end
 
     def has_key?(k)
-      super capitalize(k)
+      field_def(k).exists_in?(@raw_fields)
+    end
+
+    def each(&blk)
+      @raw_fields.each(&blk)
+    end
+    alias each_field each
+
+    def merge!(another)
+      another.each do |k,v|
+        self[k] = v
+      end
+      self
     end
 
-    def capitalize(k)
-      k.to_s.downcase.gsub(/^.|[-_\s]./) { |x| x.upcase }.gsub('_', '-')
+    def merge(another)
+      self.class.new(self).merge!(another)
     end
 
-    def each_field(&blk)
-      to_hash.each { |k,v|
-        blk.call capitalize(k), v
-      }
+    def reverse_merge(another)
+      self.class.new(another).merge!(self)
     end
 
-    HEADERS = %w[
-      Accept
-      Accept-Charset
-      Accept-Encoding
-      Accept-Language
-      Accept-Ranges
-      Age
-      Allow
-      Authorization
-      Cache-Control
-      Connection
-      Content-Encoding
-      Content-Language
-      Content-Length
-      Content-Location
-      Content-MD5
-      Content-Range
-      Content-Type
-      Date
-      ETag
-      Expect
-      Expires
-      From
-      Host
-      If-Match
-      If-Modified-Since
-      If-None-Match
-      If-Range
-      If-Unmodified-Since
-      Keep-Alive
-      Last-Modified
-      Location
-      Max-Forwards
-      Pragma
-      Proxy-Authenticate
-      Proxy-Authorization
-      Range
-      Referer
-      Retry-After
-      Server
-      TE
-      Trailer
-      Transfer-Encoding
-      Upgrade
-      User-Agent
-      Vary
-      Via
-      Warning
-      WWW-Authenticate
-    ]
-
-    HEADERS.each do |header|
-      const = header.upcase.gsub('-', '_')
-      meth  = header.downcase.gsub('-', '_')
-
-      class_eval <<-RUBY, __FILE__, __LINE__
-        #{const} = "#{header}".freeze    # ACCEPT = "accept".freeze
-
-        def #{meth}                      # def accept
-          self[#{const}]                 #   self[ACCEPT]
-        end                              # end
-
-        def #{meth}=(str)                # def accept=(str)
-          self[#{const}] = str           #   self[ACCEPT] = str
-        end                              # end
-      RUBY
+    def dup
+      self.class.new(@raw_fields.dup)
+    end
+
+
+    # Class to handle the details of each type of field.
+    class HeaderFieldDef
+      include Comparable
+      include OptionsInterpretation
+
+      ##
+      attr_reader :name
+
+      def initialize(name, options = {})
+        @name = name
+        extract_opts(options) do |opts|
+          @repeatable = opts.extract(:repeatable, :default => false)
+          @hop_by_hop = opts.extract(:hop_by_hop, :default => false)
+          @modifiable = opts.extract(:modifiable, :default => true)
+        end
+      end
+
+      def repeatable?
+        @repeatable
+      end
+
+      def hop_by_hop?
+        @hop_by_hop
+      end
+
+      def modifiable?
+        @modifiable
+      end
+
+      def get_from(raw_fields_hash)
+        raw_fields_hash[name]
+      end
+
+      def set_to(value, raw_fields_hash)
+        raw_fields_hash[name] = if repeatable?
+                                  Array(value)
+                                elsif value.kind_of?(Array)
+                                  raise ArgumentError, "#{name} field may only have one value" if value.size > 1
+                                  value.first
+                                else
+                                  value
+                                end
+      end
+
+      def exists_in?(raw_fields_hash)
+        raw_fields_hash.has_key?(name)
+      end
+
+      def <=>(another)
+        name <=> another.name
+      end
 
+      def ==(another)
+        name_pattern === another.name
+      end
+      alias eql? ==
+
+      def ===(another)
+        if another.kind_of?(HeaderFieldDef)
+          self == another
+        else
+          name_pattern === another
+        end
+      end
+
+      def name_pattern
+        Regexp.new('^' + name.gsub('-', '[_-]') + '$', Regexp::IGNORECASE)
+      end
+
+      def methodized_name
+        name.downcase.gsub('-', '_')
+      end
+
+      alias to_s name
+
+      def gen_setter(klass)
+        klass.class_eval <<-RUBY
+          def #{methodized_name}=(val)  # def accept=(val)
+            self['#{name}'] = val       #   self['Accept'] = val
+          end                           # end
+        RUBY
+      end
+
+      def gen_getter(klass)
+        klass.class_eval <<-RUBY
+          def #{methodized_name}  # def accept
+            self['#{name}']       #   self['Accept']
+          end                     # end
+        RUBY
+      end
+
+      def gen_canonical_name_const(klass)
+        const_name = name.upcase.gsub('-', '_')
+        
+        klass.const_set(const_name, name)
+      end
+    end
+ 
+    @@header_field_defs = Set.new
+
+    def self.header_field(name, options = {})
+      hfd = HeaderFieldDef.new(name, options)
+
+      @@header_field_defs << hfd
+
+      hfd.gen_getter(self)
+      hfd.gen_setter(self)
+      hfd.gen_canonical_name_const(self)
+    end
+
+    def self.hop_by_hop_headers
+      @@header_field_defs.select{|hfd| hfd.hop_by_hop?}
+    end
+
+    def self.non_modifiable_headers
+      @@header_field_defs.reject{|hfd| hfd.repeatable?}
+    end
+    
+    def field_def(name)
+      @@header_field_defs.find{|hfd| hfd === name} || 
+        HeaderFieldDef.new(name.to_s.downcase.gsub(/^.|[-_\s]./) { |x| x.upcase }.gsub('_', '-'), :repeatable => true)
     end
 
-    HOP_BY_HOP_HEADERS = [
-      CONNECTION,
-      KEEP_ALIVE,
-      PROXY_AUTHENTICATE,
-      PROXY_AUTHORIZATION,
-      TE,
-      TRAILER,
-      TRANSFER_ENCODING,
-      UPGRADE
-    ].freeze
-
-    NON_MODIFIABLE_HEADERS = [
-      CONTENT_LOCATION,
-      CONTENT_MD5,
-      ETAG,
-      LAST_MODIFIED,
-      EXPIRES
-    ].freeze
 
+    header_field('Accept', :repeatable => true)
+    header_field('Accept-Charset', :repeatable => true)
+    header_field('Accept-Encoding', :repeatable => true)
+    header_field('Accept-Language', :repeatable => true)
+    header_field('Accept-Ranges', :repeatable => true)
+    header_field('Age')
+    header_field('Allow', :repeatable => true)
+    header_field('Authorization', :repeatable => true)
+    header_field('Cache-Control', :repeatable => true)
+    header_field('Connection', :hop_by_hop => true)
+    header_field('Content-Encoding', :repeatable => true)
+    header_field('Content-Language', :repeatable => true)
+    header_field('Content-Length')
+    header_field('Content-Location', :modifiable => false)
+    header_field('Content-MD5', :modifiable => false)
+    header_field('Content-Range')
+    header_field('Content-Type')
+    header_field('Date')
+    header_field('ETag', :modifiable => false)
+    header_field('Expect', :repeatable => true)
+    header_field('Expires', :modifiable => false)
+    header_field('From')
+    header_field('Host')
+    header_field('If-Match', :repeatable => true)
+    header_field('If-Modified-Since')
+    header_field('If-None-Match', :repeatable => true)
+    header_field('If-Range')
+    header_field('If-Unmodified-Since')
+    header_field('Keep-Alive', :hop_by_hop => true)
+    header_field('Last-Modified', :modifiable => false)
+    header_field('Location')
+    header_field('Max-Forwards')
+    header_field('Pragma', :repeatable => true)
+    header_field('Proxy-Authenticate', :hop_by_hop => true)
+    header_field('Proxy-Authorization', :hop_by_hop => true)
+    header_field('Range')
+    header_field('Referer')
+    header_field('Retry-After')
+    header_field('Server')
+    header_field('TE', :repeatable => true, :hop_by_hop => true)
+    header_field('Trailer', :repeatable => true, :hop_by_hop => true)
+    header_field('Transfer-Encoding', :repeatable => true, :hop_by_hop => true)
+    header_field('Upgrade', :repeatable => true, :hop_by_hop => true)
+    header_field('User-Agent')
+    header_field('Vary', :repeatable => true)
+    header_field('Via', :repeatable => true)
+    header_field('Warning', :repeatable => true)
+    header_field('WWW-Authenticate', :repeatable => true)
   end
 end
 

data/lib/resourceful/http_accessor.rb

@@ -1,6 +1,6 @@
 require 'net/http'
 
-require 'resourceful/options_interpreter'
+require 'resourceful/options_interpretation'
 require 'resourceful/authentication_manager'
 require 'resourceful/cache_manager'
 require 'resourceful/resource'
@@ -28,7 +28,8 @@ module Resourceful
   # provided by the Resourceful library.  Conceptually this object
   # acts a collection of all the resources available via HTTP.
   class HttpAccessor
-    
+    include OptionsInterpretation
+
     # A logger object to which messages about the activities of this
     # object will be written.  This should be an object that responds
     # to +#info(message)+ and +#debug(message)+.  
@@ -40,40 +41,45 @@ module Resourceful
     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
+    ##
+    # The adapter this accessor will use to make the actual HTTP requests.
+    attr_reader :http_adapter
     
     # Initializes a new HttpAccessor.  Valid options:
     #
-    #  +:logger+:: A Logger object that the new HTTP accessor should
-    #    send log messages
+    #  `:logger`
+    #  :    A Logger object that the new HTTP accessor should send log messages
+    #
+    #  `:user_agent`
+    #  :    One or more additional user agent tokens to added to the user agent string.
     #
-    #  +: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.
     #
-    #  +:cache_manager+:: The cache manager this accessor should use.
+    #  `:authenticator`
+    #  :    Add a single authenticator for this accessor.
     #
-    #  +:authenticator+:: Add a single authenticator for this accessor.
+    #  `:authenticators`
+    #  :    Enumerable of the authenticators for this accessor.
     #
-    #  +:authenticators+:: Enumerable of the authenticators for this
-    #    accessor.
+    #  `http_adapter`
+    #  :    The HttpAdapter to be used by this accessor
+    #
+    # 
     def initialize(options = {})
       @user_agent_tokens = [RESOURCEFUL_USER_AGENT_TOKEN]
-      
-      INIT_OPTIONS.interpret(options) do |opts|
-        @user_agent_tokens.push(*opts[:user_agent].reverse)
-        self.logger = opts[:logger]
-        @auth_manager = AuthenticationManager.new()
-        @cache_manager = opts[:cache_manager]
+      @auth_manager = AuthenticationManager.new()
+
+      extract_opts(options) do |opts|
+        @user_agent_tokens.push(*opts.extract(:user_agent, :default => []) {|ua| [ua].flatten})
+        
+        self.logger    = opts.extract(:logger, :default => BitBucketLogger.new)
+        @cache_manager = opts.extract(:cache_manager, :default => NullCacheManager.new)
+        @http_adapter  = opts.extract(:http_adapter, :default => lambda{NetHttpAdapter.new})
         
-        add_authenticator(opts[:authenticator]) if opts[:authenticator]
-        opts[:authenticators].each { |a| add_authenticator(a) }
-      end     
+        opts.extract(:authenticator, :required => false).tap{|a| add_authenticator(a) if a}
+        opts.extract(:authenticators, :default => []).each { |a| add_authenticator(a) }
+      end
     end
     
     # Returns the string that identifies this HTTP accessor.  If you

data/lib/resourceful/multipart_form_data.rb

@@ -0,0 +1,46 @@
+require 'resourceful/abstract_form_data'
+
+module Resourceful
+  class MultipartFormData < AbstractFormData
+    FileParamValue = Struct.new(:content, :file_name, :content_type)
+
+    def add_file(name, file_name, content_type="application/octet-stream")
+      add(name, FileParamValue.new(File.new(file_name, 'r'), File.basename(file_name), content_type))
+    end
+
+    def content_type
+      "multipart/form-data; boundary=#{boundary}"
+    end
+
+    def read
+      StringIO.new.tap do |out|
+        first = true
+        form_data.each do |key, val|
+          out << "\r\n" unless first
+          out << "--" << boundary
+          out << "\r\nContent-Disposition: form-data; name=\"#{key}\""
+          if val.kind_of?(FileParamValue)
+            out << "; filename=\"#{val.file_name}\""
+            out << "\r\nContent-Type: #{val.content_type}"
+          end
+          out << "\r\n\r\n"
+          if val.kind_of?(FileParamValue)
+            out << val.content.read
+          else
+            out << val.to_s
+          end
+          first = false
+        end
+        out << "\r\n--#{boundary}--"
+      end.string
+    end
+
+    protected
+
+    def boundary
+      @boundary ||= (0..30).map{BOUNDARY_CHARS[rand(BOUNDARY_CHARS.length)]}.join
+    end
+
+    BOUNDARY_CHARS = [('a'..'z').to_a,('A'..'Z').to_a,(0..9).to_a].flatten
+  end
+end