patron 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c0a3e8dc6975392e43cac53cb03387ef07c3cab3
-  data.tar.gz: c58f5c72242c526bd2b8a9a70f13fa53248512e4
+  metadata.gz: 10e347aa0ab1915c0d428cbfaf4bd6888ae2a9ba
+  data.tar.gz: 76476a77a366bd7b5b2aacc7fe946b26e142b995
 SHA512:
-  metadata.gz: d4e0312f0cf82ed1db7d980bd93771016e710e7d2b1c6c3b7d7eaf965ff654eba61199eaa6a54df44e9c9ece0f610a8b16eb4bde37fce15b84fb733abf61f531
-  data.tar.gz: 28e92d83ad9d9e7e173c327c7797b6d11240e41c1fceadb4e3cfdbc9a35abe0597150c2ab32626d183992ec835d5bfd1a6c771df506e10b2fe44c9ca3ada15d1
+  metadata.gz: 66045fc85f95a730550b061b255cc1420c4b0e6feee1a5cf5252d5cda68dad5792a146ea290208b683d5fe05c596d767864ef6189cade817c84792b4ae963f47
+  data.tar.gz: c7292c8749d8c70e051b032069fe136e6715c8158c4b8b5a9b9c24967a629aa2314b77ea8e5addca9880163facebe728b255e7a3063a803b8fbc33ee100b2bc6

data/.gitignore

@@ -6,3 +6,4 @@ rdoc
 doc
 pkg
 tmp
+.yardoc

data/.travis.yml

@@ -0,0 +1,6 @@
+rvm:
+- 1.9.3
+- 2.1.5
+- 2.2.2
+sudo: false
+cache: bundler

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    patron (0.5.1)
+    patron (0.6.1)
 
 GEM
   remote: https://rubygems.org/
@@ -30,6 +30,7 @@ GEM
       json (~> 1.8)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.0)
+    yard (0.8.7.6)
 
 PLATFORMS
   ruby
@@ -40,6 +41,7 @@ DEPENDENCIES
   rake-compiler (>= 0.7.5)
   rspec (>= 2.3.0)
   simplecov (>= 0.10.0)
+  yard (~> 0.8)
 
 BUNDLED WITH
    1.11.2

data/README.md

@@ -1,15 +1,10 @@
-# Ruby HTTP Client
-
-## SYNOPSIS
-
 Patron is a Ruby HTTP client library based on libcurl. It does not try to expose
 the full "power" (read complexity) of libcurl but instead tries to provide a
 sane API while taking advantage of libcurl under the hood.
 
+## Usage
 
-## USAGE
-
-Usage is very simple. First, you instantiate a Session object. You can set a few
+First, you instantiate a Session object. You can set a few
 default options on the Session instance that will be used by all subsequent
 requests:
 
@@ -55,18 +50,27 @@ You can ship custom headers with a single request:
 
     sess.post("/foo/stuff", "some data", {"Content-Type" => "text/plain"})
 
-That is pretty much all there is to it.
+## Threading
 
