rest-man 1.0.0

data/lib/restman/exceptions.rb

@@ -0,0 +1,238 @@
+module RestMan
+
+  # Hash of HTTP status code => message.
+  #
+  # 1xx: Informational - Request received, continuing process
+  # 2xx: Success - The action was successfully received, understood, and
+  #      accepted
+  # 3xx: Redirection - Further action must be taken in order to complete the
+  #      request
+  # 4xx: Client Error - The request contains bad syntax or cannot be fulfilled
+  # 5xx: Server Error - The server failed to fulfill an apparently valid
+  #      request
+  #
+  # @see
+  #   http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
+  #
+  STATUSES = {100 => 'Continue',
+              101 => 'Switching Protocols',
+              102 => 'Processing', #WebDAV
+
+              200 => 'OK',
+              201 => 'Created',
+              202 => 'Accepted',
+              203 => 'Non-Authoritative Information', # http/1.1
+              204 => 'No Content',
+              205 => 'Reset Content',
+              206 => 'Partial Content',
+              207 => 'Multi-Status', #WebDAV
+              208 => 'Already Reported', # RFC5842
+              226 => 'IM Used', # RFC3229
+
+              300 => 'Multiple Choices',
+              301 => 'Moved Permanently',
+              302 => 'Found',
+              303 => 'See Other', # http/1.1
+              304 => 'Not Modified',
+              305 => 'Use Proxy', # http/1.1
+              306 => 'Switch Proxy', # no longer used
+              307 => 'Temporary Redirect', # http/1.1
+              308 => 'Permanent Redirect', # RFC7538
+
+              400 => 'Bad Request',
+              401 => 'Unauthorized',
+              402 => 'Payment Required',
+              403 => 'Forbidden',
+              404 => 'Not Found',
+              405 => 'Method Not Allowed',
+              406 => 'Not Acceptable',
+              407 => 'Proxy Authentication Required',
+              408 => 'Request Timeout',
+              409 => 'Conflict',
+              410 => 'Gone',
+              411 => 'Length Required',
+              412 => 'Precondition Failed',
+              413 => 'Payload Too Large', # RFC7231 (renamed, see below)
+              414 => 'URI Too Long', # RFC7231 (renamed, see below)
+              415 => 'Unsupported Media Type',
+              416 => 'Range Not Satisfiable', # RFC7233 (renamed, see below)
+              417 => 'Expectation Failed',
+              418 => 'I\'m A Teapot', #RFC2324
+              421 => 'Too Many Connections From This IP',
+              422 => 'Unprocessable Entity', #WebDAV
+              423 => 'Locked', #WebDAV
+              424 => 'Failed Dependency', #WebDAV
+              425 => 'Unordered Collection', #WebDAV
+              426 => 'Upgrade Required',
+              428 => 'Precondition Required', #RFC6585
+              429 => 'Too Many Requests', #RFC6585
+              431 => 'Request Header Fields Too Large', #RFC6585
+              449 => 'Retry With', #Microsoft
+              450 => 'Blocked By Windows Parental Controls', #Microsoft
+
+              500 => 'Internal Server Error',
+              501 => 'Not Implemented',
+              502 => 'Bad Gateway',
+              503 => 'Service Unavailable',
+              504 => 'Gateway Timeout',
+              505 => 'HTTP Version Not Supported',
+              506 => 'Variant Also Negotiates',
+              507 => 'Insufficient Storage', #WebDAV
+              508 => 'Loop Detected', # RFC5842
+              509 => 'Bandwidth Limit Exceeded', #Apache
+              510 => 'Not Extended',
+              511 => 'Network Authentication Required', # RFC6585
+  }
+
+  STATUSES_COMPATIBILITY = {
+    # The RFCs all specify "Not Found", but "Resource Not Found" was used in
+    # earlier RestMan releases.
+    404 => ['ResourceNotFound'],
+
+    # HTTP 413 was renamed to "Payload Too Large" in RFC7231.
+    413 => ['RequestEntityTooLarge'],
+
+    # HTTP 414 was renamed to "URI Too Long" in RFC7231.
+    414 => ['RequestURITooLong'],
+
+    # HTTP 416 was renamed to "Range Not Satisfiable" in RFC7233.
+    416 => ['RequestedRangeNotSatisfiable'],
+  }
+
+
+  # This is the base RestMan exception class. Rescue it if you want to
+  # catch any exception that your request might raise
+  # You can get the status code by e.http_code, or see anything about the
+  # response via e.response.
+  # For example, the entire result body (which is
+  # probably an HTML error page) is e.response.
+  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
+
+  # Compatibility
+  class ExceptionWithResponse < RestMan::Exception
+  end
+
+  # 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
+
+  # RestMan exception classes. TODO: move all exceptions into this module.
+  #
+  # We will a create an exception for each status code, see
+  # http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
+  #
+  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
+
+  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.
+
+    # Base class for request timeouts.
+    #
+    # NB: Previous releases of rest-man would raise RequestTimeout both for
+    # HTTP 408 responses and for actual connection timeouts.
+    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 (in
+    # ruby 2.0 or greater).
+    class OpenTimeout < Timeout
+      def default_message
+        'Timed out connecting to server'
+      end
+    end
+
+    # Timeout when reading from a server. Typically wraps Net::ReadTimeout (in
+    # ruby 2.0 or greater).
+    class ReadTimeout < Timeout
+      def default_message
+        'Timed out reading data from server'
+      end
+    end
+  end
+
+
+  # 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/params_array.rb

@@ -0,0 +1,72 @@
+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
+  #
+  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.
+    #
+    #
+    def initialize(array)
+      @array = process_input(array)
+    end
+
+    def each(*args, &blk)
+      @array.each(*args, &blk)
+    end
+
+    def empty?
+      @array.empty?
+    end
+
+    private
+
+    def process_input(array)
+      array.map {|v| process_pair(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.rb

@@ -0,0 +1,234 @@
+require 'tempfile'
+require 'securerandom'
+require 'stringio'
+
+begin
+  # Use mime/types/columnar if available, for reduced memory usage
+  require 'mime/types/columnar'
+rescue LoadError
+  require 'mime/types'
+end
+
+module RestMan
+  module Payload
+    extend self
+
+    def generate(params)
+      if params.is_a?(RestMan::Payload::Base)
+        # pass through Payload objects unchanged
+        params
+      elsif params.is_a?(String)
+        Base.new(params)
+      elsif params.is_a?(Hash)
+        if params.delete(:multipart) == true || has_file?(params)
+          Multipart.new(params)
+        else
+          UrlEncoded.new(params)
+        end
+      elsif params.is_a?(ParamsArray)
+        if _has_file?(params)
+          Multipart.new(params)
+        else
+          UrlEncoded.new(params)
+        end
+      elsif params.respond_to?(:read)
+        Streamed.new(params)
+      else
+        nil
+      end
+    end
+
+    def has_file?(params)
+      unless params.is_a?(Hash)
+        raise ArgumentError.new("Must pass Hash, not #{params.inspect}")
+      end
+      _has_file?(params)
+    end
+
+    def _has_file?(obj)
+      case obj
+      when Hash, ParamsArray
+        obj.any? {|_, v| _has_file?(v) }
+      when Array
+        obj.any? {|v| _has_file?(v) }
+      else
+        obj.respond_to?(:path) && obj.respond_to?(:read)
+      end
+    end
+
+    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
+
+    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
+
+    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
+
+    class Multipart < Base
+      EOL = "\r\n"
+
+      def build_stream(params)
+        b = '--' + boundary
+
+        @stream = Tempfile.new('rest-man.multipart.')
+        @stream.binmode
+        @stream.write(b + EOL)
+
+        case params
+        when Hash, ParamsArray
+          x = Utils.flatten_params(params)
+        else
+          x = params
+        end
+
+        last_index = x.length - 1
+        x.each_with_index do |a, index|
+          k, v = * a
+          if v.respond_to?(:read) && v.respond_to?(:path)
+            create_file_field(@stream, k, v)
+          else
+            create_regular_field(@stream, k, v)
+          end
+          @stream.write(EOL + b)
+          @stream.write(EOL) unless last_index == index
+        end
+        @stream.write('--')
+        @stream.write(EOL)
+        @stream.seek(0)
+      end
+
+      def create_regular_field(s, k, v)
+        s.write("Content-Disposition: form-data; name=\"#{k}\"")
+        s.write(EOL)
+        s.write(EOL)
+        s.write(v)
+      end
+
+      def create_file_field(s, k, v)
+        begin
+          s.write("Content-Disposition: form-data;")
+          s.write(" name=\"#{k}\";") unless (k.nil? || k=='')
+          s.write(" filename=\"#{v.respond_to?(:original_filename) ? v.original_filename : File.basename(v.path)}\"#{EOL}")
+          s.write("Content-Type: #{v.respond_to?(:content_type) ? v.content_type : mime_for(v.path)}#{EOL}")
+          s.write(EOL)
+          while (data = v.read(8124))
+            s.write(data)
+          end
+        ensure
+          v.close if v.respond_to?(:close)
+        end
+      end
+
+      def mime_for(path)
+        mime = MIME::Types.type_for path
+        mime.empty? ? 'text/plain' : mime[0].content_type
+      end
+
+      def boundary
+        return @boundary if defined?(@boundary) && @boundary
+
+        # 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.
+        s = SecureRandom.base64(12)
+        s.tr!('+/', 'AB')
+
+        @boundary = '----RubyFormBoundary' + s
+      end
+
+      # for Multipart do not escape the keys
+      #
+      # Ostensibly multipart keys MAY be percent encoded per RFC 7578, but in
+      # practice no major browser that I'm aware of uses percent encoding.
+      #
+      # Further discussion of multipart encoding:
+      # https://github.com/rest-man/rest-man/pull/403#issuecomment-156976930
+      #
+      def handle_key key
+        key
+      end
+
+      def headers
+        super.merge({'Content-Type' => %Q{multipart/form-data; boundary=#{boundary}}})
+      end
+
+      def close
+        @stream.close!
+      end
+    end
+  end
+end

data/lib/restman/platform.rb

@@ -0,0 +1,49 @@
+require 'rbconfig'
+
+module RestMan
+  module Platform
+    # Return true if we are running on a darwin-based Ruby platform. This will
+    # be false for jruby even on OS X.
+    #
+    # @return [Boolean]
+    def self.mac_mri?
+      RUBY_PLATFORM.include?('darwin')
+    end
+
+    # Return true if we are running on Windows.
+    #
+    # @return [Boolean]
+    #
+    def self.windows?
+      # Ruby only sets File::ALT_SEPARATOR on Windows, and the Ruby standard
+      # library uses that to test what platform it's on.
+      !!File::ALT_SEPARATOR
+    end
+
+    # Return true if we are running on jruby.
+    #
+    # @return [Boolean]
+    #
+    def self.jruby?
+      # defined on mri >= 1.9
+      RUBY_ENGINE == 'jruby'
+    end
+
+    def self.architecture
+      "#{RbConfig::CONFIG['host_os']} #{RbConfig::CONFIG['host_cpu']}"
+    end
+
+    def self.ruby_agent_version
+      case RUBY_ENGINE
+      when 'jruby'
+        "jruby/#{JRUBY_VERSION} (#{RUBY_VERSION}p#{RUBY_PATCHLEVEL})"
+      else
+        "#{RUBY_ENGINE}/#{RUBY_VERSION}p#{RUBY_PATCHLEVEL}"
+      end
+    end
+
+    def self.default_user_agent
+      "rest-man/#{VERSION} (#{architecture}) #{ruby_agent_version}"
+    end
+  end
+end

data/lib/restman/raw_response.rb

@@ -0,0 +1,49 @@
+module RestMan
+  # The response from RestMan on a raw request looks like a string, but is
+  # actually one of these.  99% of the time you're making a rest call all you
+  # care about is the body, but on the occasion you want to fetch the
+  # headers you can:
+  #
+  #   RestMan.get('http://example.com').headers[:content_type]
+  #
+  # In addition, if you do not use the response as a string, you can access
+  # a Tempfile object at res.file, which contains the path to the raw
+  # downloaded request body.
+  class RawResponse
+
+    include AbstractResponse
+
+    attr_reader :file, :request, :start_time, :end_time
+
+    def inspect
+      "<RestMan::RawResponse @code=#{code.inspect}, @file=#{file.inspect}, @request=#{request.inspect}>"
+    end
+
+    # @param [Tempfile] tempfile The temporary file containing the body
+    # @param [Net::HTTPResponse] net_http_res
+    # @param [RestMan::Request] request
+    # @param [Time] start_time
+    def initialize(tempfile, net_http_res, request, start_time=nil)
+      @file = tempfile
+
+      # reopen the tempfile so we can read it
+      @file.open
+
+      response_set_vars(net_http_res, request, start_time)
+    end
+
+    def to_s
+      body
+    end
+
+    def body
+      @file.rewind
+      @file.read
+    end
+
+    def size
+      file.size
+    end
+
+  end
+end