rest-man 1.0.0 → 1.1.0

data/_doc/lib/restman/request/init/cookie_jar.rdoc

@@ -0,0 +1,55 @@
+:call-seq:
+  cookie_jar(uri, headers, args) -> HTTP::CookieJar
+
+Process cookies passed as hash or as HTTP::CookieJar. For backwards
+compatibility, these may be passed as a :cookies option masquerading
+inside the headers hash. To avoid confusion, if :cookies is passed in
+both headers and Request#initialize, raise an error.
+
+[cookies may be a:]
+
+  - Hash{String/Symbol => String}
+  - Array<HTTP::Cookie>
+  - HTTP::CookieJar
+
+Passing as a hash:
+  Keys may be symbols or strings. Values must be strings.
+  Infer the domain name from the request URI and allow subdomains (as
+  though '.example.com' had been set in a Set-Cookie header). Assume a
+  path of '/'.
+
+    RestMan::Request.new(url: 'http://example.com', method: :get,
+      :cookies => {:foo => 'Value', 'bar' => '123'}
+    )
+
+results in cookies as though set from the server by:
+    Set-Cookie: foo=Value; Domain=.example.com; Path=/
+    Set-Cookie: bar=123; Domain=.example.com; Path=/
+
+which yields a client cookie header of:
+    Cookie: foo=Value; bar=123
+
+Passing as HTTP::CookieJar, which will be passed through directly:
+
+    jar = HTTP::CookieJar.new
+    jar.add(HTTP::Cookie.new('foo', 'Value', domain: 'example.com',
+                            path: '/', for_domain: false))
+
+    RestMan::Request.new(..., :cookies => jar)
+
+[Parameters:]
+
+  - *uri* (URI::HTTP) -- The URI for the request. This will be used to
+    infer the domain name for cookies passed as strings in a hash. To avoid
+    this implicit behavior, pass a full cookie jar or use HTTP::Cookie hash
+    values.
+  - *headers* (Hash) -- The headers hash from which to pull the :cookies
+    option. MUTATION NOTE: This key will be deleted from the hash if
+    present.
+  - *args* (Hash) -- The options passed to Request#initialize. This hash
+    will be used as another potential source for the :cookies key.
+    These args will not be mutated.
+
+[Returns:]
+
+  - (HTTP::CookieJar) -- A cookie jar containing the parsed cookies.

data/_doc/lib/restman/request/init/http_method.rdoc

@@ -0,0 +1,15 @@
+:call-seq:
+  http_method(args) -> string
+
+Parse `args[:method]` and return a normalized string version.
+
+Raise ArgumentError if the `args[:method]` is falsy, but otherwise do no
+validation.
+
+[Parameters:]
+
+  - *args* (Hash)
+
+[See Also:]
+
+  - net_http_request_class

data/_doc/lib/restman/request/make_cookie_header.rdoc

@@ -0,0 +1,8 @@
+:call-seq:
+  make_cookie_header -> string or nil
+ 
+Render a Cookie HTTP request header from the contents of the @cookie_jar,
+or nil if the jar is empty.
+
+[See Also]
+  - Request#cookie_jar

data/_doc/lib/restman/request/make_headers.rdoc

@@ -0,0 +1,25 @@
+:call-seq:
+  make_headers(user_headers) -> Hash<String, String>
+ 
+Generate headers for use by a request. Header keys will be stringified
+using `#stringify_headers` to normalize them as capitalized strings.
+
+The final headers consist of:
+  - default headers from #default_headers
+  - user_headers provided here
+  - headers from the payload object (e.g. Content-Type, Content-Lenth)
+  - cookie headers from #make_cookie_header
+
+BUG: stringify_headers does not alter the capitalization of headers that
+are passed as strings, it only normalizes those passed as symbols. This
+behavior will probably remain for a while for compatibility, but it means
+that the warnings that attempt to detect accidental header overrides may
+not always work.
+https://github.com/rest-man/rest-man/issues/599
+
+[Parameters:]
+
+  - user_headers (Hash) -- User-provided headers to include
+
+[Returns]
+  - (Hash<String, String>) -- A hash of HTTP headers => values

