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.rb

@@ -10,9 +10,13 @@ require 'resourceful/util'
 require 'resourceful/header'
 require 'resourceful/http_accessor'
 
+module Resourceful
+  autoload :MultipartFormData, 'resourceful/multipart_form_data'
+  autoload :UrlencodedFormData, 'resourceful/urlencoded_form_data'
+end
+
 # Resourceful is a library that provides a high level HTTP interface.
 module Resourceful
-  VERSION = "0.5.4"
+  VERSION = "0.6.0"
   RESOURCEFUL_USER_AGENT_TOKEN = "Resourceful/#{VERSION}(Ruby/#{RUBY_VERSION})"
-
 end

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