ethon 0.18.0 → 0.19.1

data/lib/ethon/easy/queryable.rb

@@ -5,11 +5,51 @@ module Ethon
     # This module contains logic about building
     # query parameters for url or form.
     module Queryable
+      # Marker for the [filename, content type, path] tuple produced for a
+      # file value. It stays an Array for compatibility, but lets a form tell a
+      # file upload apart from a plain array value (including the arrays kept
+      # intact by params_encoding :none).
+      class FileInfo < ::Array
+        def initialize(filename, content_type, path)
+          super(3)
+          self[0] = filename
+          self[1] = content_type
+          self[2] = path
+        end
+      end
+
+      attr_reader :escape, :params_encoding
+
+      def escape=(value)
+        @to_s = nil
+        @escape = value
+      end
+
+      def params_encoding=(value)
+        @query_pairs = nil
+        @to_s = nil
+        @params_encoding = value
+      end
 
-      # :nodoc:
-      def self.included(base)
-        base.send(:attr_accessor, :escape)
-        base.send(:attr_accessor, :params_encoding)
+      # Loads mime-types on first use rather than when ethon is required:
+      # its registry costs megabytes in every process, while only file
+      # uploads need it. Concurrent first calls are safe, `require` is.
+      #
+      # @return [ Boolean ] True if mime-types could be loaded.
+      def self.mime_types_available?
+        return @mime_types_available unless @mime_types_available.nil?
+
+        @mime_types_available = begin
+          require 'mime/types/columnar'
+          true
+        rescue LoadError
+          begin
+            require 'mime/types'
+            true
+          rescue LoadError
+            false
+          end
+        end
       end
 
       # Return wether there are elements in params or not.
@@ -19,7 +59,9 @@ module Ethon
       #
       # @return [ Boolean ] True if params is empty, else false.
       def empty?
-        @params.empty?
+        # Build the pairs instead of asking @params directly: params may be a
+        # String or a scalar, and only the pairs describe what is sent.
+        query_pairs.empty?
       end
 
       # Return the string representation of params.
@@ -60,7 +102,11 @@ module Ethon
       #
       # @return [ Array ] The array of query pairs.
       def build_query_pairs(hash)
-        return [hash] if hash.is_a?(String)
+        if hash.is_a?(String)
+          # An empty string describes no pairs. Treating it as one would make
+          # #empty? false and leave a stray "?" or "&" in the url.
+          return hash.empty? ? [] : [hash]
+        end
 
         pairs = []
         recursively_generate_pairs(hash, nil, pairs)
@@ -77,17 +123,17 @@ module Ethon
       # @return [ Array ] Array of informations.
       def file_info(file)
         filename = File.basename(file.path)
-        [
+        FileInfo.new(
           filename,
           mime_type(filename),
           File.expand_path(file.path)
-        ]
+        )
       end
 
       private
 
       def mime_type(filename)
-        if defined?(MIME) && t = MIME::Types.type_for(filename).first
+        if Queryable.mime_types_available? && defined?(MIME) && t = MIME::Types.type_for(filename).first
           t.to_s
         else
           'application/octet-stream'
@@ -132,12 +178,11 @@ module Ethon
         end
       end
 
-    def encode_multi_array_pairs(h, prefix, pairs)
-      h.each_with_index do |v, i|
-        key = prefix
-        pairs_for(v, key, pairs)
+      def encode_multi_array_pairs(h, prefix, pairs)
+        h.each do |v|
+          pairs_for(v, prefix, pairs)
+        end
       end
-    end
 
       def pairs_for(v, key, pairs)
         case v

data/lib/ethon/easy/response_callbacks.rb

@@ -69,9 +69,30 @@ module Ethon
       # @example Execute on_completes.
       #   request.complete
       def complete