data/_doc/lib/restman/request/maybe_convert_extension.rdoc

@@ -0,0 +1,18 @@
+:call-seq:
+  maybe_convert_extension(ext) -> string
+
+Given a MIME type or file extension, return either a MIME type or, if
+none is found, the input unchanged.
+
+    >> maybe_convert_extension('json')
+    => 'application/json'
+
+    >> maybe_convert_extension('unknown')
+    => 'unknown'
+
+    >> maybe_convert_extension('application/xml')
+    => 'application/xml'
+
+[Parameters:]
+
+  - ext (String)

data/_doc/lib/restman/request/process_result.rdoc

@@ -0,0 +1,4 @@
+[Parameters:]
+
+  - *res*  -- The Net::HTTP response object
+  - *start_time* (Time) -- Time of request start

data/_doc/lib/restman/request/proxy_uri.rdoc

@@ -0,0 +1,7 @@
+:call-seq:
+  proxy_uri -> URI or boolean or nil
+ 
+The proxy URI for this request. If `:proxy` was provided on this request,
+use it over `RestMan.proxy`.
+
+Return false if a proxy was explicitly set and is falsy.

data/_doc/lib/restman/request/stringify_headers.rdoc

@@ -0,0 +1,9 @@
+:call-seq:
+  stringify_headers(headers) -> Object
+
+Return a hash of headers whose keys are capitalized strings
+
+BUG: stringify_headers does not fix the capitalization of headers that
+are already Strings. Leaving this behavior as is for now for
+backwards compatibility.
+https://github.com/rest-man/rest-man/issues/599

data/_doc/lib/restman/request/use_ssl.rdoc

@@ -0,0 +1,4 @@
+:call-seq:
+  use_ssl? -> boolean
+
+Return true if the request URI will use HTTPS.

data/_doc/lib/restman/request.rdoc

@@ -0,0 +1,46 @@
+This class is used internally by RestMan to send the request, but you can also
+call it directly if you'd like to use a method not supported by the
+main API.  For example:
+
+  RestMan::Request.execute(:method => :head, :url => 'http://example.com')
+
+Mandatory parameters:
+* :method
+* :url
+Optional parameters (have a look at ssl and/or uri for some explanations):
+* :headers a hash containing the request headers
+* :cookies may be a Hash{String/Symbol => String} of cookie values, an
+    Array<HTTP::Cookie>, or an HTTP::CookieJar containing cookies. These
+    will be added to a cookie jar before the request is sent.
+* :user and :password for basic auth, will be replaced by a user/password available in the :url
+* :block_response call the provided block with the HTTPResponse as parameter
+* :raw_response return a low-level RawResponse instead of a Response
+* :log Set the log for this request only, overriding RestMan.log, if
+    any.
+* :stream_log_percent (Only relevant with :raw_response => true) Customize
+    the interval at which download progress is logged. Defaults to every
+    10% complete.
+* :max_retries maximum number of times to retry an idempotent request (default to 1)
+* :max_redirects maximum number of redirections (default to 10)
+* :proxy An HTTP proxy URI to use for this request. Any value here
+  (including nil) will override RestMan.proxy.
+* :verify_ssl enable ssl verification, possible values are constants from
+    OpenSSL::SSL::VERIFY_*, defaults to OpenSSL::SSL::VERIFY_PEER
+* :read_timeout, :open_timeout and :write_timeout are how long to wait for a response and
+    to open a connection, in seconds. Pass nil to disable the timeout.
+* :timeout can be used to set: read_timeout, open_timeout and write_timeout
+* :keep_alive_timeout sets seconds to reuse the connection of the previous request. (default to 2 seconds)
+* :ssl_client_cert, :ssl_client_key, :ssl_ca_file, :ssl_ca_path,
+    :ssl_cert_store, :ssl_verify_callback, :ssl_verify_callback_warnings
+* :ssl_version specifies the SSL version for the underlying Net::HTTP connection
+* :ssl_min_version specifies the minimum SSL version for the underlying Net::HTTP connection
+* :ssl_max_version specifies the maximum SSL version for the underlying Net::HTTP connection
+* :ssl_timeout sets the SSL timeout seconds
+* :ssl_ciphers sets SSL ciphers for the connection. See
+    OpenSSL::SSL::SSLContext#ciphers=
+* :before_execution_proc a Proc to call before executing the request. This
+    proc, like procs from RestMan.before_execution_procs, will be
+    called with the HTTP request and request params.
+* :close_on_empty_response default to false
+* :local_host sets the local address for the outgoing connection
+* :local_port sets the local port for the outgoing connection