+By itself, the `Patron::Session` objects are not thread safe (each `Session` holds a single `curl_state` pointer
+during the request/response cycle). At this time, Patron has no support for `curl_multi_*` family of functions 
+for doing concurrent requests. However, the actual code that interacts with libCURL does unlock the RVM GIL,
+so using multiple `Session` objects in different threads is possible with a high degree of concurrency.
+For sharing a resource of sessions between threads we recommend using the excellent [connection_pool](https://rubygems.org/gems/connection_pool) gem by Mike Perham.
 
-## REQUIREMENTS
+    patron_pool = ConnectionPool.new(size: 5, timeout: 5) { Patron::Session.new }
+    patron_pool.with do |session|
+      session.get(...)
+    end
+
+## Requirements
 
 You need a recent version of libcurl in order to install this gem. On MacOS X
 the provided libcurl is sufficient. You will have to install the libcurl
 development packages on Debian or Ubuntu. Other Linux systems are probably
 similar. Windows users are on your own. Good luck with that.
 
-
-## INSTALL
+## Installation
 
     sudo gem install patron
 

data/Rakefile

@@ -22,10 +22,10 @@
 ##
 ## -------------------------------------------------------------------
 require 'rake/clean'
-require 'rdoc/task'
 require 'rake/extensiontask'
 require 'rspec/core/rake_task'
 require 'bundler'
+require 'yard'
 
 Rake::ExtensionTask.new do |ext|
   ext.name = 'session_ext'           # indicate the name of the extension.
@@ -43,12 +43,11 @@ task :shell => :compile do
   sh 'irb -I./lib -I./ext -r patron'
 end
 
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = 'Patron documentation'
-  rdoc.main = 'README.txt'
-  rdoc.rdoc_files.include('README.txt')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+desc "Generate YARD documentation"
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', 'ext/**/*.c' ]
+  t.options = ['--markup markdown']
+  t.stats_options = ['--list-undoc']
 end
 
 desc "Run specs"

data/ext/patron/extconf.rb

@@ -22,6 +22,7 @@
 ##
 ## -------------------------------------------------------------------
 
+
 require 'mkmf'
 require 'rbconfig'
 

data/ext/patron/session_ext.c

@@ -38,6 +38,7 @@ static VALUE cSession = Qnil;
 static VALUE cRequest = Qnil;
 static VALUE ePatronError = Qnil;
 static VALUE eUnsupportedProtocol = Qnil;
+static VALUE eUnsupportedSSLVersion = Qnil;
 static VALUE eURLFormatError = Qnil;
 static VALUE eHostResolutionError = Qnil;
 static VALUE eConnectionFailed = Qnil;
@@ -206,10 +207,10 @@ static struct curl_state* get_curl_state(VALUE self) {
 /*----------------------------------------------------------------------------*/
 /* Method implementations                                                     */
 
-/* call-seq:
- *    Patron.libcurl_version   -> version string
- *
- * Returns the version of the embedded libcurl as a string.
+/*
+* Returns the version of the embedded libcurl.
+* 
+*  @return [String] libcurl version string
  */
 static VALUE libcurl_version(VALUE klass) {
   char* value = curl_version();
@@ -217,10 +218,11 @@ static VALUE libcurl_version(VALUE klass) {
   return rb_str_new2(value);
 }
 
-/* call-seq:
- *    Session.escape( string )   -> escaped string
+/*
+ * Escapes the provided string using libCURL URL escaping functions.
  *
- * URL escapes the provided string.
+ * @param [String] value plain string to URL-escape
+*  @return [String] the escaped string
  */
 static VALUE session_escape(VALUE self, VALUE value) {
   
@@ -240,10 +242,11 @@ static VALUE session_escape(VALUE self, VALUE value) {
   return retval;
 }
 
-/* call-seq:
- *    Session.unescape( string )   -> unescaped string
+/*
+ * Unescapes the provided string using libCURL URL escaping functions.
  *
- * Unescapes the provided string.
+ * @param [String] value URL-encoded String to unescape
+*  @return [String] unescaped (decoded) string
  */
 static VALUE session_unescape(VALUE self, VALUE value) {
   VALUE string = StringValue(value);
@@ -271,7 +274,8 @@ static int each_http_header(VALUE header_key, VALUE header_value, VALUE self) {
   VALUE name = rb_obj_as_string(header_key);
   VALUE value = rb_obj_as_string(header_value);
   VALUE header_str = Qnil;
-
+  
+  // TODO: see how to combine this with automatic_content_encoding
   if (rb_str_cmp(name, rb_str_new2("Accept-Encoding")) == 0) {
     if (rb_funcall(value, rb_intern("include?"), 1, rb_str_new2("gzip"))) {
       #ifdef CURLOPT_ACCEPT_ENCODING
@@ -461,7 +465,14 @@ static void set_options_from_request(VALUE self, VALUE request) {
   // Enable automatic content-encoding support via gzip/deflate if set in the request,
   // see https://curl.haxx.se/libcurl/c/CURLOPT_ACCEPT_ENCODING.html
   if(RTEST(a_c_encoding)) {
-    curl_easy_setopt(curl, CURLOPT_ACCEPT_ENCODING, "");
+    #ifdef CURLOPT_ACCEPT_ENCODING
+      curl_easy_setopt(curl, CURLOPT_ACCEPT_ENCODING, "");
+    #elif defined CURLOPT_ENCODING
+      curl_easy_setopt(curl, CURLOPT_ENCODING, "");
+    #else
+      rb_raise(rb_eArgError,
+        "The libcurl version installed doesn't support automatic content negotiation");
+    #endif
   }
   
   url = rb_iv_get(request, "@url");
@@ -494,12 +505,12 @@ static void set_options_from_request(VALUE self, VALUE request) {
 
   proxy_type = rb_iv_get(request, "@proxy_type");
   if (!NIL_P(proxy_type)) {
-    curl_easy_setopt(curl, CURLOPT_PROXYTYPE, FIX2INT(proxy_type));
+    curl_easy_setopt(curl, CURLOPT_PROXYTYPE, NUM2LONG(proxy_type));
   }
 
   credentials = rb_funcall(request, rb_intern("credentials"), 0);
   if (!NIL_P(credentials)) {
-    curl_easy_setopt(curl, CURLOPT_HTTPAUTH, FIX2INT(rb_iv_get(request, "@auth_type")));
+    curl_easy_setopt(curl, CURLOPT_HTTPAUTH, NUM2LONG(rb_iv_get(request, "@auth_type")));
     curl_easy_setopt(curl, CURLOPT_USERPWD, StringValuePtr(credentials));
   }
 
@@ -516,13 +527,16 @@ static void set_options_from_request(VALUE self, VALUE request) {
 
   ssl_version = rb_iv_get(request, "@ssl_version");
   if(!NIL_P(ssl_version)) {
-    char* version = StringValuePtr(ssl_version);
+    VALUE ssl_version_str = rb_funcall(ssl_version, rb_intern("to_s"), 0);
+    char* version = StringValuePtr(ssl_version_str);
     if(strcmp(version, "SSLv2") == 0) {
       curl_easy_setopt(curl, CURLOPT_SSLVERSION, CURL_SSLVERSION_SSLv2);
     } else if(strcmp(version, "SSLv3") == 0) {
       curl_easy_setopt(curl, CURLOPT_SSLVERSION, CURL_SSLVERSION_SSLv3);
     } else if(strcmp(version, "TLSv1") == 0) {
       curl_easy_setopt(curl, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1);
+    } else {
+      rb_raise(eUnsupportedSSLVersion, "Unsupported SSL version: %s", version);
     }
   }
 
@@ -533,7 +547,7 @@ static void set_options_from_request(VALUE self, VALUE request) {
 
   buffer_size = rb_iv_get(request, "@buffer_size");
   if (!NIL_P(buffer_size)) {
-     curl_easy_setopt(curl, CURLOPT_BUFFERSIZE, FIX2INT(buffer_size));
+     curl_easy_setopt(curl, CURLOPT_BUFFERSIZE, NUM2LONG(buffer_size));
   }
 
   if(state->debug_file) {
@@ -631,7 +645,9 @@ static VALUE perform_request(VALUE self) {
     VALUE header_str = membuffer_to_rb_str(header_buffer);
     VALUE body_str = Qnil;
     if (!state->download_file) { body_str = membuffer_to_rb_str(body_buffer); }
-
+    
+    curl_easy_setopt(curl, CURLOPT_COOKIELIST, "FLUSH"); // Flush cookies to the cookie jar
+    
     return create_response(self, curl, header_str, body_str);
   } else {
     rb_raise(select_error(ret), "%s", state->error_buf);
@@ -669,9 +685,7 @@ static VALUE cleanup(VALUE self) {
   return Qnil;
 }
 
-/* call-seq:
- *    session.handle_request( request )   -> response
- *
+/*
  * Peform the actual HTTP request by calling libcurl. Each filed in the
  * +request+ object will be used to set the appropriate option on the libcurl
  * library. After the request completes, a Response object will be created and
@@ -680,17 +694,25 @@ static VALUE cleanup(VALUE self) {
  * In the event of an error in the libcurl library, a Ruby exception will be
  * created and raised. The exception will return the libcurl error code and
  * error message.
+ *
+ * @param request[Patron::Request] the request to use when filling the CURL options
+ * @return [Patron::Response] the result of calling `response_class` on the Session
  */
 static VALUE session_handle_request(VALUE self, VALUE request) {
   set_options_from_request(self, request);
   return rb_ensure(&perform_request, self, &cleanup, self);
 }
 
-/* call-seq:
- *    session.reset   -> session
- *
+/*
+ * FIXME: figure out how this method should be used at all given Session is not multithreaded.
+ * FIXME: also: what is the difference with `interrupt()` and also relationship with `cleanup()`?
  * Reset the underlying cURL session. This effectively closes all open
- * connections and disables debug output.
+ * connections and disables debug output. There is no need to call this method
+ * manually after performing a request, since cleanup is performed automatically
+ * but the method can be used from another thread
+ * to abort a request currently in progress.
+ *
+ * @return self
  */
 static VALUE session_reset(VALUE self) {
   struct curl_state *state;
@@ -706,11 +728,10 @@ static VALUE session_reset(VALUE self) {
   return self;
 }
 
-/* call-seq:
- *    session.interrupt   -> session
- *
- * Interrupt any currently executing request. This will cause the current
+/* Interrupt any currently executing request. This will cause the current
  * request to error and raise an exception.
+ *
+ * @return [void] This method always raises
  */
 static VALUE session_interrupt(VALUE self) {
   struct curl_state *state = get_curl_state(self);
@@ -718,18 +739,21 @@ static VALUE session_interrupt(VALUE self) {
   return self;
 }
 
-/* call-seq:
- *    session.enable_cookie_session( file )   -> session
- *
+/*
  * Turn on cookie handling for this session, storing them in memory by
- * default or in +file+ if specified. The +file+ must be readable and
+ * default or in +file+ if specified. The `file` must be readable and
  * writable. Calling multiple times will add more files.
+ * FIXME: what does the empty string actually do here?
+* 
+ * @param [String] file path to the existing cookie file, or nil to store in memory.
+*  @return self
  */
-static VALUE enable_cookie_session(VALUE self, VALUE file) {
+static VALUE add_cookie_file(VALUE self, VALUE file) {
   struct curl_state *state = get_curl_state(self);
   CURL* curl = state->handle;
   char* file_path = NULL;
 
+  // FIXME: http://websystemsengineering.blogspot.nl/2013/03/curloptcookiefile-vs-curloptcookiejar.html
   file_path = RSTRING_PTR(file);
   if (file_path != NULL && strlen(file_path) != 0) {
     curl_easy_setopt(curl, CURLOPT_COOKIEJAR, file_path);
@@ -739,10 +763,11 @@ static VALUE enable_cookie_session(VALUE self, VALUE file) {
   return self;
 }
 
-/* call-seq:
- *    session.set_debug_file( file )   -> session
- *
+/*
  * Enable debug output to stderr or to specified +file+.
+ *
+ * @param [String, nil] file path to the debug file, or nil to write to STDERR
+*  @return self
  */
 static VALUE set_debug_file(VALUE self, VALUE file) {
   struct curl_state *state = get_curl_state(self);
@@ -774,6 +799,7 @@ void Init_session_ext() {
   ePatronError = rb_const_get(mPatron, rb_intern("Error"));
 
   eUnsupportedProtocol = rb_const_get(mPatron, rb_intern("UnsupportedProtocol"));
+  eUnsupportedSSLVersion = rb_const_get(mPatron, rb_intern("UnsupportedSSLVersion"));
   eURLFormatError = rb_const_get(mPatron, rb_intern("URLFormatError"));
   eHostResolutionError = rb_const_get(mPatron, rb_intern("HostResolutionError"));
   eConnectionFailed = rb_const_get(mPatron, rb_intern("ConnectionFailed"));
@@ -798,20 +824,20 @@ void Init_session_ext() {
   rb_define_method(cSession, "handle_request", session_handle_request, 1);
   rb_define_method(cSession, "reset",          session_reset,          0);
   rb_define_method(cSession, "interrupt",      session_interrupt,      0);
-  rb_define_method(cSession, "enable_cookie_session", enable_cookie_session, 1);
+  rb_define_method(cSession, "add_cookie_file", add_cookie_file, 1);
   rb_define_method(cSession, "set_debug_file", set_debug_file, 1);
   rb_define_alias(cSession, "urlencode", "escape");
   rb_define_alias(cSession, "urldecode", "unescape");
 
-  rb_define_const(cRequest, "AuthBasic",  INT2FIX(CURLAUTH_BASIC));
-  rb_define_const(cRequest, "AuthDigest", INT2FIX(CURLAUTH_DIGEST));
-  rb_define_const(cRequest, "AuthAny",    INT2FIX(CURLAUTH_ANY));
+  rb_define_const(cRequest, "AuthBasic",  LONG2NUM(CURLAUTH_BASIC));
+  rb_define_const(cRequest, "AuthDigest", LONG2NUM(CURLAUTH_DIGEST));
+  rb_define_const(cRequest, "AuthAny",    LONG2NUM(CURLAUTH_ANY));
 
   mProxyType = rb_define_module_under(mPatron, "ProxyType");
-  rb_define_const(mProxyType, "HTTP", INT2FIX(CURLPROXY_HTTP));
-  rb_define_const(mProxyType, "HTTP_1_0", INT2FIX(CURLPROXY_HTTP_1_0));
-  rb_define_const(mProxyType, "SOCKS4", INT2FIX(CURLPROXY_SOCKS4));
-  rb_define_const(mProxyType, "SOCKS5", INT2FIX(CURLPROXY_SOCKS5));
-  rb_define_const(mProxyType, "SOCKS4A", INT2FIX(CURLPROXY_SOCKS4A));
-  rb_define_const(mProxyType, "SOCKS5_HOSTNAME", INT2FIX(CURLPROXY_SOCKS5_HOSTNAME));
+  rb_define_const(mProxyType, "HTTP", LONG2NUM(CURLPROXY_HTTP));
+  rb_define_const(mProxyType, "HTTP_1_0", LONG2NUM(CURLPROXY_HTTP_1_0));
+  rb_define_const(mProxyType, "SOCKS4", LONG2NUM(CURLPROXY_SOCKS4));
+  rb_define_const(mProxyType, "SOCKS5", LONG2NUM(CURLPROXY_SOCKS5));
+  rb_define_const(mProxyType, "SOCKS4A", LONG2NUM(CURLPROXY_SOCKS4A));
+  rb_define_const(mProxyType, "SOCKS5_HOSTNAME", LONG2NUM(CURLPROXY_SOCKS5_HOSTNAME));
 }

data/lib/patron.rb

@@ -22,6 +22,8 @@
 ## THE SOFTWARE.
 ##
 ## -------------------------------------------------------------------
+
+
 require 'pathname'
 
 cwd = Pathname(__FILE__).dirname
@@ -30,8 +32,9 @@ $:.unshift(cwd.to_s) unless $:.include?(cwd.to_s) || $:.include?(cwd.expand_path
 require 'patron/session'
 require 'patron/version'
 
-module Patron #:nodoc:
-  # Returns the version number of the Patron library as a string
+module Patron
+  # Returns the version number of the gem
+  # @return [String]
   def self.version
     VERSION
   end

data/lib/patron/error.rb

@@ -23,33 +23,37 @@
 ##
 ## -------------------------------------------------------------------
 
+
 module Patron
 
   # Base class for Patron exceptions.
   class Error < StandardError; end
 
-  # The URL you passed to Patron used a protocol that it does not support.
+  # Gets raised when the URL passed to Patron used a protocol that it does not support.
   # This most likely the result of a misspelled protocol string.
   class UnsupportedProtocol   < Error; end
 
-  # The URL was not properly formatted.
+  # Gets raised when a request is attempted with an unsupported SSL version.
+  class UnsupportedSSLVersion < Error; end
+
+  # Gets raised when the URL was not properly formatted.
   class URLFormatError        < Error; end
 
-  # Could not resolve the remote host name.
+  # Gets raised when the remote host name could not be resolved.
   class HostResolutionError   < Error; end
 
-  # Failed to connect to the remote host.
+  # Gets raised when failing to connect to the remote host.
   class ConnectionFailed      < Error; end
 
-  # A file transfer was shorter or larger than expected.
+  # Gets raised when the response was shorter or larger than expected.
   # This happens when the server first reports an expected transfer size,
   # and then delivers data that doesn't match the previously given size.
   class PartialFileError      < Error; end
 
-  # Operation timeout. The specified time-out period was reached.
+  # Gets raised on an operation timeout. The specified time-out period was reached.
   class TimeoutError          < Error; end
 
-  # Too many redirects. When following redirects, Patron hit the maximum amount.
+  # Gets raised on too many redirects. When following redirects, Patron hit the maximum amount.
   class TooManyRedirects      < Error; end
 
 end

data/lib/patron/proxy_type.rb

@@ -1,4 +1,5 @@
 module Patron
+  # Represents proxy types that can be used when configured requests via CURL.
   module ProxyType
     HTTP
     HTTP_1_0

data/lib/patron/request.rb

@@ -23,6 +23,7 @@
 ##
 ## -------------------------------------------------------------------
 
+
 require 'patron/util'
 
 module Patron
@@ -32,8 +33,11 @@ module Patron
   # used in every request.
   class Request
 
+    # Contains the valid HTTP verbs that can be used to perform requests
     VALID_ACTIONS = %w[GET PUT POST DELETE HEAD COPY]
 
+    # Initializes a new Request, which defaults to the GET HTTP verb and
+    # has it's timeouts set to 0
     def initialize
       @action = :get
       @headers = {}
@@ -59,7 +63,7 @@ module Patron
 
     # Set the type of authentication to use for this request.
     #
-    # @param [String, Symbol] type - The type of authentication to use for this request, can be one of
+    # @param [String, Symbol]type The type of authentication to use for this request, can be one of
     #   :basic, :digest, or :any
     #
     # @example
@@ -79,6 +83,16 @@ module Patron
       end
     end
 
+    # Sets the upload data (request body) for the request. If the
+    # given argument is a Hash, the contents of the hash will be handled
+    # as form fields and will be form-encoded. The somposition of the request
+    # body is then going to be handled by Curl.
+    #
+    # If the given `data` is any other object, it is going to be treated as a stringable
+    # request body (JSON or other verbatim type) and will have it's `to_s` method called
+    # before sending out the request.
+    #
+    # @param data[Hash, #to_s] a Hash of form fields to values, or an object that responds to `to_s`
     def upload_data=(data)
       @upload_data = case data
       when Hash
@@ -88,6 +102,9 @@ module Patron
       end
     end
 
+    # Sets the HTTP verb for the request
+    #
+    # @param action[String] the name of the HTTP verb
     def action=(action)
       if !VALID_ACTIONS.include?(action.to_s.upcase)
         raise ArgumentError, "Action must be one of #{VALID_ACTIONS.join(', ')}"
@@ -95,6 +112,9 @@ module Patron
       @action = action.downcase.to_sym
     end
 
+    # Sets the read timeout for the CURL request, in seconds
+    #
+    # @param new_timeout[Integer] the number of seconds to wait before raising a timeout error
     def timeout=(new_timeout)
       if new_timeout && new_timeout.to_i < 1
         raise ArgumentError, "Timeout must be a positive integer greater than 0"
@@ -103,6 +123,9 @@ module Patron
       @timeout = new_timeout.to_i
     end
 
+    # Sets the connect timeout for the CURL request, in seconds.
+    #
+    # @param new_timeout[Integer] the number of seconds to wait before raising a timeout error
     def connect_timeout=(new_timeout)
       if new_timeout && new_timeout.to_i < 1
         raise ArgumentError, "Timeout must be a positive integer greater than 0"
@@ -111,6 +134,9 @@ module Patron
       @connect_timeout = new_timeout.to_i
     end
     
+    # Sets the maximum number of redirects that are going to be followed.
+    #
+    # @param new_max_redirects[Integer] The number of redirects to follow, or `-1` for unlimited redirects.
     def max_redirects=(new_max_redirects)
       if new_max_redirects.to_i < -1
         raise ArgumentError, "Max redirects must be a positive integer, 0 or -1"
@@ -119,6 +145,10 @@ module Patron
       @max_redirects = new_max_redirects.to_i
     end
 
+    # Sets the headers for the request. Headers muse be set with the right capitalization.
+    # The previously set headers will be replaced.
+    #
+    # @param new_headers[Hash] the hash of headers to set.
     def headers=(new_headers)
       if !new_headers.kind_of?(Hash)
         raise ArgumentError, "Headers must be a hash"
@@ -127,6 +157,12 @@ module Patron
       @headers = new_headers
     end
 
+    # Sets the receive buffer size. This is a recommendedation value, as CURL is not guaranteed to
+    # honor this value internally (see https://curl.haxx.se/libcurl/c/CURLOPT_BUFFERSIZE.html).
+    # By default, CURL uses the maximum possible buffer size, which will be the best especially
+    # for smaller and quickly-executing requests.
+    #
+    # @param buffer_size[Integer,nil] the desired buffer size, or `nil` for automatic buffer size
     def buffer_size=(buffer_size)
       if buffer_size != nil && buffer_size.to_i < 1
         raise ArgumentError, "Buffer size must be a positive integer greater than 0 or nil"
@@ -135,15 +171,23 @@ module Patron
       @buffer_size = buffer_size != nil ? buffer_size.to_i : nil
     end
 
+    # Returns the set HTTP authentication string for basic authentication.
+    #
+    # @return [String, NilClass] the authentication string or nil if no authentication is used
     def credentials
       return nil if username.nil? || password.nil?
       "#{username}:#{password}"
     end
 
+    # Returns the set HTTP verb
+    #
+    # @return [String] the HTTP verb
     def action_name
       @action.to_s.upcase
     end
 
+    # Tells whether this Request is configured the same as the other request
+    # @return [TrueClass, FalseClass]
     def eql?(request)
       return false unless Request === request
 
@@ -154,12 +198,17 @@ module Patron
 
     alias_method :==, :eql?
 
+    # Returns a Marshalable representation of the Request
+    # @return [Array]
     def marshal_dump
       [ @url, @username, @password, @file_name, @proxy, @proxy_type, @insecure,
         @ignore_content_length, @multipart, @action, @timeout, @connect_timeout,
         @max_redirects, @headers, @auth_type, @upload_data, @buffer_size, @cacert ]
     end
 
+    # Reinstates instance variables from a marshaled representation
+    # @param data[Array]
+    # @return [void]
     def marshal_load(data)
       @url, @username, @password, @file_name, @proxy, @proxy_type, @insecure,
       @ignore_content_length, @multipart, @action, @timeout, @connect_timeout,

data/lib/patron/response.rb

@@ -23,10 +23,38 @@
 ##
 ## -------------------------------------------------------------------
 
+
 module Patron
 
   # Represents the response from the HTTP server.
   class Response
+    # @return [String] the original URL used to perform the request (contains the final URL after redirects)
+    attr_reader :url
+
+    # @return [Fixnum] the HTTP status code of the final response after all the redirects
+    attr_reader :status
+
+    # @return [String] the complete status line (code and message)
+    attr_reader :status_line
+
+    # @return [Fixnum] how many redirects were followed when fulfilling this request
+    attr_reader :redirect_count
+
+    # @return [String, nil] the response body, or nil if the response was written directly to a file
+    attr_reader :body
+
+    # @return [Hash] the response headers. If there were multiple headers received for the same value
+    #   (like "Cookie"), the header values will be within an Array under the key for the header, in order.
+    attr_reader :headers
+
+    # @return [String] the recognized name of the charset for the response
+    attr_reader :charset
+
+    # Overridden so that the output is shorter and there is no response body printed
+    def inspect
+      # Avoid spamming the console with the header and body data
+      "#<Patron::Response @status_line='#{@status_line}'>"
+    end
 
     def initialize(url, status, redirect_count, header_data, body, default_charset = nil)
       # Don't let a response clear out the default charset, which would cause encoding to fail
@@ -48,22 +76,7 @@ module Patron
       end
     end
 
-    attr_reader :url, :status, :status_line, :redirect_count, :body, :headers, :charset
-
-    def inspect
-      # Avoid spamming the console with the header and body data
-      "#<Patron::Response @status_line='#{@status_line}'>"
-    end
-
-    def marshal_dump
-      [@url, @status, @status_line, @redirect_count, @body, @headers, @charset]
-    end
-
-    def marshal_load(data)
-      @url, @status, @status_line, @redirect_count, @body, @headers, @charset = data
-    end
-
-  private
+    private
 
     def determine_charset(header_data, body)
       header_data.match(charset_regex) || (body && body.match(charset_regex))

data/lib/patron/session.rb

@@ -23,6 +23,7 @@
 ##
 ## -------------------------------------------------------------------
 
+
 require 'uri'
 require 'patron/error'
 require 'patron/request'
@@ -36,63 +37,80 @@ module Patron
   # server. This is the primary API for Patron.
   class Session
 
-    # HTTP connection timeout in seconds. Defaults to 1 second.
+    # @return [Integer] HTTP connection timeout in seconds. Defaults to 1 second.
     attr_accessor :connect_timeout
 
-    # HTTP transaction timeout in seconds. Defaults to 5 seconds.
+    # @return [Integer] HTTP transaction timeout in seconds. Defaults to 5 seconds.
     attr_accessor :timeout
 
-    # Maximum number of times to follow redirects.
+    # Maximum number of redirects to follow
     # Set to 0 to disable and -1 to follow all redirects. Defaults to 5.
+    # @return [Integer]
     attr_accessor :max_redirects
 
-    # Prepended to the URL in all requests.
+    # @return [String] The URL to prepend to all requests.
     attr_accessor :base_url
 
-    # Username and password for http authentication
-    attr_accessor :username, :password
+    # Username for http authentication
+    # @return [String,nil] the HTTP basic auth username
+    attr_accessor :username
+    
+    # Password for http authentication
+    # @return [String,nil] the HTTP basic auth password
+    attr_accessor :password
 
-    # Proxy URL in cURL format ('hostname:8080')
+    # @return [String] Proxy URL in cURL format ('hostname:8080')
     attr_accessor :proxy
 
-    # Proxy type (default is HTTP), see constants under ProxyType for supported types.
+    # @return [Integer] Proxy type (default is HTTP)
+    # @see Patron::ProxyType
     attr_accessor :proxy_type
 
-    # Standard set of headers that are used in all requests.
+    # @return [Hash] headers used in all requests.
     attr_accessor :headers
 
-    # Set the authentication type for the request.
+    # @return [Symbol] the authentication type for the request (`:basic`, `:digest` or `:token`).
     # @see Patron::Request#auth_type
     attr_accessor :auth_type
 
-    # Does this session stricly verify SSL certificates?
+    # @return [Boolean] `true` if SSL certificate verification is disabled.
+    # Please consider twice before using this option..
     attr_accessor :insecure
 
-    # Specifies the ssl version
+    # @return [String] the SSL version for the requests, or nil if all versions are permitted
+    # The supported values are nil, "SSLv2", "SSLv3", and "TLSv1".
     attr_accessor :ssl_version
 
-    # What cacert file should this session use to verify SSL certificates?
+    # @return [String] path to the CA file used for certificate verification, or `nil` if CURL default is used
     attr_accessor :cacert
 
-    # Does this session ignore Content-Size headers?
+    # @return [Boolean] whether Content-Range and Content-Length headers should be ignored
     attr_accessor :ignore_content_length
 
+    # @return [Integer, nil]
     # Set the buffer size for this request. This option will
     # only be set if buffer_size is non-nil
     attr_accessor :buffer_size
 
-    # Default encoding of responses. Used if no charset is provided by the host.
+    # @return [String, nil]
+    # Sets the name of the charset to assume for the response. The argument should be a String that
+    # is an acceptable argument for `Encoding.find()` in Ruby. The variable will only be used if the
+    # response does not specify a charset in it's `Content-Type` header already, if it does that charset
+    # will take precedence.
     attr_accessor :default_response_charset
     
-    # Force curl to use IPv4
+    # @return [Boolean] Force curl to use IPv4
     attr_accessor :force_ipv4
 
-    # Support automatic Content-Encoding decompression and set liberal Accept-Encoding headers
+    # @return [Boolean] Support automatic Content-Encoding decompression and set liberal Accept-Encoding headers
     attr_accessor :automatic_content_encoding
     
-    private :handle_request, :enable_cookie_session, :set_debug_file
+    private :handle_request, :add_cookie_file, :set_debug_file
 
     # Create a new Session object.
+    #
+    # @param args[Hash] options for the Session (same names as the writable attributes of the Session)
+    # @yield self
     def initialize(args = {}, &block)
 
       # Allows accessors to be set via constructor hash. Ex:  {:base_url => 'www.home.com'}
@@ -114,73 +132,123 @@ module Patron
     end
 
     # Turn on cookie handling for this session, storing them in memory by
-    # default or in +file+ if specified. The +file+ must be readable and
+    # default or in +file+ if specified. The `file` must be readable and
     # writable. Calling multiple times will add more files.
-    def handle_cookies(file = nil)
-      if file
-        path = Pathname(file).expand_path
-        unless File.exists?(file) and File.writable?(path.dirname)
+    #
+    # @todo the cookie jar and cookie file path options should be split
+    # @param file_path[String] path to an existing cookie jar file, or nil to store cookies in memory
+    # @return self
+    def handle_cookies(file_path = nil)
+      if file_path
+        path = Pathname(file_path).expand_path
+        
+        if !File.exists?(file_path) && !File.writable?(path.dirname)
           raise ArgumentError, "Can't create file #{path} (permission error)"
-        end
-        unless File.readable?(file) or File.writable?(path)
+        elsif File.exists?(file_path) && !File.writable?(file_path)
           raise ArgumentError, "Can't read or write file #{path} (permission error)"
         end
+      else
+        path = nil
       end
-      enable_cookie_session(path.to_s)
+      
+      # Apparently calling this with an empty string sets the cookie file,
+      # but calling it with a path to a writable file sets that file to be
+      # the cookie jar (new cookies are written there)
+      add_cookie_file(path.to_s)
+      
       self
     end
 
-    # Enable debug output to stderr or to specified +file+.
+    # Enable debug output to stderr or to specified `file`.
+    #
+    # @todo Change to an assignment of an IO object
+    # @param file[String, nil] path to the file to write debug data to, or `nil` to print to `STDERR`
+    # @return self
     def enable_debug(file = nil)
       set_debug_file(file.to_s)
+      self
     end
 
-    ###################################################################
-    ### Standard HTTP methods
-    ###
-
-    # Retrieve the contents of the specified +url+ optionally sending the
+    # Retrieve the contents of the specified `url` optionally sending the
     # specified headers. If the +base_url+ varaible is set then it is prepended
     # to the +url+ parameter. Any custom headers are merged with the contents
     # of the +headers+ instance variable. The results are returned in a
     # Response object.
-    # Notice: this method doesn't accept any +data+ argument: if you need to send data with
-    # a get request, please, use the #request method.
+    # Notice: this method doesn't accept any `data` argument: if you need to send a request body
+    # with a GET request, when using ElasticSearch for example, please, use the #request method.
+    #
+    # @param url[String] the URL to fetch
+    # @param headers[Hash] the hash of header keys to values
+    # @return [Patron::Response]
     def get(url, headers = {})
       request(:get, url, headers)
     end
 
     # Retrieve the contents of the specified +url+ as with #get, but the
-    # content at the URL is downloaded directly into the specified file.
+    # content at the URL is downloaded directly into the specified file. The file will be accessed
+    # by libCURL bypassing the Ruby runtime entirely.
+    #
+    # Note that when using this option, the Response object will have ++nil++ as the body, and you
+    # will need to read your target file for access to the body string).
+    #
+    # @param url[String] the URL to fetch
+    # @param filename[String] path to the file to save the response body in
+    # @return [Patron::Response]
     def get_file(url, filename, headers = {})
       request(:get, url, headers, :file => filename)
     end
 
-    # As #get but sends an HTTP HEAD request.
+    # Same as #get but performs a HEAD request.
+    #
+    # @see #get
+    # @param url[String] the URL to fetch
+    # @param headers[Hash] the hash of header keys to values
+    # @return [Patron::Response]
     def head(url, headers = {})
       request(:head, url, headers)
     end
 
-    # As #get but sends an HTTP DELETE request.
-    # Notice: this method doesn't accept any +data+ argument: if you need to send data with
-    # a delete request, please, use the #request method.
+    # Same as #get but performs a DELETE request.
+    #
+    # Notice: this method doesn't accept any `data` argument: if you need to send data with
+    # a delete request (as might be needed for ElasticSearch), please, use the #request method.
+    #
+    # @param url[String] the URL to fetch
+    # @param headers[Hash] the hash of header keys to values
+    # @return [Patron::Response]
     def delete(url, headers = {})
       request(:delete, url, headers)
     end
 
-    # Uploads the passed +data+ to the specified +url+ using HTTP PUT. +data+
-    # must be a string.
+    # Uploads the passed `data` to the specified `url` using an HTTP PUT. Note that
+    # unline ++post++, a Hash is not accepted as the ++data++ argument.
+    #
+    # @todo inconsistency with "post" - Hash not accepted
+    # @param url[String] the URL to fetch
+    # @param data[#to_s] an object that can be converted to a String to create the request body
+    # @param headers[Hash] the hash of header keys to values
+    # @return [Patron::Response]
     def put(url, data, headers = {})
       request(:put, url, headers, :data => data)
     end
 
-    # Uploads the contents of a file to the specified +url+ using HTTP PUT.
+    # Uploads the contents of `file` to the specified `url` using an HTTP PUT. The file will be
+    # sent "as-is" without any multipart encoding.
+    #
+    # @param url[String] the URL to fetch
+    # @param filename[String] path to the file to be uploaded
+    # @param headers[Hash] the hash of header keys to values
+    # @return [Patron::Response]
     def put_file(url, filename, headers = {})
       request(:put, url, headers, :file => filename)
     end
 
-    # Uploads the passed +data+ to the specified +url+ using HTTP POST. +data+
-    # can be a string or a hash.
+    # Uploads the passed `data` to the specified `url` using an HTTP POST.
+    #
+    # @param url[String] the URL to fetch
+    # @param data[Hash, #to_s] a Hash of form fields/values, or an object that can be converted to a String to create the request body
+    # @param headers[Hash] the hash of header keys to values
+    # @return [Patron::Response]
     def post(url, data, headers = {})
       if data.is_a?(Hash)
         data = data.map {|k,v| urlencode(k.to_s) + '=' + urlencode(v.to_s) }.join('&')
@@ -189,31 +257,52 @@ module Patron
       request(:post, url, headers, :data => data)
     end
 
-    # Uploads the contents of a file to the specified +url+ using HTTP POST.
+    # Uploads the contents of `file` to the specified `url` using an HTTP POST.
+    # The file will be sent "as-is" without any multipart encoding.
+    #
+    # @param url[String] the URL to fetch
+    # @param filename[String] path to the file to be uploaded
+    # @param headers[Hash] the hash of header keys to values
+    # @return [Patron::Response]
     def post_file(url, filename, headers = {})
       request(:post, url, headers, :file => filename)
     end
 
-    # Uploads the contents of a file and data to the specified +url+ using HTTP POST.
+    # Uploads the contents of `filename` to the specified `url` using an HTTP POST,
+    # in combination with given form fields passed in `data`.
+    #
+    # @param url[String] the URL to fetch
+    # @param data[Hash] hash of the form fields
+    # @param filename[String] path to the file to be uploaded
+    # @param headers[Hash] the hash of header keys to values
+    # @return [Patron::Response]
     def post_multipart(url, data, filename, headers = {})
       request(:post, url, headers, {:data => data, :file => filename, :multipart => true})
     end
 
-    ###################################################################
-    ### WebDAV methods
-    ###
 
+    # @!group WebDAV methods
     # Sends a WebDAV COPY request to the specified +url+.
+    #
+    # @param url[String] the URL to copy
+    # @param dest[String] the URL of the COPY destination
+    # @param headers[Hash] the hash of header keys to values
+    # @return [Patron::Response]
     def copy(url, dest, headers = {})
       headers['Destination'] = dest
       request(:copy, url, headers)
     end
-
-    ###################################################################
-    ### Basic API methods
-    ###
-
-    # Send an HTTP request to the specified +url+.
+    # @!endgroup
+    
+    # @!group Basic API methods
+    # Send an HTTP request to the specified `url`.
+    #
+    # @param action[#to_s] the HTTP verb
+    # @param url[String] the URL for the request
+    # @param headers[Hash] headers to send along with the request
+    # @param options[Hash] any additonal setters to call on the Request
+    # @see Patron::Request
+    # @return [Patron::Response]
     def request(action, url, headers, options = {})
       req = build_request(action, url, headers, options)
       handle_request(req)
@@ -227,11 +316,22 @@ module Patron
     # various headers/status codes. The method must return
     # a module that supports the same interface for +new+
     # as ++Patron::Response++
+    #
+    # @return [#new] Returns any object that responds to `.new` with 6 arguments
+    # @see Patron::Response#initialize
     def response_class
       ::Patron::Response
     end
     
-    # Build a request object that can be used in +handle_request+
+    # Builds a request object that can be used by ++handle_request++
+    # Note that internally, ++handle_request++ uses instance variables of
+    # the Request object, and not it's public methods.
+    #
+    # @param action[String] the HTTP verb
+    # @paran url[#to_s] the addition to the base url component, or a complete URL
+    # @paran headers[Hash] a hash of headers, "Accept" will be automatically set to an empty string if not provided
+    # @paran options[Hash] any overriding options (will shadow the options from the Session object)
+    # @return [Patron::Request] the request that will be passed to ++handle_request++
     def build_request(action, url, headers, options = {})
       # If the Expect header isn't set uploads are really slow
       headers['Expect'] ||= ''
@@ -270,5 +370,6 @@ module Patron
         req.url = url
       end
     end
+    # @!endgroup
   end
 end

data/lib/patron/util.rb

@@ -23,6 +23,7 @@
 ##
 ## -------------------------------------------------------------------
 
+
 module Patron
   module Util
     extend self

data/lib/patron/version.rb

@@ -1,3 +1,3 @@
 module Patron
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 end

data/patron.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency "rake-compiler", ">= 0.7.5"
   s.add_development_dependency "rspec", ">= 2.3.0"
   s.add_development_dependency "simplecov", ">= 0.10.0"
+  s.add_development_dependency "yard", "~> 0.8"
 
   s.files        = `git ls-files`.split("\n")
   s.executables  = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact

data/spec/patron_spec.rb

@@ -21,6 +21,8 @@
 ## THE SOFTWARE.
 ##
 ## -------------------------------------------------------------------
+
+
 require File.expand_path("./spec") + '/spec_helper.rb'
 
 describe Patron do

data/spec/request_spec.rb

@@ -21,6 +21,8 @@
 ## THE SOFTWARE.
 ##
 ## -------------------------------------------------------------------
+
+
 require File.expand_path("./spec") + '/spec_helper.rb'
 
 

data/spec/response_spec.rb

@@ -1,3 +1,6 @@
+# -*- coding: UTF-8 -*-
+# Encoding pragma is needed for loading this test properly on Ruby < 2.0
+
 ## -------------------------------------------------------------------
 ##
 ## Copyright (c) 2009 Phillip Toland <phil.toland@gmail.com>
@@ -21,6 +24,8 @@
 ## THE SOFTWARE.
 ##
 ## -------------------------------------------------------------------
+
+
 require File.expand_path("./spec") + '/spec_helper.rb'
 require 'webrick'
 require 'base64'

data/spec/session_spec.rb

@@ -21,6 +21,8 @@
 ## THE SOFTWARE.
 ##
 ## -------------------------------------------------------------------
+
+
 require File.expand_path("./spec") + '/spec_helper.rb'
 require 'webrick'
 require 'yaml'
@@ -286,6 +288,18 @@ describe Patron::Session do
     expect(body.header['authorization']).to be == [encode_authz("foo", "bar")]
   end
 
+  it "should store cookies across multiple requests" do
+    tf = Tempfile.new('cookiejar')
+    cookie_jar_path = tf.path
+    
+    @session.handle_cookies(cookie_jar_path)
+    response = @session.get("/setcookie").body
+    
+    cookie_jar_contents = tf.read
+    expect(cookie_jar_contents).not_to be_empty
+    expect(cookie_jar_contents).to include('Netscape HTTP Cookie File')
+  end
+  
   it "should handle cookies if set" do
     @session.handle_cookies
     response = @session.get("/setcookie").body
@@ -471,10 +485,12 @@ describe Patron::Session do
     it 'it should not clobber stderr' do
       rdev = STDERR.stat.rdev
 
-      @session.enable_debug
+      retval = @session.enable_debug
+      expect(retval).to eq(@session)
       expect(STDERR.stat.rdev).to be == rdev
 
-      @session.enable_debug
+      retval = @session.enable_debug
+      expect(retval).to eq(@session)
       expect(STDERR.stat.rdev).to be == rdev
     end
   end

data/spec/session_ssl_spec.rb

@@ -21,6 +21,8 @@
 ## THE SOFTWARE.
 ##
 ## -------------------------------------------------------------------
+
+
 require File.expand_path("./spec") + '/spec_helper.rb'
 require 'webrick'
 require 'yaml'
@@ -267,6 +269,15 @@ describe Patron::Session do
     end
   end
 
+  it "should raise when an unsupported or unknown SSL version is requested" do
+    ['something', 1].each do |version|
+      @session.ssl_version = version
+      expect {
+        @session.get("/test")
+      }.to raise_error(Patron::UnsupportedSSLVersion)
+    end
+  end
+  
   # ------------------------------------------------------------------------
   describe 'when debug is enabled' do
     it 'it should not clobber stderr' do

data/spec/spec_helper.rb

@@ -21,6 +21,8 @@
 ## THE SOFTWARE.
 ##
 ## -------------------------------------------------------------------
+
+
 if ENV["COVERAGE"]
   require 'simplecov'
   SimpleCov.start do

data/spec/support/test_server.rb

@@ -22,6 +22,8 @@
 ## THE SOFTWARE.
 ##
 ## -------------------------------------------------------------------
+
+
 require 'yaml'
 require 'webrick'
 require 'webrick/https'

data/spec/util_spec.rb

@@ -21,6 +21,8 @@
 ## THE SOFTWARE.
 ##
 ## -------------------------------------------------------------------
+
+
 require File.expand_path("./spec") + '/spec_helper.rb'
 
 describe Patron::Util do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: patron
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Phillip Toland
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-09 00:00:00.000000000 Z
+date: 2016-04-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.10.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 description: Ruby HTTP client library based on libcurl
 email:
 - phil.toland@gmail.com
@@ -77,6 +91,7 @@ files:
 - ".autotest"
 - ".gitignore"
 - ".rspec"
+- ".travis.yml"
 - Gemfile
 - Gemfile.lock
 - LICENSE
@@ -135,3 +150,4 @@ signing_key:
 specification_version: 4
 summary: Patron HTTP Client
 test_files: []
+has_rdoc: