ruby-ethon 0.7.0-1 / usr / lib / ruby / vendor_ruby / ethon / easy.rb

require 'ethon/easy/informations'
require 'ethon/easy/callbacks'
require 'ethon/easy/options'
require 'ethon/easy/header'
require 'ethon/easy/util'
require 'ethon/easy/params'
require 'ethon/easy/form'
require 'ethon/easy/http'
require 'ethon/easy/operations'
require 'ethon/easy/response_callbacks'
require 'ethon/easy/debug_info'
require 'ethon/easy/mirror'

module Ethon

  # This is the class representing the libcurl easy interface
  # See http://curl.haxx.se/libcurl/c/libcurl-easy.html for more informations.
  #
  # @example You can access the libcurl easy interface through this class, every request is based on it. The simplest setup looks like that:
  #
  #   e = Ethon::Easy.new(url: "www.example.com")
  #   e.perform
  #   #=> :ok
  #
  # @example You can the reuse this Easy for the next request:
  #
  #   e.reset # reset easy handle
  #   e.url = "www.google.com"
  #   e.followlocation = true
  #   e.perform
  #   #=> :ok
  #
  # @see initialize
  class Easy
    include Ethon::Easy::Informations
    include Ethon::Easy::Callbacks
    include Ethon::Easy::Options
    include Ethon::Easy::Header
    include Ethon::Easy::Http
    include Ethon::Easy::Operations
    include Ethon::Easy::ResponseCallbacks

    # Returns the curl return code.
    #
    # @return [ Symbol ] The return code.
    #   * :ok: All fine. Proceed as usual.
    #   * :unsupported_protocol: The URL you passed to libcurl used a
    #     protocol that this libcurl does not support. The support
    #     might be a compile-time option that you didn't use, it can
    #     be a misspelled protocol string or just a protocol
    #     libcurl has no code for.
    #   * :failed_init: Very early initialization code failed. This
    #     is likely to be an internal error or problem, or a
    #     resource problem where something fundamental couldn't
    #     get done at init time.
    #   * :url_malformat: The URL was not properly formatted.
    #   * :not_built_in: A requested feature, protocol or option
    #     was not found built-in in this libcurl due to a build-time
    #     decision. This means that a feature or option was not enabled
    #     or explicitly disabled when libcurl was built and in
    #     order to get it to function you have to get a rebuilt libcurl.
    #   * :couldnt_resolve_proxy: Couldn't resolve proxy. The given
    #     proxy host could not be resolved.
    #   * :couldnt_resolve_host: Couldn't resolve host. The given remote
    #     host was not resolved.
    #   * :couldnt_connect: Failed to connect() to host or proxy.
    #   * :ftp_weird_server_reply: After connecting to a FTP server,
    #     libcurl expects to get a certain reply back. This error
    #     code implies that it got a strange or bad reply. The given
    #     remote server is probably not an OK FTP server.
    #   * :remote_access_denied: We were denied access to the resource
    #     given in the URL. For FTP, this occurs while trying to
    #     change to the remote directory.
    #   * :ftp_accept_failed: While waiting for the server to connect
    #     back when an active FTP session is used, an error code was
    #     sent over the control connection or similar.
    #   * :ftp_weird_pass_reply: After having sent the FTP password to
    #     the server, libcurl expects a proper reply. This error code
    #     indicates that an unexpected code was returned.
    #   * :ftp_accept_timeout: During an active FTP session while
    #     waiting for the server to connect, the CURLOPT_ACCEPTTIMOUT_MS
    #     (or the internal default) timeout expired.
    #   * :ftp_weird_pasv_reply: libcurl failed to get a sensible result
    #     back from the server as a response to either a PASV or a
    #     EPSV command. The server is flawed.
    #   * :ftp_weird_227_format: FTP servers return a 227-line as a response
    #     to a PASV command. If libcurl fails to parse that line,
    #     this return code is passed back.
    #   * :ftp_cant_get_host: An internal failure to lookup the host used
    #     for the new connection.
    #   * :ftp_couldnt_set_type: Received an error when trying to set
    #     the transfer mode to binary or ASCII.
    #   * :partial_file: A file transfer 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.
    #   * :ftp_couldnt_retr_file: This was either a weird reply to a
    #     'RETR' command or a zero byte transfer complete.
    #   * :quote_error: When sending custom "QUOTE" commands to the
    #     remote server, one of the commands returned an error code that
    #     was 400 or higher (for FTP) or otherwise indicated unsuccessful
    #     completion of the command.
    #   * :http_returned_error: This is returned if CURLOPT_FAILONERROR is
    #     set TRUE and the HTTP server returns an error code that is >= 400.
    #   * :write_error: An error occurred when writing received data to a
    #     local file, or an error was returned to libcurl from a write callback.
    #   * :upload_failed: Failed starting the upload. For FTP, the server
    #     typically denied the STOR command. The error buffer usually
    #     contains the server's explanation for this.
    #   * :read_error: There was a problem reading a local file or an error
    #     returned by the read callback.
    #   * :out_of_memory: A memory allocation request failed. This is serious
    #     badness and things are severely screwed up if this ever occurs.
    #   * :operation_timedout: Operation timeout. The specified time-out
    #     period was reached according to the conditions.
    #   * :ftp_port_failed: The FTP PORT command returned error. This mostly
    #     happens when you haven't specified a good enough address for
    #     libcurl to use. See CURLOPT_FTPPORT.
    #   * :ftp_couldnt_use_rest: The FTP REST command returned error. This
    #     should never happen if the server is sane.
    #   * :range_error: The server does not support or accept range requests.
    #   * :http_post_error: This is an odd error that mainly occurs due to
    #     internal confusion.
    #   * :ssl_connect_error: A problem occurred somewhere in the SSL/TLS
    #     handshake. You really want the error buffer and read the message
    #     there as it pinpoints the problem slightly more. Could be
    #     certificates (file formats, paths, permissions), passwords, and others.
    #   * :bad_download_resume: The download could not be resumed because
    #     the specified offset was out of the file boundary.
    #   * :file_couldnt_read_file: A file given with FILE:// couldn't be
    #     opened. Most likely because the file path doesn't identify an
    #     existing file. Did you check file permissions?
    #   * :ldap_cannot_bind: LDAP cannot bind. LDAP bind operation failed.
    #   * :ldap_search_failed: LDAP search failed.
    #   * :function_not_found: Function not found. A required zlib function was not found.
    #   * :aborted_by_callback: Aborted by callback. A callback returned
    #     "abort" to libcurl.
    #   * :bad_function_argument: Internal error. A function was called with
    #     a bad parameter.
    #   * :interface_failed: Interface error. A specified outgoing interface
    #     could not be used. Set which interface to use for outgoing
    #     connections' source IP address with CURLOPT_INTERFACE.
    #   * :too_many_redirects: Too many redirects. When following redirects,
    #     libcurl hit the maximum amount. Set your limit with CURLOPT_MAXREDIRS.
    #   * :unknown_option: An option passed to libcurl is not recognized/known.
    #     Refer to the appropriate documentation. This is most likely a
    #     problem in the program that uses libcurl. The error buffer might
    #     contain more specific information about which exact option it concerns.
    #   * :telnet_option_syntax: A telnet option string was Illegally formatted.
    #   * :peer_failed_verification: The remote server's SSL certificate or
    #     SSH md5 fingerprint was deemed not OK.
    #   * :got_nothing: Nothing was returned from the server, and under the
    #     circumstances, getting nothing is considered an error.
    #   * :ssl_engine_notfound: The specified crypto engine wasn't found.
    #   * :ssl_engine_setfailed: Failed setting the selected SSL crypto engine as default!
    #   * :send_error: Failed sending network data.
    #   * :recv_error: Failure with receiving network data.
    #   * :ssl_certproblem: problem with the local client certificate.
    #   * :ssl_cipher: Couldn't use specified cipher.
    #   * :ssl_cacert: Peer certificate cannot be authenticated with known CA certificates.
    #   * :bad_content_encoding: Unrecognized transfer encoding.
    #   * :ldap_invalid_url: Invalid LDAP URL.
    #   * :filesize_exceeded: Maximum file size exceeded.
    #   * :use_ssl_failed: Requested FTP SSL level failed.
    #   * :send_fail_rewind: When doing a send operation curl had to rewind the data to
    #     retransmit, but the rewinding operation failed.
    #   * :ssl_engine_initfailed: Initiating the SSL Engine failed.
    #   * :login_denied: The remote server denied curl to login
    #   * :tftp_notfound: File not found on TFTP server.
    #   * :tftp_perm: Permission problem on TFTP server.
    #   * :remote_disk_full: Out of disk space on the server.
    #   * :tftp_illegal: Illegal TFTP operation.
    #   * :tftp_unknownid: Unknown TFTP transfer ID.
    #   * :remote_file_exists: File already exists and will not be overwritten.
    #   * :tftp_nosuchuser: This error should never be returned by a properly
    #     functioning TFTP server.
    #   * :conv_failed: Character conversion failed.
    #   * :conv_reqd: Caller must register conversion callbacks.
    #   * :ssl_cacert_badfile: Problem with reading the SSL CA cert (path? access rights?):
    #   * :remote_file_not_found: The resource referenced in the URL does not exist.
    #   * :ssh: An unspecified error occurred during the SSH session.
    #   * :ssl_shutdown_failed: Failed to shut down the SSL connection.
    #   * :again: Socket is not ready for send/recv wait till it's ready and try again.
    #     This return code is only returned from curl_easy_recv(3) and curl_easy_send(3)
    #   * :ssl_crl_badfile: Failed to load CRL file
    #   * :ssl_issuer_error: Issuer check failed
    #   * :ftp_pret_failed: The FTP server does not understand the PRET command at
    #     all or does not support the given argument. Be careful when
    #     using CURLOPT_CUSTOMREQUEST, a custom LIST command will be sent with PRET CMD
    #     before PASV as well.
    #   * :rtsp_cseq_error: Mismatch of RTSP CSeq numbers.
    #   * :rtsp_session_error: Mismatch of RTSP Session Identifiers.
    #   * :ftp_bad_file_list: Unable to parse FTP file list (during FTP wildcard downloading).
    #   * :chunk_failed: Chunk callback reported error.
    #   * :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

    # 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 :headers [ Hash ] Request headers.
    #
    # @return [ Easy ] A new Easy.
    #
    # @see Ethon::Easy::Options
    # @see http://curl.haxx.se/libcurl/c/curl_easy_setopt.html
    def initialize(options = {})
      Curl.init
      set_attributes(options)
      set_callbacks
    end

    # Set given options.
    #
    # @example Set options.
    #   easy.set_attributes(options)
    #
    # @param [ Hash ] options The options.
    #
    # @raise InvalidOption
    #
    # @see initialize
    def set_attributes(options)
      options.each_pair do |key, value|
        method = "#{key}="
        unless respond_to?(method)
          raise Errors::InvalidOption.new(key)
        end
        send(method, value)
      end
    end

    # Reset easy. This means resetting all options and instance variables.
    # Also the easy handle is resetted.
    #
    # @example Reset.
    #   easy.reset
    def reset
      @url = nil
      @hash = nil
      @on_complete = nil
      @on_headers = nil
      @on_body = nil
      @procs = nil
      @mirror = nil
      Curl.easy_reset(handle)
      set_callbacks
    end

    # Url escapes the value.
    #
    # @example Url escape.
    #   easy.escape(value)
    #
    # @param [ String ] value The value to escape.
    #
    # @return [ String ] The escaped value.
    #
    # @api private
    def escape(value)
      string_pointer = Curl.easy_escape(handle, value, value.bytesize)
      returned_string = string_pointer.read_string
      Curl.free(string_pointer)
      returned_string
    end

    # Returns the informations available through libcurl as
    # a hash.
    #
    # @return [ Hash ] The informations hash.
    def to_hash
      Kernel.warn("Ethon: Easy#to_hash is deprecated and will be removed, please use #mirror.")
      mirror.to_hash
    end

    def mirror
      @mirror ||= Mirror.from_easy(self)
    end

    # Return pretty log out.
    #
    # @example Return log out.
    #   easy.log_inspect
    #
    # @return [ String ] The log out.
    def log_inspect
      "EASY #{mirror.log_informations.map{|k, v| "#{k}=#{v}"}.flatten.join(' ')}"
    end
  end
end