-        headers unless @response_headers.empty?
-        if defined?(@on_complete) and not @on_complete.nil?
-          @on_complete.each{ |callback| callback.call(self) }
+        if @completing
+          raise Errors::EthonError, "Easy is already completing; wait for the callbacks to finish"
+        end
+
+        error = nil
+        response_body_io = @response_body_io
+        begin
+          @completing = true
+          headers unless @response_headers.empty?
+          if defined?(@on_complete) and not @on_complete.nil?
+            @on_complete.each{ |callback| callback.call(self) }
+          end
+        rescue Exception => exception
+          error = exception
+          raise
+        ensure
+          @completing = false
+          begin
+            finish_response_body_io(response_body_io)
+          rescue Exception
+            # A failed close or flush must not hide the error that caused the
+            # teardown, or a callback error that is about to be raised.
+            raise unless error || @callback_error
+          end
         end
       end
 
@@ -120,16 +141,16 @@ module Ethon
       #
       # @return [ Object ] If there are no on_body callbacks, returns the symbol :unyielded.
       def body(chunk)
-        if defined?(@on_body) and not @on_body.nil?
-          result = nil
-          @on_body.each do |callback|
-            result = callback.call(chunk, self)
-            break if result == :abort
-          end
-          result
-        else
-          :unyielded
+        # Merely reading #on_body creates an empty list. It must not change
+        # whether the response body is buffered.
+        return :unyielded if !defined?(@on_body) || @on_body.nil? || @on_body.empty?
+
+        result = nil
+        @on_body.each do |callback|
+          result = callback.call(chunk, self)
+          break if result == :abort
         end
+        result
       end
     end
   end

data/lib/ethon/easy/share.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+module Ethon
+  class Easy
+    module Share
+      attr_reader :share
+
+      # Attach a curl share handle.
+      #
+      # @param [ Ethon::Curl::Share, nil ] share The share handle.
+      #
+      # @raise [ TypeError ] If share is not a share handle.
+      #
+      # @return [ Ethon::Curl::Share, nil ] The share handle.
+      def share=(share)
+        unless share.nil? || share.is_a?(Curl::Share)
+          raise TypeError, "expected an Ethon::Curl::Share, got #{share.class}"
+        end
+
+        share.check_pid! if share
+        Curl.set_option(:share, share, handle)
+        @share = share
+        share
+      end
+    end
+
+    include Share
+  end
+end

data/lib/ethon/easy/url.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+module Ethon
+  class Easy
+    module Url
+      attr_reader :curlu
+
+      # Install a URL handle as the request target.
+      #
+      # @param [ Ethon::Curl::Url, nil ] url The URL handle.
+      #
+      # @raise [ TypeError ] If url is not a URL handle.
+      #
+      # @return [ Ethon::Curl::Url, nil ] The URL handle.
+      def curlu=(url)
+        unless url.nil? || url.is_a?(Curl::Url)
+          raise TypeError, "expected an Ethon::Curl::Url, got #{url.class}"
+        end
+
+        url.check_pid! if url
+        Curl.set_option(:curlu, url, handle)
+        if url
+          Curl.set_option(:url, nil, handle)
+          @url = nil
+        end
+        @curlu = url
+        url
+      end
+    end
+
+    include Url
+  end
+end

data/lib/ethon/easy/util.rb

@@ -22,6 +22,25 @@ module Ethon
         value.to_s.gsub(0.chr, '\\\0')
       end
 
+      # Rejects header lines libcurl would send verbatim as extra headers.
+      #
+      # @example Validate a header line.
+      #   Util.validate_header_line(:headers, "X-Test: 1")
+      #
+      # @param [ Symbol ] option The option name used in the error.
+      # @param [ String ] line The header line.
+      #
+      # @raise [ Errors::InvalidValue ] If the line contains CR, LF, or NUL.
+      #
+      # @return [ String ] The validated line.
+      def validate_header_line(option, line)
+        if line.include?("\r") || line.include?("\n") || line.include?("\0")
+          raise Errors::InvalidValue.new(option, line)
+        end
+
+        line
+      end
+
       extend self
     end
   end

data/lib/ethon/easy.rb

@@ -12,11 +12,12 @@ require 'ethon/easy/operations'
 require 'ethon/easy/response_callbacks'
 require 'ethon/easy/debug_info'
 require 'ethon/easy/mirror'
+require 'ethon/easy/files'
 
 module Ethon
 
   # This is the class representing the libcurl easy interface
-  # See http://curl.haxx.se/libcurl/c/libcurl-easy.html for more informations.
+  # See https://curl.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:
   #
@@ -41,6 +42,7 @@ module Ethon
     include Ethon::Easy::Http
     include Ethon::Easy::Operations
     include Ethon::Easy::ResponseCallbacks
+    include Ethon::Easy::Files
     extend Ethon::Easy::Features
 
     # Returns the curl return code.
@@ -197,7 +199,7 @@ 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
+    # @see https://curl.se/libcurl/c/libcurl-errors.html
     attr_accessor :return_code
 
     # Initialize a new Easy.
@@ -214,11 +216,18 @@ module Ethon
     # @return [ Easy ] A new Easy.
     #
     # @see Ethon::Easy::Options
-    # @see http://curl.haxx.se/libcurl/c/curl_easy_setopt.html
+    # @see https://curl.se/libcurl/c/curl_easy_setopt.html
     def initialize(options = {})
       Curl.init
-      set_attributes(options)
+      options = options.dup
+      # Apply a supplied handle before the other options so they are set on
+      # that handle instead of the one Ethon would otherwise create.
+      handle_key = options.keys.find { |key| key.to_s == "handle" }
+      self.handle = options.delete(handle_key) if handle_key
+      # Install Ethon's internal callbacks first so callback options passed to
+      # the constructor override them instead of being overwritten here.
       set_callbacks
+      set_attributes(options)
     end
 
     # Set given options.
@@ -247,31 +256,144 @@ module Ethon
     # @example Reset.
     #   easy.reset
     def reset
+      ensure_not_attached_to_multi!
+      ensure_not_in_transfer!
+      # Check the handle before clearing state so reset is a no-op when the
+      # handle was cleaned up or inherited across a fork.
+      handle
+      # Close the response stream before clearing any state. If closing fails,
+      # leave the handle and its Ruby-side description untouched so the caller
+      # can recover instead of ending up with a half-reset Easy.
+      clear_response_body_io
+
+      @postfields = nil
+      @postfields_pointer = nil
+      @postfield_body_size = nil
+      @postfieldsize_value = nil
       @url = nil
       @escape = nil
-      @hash = nil
+      @multipart = nil
+      @headers = nil
+      @return_code = nil
+      # A reset from on_complete is cleanup for the finished transfer. Keep a
+      # callback error so perform still raises it afterwards.
+      @callback_error = nil unless @completing
       @on_complete = nil
       @on_headers = nil
       @on_body = nil
       @on_progress = nil
+      @progress_source = nil
+      @internal_progress_option = nil
+      @user_debug_callback = nil
+      @noprogress_value = nil
       @procs = nil
+      @blobs = nil
+      @slists = nil
       @mirror = nil
+      @read_callback = nil
+      @request_body = nil
+      @request_body_start = nil
       Curl.easy_reset(handle)
+      # libcurl no longer references these after easy_reset.
+      @header_list = nil
+      handle.error_buffer = nil
+      @error_buffer_enabled = nil
+      @multipart_form = nil
+      @curlu = nil
+      @mime = nil
+      # curl_easy_reset preserves CURLOPT_SHARE, so detach it explicitly.
+      self.share = nil if @share
       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.
+    #
+    # libcurl requires the source handle to be idle while it is cloned, and the
+    # copy can never be part of the same Multi. An Easy that a Multi owns must
+    # therefore be removed first.
+    #
+    # @raise [ Errors::EthonError ] If the Easy is still attached to a Multi.
     def dup
+      ensure_not_performing!
+      ensure_not_attached_to_multi!
+      unless Curl.respond_to?(:easy_duphandle)
+        raise NotImplementedError, "curl_easy_duphandle is not supported by this libcurl"
+      end
+
       e = super
-      e.handle = Curl.easy_duphandle(handle)
+      duplicated_handle = Curl.easy_duphandle(handle)
+      raise NoMemoryError, "curl_easy_duphandle failed" if duplicated_handle.null?
+
+      # The copied callback closures still reference the original Easy. Clear
+      # them before installing callbacks on the duplicate so the new native
+      # handle never points at the original.
       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.instance_variable_set(:@user_debug_callback, @user_debug_callback)
+      # Do not share an open response stream with the original. A path
+      # destination stays configured so the copy opens its own stream for the
+      # next transfer; a caller-owned IO is dropped because both handles would
+      # write into the same object.
+      e.instance_variable_set(:@response_body_io, nil)
+      e.instance_variable_set(:@owns_response_body_io, false)
+      e.instance_variable_set(:@multi, nil)
+      # The duplicated native handle already carries the request options, so
+      # keep the Ruby-side request state that describes them.
+      e.send(:assign_handle, Curl::EasyHandle.new(duplicated_handle), false)
+      # curl_easy_duphandle copies the native MIME structure, but there is no
+      # way to wrap that copy. Keeping the original wrapper would make both
+      # handles appear to share a structure they do not actually share.
+      e.instance_variable_set(:@mime, nil)
       e.set_callbacks
+      restore_callbacks_on(e)
+      # curl_easy_duphandle copies the error buffer pointer, give the copy its own
+      e.instance_variable_set(:@error_buffer, nil)
+      e.errorbuffer = true if @error_buffer_enabled
+      # curl_easy_duphandle does not inherit share state, so reattach it.
+      e.share = e.share if e.share
+      # The copy starts a fresh transfer and must not report the original's
+      # result or a callback error from it.
+      e.return_code = nil
+      e.clear_callback_error
       e
     end
+
+    # Install fresh callback closures on a duplicate.
+    #
+    # curl_easy_duphandle copies callback pointers, but those closures still
+    # reference the original Easy. Reinstalling them keeps the duplicate from
+    # calling into the original and from depending on it staying alive.
+    def restore_callbacks_on(copy)
+      if defined?(@request_body) && @request_body
+        copy.set_read_callback(@request_body)
+        # Replay the original body range instead of wherever the shared body
+        # happens to be when the copy is made.
+        copy.instance_variable_set(:@request_body_start, @request_body_start)
+      end
+
+      (@procs || {}).each do |option, callback|
+        next if option == :readfunction && defined?(@request_body) && @request_body
+
+        copy.public_send("#{option}=", callback)
+      end
+
+      # Replay custom progress functions first: on_progress installs its
+      # internal callback on top of them, so it has to win in the same order.
+      if @progress_source == :internal && defined?(@on_progress) && @on_progress && @progress_callback
+        copy.set_progress_callback
+      end
+    end
+    private :restore_callbacks_on
+
+    # Cloning shares the native handle, so route it through #dup instead.
+    def clone(freeze: true)
+      copy = dup
+      copy.freeze if freeze && frozen?
+      copy
+    end
     # Url escapes the value.
     #
     # @example Url escape.
@@ -284,9 +406,13 @@ module Ethon
     # @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
+      raise NoMemoryError, "curl_easy_escape failed" if string_pointer.null?
+
+      begin
+        string_pointer.read_string.force_encoding(value.encoding)
+      ensure
+        Curl.free(string_pointer)
+      end
     end
 
     # Returns the informations available through libcurl as
@@ -299,7 +425,7 @@ module Ethon
     end
 
     def mirror
-      @mirror ||= Mirror.from_easy(self)
+      Mirror.from_easy(self)
     end
 
     # Return pretty log out.
@@ -311,5 +437,54 @@ module Ethon
     def log_inspect
       "EASY #{mirror.log_informations.map{|k, v| "#{k}=#{v}"}.flatten.join(' ')}"
     end
+
+    # Url unescapes the value.
+    #
+    # @example Url unescape.
+    #   easy.unescape("a%20b")
+    #   #=> "a b"
+    #
+    # @param [ String ] value The value to unescape.
+    #
+    # @return [ String ] The unescaped value.
+    def unescape(value)
+      unless Curl.respond_to?(:easy_unescape)
+        raise NotImplementedError, "curl_easy_unescape is not supported by this libcurl"
+      end
+
+      out_length = FFI::MemoryPointer.new(:int)
+      string_pointer = Curl.easy_unescape(handle, value, value.bytesize, out_length)
+      raise NoMemoryError, "curl_easy_unescape failed" if string_pointer.null?
+
+      begin
+        string_pointer.read_string(out_length.read_int).force_encoding(value.encoding)
+      ensure
+        Curl.free(string_pointer)
+      end
+    end
+
+    # Pause or resume a transfer. See Curl::PAUSE_*.
+    #
+    # @param [ Integer ] bitmask The parts to pause.
+    #
+    # @return [ Symbol ] The Curl return code.
+    def pause(bitmask = 0)
+      unless Curl.respond_to?(:easy_pause)
+        raise NotImplementedError, "curl_easy_pause is not supported by this libcurl"
+      end
+
+      Curl.easy_pause(handle, bitmask)
+    end
+
+    # Let libcurl perform connection upkeep tasks.
+    #
+    # @return [ Symbol ] The Curl return code.
+    def upkeep
+      unless Curl.respond_to?(:easy_upkeep)
+        raise NotImplementedError, "curl_easy_upkeep is not supported by this libcurl"
+      end
+
+      Curl.easy_upkeep(handle)
+    end
   end
 end