data/_doc/lib/restman/reset_before_execution_procs.rdoc

@@ -0,0 +1 @@
+Reset the procs to be called before each request is executed.

data/_doc/lib/restman/resource/[].rdoc

@@ -0,0 +1,25 @@
+Construct a subresource, preserving authentication.
+
+Example:
+
+  site = RestMan::Resource.new('http://example.com', 'adam', 'mypasswd')
+  site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'
+
+This is especially useful if you wish to define your site in one place and
+call it in multiple locations:
+
+  def orders
+    RestMan::Resource.new('http://example.com/orders', 'admin', 'mypasswd')
+  end
+
+  orders.get                     # GET http://example.com/orders
+  orders['1'].get                # GET http://example.com/orders/1
+  orders['1/items'].delete       # DELETE http://example.com/orders/1/items
+
+Nest resources as far as you want:
+
+  site = RestMan::Resource.new('http://example.com')
+  posts = site['posts']
+  first_post = posts['1']
+  comments = first_post['comments']
+  comments.post 'Hello', :content_type => 'text/plain'

data/_doc/lib/restman/resource.rdoc

@@ -0,0 +1,33 @@
+A class that can be instantiated for access to a RESTful resource,
+including authentication.
+
+Example:
+
+  resource = RestMan::Resource.new('http://some/resource')
+  jpg = resource.get(:accept => 'image/jpg')
+
+With HTTP basic authentication:
+
+  resource = RestMan::Resource.new('http://protected/resource', :user => 'user', :password => 'password')
+  resource.delete
+
+With a timeout (seconds):
+
+  RestMan::Resource.new('http://slow', :read_timeout => 10)
+
+With an open timeout (seconds):
+
+  RestMan::Resource.new('http://behindfirewall', :open_timeout => 10)
+
+You can also use resources to share common headers. For headers keys,
+symbols are converted to strings. Example:
+
+  resource = RestMan::Resource.new('http://some/resource', :headers => { :client_version => 1 })
+
+This header will be transported as X-Client-Version (notice the X prefix,
+capitalization and hyphens)
+
+Use the [] syntax to allocate subresources:
+
+  site = RestMan::Resource.new('http://example.com', :user => 'adam', :password => 'mypasswd')
+  site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'

data/_doc/lib/restman/response/body.rdoc

@@ -0,0 +1,7 @@
+:call-seq:
+  body -> string
+
+Return the HTTP response body.
+
+Future versions of RestMan will deprecate treating response objects
+directly as strings, so it will be necessary to call `.body`.

data/_doc/lib/restman/response/create.rdoc

@@ -0,0 +1,10 @@
+Initialize a Response object. Because RestMan::Response is
+(unfortunately) a subclass of String for historical reasons,
+Response.create is the preferred initializer.
+
+[Parameters:]
+
+  - *body* (String, nil) -- The response body from the Net::HTTPResponse
+  - *net_http_res* (Net::HTTPResponse)
+  - *request* (RestMan::Request)
+  - *start_time* (Time)

data/_doc/lib/restman/response/fix_encoding.rdoc

@@ -0,0 +1,2 @@
+Set the String encoding according to the 'Content-Type: charset' header,
+if possible.

data/_doc/lib/restman/statuses.rdoc

@@ -0,0 +1,11 @@
+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 Also:]
+
+  http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

data/_doc/lib/restman/utils/cgi_parse_header.rdoc

@@ -0,0 +1,6 @@
+:call-seq:
+  cgi_parse_header(line) -> Array(String, Hash)
+
+Parse a Content-Type like header.
+
+Return the main content-type and a hash of params.

