scnr-ethon 0.15.0

data/lib/ethon/easy.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+require 'ethon/easy/informations'
+require 'ethon/easy/features'
+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
+    extend Ethon::Easy::Features
+
+    # 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.
+    #   * :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
+      @escape = nil
+      @hash = nil
+      @on_complete = nil
+      @on_headers = nil
+      @on_body = nil
+      @on_progress = nil
+      @procs = nil
+      @mirror = nil
+      Curl.easy_reset(handle)
+      set_callbacks
+    end
+
+    # Clones libcurl session handle. This means that all options that is set in
+    #   the current handle will be set on duplicated handle.
+    def dup
+      e = super
+      e.handle = Curl.easy_duphandle(handle)
+      e.instance_variable_set(:@body_write_callback, nil)
+      e.instance_variable_set(:@header_write_callback, nil)
+      e.instance_variable_set(:@debug_callback, nil)
+      e.instance_variable_set(:@progress_callback, nil)
+      e.set_callbacks
+      e
+    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

data/lib/ethon/errors/ethon_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Default Ethon error class for all custom errors.
+    class EthonError < StandardError
+    end
+  end
+end

data/lib/ethon/errors/global_init.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raises when global_init failed.
+    class GlobalInit < EthonError
+      def initialize
+        super("An error occured initializing curl.")
+      end
+    end
+  end
+end
+

data/lib/ethon/errors/invalid_option.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raises when option is invalid.
+    class InvalidOption < EthonError
+      def initialize(option)
+        super("The option: #{option} is invalid.")
+      end
+    end
+  end
+end
+

data/lib/ethon/errors/invalid_value.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raises when option is invalid.
+    class InvalidValue < EthonError
+      def initialize(option, value)
+        super("The value: #{value} is invalid for option: #{option}.")
+      end
+    end
+  end
+end
+

data/lib/ethon/errors/multi_add.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raises when multi_add_handle failed.
+    class MultiAdd < EthonError
+      def initialize(code, easy)
+        super("An error occured adding the easy handle: #{easy} to the multi: #{code}")
+      end
+    end
+  end
+end

data/lib/ethon/errors/multi_fdset.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raises when multi_fdset failed.
+    class MultiFdset < EthonError
+      def initialize(code)
+        super("An error occured getting the fdset: #{code}")
+      end
+    end
+  end
+end

data/lib/ethon/errors/multi_remove.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raises when multi_remove_handle failed.
+    class MultiRemove < EthonError
+      def initialize(code, easy)
+        super("An error occured removing the easy handle: #{easy} from the multi: #{code}")
+      end
+    end
+  end
+end

data/lib/ethon/errors/multi_timeout.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raised when multi_timeout failed.
+    class MultiTimeout < EthonError
+      def initialize(code)
+        super("An error occured getting the timeout: #{code}")
+        # "An error occured getting the timeout: #{code}: #{Curl.multi_strerror(code)}"
+      end
+    end
+  end
+end

data/lib/ethon/errors/select.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raised when select failed.
+    class Select < EthonError
+      def initialize(errno)
+        super("An error occured on select: #{errno}")
+      end
+    end
+  end
+end
+

data/lib/ethon/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+require 'ethon/errors/ethon_error'
+require 'ethon/errors/global_init'
+require 'ethon/errors/multi_timeout'
+require 'ethon/errors/multi_fdset'
+require 'ethon/errors/multi_add'
+require 'ethon/errors/multi_remove'
+require 'ethon/errors/select'
+require 'ethon/errors/invalid_option'
+require 'ethon/errors/invalid_value'
+
+module Ethon
+
+  # This namespace contains all errors raised by ethon.
+  module Errors
+  end
+end

data/lib/ethon/libc.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+module Ethon
+
+  # FFI Wrapper module for Libc.
+  #
+  # @api private
+  module Libc
+    extend FFI::Library
+    ffi_lib 'c'
+
+    # :nodoc:
+    def self.windows?
+      Gem.win_platform?
+    end
+
+    unless windows?
+      attach_function :getdtablesize, [], :int
+      attach_function :free, [:pointer], :void
+    end
+  end
+end

data/lib/ethon/loggable.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+# frozen_string_literal: true
+module Ethon
+
+  # Contains logging behaviour.
+  module Loggable
+
+    # Get the logger.
+    #
+    # @note Will try to grab Rails' logger first before creating a new logger
+    #   with stdout.
+    #
+    # @example Get the logger.
+    #   Loggable.logger
+    #
+    # @return [ Logger ] The logger.
+    def logger
+      return @logger if defined?(@logger)
+      @logger = rails_logger || default_logger
+    end
+
+    # Set the logger.
+    #
+    # @example Set the logger.
+    #   Loggable.logger = Logger.new($stdout)
+    #
+    # @param [ Logger ] logger The logger to set.
+    #
+    # @return [ Logger ] The new logger.
+    def logger=(logger)
+      @logger = logger
+    end
+
+    private
+
+    # Gets the default Ethon logger - stdout.
+    #
+    # @example Get the default logger.
+    #   Loggable.default_logger
+    #
+    # @return [ Logger ] The default logger.
+    def default_logger
+      logger = Logger.new($stdout)
+      logger.level = Logger::INFO
+      logger
+    end
+
+    # Get the Rails logger if it's defined.
+    #
+    # @example Get Rails' logger.
+    #   Loggable.rails_logger
+    #
+    # @return [ Logger ] The Rails logger.
+    def rails_logger
+      defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+    end
+  end
+  extend Loggable
+end