data/lib/ethon/errors/fork_safety.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+    class ForkSafety < EthonError
+      def initialize
+        super("Ethon cannot use libcurl initialized before a fork; use fork+exec or initialize libcurl after forking")
+      end
+    end
+  end
+end

data/lib/ethon/errors/form_add.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raised when curl_formadd fails.
+    class FormAdd < EthonError
+      def initialize(code)
+        super("An error occurred adding a form field: #{code}")
+      end
+    end
+  end
+end

data/lib/ethon/errors/global_init.rb

@@ -5,7 +5,7 @@ module Ethon
     # Raises when global_init failed.
     class GlobalInit < EthonError
       def initialize
-        super("An error occured initializing curl.")
+        super("An error occurred initializing curl.")
       end
     end
   end

data/lib/ethon/errors/header.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raised when curl_easy_header fails.
+    class Header < EthonError
+      def initialize(code)
+        super("An error occurred reading headers: #{code}")
+      end
+    end
+  end
+end

data/lib/ethon/errors/invalid_option.rb

@@ -5,7 +5,9 @@ module Ethon
     # Raises when option is invalid.
     class InvalidOption < EthonError
       def initialize(option)
-        super("The option: #{option} is invalid.")
+        # Inspect so control characters in an untrusted option name cannot
+        # inject lines into logs that record the message.
+        super("The option: #{option.inspect} is invalid.")
       end
     end
   end

data/lib/ethon/errors/invalid_value.rb

@@ -5,7 +5,9 @@ module Ethon
     # Raises when option is invalid.
     class InvalidValue < EthonError
       def initialize(option, value)
-        super("The value: #{value} is invalid for option: #{option}.")
+        # Inspect so control characters in a rejected value cannot inject
+        # lines into logs that record the message.
+        super("The value: #{value.inspect} is invalid for option: #{option}.")
       end
     end
   end

data/lib/ethon/errors/mime.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raised when a curl MIME API call fails.
+    class Mime < EthonError
+      def initialize(code)
+        message = if Ethon::Curl.respond_to?(:easy_strerror)
+          Ethon::Curl.easy_strerror(code)
+        else
+          code.to_s
+        end
+        super("An error occurred building the MIME form: #{message}")
+      end
+    end
+  end
+end

data/lib/ethon/errors/multi_add.rb

@@ -5,7 +5,7 @@ module Ethon
     # 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}")
+        super("An error occurred adding the easy handle: #{easy} to the multi: #{code}")
       end
     end
   end

data/lib/ethon/errors/multi_assign.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raised when curl_multi_assign fails.
+    class MultiAssign < EthonError
+      def initialize(code)
+        super("An error occurred assigning the multi socket: #{code}")
+      end
+    end
+  end
+end

data/lib/ethon/errors/multi_fdset.rb

@@ -5,7 +5,7 @@ module Ethon
     # Raises when multi_fdset failed.
     class MultiFdset < EthonError
       def initialize(code)
-        super("An error occured getting the fdset: #{code}")
+        super("An error occurred getting the fdset: #{code}")
       end
     end
   end

data/lib/ethon/errors/multi_perform.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module Ethon
+  module Errors
+
+    # Raises when multi_perform failed.
+    class MultiPerform < EthonError
+      def initialize(code)
+        super("An error occurred performing the multi: #{code}")
+      end
+    end
+  end
+end