ethon 0.5.3 → 0.5.4

data/CHANGELOG.md

@@ -2,7 +2,17 @@
 
 ## Master
 
-[Full Changelog](http://github.com/typhoeus/ethon/compare/v0.5.3...master)
+[Full Changelog](http://github.com/typhoeus/ethon/compare/v0.5.4...master)
+
+## 0.5.4
+
+[Full Changelog](http://github.com/typhoeus/ethon/compare/v0.5.3...v0.5.4)
+
+Enhancements:
+
+* Use Libc#getdtablesize to get the FDSet size.
+* New libcurl option accept_encoding.
+* Documentation updates.
 
 ## 0.5.3
 

data/lib/ethon/curls/classes.rb

@@ -17,15 +17,14 @@ module Ethon
 
     # :nodoc:
     class FDSet < ::FFI::Struct
-      # XXX how does this work on non-windows? how can curl know the new size...
-      FD_SETSIZE = ::Ethon::Libc.getdtablesize
-
       if Curl.windows?
         layout :fd_count, :u_int,
                :fd_array, [:u_int, 64] # 2048 FDs
 
         def clear; self[:fd_count] = 0; end
       else
+        # FD Set size.
+        FD_SETSIZE = ::Ethon::Libc.getdtablesize
         layout :fds_bits, [:long, FD_SETSIZE / ::FFI::Type::LONG.size]
 
         # :nodoc:

data/lib/ethon/curls/options.rb

@@ -133,7 +133,7 @@ module Ethon
           :nosignal                    =>  option_types[:long]            +  99,
           :share                       =>  option_types[:object_point]    +  100,
           :proxytype                   =>  option_types[:long]            +  101,
-          :encoding                    =>  option_types[:object_point]    +  102,
+          :accept_encoding             =>  option_types[:object_point]    +  102,
           :private                     =>  option_types[:object_point]    +  103,
           :unrestricted_auth           =>  option_types[:long]            +  105,
           :ftp_use_eprt                =>  option_types[:long]            +  106,

data/lib/ethon/easy.rb

@@ -193,7 +193,6 @@ module Ethon
     #   * :obsolete: These error codes will never be returned. They were used in an old
     #     libcurl version and are currently unused.
     #
-    #
     # @see http://curl.haxx.se/libcurl/c/libcurl-errors.html
     attr_accessor :return_code
 
@@ -219,591 +218,19 @@ module Ethon
 
     # Initialize a new Easy.
     # It initializes curl, if not already done and applies the provided options.
+    # Look into {Ethon::Easy::Options Options} to see what you can provide in the
+    # options hash.
     #
     # @example Create a new Easy.
     #   Easy.new(url: "www.google.de")
     #
     # @param [ Hash ] options The options to set.
-    #
-    # @option options :cainfo [String] Pass a char * to a zero terminated
-    #  string naming a file holding one or more certificates to verify
-    #  the peer with. This makes sense only when used in combination with
-    #  the CURLOPT_SSL_VERIFYPEER option. If CURLOPT_SSL_VERIFYPEER is
-    #  zero, CURLOPT_CAINFO need not even indicate an accessible file.
-    #  This option is by default set to the system path where libcurl's
-    #  cacert bundle is assumed to be stored, as established at build time.
-    #  When built against NSS, this is the directory that the NSS certificate
-    #  database resides in.
-    # @option options :capath [String]
-    #  Pass a char * to a zero terminated string naming a directory holding
-    #  multiple CA certificates to verify the peer with. If libcurl is built
-    #  against OpenSSL, the certificate directory must be prepared using the
-    #  openssl c_rehash utility. This makes sense only when used in
-    #  combination with the CURLOPT_SSL_VERIFYPEER option. If
-    #  CURLOPT_SSL_VERIFYPEER is zero, CURLOPT_CAPATH need not even indicate
-    #  an accessible path. The CURLOPT_CAPATH function apparently does not
-    #  work in Windows due to some limitation in openssl. This option is
-    #  OpenSSL-specific and does nothing if libcurl is built to use GnuTLS.
-    #  NSS-powered libcurl provides the option only for backward
-    #  compatibility.
-    # @option options :connecttimeout [Integer]
-    #  Pass a long. It should contain the maximum time in seconds that you
-    #  allow the connection to the server to take. This only limits the
-    #  connection phase, once it has connected, this option is of no more
-    #  use. Set to zero to switch to the default built-in connection timeout
-    #  \- 300 seconds. See also the CURLOPT_TIMEOUT option.
-    #  In unix-like systems, this might cause signals to be used unless
-    #  CURLOPT_NOSIGNAL is set.
-    # @option options :connecttimeout_ms [Integer]
-    #  Like CURLOPT_CONNECTTIMEOUT but takes the number of milliseconds
-    #  instead. If libcurl is built to use the standard system name
-    #  resolver, that portion of the connect will still use full-second
-    #  resolution for timeouts with a minimum timeout allowed of one second.
-    #  (Added in 7.16.2)
-    # @option options :copypostfields [String]
-    #  Pass a char * as parameter, which should be the full data to post in
-    #  a HTTP POST operation. It behaves as the CURLOPT_POSTFIELDS option,
-    #  but the original data are copied by the library, allowing the
-    #  application to overwrite the original data after setting this option.
-    #  Because data are copied, care must be taken when using this option in
-    #  conjunction with CURLOPT_POSTFIELDSIZE or
-    #  CURLOPT_POSTFIELDSIZE_LARGE: If the size has not been set prior to
-    #  CURLOPT_COPYPOSTFIELDS, the data are assumed to be a NUL-terminated
-    #  string; else the stored size informs the library about the data byte
-    #  count to copy. In any case, the size must not be changed after
-    #  CURLOPT_COPYPOSTFIELDS, unless another CURLOPT_POSTFIELDS or
-    #  CURLOPT_COPYPOSTFIELDS option is issued. (Added in 7.17.1)
-    # @option options :customrequest [String]
-    #  Pass a pointer to a zero terminated string as parameter. It can be
-    #  used to specify the request instead of GET or HEAD when performing
-    #  HTTP based requests, instead of LIST and NLST when performing FTP
-    #  directory listings and instead of LIST and RETR when issuing POP3
-    #  based commands. This is particularly useful, for example, for
-    #  performing a HTTP DELETE request or a POP3 DELE command.
-    #  Please don't perform this at will, on HTTP based requests, by making
-    #  sure your server supports the command you are sending first.
-    #  When you change the request method by setting CURLOPT_CUSTOMREQUEST
-    #  to something, you don't actually change how libcurl behaves or acts
-    #  in regards to the particular request method, it will only change the
-    #  actual string sent in the request.
-    #  For example:
-    #  With the HTTP protocol when you tell libcurl to do a HEAD request,
-    #  but then specify a GET though a custom request libcurl will still act
-    #  as if it sent a HEAD. To switch to a proper HEAD use CURLOPT_NOBODY,
-    #  to switch to a proper POST use CURLOPT_POST or CURLOPT_POSTFIELDS and
-    #  to switch to a proper GET use CURLOPT_HTTPGET.
-    #  With the POP3 protocol when you tell libcurl to use a custom request
-    #  it will behave like a LIST or RETR command was sent where it expects
-    #  data to be returned by the server. As such CURLOPT_NOBODY should be
-    #  used when specifying commands such as DELE and NOOP for example.
-    #  Restore to the internal default by setting this to NULL.
-    #  Many people have wrongly used this option to replace the entire
-    #  request with their own, including multiple headers and POST contents.
-    #  While that might work in many cases, it will cause libcurl to send
-    #  invalid requests and it could possibly confuse the remote server
-    #  badly. Use CURLOPT_POST and CURLOPT_POSTFIELDS to set POST data. Use
-    #  CURLOPT_HTTPHEADER to replace or extend the set of headers sent by
-    #  libcurl. Use CURLOPT_HTTP_VERSION to change HTTP version.
-    #  (Support for POP3 added in 7.26.0)
-    # @option options :dns_cache_timeout [Integer]
-    #  Pass a long, this sets the timeout in seconds. Name resolves will be
-    #  kept in memory for this number of seconds. Set to zero to completely
-    #  disable caching, or set to -1 to make the cached entries remain
-    #  forever. By default, libcurl caches this info for 60 seconds.
-    #  The name resolve functions of various libc implementations don't
-    #  re-read name server information unless explicitly told so (for
-    #  example, by calling res_init(3)). This may cause libcurl to keep
-    #  using the older server even if DHCP has updated the server info, and
-    #  this may look like a DNS cache issue to the casual libcurl-app user.
-    # @option options :followlocation [Boolean]
-    #  A parameter set to 1 tells the library to follow any Location: header
-    #  that the server sends as part of a HTTP header.
-    #  This means that the library will re-send the same request on the new
-    #  location and follow new Location: headers all the way until no more
-    #  such headers are returned. CURLOPT_MAXREDIRS can be used to limit the
-    #  number of redirects libcurl will follow.
-    #  Since 7.19.4, libcurl can limit what protocols it will automatically
-    #  follow. The accepted protocols are set with CURLOPT_REDIR_PROTOCOLS
-    #  and it excludes the FILE protocol by default.
-    # @option options :forbid_reuse [Boolean]
-    #  Pass a long. Set to 1 to make the next transfer explicitly close the
-    #  connection when done. Normally, libcurl keeps all connections alive
-    #  when done with one transfer in case a succeeding one follows that can
-    #  re-use them. This option should be used with caution and only if you
-    #  understand what it does. Set to 0 to have libcurl keep the connection
-    #  open for possible later re-use (default behavior).
-    # @option options :httpauth [String]
-    #  Pass a long as parameter, which is set to a bitmask, to tell libcurl
-    #  which authentication method(s) you want it to use. The available bits
-    #  are listed below. If more than one bit is set, libcurl will first
-    #  query the site to see which authentication methods it supports and
-    #  then pick the best one you allow it to use. For some methods, this
-    #  will induce an extra network round-trip. Set the actual name and
-    #  password with the CURLOPT_USERPWD option or with the CURLOPT_USERNAME
-    #  and the CURLOPT_PASSWORD options. (Added in 7.10.6)
-    # @option options :httpget [Boolean]
-    #  Pass a long. If the long is 1, this forces the HTTP request to get
-    #  back to GET. Usable if a POST, HEAD, PUT, or a custom request has
-    #  been used previously using the same curl handle.
-    #  When setting CURLOPT_HTTPGET to 1, it will automatically set
-    #  CURLOPT_NOBODY to 0 (since 7.14.1).
-    # @option options :httppost [String]
-    #  Tells libcurl you want a multipart/formdata HTTP POST to be made and
-    #  you instruct what data to pass on to the server. Pass a pointer to a
-    #  linked list of curl_httppost structs as parameter. The easiest way to
-    #  create such a list, is to use curl_formadd(3) as documented. The data
-    #  in this list must remain intact until you close this curl handle
-    #  again with curl_easy_cleanup(3).
-    #  Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue"
-    #  header. You can disable this header with CURLOPT_HTTPHEADER as usual.
-    #  When setting CURLOPT_HTTPPOST, it will automatically set
-    #  CURLOPT_NOBODY to 0 (since 7.14.1).
-    # @option options :infilesize [Integer]
-    #  When uploading a file to a remote site, this option should be used to
-    #  tell libcurl what the expected size of the infile is. This value
-    #  should be passed as a long. See also CURLOPT_INFILESIZE_LARGE.
-    #  For uploading using SCP, this option or CURLOPT_INFILESIZE_LARGE is
-    #  mandatory.
-    #  When sending emails using SMTP, this command can be used to specify
-    #  the optional SIZE parameter for the MAIL FROM command. (Added in
-    #  7.23.0)
-    #  This option does not limit how much data libcurl will actually send,
-    #  as that is controlled entirely by what the read callback returns.
-    # @option options :interface [String]
-    #  Pass a char * as parameter. This sets the interface name to use as
-    #  outgoing network interface. The name can be an interface name, an IP
-    #  address, or a host name.
-    #  Starting with 7.24.0: If the parameter starts with "if!" then it is
-    #  treated as only as interface name and no attempt will ever be named
-    #  to do treat it as an IP address or to do name resolution on it. If
-    #  the parameter starts with "host!" it is treated as either an IP
-    #  address or a hostname. Hostnames are resolved synchronously. Using
-    #  the if! format is highly recommended when using the multi interfaces
-    #  to avoid allowing the code to block. If "if!" is specified but the
-    #  parameter does not match an existing interface,
-    #  CURLE_INTERFACE_FAILED is returned.
-    # @option options :keypasswd [String]
-    #  Pass a pointer to a zero terminated string as parameter. It will be
-    #  used as the password required to use the CURLOPT_SSLKEY or
-    #  CURLOPT_SSH_PRIVATE_KEYFILE private key. You never needed a pass
-    #  phrase to load a certificate but you need one to load your private key.
-    #  (This option was known as CURLOPT_SSLKEYPASSWD up to 7.16.4 and
-    #  CURLOPT_SSLCERTPASSWD up to 7.9.2)
-    # @option options :maxredirs [Integer]
-    #  Pass a long. The set number will be the redirection limit. If that
-    #  many redirections have been followed, the next redirect will cause an
-    #  error (CURLE_TOO_MANY_REDIRECTS). This option only makes sense if the
-    #  CURLOPT_FOLLOWLOCATION is used at the same time. Added in 7.15.1:
-    #  Setting the limit to 0 will make libcurl refuse any redirect. Set it
-    #  to -1 for an infinite number of redirects (which is the default)
-    # @option options :nobody [Boolean]
-    #  A parameter set to 1 tells the library to not include the body-part
-    #  in the output. This is only relevant for protocols that have separate
-    #  header and body parts. On HTTP(S) servers, this will make libcurl do
-    #  a HEAD request.
-    #  To change request to GET, you should use CURLOPT_HTTPGET. Change
-    #  request to POST with CURLOPT_POST etc.
-    # @option options :nosignal [Boolean]
-    #  Pass a long. If it is 1, libcurl will not use any functions that
-    #  install signal handlers or any functions that cause signals to be
-    #  sent to the process. This option is mainly here to allow
-    #  multi-threaded unix applications to still set/use all timeout options
-    #  etc, without risking getting signals. (Added in 7.10)
-    #  If this option is set and libcurl has been built with the standard
-    #  name resolver, timeouts will not occur while the name resolve takes
-    #  place. Consider building libcurl with c-ares support to enable
-    #  asynchronous DNS lookups, which enables nice timeouts for name
-    #  resolves without signals.
-    #  Setting CURLOPT_NOSIGNAL to 1 makes libcurl NOT ask the system to
-    #  ignore SIGPIPE signals, which otherwise are sent by the system when
-    #  trying to send data to a socket which is closed in the other end.
-    #  libcurl makes an effort to never cause such SIGPIPEs to trigger, but
-    #  some operating systems have no way to avoid them and even on those
-    #  that have there are some corner cases when they may still happen,
-    #  contrary to our desire. In addition, using CURLAUTH_NTLM_WB
-    #  authentication could cause a SIGCHLD signal to be raised.
-    # @option options :postfieldsize [Integer]
-    #  If you want to post data to the server without letting libcurl do a
-    #  strlen() to measure the data size, this option must be used. When
-    #  this option is used you can post fully binary data, which otherwise
-    #  is likely to fail. If this size is set to -1, the library will use
-    #  strlen() to get the size.
-    # @option options :proxy [String]
-    #  Set HTTP proxy to use. The parameter should be a char * to a zero
-    #  terminated string holding the host name or dotted IP address. To
-    #  specify port number in this string, append :[port] to the end of the
-    #  host name. The proxy string may be prefixed with [protocol]:// since
-    #  any such prefix will be ignored. The proxy's port number may
-    #  optionally be specified with the separate option. If not specified,
-    #  libcurl will default to using port 1080 for proxies.
-    #  CURLOPT_PROXYPORT.
-    #  When you tell the library to use a HTTP proxy, libcurl will
-    #  transparently convert operations to HTTP even if you specify an FTP
-    #  URL etc. This may have an impact on what other features of the
-    #  library you can use, such as CURLOPT_QUOTE and similar FTP specifics
-    #  that don't work unless you tunnel through the HTTP proxy. Such
-    #  tunneling is activated with CURLOPT_HTTPPROXYTUNNEL.
-    #  libcurl respects the environment variables http_proxy, ftp_proxy,
-    #  all_proxy etc, if any of those are set. The CURLOPT_PROXY option does
-    #  however override any possibly set environment variables.
-    #  Setting the proxy string to "" (an empty string) will explicitly
-    #  disable the use of a proxy, even if there is an environment variable
-    #  set for it.
-    #  Since 7.14.1, the proxy host string given in environment variables
-    #  can be specified the exact same way as the proxy can be set with
-    #  CURLOPT_PROXY, include protocol prefix (http://) and embedded user +
-    #  password.
-    #  Since 7.21.7, the proxy string may be specified with a protocol://
-    #  prefix to specify alternative proxy protocols. Use socks4://,
-    #  socks4a://, socks5:// or socks5h:// (the last one to enable socks5
-    #  and asking the proxy to do the resolving, also known as
-    #  CURLPROXY_SOCKS5_HOSTNAME type) to request the specific SOCKS version
-    #  to be used. No protocol specified, http:// and all others will be
-    #  treated as HTTP proxies.
-    # @option options :proxyauth [String]
-    #  Pass a long as parameter, which is set to a bitmask, to tell libcurl
-    #  which authentication method(s) you want it to use for your proxy
-    #  authentication. If more than one bit is set, libcurl will first query
-    #  the site to see what authentication methods it supports and then pick
-    #  the best one you allow it to use. For some methods, this will induce
-    #  an extra network round-trip. Set the actual name and password with
-    #  the CURLOPT_PROXYUSERPWD option. The bitmask can be constructed by
-    #  or'ing together the bits listed above for the CURLOPT_HTTPAUTH
-    #  option. As of this writing, only Basic, Digest and NTLM work. (Added
-    #  in 7.10.7)
-    # @option options :proxytype [String]
-    #  Pass a long with this option to set type of the proxy. Available
-    #  options for this are CURLPROXY_HTTP, CURLPROXY_HTTP_1_0 (added in
-    #  7.19.4), CURLPROXY_SOCKS4 (added in 7.10), CURLPROXY_SOCKS5,
-    #  CURLPROXY_SOCKS4A (added in 7.18.0) and CURLPROXY_SOCKS5_HOSTNAME
-    #  (added in 7.18.0). The HTTP type is default. (Added in 7.10)
-    #  If you set CURLOPT_PROXYTYPE to CURLPROXY_HTTP_1_0, it will only
-    #  affect how libcurl speaks to a proxy when CONNECT is used. The HTTP
-    #  version used for "regular" HTTP requests is instead controlled with
-    #  CURLOPT_HTTP_VERSION.
-    # @option options :proxyport [Integer]
-    #  Pass a long with this option to set the proxy port to connect to
-    #  unless it is specified in the proxy string CURLOPT_PROXY.
-    # @option options :proxyuserpwd [String]
-    #  Pass a char * as parameter, which should be [user name]:[password]
-    #  to use for the connection to the HTTP proxy. Use CURLOPT_PROXYAUTH
-    #  to decide the authentication method.
-    # @option options :readdata [String]
-    #  Data pointer to pass to the file read function. If you use the
-    #  CURLOPT_READFUNCTION option, this is the pointer you'll get as input.
-    #  If you don't specify a read callback but instead rely on the default
-    #  internal read function, this data must be a valid readable FILE *.
-    #  If you're using libcurl as a win32 DLL, you MUST use a
-    #  CURLOPT_READFUNCTION if you set this option.
-    #  This option was also known by the older name CURLOPT_INFILE,
-    #  the name CURLOPT_READDATA was introduced in 7.9.7.
-    # @option options :readfunction [String]
-    #  Pass a pointer to a function that matches the following prototype:
-    #  size_t function( void *ptr, size_t size, size_t nmemb, void
-    #  *userdata); This function gets called by libcurl as soon as it needs
-    #  to read data in order to send it to the peer. The data area pointed
-    #  at by the pointer ptr may be filled with at most size multiplied with
-    #  nmemb number of bytes. Your function must return the actual number of
-    #  bytes that you stored in that memory area. Returning 0 will signal
-    #  end-of-file to the library and cause it to stop the current transfer.
-    #  If you stop the current transfer by returning 0 "pre-maturely" (i.e
-    #  before the server expected it, like when you've said you will upload
-    #  N bytes and you upload less than N bytes), you may experience that
-    #  the server "hangs" waiting for the rest of the data that won't come.
-    #  The read callback may return CURL_READFUNC_ABORT to stop the current
-    #  operation immediately, resulting in a CURLE_ABORTED_BY_CALLBACK error
-    #  code from the transfer (Added in 7.12.1)
-    #  From 7.18.0, the function can return CURL_READFUNC_PAUSE which then
-    #  will cause reading from this connection to become paused. See
-    #  curl_easy_pause(3) for further details.
-    #  Bugs: when doing TFTP uploads, you must return the exact amount of
-    #  data that the callback wants, or it will be considered the final
-    #  packet by the server end and the transfer will end there.
-    #  If you set this callback pointer to NULL, or don't set it at all, the
-    #  default internal read function will be used. It is doing an fread()
-    #  on the FILE * userdata set with CURLOPT_READDATA.
-    # @option options :ssl_verifyhost [Integer]
-    #  Pass a long as parameter.
-    #  This option determines whether libcurl verifies that the server cert
-    #  is for the server it is known as.
-    #  When negotiating a SSL connection, the server sends a certificate
-    #  indicating its identity.
-    #  When CURLOPT_SSL_VERIFYHOST is 2, that certificate must indicate that
-    #  the server is the server to which you meant to connect, or the
-    #  connection fails.
-    #  Curl considers the server the intended one when the Common Name field
-    #  or a Subject Alternate Name field in the certificate matches the host
-    #  name in the URL to which you told Curl to connect.
-    #  When the value is 1, the certificate must contain a Common Name
-    #  field, but it doesn't matter what name it says. (This is not
-    #  ordinarily a useful setting).
-    #  When the value is 0, the connection succeeds regardless of the names
-    #  in the certificate.
-    #  The default value for this option is 2.
-    #  This option controls checking the server's certificate's claimed
-    #  identity. The server could be lying. To control lying, see
-    #  CURLOPT_SSL_VERIFYPEER. If libcurl is built against NSS and
-    #  CURLOPT_SSL_VERIFYPEER is zero, CURLOPT_SSL_VERIFYHOST is ignored.
-    # @option options :ssl_verifypeer [Boolean]
-    #  Pass a long as parameter. By default, curl assumes a value of 1.
-    #  This option determines whether curl verifies the authenticity of the
-    #  peer's certificate. A value of 1 means curl verifies; 0 (zero) means
-    #  it doesn't.
-    #  When negotiating a SSL connection, the server sends a certificate
-    #  indicating its identity. Curl verifies whether the certificate is
-    #  authentic, i.e. that you can trust that the server is who the
-    #  certificate says it is. This trust is based on a chain of digital
-    #  signatures, rooted in certification authority (CA) certificates you
-    #  supply. curl uses a default bundle of CA certificates (the path for
-    #  that is determined at build time) and you can specify alternate
-    #  certificates with the CURLOPT_CAINFO option or the CURLOPT_CAPATH
-    #  option.
-    #  When CURLOPT_SSL_VERIFYPEER is nonzero, and the verification fails to
-    #  prove that the certificate is authentic, the connection fails. When
-    #  the option is zero, the peer certificate verification succeeds
-    #  regardless.
-    #  Authenticating the certificate is not by itself very useful. You
-    #  typically want to ensure that the server, as authentically identified
-    #  by its certificate, is the server you mean to be talking to. Use
-    #  CURLOPT_SSL_VERIFYHOST to control that. The check that the host name
-    #  in the certificate is valid for the host name you're connecting to is
-    #  done independently of the CURLOPT_SSL_VERIFYPEER option.
-    # @option options :sslcert [String]
-    #  Pass a pointer to a zero terminated string as parameter. The string
-    #  should be the file name of your certificate. The default format is
-    #  "PEM" and can be changed with CURLOPT_SSLCERTTYPE.
-    #  With NSS this can also be the nickname of the certificate you wish to
-    #  authenticate with. If you want to use a file from the current
-    #  directory, please precede it with "./" prefix, in order to avoid
-    #  confusion with a nickname.
-    # @option options :sslcerttype [String]
-    #  Pass a pointer to a zero terminated string as parameter. The string
-    #  should be the format of your certificate. Supported formats are "PEM"
-    #  and "DER". (Added in 7.9.3)
-    # @option options :sslkey [String]
-    #  Pass a pointer to a zero terminated string as parameter. The string
-    #  should be the file name of your private key. The default format is
-    #  "PEM" and can be changed with CURLOPT_SSLKEYTYPE.
-    # @option options :sslkeytype [String]
-    #  Pass a pointer to a zero terminated string as parameter. The string
-    #  should be the format of your private key. Supported formats are
-    #  "PEM", "DER" and "ENG".
-    #  The format "ENG" enables you to load the private key from a crypto
-    #  engine. In this case CURLOPT_SSLKEY is used as an identifier passed
-    #  to the engine. You have to set the crypto engine with
-    #  CURLOPT_SSLENGINE. "DER" format key file currently does not work
-    #  because of a bug in OpenSSL.
-    # @option options :sslversion [String]
-    #  Pass a long as parameter to control what version of SSL/TLS to
-    #  attempt to use. The available options are:
-    # @option options :timeout [Integer]
-    #  Pass a long as parameter containing the maximum time in seconds that
-    #  you allow the libcurl transfer operation to take. Normally, name
-    #  lookups can take a considerable time and limiting operations to less
-    #  than a few minutes risk aborting perfectly normal operations. This
-    #  option will cause curl to use the SIGALRM to enable time-outing
-    #  system calls.
-    #  In unix-like systems, this might cause signals to be used unless
-    #  CURLOPT_NOSIGNAL is set.
-    #  Default timeout is 0 (zero) which means it never times out.
-    # @option options :timeout_ms [Integer]
-    #  Like CURLOPT_TIMEOUT but takes number of milliseconds instead. If
-    #  libcurl is built to use the standard system name resolver, that
-    #  portion of the transfer will still use full-second resolution for
-    #  timeouts with a minimum timeout allowed of one second. (Added in
-    #  7.16.2)
-    # @option options :upload [Boolean]
-    #  A parameter set to 1 tells the library to prepare for an upload. The
-    #  CURLOPT_READDATA and CURLOPT_INFILESIZE or CURLOPT_INFILESIZE_LARGE
-    #  options are also interesting for uploads. If the protocol is HTTP,
-    #  uploading means using the PUT request unless you tell libcurl
-    #  otherwise.
-    #  Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue"
-    #  header. You can disable this header with CURLOPT_HTTPHEADER as usual.
-    #  If you use PUT to a HTTP 1.1 server, you can upload data without
-    #  knowing the size before starting the transfer if you use chunked
-    #  encoding. You enable this by adding a header like "Transfer-Encoding:
-    #  chunked" with CURLOPT_HTTPHEADER. With HTTP 1.0 or without chunked
-    #  transfer, you must specify the size.
-    # @option options :url [String]
-    #  Pass in a pointer to the actual URL to deal with. The parameter
-    #  should be a char * to a zero terminated string which must be
-    #  URL-encoded in the following format:
-    #  scheme://host:port/path
-    #  For a greater explanation of the format please see RFC 3986.
-    #  If the given URL lacks the scheme, or protocol, part ("http://" or
-    #  "ftp://" etc), libcurl will attempt to resolve which protocol to use
-    #  based on the given host mame. If the protocol is not supported,
-    #  libcurl will return (CURLE_UNSUPPORTED_PROTOCOL) when you call
-    #  curl_easy_perform(3) or curl_multi_perform(3). Use
-    #  curl_version_info(3) for detailed information on which protocols are
-    #  supported.
-    #  The host part of the URL contains the address of the server that you
-    #  want to connect to. This can be the fully qualified domain name of
-    #  the server, the local network name of the machine on your network or
-    #  the IP address of the server or machine represented by either an IPv4
-    #  or IPv6 address. For example:
-    #  http://www.example.com/
-    #  http://hostname/
-    #  http://192.168.0.1/
-    #  http://[2001:1890:1112:1::20]/
-    #  It is also possible to specify the user name and password as part of
-    #  the host, for some protocols, when connecting to servers that require
-    #  authentication.
-    #  For example the following types of authentication support this:
-    #  http://user:password@www.example.com
-    #  ftp://user:password@ftp.example.com
-    #  pop3://user:password@mail.example.com
-    #  The port is optional and when not specified libcurl will use the
-    #  default port based on the determined or specified protocol: 80 for
-    #  HTTP, 21 for FTP and 25 for SMTP, etc. The following examples show
-    #  how to specify the port:
-    #  http://www.example.com:8080/ - This will connect to a web server
-    #  using port 8080 rather than 80.
-    #  smtp://mail.example.com:587/ - This will connect to a SMTP server on
-    #  the alternative mail port.
-    #  The path part of the URL is protocol specific and whilst some
-    #  examples are given below this list is not conclusive:
-    #  HTTP
-    #  The path part of a HTTP request specifies the file to retrieve and
-    #  from what directory. If the directory is not specified then the web
-    #  server's root directory is used. If the file is omitted then the
-    #  default document will be retrieved for either the directory specified
-    #  or the root directory. The exact resource returned for each URL is
-    #  entirely dependent on the server's configuration.
-    #  http://www.example.com - This gets the main page from the web server.
-    #  http://www.example.com/index.html - This returns the main page by
-    #  explicitly requesting it.
-    #  http://www.example.com/contactus/ - This returns the default document
-    #  from the contactus directory.
-    #  FTP
-    #  The path part of an FTP request specifies the file to retrieve and
-    #  from what directory. If the file part is omitted then libcurl
-    #  downloads the directory listing for the directory specified. If the
-    #  directory is omitted then the directory listing for the root / home
-    #  directory will be returned.
-    #  ftp://ftp.example.com - This retrieves the directory listing for the
-    #  root directory.
-    #  ftp://ftp.example.com/readme.txt - This downloads the file readme.txt
-    #  from the root directory.
-    #  ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt
-    #  from the libcurl directory.
-    #  ftp://user:password@ftp.example.com/readme.txt - This retrieves the
-    #  readme.txt file from the user's home directory. When a username and
-    #  password is specified, everything that is specified in the path part
-    #  is relative to the user's home directory. To retrieve files from the
-    #  root directory or a directory underneath the root directory then the
-    #  absolute path must be specified by prepending an additional forward
-    #  slash to the beginning of the path.
-    #  ftp://user:password@ftp.example.com//readme.txt - This retrieves the
-    #  readme.txt from the root directory when logging in as a specified
-    #  user.
-    #  SMTP
-    #  The path part of a SMTP request specifies the host name to present
-    #  during communication with the mail server. If the path is omitted
-    #  then libcurl will attempt to resolve the local computer's host name.
-    #  However, this may not return the fully qualified domain name that is
-    #  required by some mail servers and specifying this path allows you to
-    #  set an alternative name, such as your machine's fully qualified
-    #  domain name, which you might have obtained from an external function
-    #  such as gethostname or getaddrinfo.
-    #  smtp://mail.example.com - This connects to the mail server at
-    #  example.com and sends your local computer's host name in the HELO /
-    #  EHLO command.
-    #  smtp://mail.example.com/client.example.com - This will send
-    #  client.example.com in the HELO / EHLO command to the mail server at
-    #  example.com.
-    #  POP3
-    #  The path part of a POP3 request specifies the mailbox (message) to
-    #  retrieve. If the mailbox is not specified then a list of waiting
-    #  messages is returned instead.
-    #  pop3://user:password@mail.example.com - This lists the available
-    #  messages pop3://user:password@mail.example.com/1 - This retrieves the
-    #  first message
-    #  SCP
-    #  The path part of a SCP request specifies the file to retrieve and
-    #  from what directory. The file part may not be omitted. The file is
-    #  taken as an absolute path from the root directory on the server. To
-    #  specify a path relative to the user's home directory on the server,
-    #  prepend ~/ to the path portion. If the user name is not embedded in
-    #  the URL, it can be set with the CURLOPT_USERPWD or CURLOPT_USERNAME
-    #  option.
-    #  scp://user@example.com/etc/issue - This specifies the file /etc/issue
-    #  scp://example.com/~/my-file - This specifies the file my-file in the
-    #  user's home directory on the server
-    #  SFTP
-    #  The path part of a SFTP request specifies the file to retrieve and
-    #  from what directory. If the file part is omitted then libcurl
-    #  downloads the directory listing for the directory specified. If the
-    #  path ends in a / then a directory listing is returned instead of a
-    #  file. If the path is omitted entirely then the directory listing for
-    #  the root / home directory will be returned. If the user name is not
-    #  embedded in the URL, it can be set with the CURLOPT_USERPWD or
-    #  CURLOPT_USERNAME option.
-    #  sftp://user:password@example.com/etc/issue - This specifies the file
-    #  /etc/issue
-    #  sftp://user@example.com/~/my-file - This specifies the file my-file
-    #  in the user's home directory
-    #  sftp://ssh.example.com/~/Documents/ - This requests a directory
-    #  listing of the Documents directory under the user's home directory
-    #  LDAP
-    #  The path part of a LDAP request can be used to specify the:
-    #  Distinguished Name, Attributes, Scope, Filter and Extension for a
-    #  LDAP search. Each field is separated by a question mark and when that
-    #  field is not required an empty string with the question mark
-    #  separator should be included.
-    #  ldap://ldap.example.com/o=My%20Organisation - This will perform a
-    #  LDAP search with the DN as My Organisation.
-    #  ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will
-    #  perform the same search but will only return postalAddress attributes.
-    #  ldap://ldap.example.com/?rootDomainNamingContext - This specifies an
-    #  empty DN and requests information about the rootDomainNamingContext
-    #  attribute for an Active Directory server.
-    #  For more information about the individual components of a LDAP URL
-    #  please see RFC 4516.
-    #  NOTES
-    #  Starting with version 7.20.0, the fragment part of the URI will not
-    #  be sent as part of the path, which was previously the case.
-    #  CURLOPT_URL is the only option that must be set before
-    #  curl_easy_perform(3) is called.
-    #  CURLOPT_PROTOCOLS can be used to limit what protocols libcurl will
-    #  use for this transfer, independent of what libcurl has been compiled
-    #  to support. That may be useful if you accept the URL from an external
-    #  source and want to limit the accessibility.
-    # @option options :useragent [String]
-    #  Pass a pointer to a zero terminated string as parameter. It will be
-    #  used to set the User-Agent: header in the http request sent to the
-    #  remote server. This can be used to fool servers or scripts. You can
-    #  also set any custom header with CURLOPT_HTTPHEADER.
-    # @option options :userpwd [String]
-    #  Pass a char * as parameter, which should be [user name]:[password] to
-    #  use for the connection. Use CURLOPT_HTTPAUTH to decide the
-    #  authentication method.
-    #  When using NTLM, you can set the domain by prepending it to the user
-    #  name and separating the domain and name with a forward (/) or
-    #  backward slash (\). Like this: "domain/user:password" or
-    #  "domain\user:password". Some HTTP servers (on Windows) support this
-    #  style even for Basic authentication.
-    #  When using HTTP and CURLOPT_FOLLOWLOCATION, libcurl might perform
-    #  several requests to possibly different hosts. libcurl will only send
-    #  this user and password information to hosts using the initial host
-    #  name (unless CURLOPT_UNRESTRICTED_AUTH is set), so if libcurl follows
-    #  locations to other hosts it will not send the user and password to
-    #  those. This is enforced to prevent accidental information leakage.
-    # @option options :verbose [Boolean]
-    #  Set the parameter to 1 to get the library to display a lot of verbose
-    #  information about its operations. Very useful for libcurl and/or
-    #  protocol debugging and understanding. The verbose information will be
-    #  sent to stderr, or the stream set with CURLOPT_STDERR.
-    #  You hardly ever want this set in production use, you will almost
-    #  always want this when you debug/report problems. Another neat option
-    #  for debugging is the CURLOPT_DEBUGFUNCTION.
+    # @option options :headers [ Hash ] Request headers.
     #
     # @return [ Easy ] A new Easy.
     #
+    # @see Ethon::Easy::Options
     # @see http://curl.haxx.se/libcurl/c/curl_easy_setopt.html
-    #
-    # @api public
     def initialize(options = {})
       Curl.init
       ObjectSpace.define_finalizer(self, self.class.finalizer(self))
@@ -821,8 +248,6 @@ module Ethon
     # @raise InvalidOption
     #
     # @see initialize
-    #
-    # @api private
     def set_attributes(options)
       options.each_pair do |key, value|
         unless respond_to?("#{key}=")