data/_doc/lib/restman/utils/encode_query_string.rdoc

@@ -0,0 +1,90 @@
+:call-seq:
+  encode_query_string(object) -> string
+
+Serialize a ruby object into HTTP query string parameters.
+
+There is no standard for doing this, so we choose our own slightly
+idiosyncratic format. The output closely matches the format understood by
+Rails, Rack, and PHP.
+
+If you don't want handling of complex objects and only want to handle
+simple flat hashes, you may want to use `URI.encode_www_form` instead,
+which implements HTML5-compliant URL encoded form data.
+
+[Examples:]
+
+Simple hashes
+
+  >> encode_query_string({foo: 123, bar: 456})
+  => 'foo=123&bar=456'
+
+Simple arrays
+
+  >> encode_query_string({foo: [1,2,3]})
+  => 'foo[]=1&foo[]=2&foo[]=3'
+
+Nested hashes
+
+  >> encode_query_string({outer: {foo: 123, bar: 456}})
+  => 'outer[foo]=123&outer[bar]=456'
+
+Deeply nesting
+
+  >> encode_query_string({coords: [{x: 1, y: 0}, {x: 2}, {x: 3}]})
+  => 'coords[][x]=1&coords[][y]=0&coords[][x]=2&coords[][x]=3'
+
+Null and empty values
+
+  >> encode_query_string({string: '', empty: nil, list: [], hash: {}})
+  => 'string=&empty&list&hash'
+
+Nested nulls
+
+  >> encode_query_string({foo: {string: '', empty: nil}})
+  => 'foo[string]=&foo[empty]'
+
+Multiple fields with the same name using ParamsArray
+
+  >> encode_query_string(RestMan::ParamsArray.new([[:foo, 1], [:foo, 2], [:foo, 3]]))
+  => 'foo=1&foo=2&foo=3'
+
+Nested ParamsArray
+
+  >> encode_query_string({foo: RestMan::ParamsArray.new([[:a, 1], [:a, 2]])})
+  => 'foo[a]=1&foo[a]=2'
+
+  >> encode_query_string(RestMan::ParamsArray.new([[:foo, {a: 1}], [:foo, {a: 2}]]))
+  => 'foo[a]=1&foo[a]=2'
+
+
+
+[Parameters:]
+
+  - object (Hash,ParamsArray) -- The object to serialize
+
+[Returns:]
+
+  - (String) -- A string appropriate for use as an HTTP query string
+
+[See Also:]
+
+  - flatten_params
+  - URI.encode_www_form
+  - Object#to_query in ActiveSupport
+  - http://php.net/manual/en/function.http-build-query.php
+    http_build_query in PHP
+  - Rack::Utils.build_nested_query in Rack
+
+Notable differences from the ActiveSupport implementation:
+
+- Empty hash and empty array are treated the same as nil instead of being
+  omitted entirely from the output. Rather than disappearing, they will
+  appear to be nil instead.
+
+It's most common to pass a Hash as the object to serialize, but you can
+also use a ParamsArray if you want to be able to pass the same key with
+multiple values and not use the rack/rails array convention.
+
+[since:]
+
+  - 2.0.0

data/_doc/lib/restman/utils/escape.rdoc

@@ -0,0 +1,11 @@
+Encode string for safe transport by URI or form encoding. This uses a CGI
+style escape, which transforms ` ` into `+` and various special
+characters into percent encoded forms.
+
+This calls URI.encode_www_form_component for the implementation. The only
+difference between this and CGI.escape is that it does not escape `*`.
+http://stackoverflow.com/questions/25085992/
+
+[See Also:]
+
+  - URI.encode_www_form_component

data/_doc/lib/restman/utils/flatten_params.rdoc

@@ -0,0 +1,16 @@
+Transform deeply nested param containers into a flat array of [key,
+value] pairs.
+
+*Examples:*
+
+  >> flatten_params({key1: {key2: 123}})
+  => [["key1[key2]", 123]]
+
+  >> flatten_params({key1: {key2: 123, arr: [1,2,3]}})
+  => [["key1[key2]", 123], ["key1[arr][]", 1], ["key1[arr][]", 2], ["key1[arr][]", 3]]
+
+[Parameters:]
+
+  - object (Hash, ParamsArray) -- The container to flatten
+  - uri_escape (Boolean) -- Whether to URI escape keys and values
+  - parent_key (String) -- Should not be passed (used for recursion)

data/_doc/lib/restman/utils/get_encoding_from_headers.rdoc

@@ -0,0 +1,24 @@
+:call-seq:
+  get_encoding_from_headers(headers) -> String or nil
+
+Return encoding from an HTTP header hash.
+
+We use the RFC 7231 specification and do not impose a default encoding on
+text. This differs from the older RFC 2616 behavior, which specifies
+using ISO-8859-1 for text/* content types without a charset.
+
+Strings will use the default encoding when this method returns nil. This
+default is likely to be UTF-8 for Ruby >= 2.0
+
+[Parameters:]
+
+  - headers (Hash<Symbol, String>)
+
+[Returns:]
+
+  - (String, nil) -- Return the string encoding or nil if no header is found.
+
+Examples:
+
+  get_encoding_from_headers({:content_type => 'text/plain; charset=UTF-8'})
+  => "UTF-8"

data/_doc/lib/restman.rdoc

@@ -0,0 +1,43 @@
+This module's static methods are the entry point for using the REST client.
+
+  # GET
+  xml = RestMan.get 'http://example.com/resource'
+  jpg = RestMan.get 'http://example.com/resource', :accept => 'image/jpg'
+
+  # authentication and SSL
+  RestMan.get 'https://user:password@example.com/private/resource'
+
+  # POST or PUT with a hash sends parameters as a urlencoded form body
+  RestMan.post 'http://example.com/resource', :param1 => 'one'
+
+  # nest hash parameters
+  RestMan.post 'http://example.com/resource', :nested => { :param1 => 'one' }
+
+  # POST and PUT with raw payloads
+  RestMan.post 'http://example.com/resource', 'the post body', :content_type => 'text/plain'
+  RestMan.post 'http://example.com/resource.xml', xml_doc
+  RestMan.put 'http://example.com/resource.pdf', File.read('my.pdf'), :content_type => 'application/pdf'
+
+  # DELETE
+  RestMan.delete 'http://example.com/resource'
+
+  # retrieve the response http code and headers
+  res = RestMan.get 'http://example.com/some.jpg'
+  res.code                    # => 200
+  res.headers[:content_type]  # => 'image/jpg'
+
+  # HEAD
+  RestMan.head('http://example.com').headers
+
+To use with a proxy, just set RestMan.proxy to the proper http proxy:
+
+  RestMan.proxy = "http://proxy.example.com/"
+
+Or inherit the proxy from the environment:
+
+  RestMan.proxy = ENV['http_proxy']
+
+For live tests of RestMan, try using http://rest-test.heroku.com, which echoes back information about the rest call:
+
+  >> RestMan.put 'http://rest-test.heroku.com/resource', :foo => 'baz'
+  => "PUT http://rest-test.heroku.com/resource with a 7 byte payload, content type application/x-www-form-urlencoded {\"foo\"=>\"baz\"}"

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "restman"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/lib/restman/abstract_response.rb

@@ -31,12 +31,15 @@ module RestMan
       @code ||= @net_http_res.code.to_i
     end
 
+    def success?
+      (200..299).include?(code)
+    end
+
     def history
       @history ||= request.redirection_history || []
     end
 
-    # A hash of the headers, beautified with symbols and underscores.
-    # e.g. "Content-type" will become :content_type.
+    # :include: _doc/lib/restman/abstract_response/headers.rdoc
     def headers
       @headers ||= AbstractResponse.beautify_headers(@net_http_res.to_hash)
     end
@@ -46,9 +49,7 @@ module RestMan
       @raw_headers ||= @net_http_res.to_hash
     end
 
-    # @param [Net::HTTPResponse] net_http_res
-    # @param [RestMan::Request] request
-    # @param [Time] start_time
+    # :include: _doc/lib/restman/abstract_response/response_set_vars.rdoc
     def response_set_vars(net_http_res, request, start_time)
       @net_http_res = net_http_res
       @request = request
@@ -65,16 +66,7 @@ module RestMan
       history
     end
 
-    # Hash of cookies extracted from response headers.
-    #
-    # NB: This will return only cookies whose domain matches this request, and
-    # may not even return all of those cookies if there are duplicate names.
-    # Use the full cookie_jar for more nuanced access.
-    #
-    # @see #cookie_jar
-    #
-    # @return [Hash]
-    #
+    # :include: _doc/lib/restman/abstract_response/cookies.rdoc
     def cookies
       hash = {}
 
@@ -85,10 +77,7 @@ module RestMan
       hash
     end
 
-    # Cookie jar extracted from response headers.
-    #
-    # @return [HTTP::CookieJar]
-    #
+    # :include: _doc/lib/restman/abstract_response/cookie_jar.rdoc
     def cookie_jar
       return @cookie_jar if defined?(@cookie_jar) && @cookie_jar
 
@@ -100,16 +89,7 @@ module RestMan
       @cookie_jar = jar
     end
 
-    # Return the default behavior corresponding to the response code:
-    #
-    # For 20x status codes: return the response itself
-    #
-    # For 30x status codes:
-    #   301, 302, 307: redirect GET / HEAD if there is a Location header
-    #   303: redirect, changing method to GET, if there is a Location header
-    #
-    # For all other responses, raise a response exception
-    #
+    # :include: _doc/lib/restman/abstract_response/return.rdoc
     def return!(&block)
       case code
       when 200..207
@@ -139,14 +119,12 @@ module RestMan
       "#{code} #{STATUSES[code]} | #{(headers[:content_type] || '').gsub(/;.*$/, '')} #{size} bytes\n"
     end
 
-    # Follow a redirection response by making a new HTTP request to the
-    # redirection target.
+    # :include: _doc/lib/restman/abstract_response/follow_redirection.rdoc
     def follow_redirection(&block)
       _follow_redirection(request.args.dup, &block)
     end
 
-    # Follow a redirection response, but change the HTTP method to GET and drop
-    # the payload from the original request.
+    # :include: _doc/lib/restman/abstract_response/follow_get_redirection.rdoc
     def follow_get_redirection(&block)
       new_args = request.args.dup
       new_args[:method] = :get
@@ -155,27 +133,7 @@ module RestMan
       _follow_redirection(new_args, &block)
     end
 
-    # Convert headers hash into canonical form.
-    #
-    # Header names will be converted to lowercase symbols with underscores
-    # instead of hyphens.
-    #
-    # Headers specified multiple times will be joined by comma and space,
-    # except for Set-Cookie, which will always be an array.
-    #
-    # Per RFC 2616, if a server sends multiple headers with the same key, they
-    # MUST be able to be joined into a single header by a comma. However,
-    # Set-Cookie (RFC 6265) cannot because commas are valid within cookie
-    # definitions. The newer RFC 7230 notes (3.2.2) that Set-Cookie should be
-    # handled as a special case.
-    #
-    # http://tools.ietf.org/html/rfc2616#section-4.2
-    # http://tools.ietf.org/html/rfc7230#section-3.2.2
-    # http://tools.ietf.org/html/rfc6265
-    #
-    # @param headers [Hash]
-    # @return [Hash]
-    #
+    # :include: _doc/lib/restman/abstract_response/beautify_headers.rdoc
     def self.beautify_headers(headers)
       headers.inject({}) do |out, (key, value)|
         key_sym = key.tr('-', '_').downcase.to_sym
@@ -193,12 +151,7 @@ module RestMan
 
     private
 
-    # Follow a redirection
-    #
-    # @param new_args [Hash] Start with this hash of arguments for the
-    #   redirection request. The hash will be mutated, so be sure to dup any
-    #   existing hash that should not be modified.
-    #
+    # :include: _doc/lib/restman/abstract_response/_follow_redirection.rdoc
     def _follow_redirection(new_args, &block)
 
       # parse location header and merge into existing URL