rest-man 1.0.0 → 1.1.0

data/lib/restman/exception.rb

@@ -0,0 +1,43 @@
+module RestMan
+  # :include: _doc/lib/restman/exception.rdoc
+  class Exception < RuntimeError
+    attr_accessor :response
+    attr_accessor :original_exception
+    attr_writer :message
+
+    def initialize response = nil, initial_response_code = nil
+      @response = response
+      @message = nil
+      @initial_response_code = initial_response_code
+    end
+
+    def http_code
+      # return integer for compatibility
+      if @response
+        @response.code.to_i
+      else
+        @initial_response_code
+      end
+    end
+
+    def http_headers
+      @response.headers if @response
+    end
+
+    def http_body
+      @response.body if @response
+    end
+
+    def to_s
+      message
+    end
+
+    def message
+      @message || default_message
+    end
+
+    def default_message
+      self.class.name
+    end
+  end
+end

data/lib/restman/exceptions/exception_with_response.rb

@@ -0,0 +1,7 @@
+module RestMan
+
+  # Compatibility
+  class ExceptionWithResponse < RestMan::Exception
+  end
+
+end

data/lib/restman/exceptions/exceptions_map.rb

@@ -0,0 +1,26 @@
+module RestMan
+
+  # :include: _doc/lib/restman/exceptions.rdoc
+  module Exceptions
+    # Map http status codes to the corresponding exception class
+    EXCEPTIONS_MAP = {}
+  end
+
+  # Create HTTP status exception classes
+  STATUSES.each_pair do |code, message|
+    klass = Class.new(RequestFailed) do
+      send(:define_method, :default_message) {"#{http_code ? "#{http_code} " : ''}#{message}"}
+    end
+    klass_constant = const_set(message.delete(' \-\''), klass)
+    Exceptions::EXCEPTIONS_MAP[code] = klass_constant
+  end
+
+  # Create HTTP status exception classes used for backwards compatibility
+  STATUSES_COMPATIBILITY.each_pair do |code, compat_list|
+    klass = Exceptions::EXCEPTIONS_MAP.fetch(code)
+    compat_list.each do |old_name|
+      const_set(old_name, klass)
+    end
+  end
+
+end

data/lib/restman/exceptions/request_failed.rb

@@ -0,0 +1,15 @@
+module RestMan
+
+  # The request failed with an error code not managed by the code
+  class RequestFailed < ExceptionWithResponse
+
+    def default_message
+      "HTTP status code #{http_code}"
+    end
+
+    def to_s
+      message
+    end
+  end
+
+end

data/lib/restman/exceptions/server_broke_connection.rb

@@ -0,0 +1,13 @@
+module RestMan
+
+  # The server broke the connection prior to the request completing.  Usually
+  # this means it crashed, or sometimes that your network connection was
+  # severed before it could complete.
+  class ServerBrokeConnection < RestMan::Exception
+    def initialize(message = 'Server broke connection')
+      super nil, nil
+      self.message = message
+    end
+  end
+
+end

data/lib/restman/exceptions/timeout.rb

@@ -0,0 +1,37 @@
+module RestMan
+  module Exceptions
+    # We have to split the Exceptions module like we do here because the
+    # EXCEPTIONS_MAP is under Exceptions, but we depend on
+    # RestMan::RequestTimeout below.
+
+    # :include: _doc/lib/restman/exceptions/timeout.rdoc
+    class Timeout < RestMan::RequestTimeout
+      def initialize(message=nil, original_exception=nil)
+        super(nil, nil)
+        self.message = message if message
+        self.original_exception = original_exception if original_exception
+      end
+    end
+
+    # Timeout when connecting to a server. Typically wraps Net::OpenTimeout
+    class OpenTimeout < Timeout
+      def default_message
+        'Timed out connecting to server'
+      end
+    end
+
+    # Timeout when reading from a server. Typically wraps Net::ReadTimeout
+    class ReadTimeout < Timeout
+      def default_message
+        'Timed out reading data from server'
+      end
+    end
+
+    # Timeout when writing to a server. Typically wraps Net::WriteTimeout
+    class WriteTimeout < Timeout
+      def default_message
+        'Timed out writing data to server'
+      end
+    end
+  end
+end

data/lib/restman/params_array/process_pair.rb

@@ -0,0 +1,39 @@
+module RestMan
+  class ParamsArray
+
+    # :include: _doc/lib/restman/params_array/process_pair.rdoc
+    class ProcessPair < ActiveMethod::Base
+
+      argument :pair
+
+      def call
+        case pair
+        when Hash
+          convert_hash_pair_to_array
+        when Array
+          parse_array_pair
+        else
+          ProcessPair.call(pair.to_a)
+        end
+      end
+
+      private
+
+      def convert_hash_pair_to_array
+        if pair.length != 1
+          raise ArgumentError.new("Bad # of fields for pair: #{pair.inspect}")
+        end
+
+        pair.to_a.fetch(0)
+      end
+
+      def parse_array_pair
+        if pair.length > 2
+          raise ArgumentError.new("Bad # of fields for pair: #{pair.inspect}")
+        end
+        [pair.fetch(0), pair[1]]
+      end
+
+    end
+  end
+end

data/lib/restman/params_array.rb

@@ -1,33 +1,10 @@
 module RestMan
 
-  # The ParamsArray class is used to represent an ordered list of [key, value]
-  # pairs. Use this when you need to include a key multiple times or want
-  # explicit control over parameter ordering.
-  #
-  # Most of the request payload & parameter functions normally accept a Hash of
-  # keys => values, which does not allow for duplicated keys.
-  #
-  # @see RestMan::Utils.encode_query_string
-  # @see RestMan::Utils.flatten_params
-  #
+  # :include: _doc/lib/restman/params_array.rdoc
   class ParamsArray
     include Enumerable
 
-    # @param array [Array<Array>] An array of parameter key,value pairs. These
-    #   pairs may be 2 element arrays [key, value] or single element hashes
-    #   {key => value}. They may also be single element arrays to represent a
-    #   key with no value.
-    #
-    # @example
-    #   >> ParamsArray.new([[:foo, 123], [:foo, 456], [:bar, 789]])
-    #   This will be encoded as "foo=123&foo=456&bar=789"
-    #
-    # @example
-    #   >> ParamsArray.new({foo: 123, bar: 456})
-    #   This is valid, but there's no reason not to just use the Hash directly
-    #   instead of a ParamsArray.
-    #
-    #
+    # :include: _doc/lib/restman/params_array/new.rdoc
     def initialize(array)
       @array = process_input(array)
     end
@@ -43,30 +20,8 @@ module RestMan
     private
 
     def process_input(array)
-      array.map {|v| process_pair(v) }
+      array.map {|v| ProcessPair.call(v) }
     end
 
-    # A pair may be:
-    # - A single element hash, e.g. {foo: 'bar'}
-    # - A two element array, e.g. ['foo', 'bar']
-    # - A one element array, e.g. ['foo']
-    #
-    def process_pair(pair)
-      case pair
-      when Hash
-        if pair.length != 1
-          raise ArgumentError.new("Bad # of fields for pair: #{pair.inspect}")
-        end
-        pair.to_a.fetch(0)
-      when Array
-        if pair.length > 2
-          raise ArgumentError.new("Bad # of fields for pair: #{pair.inspect}")
-        end
-        [pair.fetch(0), pair[1]]
-      else
-        # recurse, converting any non-array to an array
-        process_pair(pair.to_a)
-      end
-    end
   end
 end

data/lib/restman/payload/base.rb

@@ -0,0 +1,57 @@
+require 'stringio'
+
+module RestMan
+  module Payload
+    class Base
+      def initialize(params)
+        build_stream(params)
+      end
+
+      def build_stream(params)
+        @stream = StringIO.new(params)
+        @stream.seek(0)
+      end
+
+      def read(*args)
+        @stream.read(*args)
+      end
+
+      def to_s
+        result = read
+        @stream.seek(0)
+        result
+      end
+
+      def headers
+        {'Content-Length' => size.to_s}
+      end
+
+      def size
+        @stream.size
+      end
+
+      alias :length :size
+
+      def close
+        @stream.close unless @stream.closed?
+      end
+
+      def closed?
+        @stream.closed?
+      end
+
+      def to_s_inspect
+        to_s.inspect
+      end
+
+      def short_inspect
+        if size && size > 500
+          "#{size} byte(s) length"
+        else
+          to_s_inspect
+        end
+      end
+
+    end
+  end
+end

data/lib/restman/payload/multipart/write_content_disposition.rb

@@ -0,0 +1,88 @@
+module RestMan
+  module Payload
+    class Multipart
+      class WriteContentDisposition < ActiveMethod::Base
+
+        argument :stream
+        argument :name
+        argument :value
+        argument :boundary
+
+        def call
+          if file?
+            write_header_for_file_field
+          else
+            write_header_for_regular_field
+          end
+        end
+
+        private
+
+        def file?
+          value.respond_to?(:read) && value.respond_to?(:path)
+        end
+
+        def write_header_for_regular_field
+          write "--#{boundary}\r\n"
+          write "Content-Disposition: form-data;#{name_directive}\r\n"
+          write "\r\n"
+          write "#{value}\r\n"
+        end
+
+        def write_header_for_file_field
+          write "--#{boundary}\r\n"
+          write "Content-Disposition: form-data;#{name_directive(";")}#{filename_directive}\r\n"
+          write "Content-Type: #{content_type}\r\n"
+          write "\r\n"
+          while data = file.read(8124)
+            write data
+          end
+          write "\r\n"
+        ensure
+          file.close if file.respond_to?(:close)
+        end
+
+        def name_directive(separator = nil)
+          return if name.nil?
+          return if name == ''
+
+          %Q( name="#{name}"#{separator})
+        end
+
+        def filename_directive
+          if file.respond_to?(:original_filename)
+            %Q( filename="#{file.original_filename}")
+          else
+            %Q( filename="#{File.basename(file.path)}")
+          end
+        end
+
+        def content_type
+          if file.respond_to?(:content_type)
+            file.content_type
+          else
+            mime_for file.path
+          end
+        end
+
+        def mime_for(path)
+          mime = MIME::Types.type_for path
+          if mime.empty?
+            'text/plain'
+          else
+            mime[0].content_type
+          end
+        end
+
+        def write(str)
+          stream.write str
+        end
+
+        def file
+          value
+        end
+
+      end
+    end
+  end
+end

data/lib/restman/payload/multipart.rb

@@ -0,0 +1,56 @@
+require 'tempfile'
+require 'securerandom'
+
+module RestMan
+  module Payload
+    class Multipart < Base
+      autoload :WriteContentDisposition, "#{File.dirname(__FILE__)}/multipart/write_content_disposition"
+
+      include ActiveMethod
+
+      active_method :write_content_disposition
+
+      def headers
+        super.merge({'Content-Type' => %Q{multipart/form-data; boundary=#{boundary}}})
+      end
+
+      def build_stream(params)
+        @stream = Tempfile.new('rest-man.multipart.')
+        @stream.binmode
+        flatten(params).each do |name, value|
+          write_content_disposition(@stream, name, value, boundary)
+        end
+        @stream.write "--#{boundary}--\r\n"
+        @stream.seek(0)
+      end
+
+      def flatten(params)
+        case params
+        when Hash, ParamsArray
+          Utils.flatten_params(params)
+        else
+          params
+        end
+      end
+
+      def close
+        @stream.close!
+      end
+
+      def boundary
+        @boundary ||= generate_boundary
+      end
+
+      private
+
+      # Use the same algorithm used by WebKit: generate 16 random
+      # alphanumeric characters, replacing `+` `/` with `A` `B` (included in
+      # the list twice) to round out the set of 64.
+      def generate_boundary
+        s = SecureRandom.base64(12).tr('+/', 'AB')
+
+        '----RubyFormBoundary' + s
+      end
+    end
+  end
+end

data/lib/restman/payload/streamed.rb

@@ -0,0 +1,22 @@
+module RestMan
+  module Payload
+    class Streamed < Base
+      def build_stream(params = nil)
+        @stream = params
+      end
+
+      def size
+        if @stream.respond_to?(:size)
+          @stream.size
+        elsif @stream.is_a?(IO)
+          @stream.stat.size
+        end
+      end
+
+      # TODO (breaks compatibility): ought to use mime_for() to autodetect the
+      # Content-Type for stream objects that have a filename.
+
+      alias :length :size
+    end
+  end
+end

data/lib/restman/payload/url_encoded.rb

@@ -0,0 +1,14 @@
+module RestMan
+  module Payload
+    class UrlEncoded < Base
+      def build_stream(params = nil)
+        @stream = StringIO.new(Utils.encode_query_string(params))
+        @stream.seek(0)
+      end
+
+      def headers
+        super.merge({'Content-Type' => 'application/x-www-form-urlencoded'})
+      end
+    end
+  end
+end