ethon 0.18.0 → 0.19.1

data/lib/ethon/easy/operations.rb

@@ -9,15 +9,34 @@ module Ethon
       # @example Return the handle.
       #   easy.handle
       #
-      # @return [ FFI::Pointer ] A pointer to the curl easy handle.
+      # @return [ Ethon::Curl::EasyHandle ] The owned wrapper around the curl
+      #   easy handle. It is an FFI::Pointer subclass.
       def handle
-        @handle ||= FFI::AutoPointer.new(Curl.easy_init, Curl.method(:easy_cleanup))
+        raise Errors::EthonError, "Easy has been cleaned up" if @cleaned_up
+
+        @handle ||= create_handle
+        handle = @handle
+        handle.check_pid!
+        handle.owner ||= self
+        handle
       end
 
       # Sets a pointer to the curl easy handle.
-      # @param [ ::FFI::Pointer ] Easy handle that will be assigned.
+      #
+      # Raw pointers are wrapped in an owned {Curl::EasyHandle}, so the
+      # handle is registered for fork safety and freed by this Easy. Assigning
+      # nil installs a fresh handle. Assigning a different handle installs
+      # Ethon's response callbacks and replays callbacks previously assigned to
+      # this Easy, then frees the handle it replaces when this Easy owned it.
+      #
+      # Request options that are not replayed are cleared, because the
+      # replacement handle does not have them. Read them before replacing the
+      # handle if they are needed again.
+      #
+      # @param [ ::FFI::Pointer, Curl::EasyHandle, nil ] h Easy handle that will
+      #   be assigned.
       def handle=(h)
-        @handle = h
+        assign_handle(h, true)
       end
 
       # Perform the easy request.
@@ -25,24 +44,93 @@ module Ethon
       # @example Perform the request.
       #   easy.perform
       #
-      # @return [ Integer ] The return code.
+      # @return [ Symbol ] The return code.
       def perform
-        @return_code = Curl.easy_perform(handle)
-        if Ethon.logger.debug?
-          Ethon.logger.debug { "ETHON: performed #{log_inspect}" }
+        ensure_not_performing!
+        # curl_easy_perform must not drive a handle that is owned by a multi.
+        ensure_not_attached_to_multi!
+        # Touch the handle before changing transfer state so a cleaned up or
+        # forked handle cannot truncate a response file or reset the previous
+        # result while raising.
+        handle
+
+        prepare_response_body_io
+        reset_transfer_state
+        clear_callback_error
+        # Only the destination that belongs to this transfer may be finished.
+        # A completion callback can install the next transfer's destination.
+        response_body_io = @response_body_io
+        @performing = true
+
+        error = nil
+        begin
+          code = Curl.easy_perform(handle)
+          @return_code = code
+          if Ethon.logger.debug?
+            Ethon.logger.debug { "ETHON: performed #{log_inspect}" }
+          end
+          # Make the complete response visible before on_complete runs. An
+          # owned file is closed by the ensure below after the callbacks.
+          begin
+            flush_response_body_io
+          rescue Exception
+            # A callback error already failed this transfer; a flush error is
+            # secondary and must not hide it.
+            raise_callback_error
+            raise
+          end
+          complete
+          raise_callback_error
+          # on_complete may reset the Easy, which clears @return_code. Return
+          # the result of the transfer that just ran.
+          code
+        rescue Exception => exception
+          error = exception
+          raise
+        ensure
+          @performing = false
+          begin
+            finish_response_body_io(response_body_io)
+          rescue Exception
+            # Keep the exception that interrupted the transfer or completion.
+            raise unless error
+          end
         end
-        complete
-        @return_code
       end
 
       # Clean up the easy.
       #
+      # Cleanup is terminal: the native handle is freed and the Easy cannot be
+      # used again. Reusing it raises Ethon::Errors::EthonError.
+      #
+      # Cleanup is allowed from an on_complete callback: the transfer has
+      # finished and a Multi detaches the handle before running its callbacks.
+      # Cleanup from body, header, and progress callbacks is rejected because
+      # those run inside libcurl.
+      #
       # @example Perform clean up.
       #   easy.cleanup
       #
       # @return the result of the free which is nil
       def cleanup
-        handle.free
+        ensure_not_in_transfer!
+        ensure_not_attached_to_multi!
+
+        # Resolve the handle first: cleanup must not clear the response body if
+        # the handle is unusable (cleaned up or inherited across a fork).
+        handle_to_free = handle
+        begin
+          clear_response_body_io
+        ensure
+          # Free the native handle even when closing the response body fails.
+          begin
+            handle_to_free.free
+          ensure
+            clear_native_state
+            @handle = nil
+            @cleaned_up = true
+          end
+        end
       end
 
       # Prepare the easy. Options, headers and callbacks
@@ -59,6 +147,171 @@ module Ethon
           "in future versions."
         )
       end
+
+      private
+
+      # Allocate the native handle. Kept separate so #handle= can replace a
+      # handle and install the callbacks before the next option setter runs.
+      def create_handle
+        Curl.check_pid!
+        pointer = Curl.easy_init
+        raise NoMemoryError, "curl_easy_init failed" if pointer.null?
+        Curl::EasyHandle.new(pointer)
+      end
+
+      # Reapply options Ethon installed on the old handle. These are not user
+      # request options: without them #error_message and progress callbacks
+      # silently stop working on the replacement.
+      def restore_handle_options
+        if @error_buffer_enabled && @error_buffer
+          Curl.set_option(:errorbuffer, @error_buffer, @handle)
+          @handle.error_buffer = @error_buffer
+          # Do not report the previous transfer's error from the new handle.
+          @error_buffer.put_char(0, 0)
+        end
+        self.noprogress = @noprogress_value unless @noprogress_value.nil?
+      end
+
+      # Install a handle and, unless the native duplicate already carries the
+      # request options, clear the Ruby-side state that belonged to the handle
+      # it replaces.
+      def assign_handle(h, clear_state)
+        raise Errors::EthonError, "Easy has been cleaned up" if @cleaned_up
+
+        ensure_not_performing!
+        ensure_not_attached_to_multi!
+
+        previous = @handle
+        @handle =
+          case h
+          when nil
+            # Create the replacement now so it gets Ethon's callbacks even
+            # before an option setter or #perform touches it.
+            create_handle
+          when Curl::EasyHandle
+            h.check_pid!
+            # Two Easies must not share one owned wrapper: whichever cleans up
+            # first invalidates the handle for the other.
+            if h.owner && !h.owner.equal?(self)
+              raise ArgumentError, "easy handle is already owned by another Ethon handle"
+            end
+            h
+          when Curl::OwnedPointer
+            raise TypeError, "expected an easy handle, got #{h.class}"
+          when ::FFI::Pointer
+            raise ArgumentError, "cannot assign a null easy handle" if h.null?
+
+            Curl::EasyHandle.new(h)
+          else
+            raise TypeError, "expected an easy handle pointer, got #{h.class}"
+          end
+        @handle.owner = self if @handle
+
+        replaced = @handle && !@handle.equal?(previous)
+        if replaced
+          # A replacement handle has no Ethon callbacks or Ethon-managed
+          # options, so its response would otherwise not be collected. Retained
+          # user callbacks are replayed on top of the internal ones.
+          install_callbacks(@handle)
+          restore_handle_options
+          restore_callbacks_on(self)
+        end
+        release_replaced_handle(previous)
+        # Free the old handle before dropping the Ruby references it owned.
+        clear_replaced_handle_state if replaced && clear_state
+        @handle
+      end
+
+      # The replacement handle does not have the old handle's request options.
+      # Clear the Ruby-side state so the accessors do not describe options the
+      # new handle never received. Callbacks, the error buffer, and the
+      # progress setting are replayed by #assign_handle and stay in place.
+      def clear_replaced_handle_state
+        @url = nil
+        @headers = nil
+        @header_list = nil
+        @postfields = nil
+        @postfields_pointer = nil
+        @postfield_body_size = nil
+        @postfieldsize_value = nil
+        @curlu = nil
+        @mime = nil
+        @multipart_form = nil
+        @slists = nil
+        @blobs = nil
+        @share = nil
+        @escape = nil
+        @multipart = nil
+        reset_transfer_state
+        clear_callback_error
+      end
+
+      # Free the handle this Easy owned before the replacement. A handle owned
+      # by another Easy (the source of #dup) must stay alive for its owner.
+      def release_replaced_handle(previous)
+        return unless previous
+        return if previous.equal?(@handle)
+        return unless previous.owner.equal?(self)
+
+        previous.free
+      end
+
+      # Drop references to native data and callbacks once the handle is gone.
+      def clear_native_state
+        @body_write_callback = nil
+        @header_write_callback = nil
+        @debug_callback = nil
+        @progress_callback = nil
+        @read_callback = nil
+        @request_body = nil
+        @request_body_start = nil
+        @postfields = nil
+        @postfields_pointer = nil
+        @postfield_body_size = nil
+        @postfieldsize_value = nil
+        @header_list = nil
+        @multipart_form = nil
+        @mime = nil
+        @curlu = nil
+        @blobs = nil
+        @slists = nil
+        @procs = nil
+        @on_complete = nil
+        @on_headers = nil
+        @on_body = nil
+        @on_progress = nil
+        @progress_source = nil
+        @internal_progress_option = nil
+        @user_debug_callback = nil
+        @share = nil
+        @error_buffer = nil
+        @error_buffer_enabled = nil
+        @noprogress_value = nil
+      end
+
+      def ensure_not_performing!
+        if @completing
+          raise Errors::EthonError, "Easy is currently completing; wait for the callbacks to finish"
+        end
+        if @performing
+          raise Errors::EthonError, "Easy is currently performing; wait for the transfer to finish"
+        end
+      end
+
+      # Resetting is safe from a completion callback: the transfer has already
+      # finished and the handle no longer belongs to a Multi. A reset from a
+      # body, header, or progress callback still runs inside libcurl.
+      def ensure_not_in_transfer!
+        return if @completing
+
+        ensure_not_performing!
+      end
+
+      def ensure_not_attached_to_multi!
+        return unless defined?(@multi) && @multi
+
+        raise Errors::EthonError, "Easy is still attached to a Multi; remove it first"
+      end
     end
   end
 end

data/lib/ethon/easy/options.rb

@@ -5,11 +5,48 @@ module Ethon
     # This module contains the logic and knowledge about the
     # available options on easy.
     module Options
+      CALLBACK_TYPES = [:callback, :debug_callback, :progress_callback, :xferinfo_callback].freeze
+
+      # Ethon installs these callbacks on every handle. Clearing the option must
+      # restore Ethon's callback instead of leaving libcurl's default writer
+      # active, which would send response bytes to the process's stdout or
+      # stderr.
+      CALLBACK_DEFAULTS = {
+        :writefunction => :body_write_callback,
+        :headerfunction => :header_write_callback,
+        :debugfunction => :debug_callback
+      }.freeze
+
       attr_reader :url
 
       def url=(value)
-        @url = value
-        Curl.set_option(:url, value, handle)
+        # libcurl copies the URL, but the accessor must describe the exact
+        # string libcurl received. Snapshot it so later caller mutations cannot
+        # make #url disagree with the handle, and assign it only once libcurl
+        # accepts the value. Do this before touching the URL handle so a
+        # rejected value cannot leave it detached.
+        snapshot = value.nil? ? nil : value.to_s
+        snapshot = snapshot.dup.freeze if snapshot && !snapshot.frozen?
+
+        previous_curlu = @curlu
+        if previous_curlu
+          Curl.set_option(:curlu, nil, handle)
+          @curlu = nil
+        end
+
+        begin
+          Curl.set_option(:url, snapshot, handle)
+        rescue Exception
+          # Detaching the URL handle was only necessary to install the new
+          # value. Put it back when that value was rejected.
+          if previous_curlu
+            Curl.set_option(:curlu, previous_curlu, handle)
+            @curlu = previous_curlu
+          end
+          raise
+        end
+        @url = snapshot
+        value
       end
 
       def escape=( b )
@@ -29,22 +66,304 @@ module Ethon
         !!@multipart
       end
 
+      def multipart_form=(form)
+        self.httppost = form ? form.first.read_pointer : nil
+        @multipart_form = form
+      rescue Errors::UnsupportedOption
+        # CURLOPT_HTTPPOST is compiled out of builds configured with
+        # --disable-form-api. Clearing is all that can happen there, because
+        # building a form needs the form API itself.
+        raise if form
+
+        @multipart_form = form
+      end
+
+      # Enables or disables libcurl's error buffer (CURLOPT_ERRORBUFFER),
+      # which holds a more detailed error description than #return_message.
+      # Read it with #error_message.
+      #
+      # @example Enable the error buffer.
+      #   easy.errorbuffer = true
+      #
+      # @param [ Boolean ] value True to enable, false to disable.
+      #
+      # @return [ Boolean ] The value.
+      def errorbuffer=(value)
+        if value
+          @error_buffer ||= FFI::MemoryPointer.new(:char, Curl.easy_options(nil)[:errorbuffer][:opts])
+          @error_buffer.put_char(0, 0)
+          Curl.set_option(:errorbuffer, @error_buffer, handle)
+          handle.error_buffer = @error_buffer
+        else
+          Curl.set_option(:errorbuffer, nil, handle)
+          handle.error_buffer = nil
+        end
+        @error_buffer_enabled = !!value
+        value
+      end
+
+      # Returns the error message libcurl stored in the error buffer during
+      # the last transfer, or nil if it is empty or #errorbuffer= isn't enabled.
+      #
+      # @example Get the error message.
+      #   easy.error_message
+      #
+      # @return [ String, nil ] The error message.
+      def error_message
+        return unless @error_buffer_enabled
+        message = @error_buffer.read_string
+        message unless message.empty?
+      end
+
+      # Enables or disables libcurl's progress callback invocation. libcurl
+      # requires CURLOPT_NOPROGRESS to be 0 before it calls a progress
+      # callback, so remember the value to restore it when the native handle
+      # is replaced.
+      #
+      # @example Enable progress callbacks.
+      #   easy.noprogress = 0
+      #
+      # @param [ Boolean, Integer ] value The value to set.
+      #
+      # @return [ Boolean, Integer ] The value.
+      def noprogress=(value)
+        Curl.set_option(:noprogress, value, handle)
+        @noprogress_value = value
+        value
+      end
+
+      # CURLOPT_TLSAUTH_TYPE and CURLOPT_PROXY_TLSAUTH_TYPE take a string, not
+      # an enum. Normalize the historical symbol API and libcurl's required
+      # "SRP" spelling.
+      def tlsauth_type=(value)
+        Curl.set_option(:tlsauth_type, tlsauth_type_value(value), handle)
+        value
+      end
+
+      def proxy_tlsauth_type=(value)
+        Curl.set_option(:proxy_tlsauth_type, tlsauth_type_value(value), handle)
+        value
+      end
+
+      # Options whose value is used to bound a retained body. Their setters
+      # have to keep the body length and the native size in sync.
+      POSTFIELD_OPTIONS = [:postfields, :postfieldsize, :postfieldsize_large, :copypostfields].freeze
+
       Curl.easy_options(nil).each do |opt, props|
+        # These setters are defined below because libcurl does not copy the
+        # CURLOPT_POSTFIELDS string and the size must stay inside its buffer.
+        next if POSTFIELD_OPTIONS.include?(opt)
+
         method_name = "#{opt}=".freeze
         unless method_defined? method_name
-          define_method(method_name) do |value|
-            Curl.set_option(opt, value, handle)
-            value
+          if CALLBACK_TYPES.include?(props[:type])
+            default_callback = CALLBACK_DEFAULTS[opt]
+            define_method(method_name) do |value|
+              native_value = value
+              native_value = send(default_callback) if value.nil? && default_callback
+              Curl.set_option(opt, native_value, handle)
+              # Do not retain Ethon's internal callback as if the caller had
+              # assigned it; a duplicate must install its own callback.
+              retain_callback(opt, value)
+              value
+            end
+          elsif props[:type] == :blob
+            define_method(method_name) do |value|
+              Curl.set_option(opt, value, handle)
+              if value
+                (@blobs ||= {})[opt] = value
+              elsif @blobs
+                @blobs.delete(opt)
+              end
+              value
+            end
+          elsif props[:type] == :curl_slist
+            # libcurl keeps the list pointer, so retain the wrapper in case it
+            # owns the native list. Clearing the option can release it.
+            define_method(method_name) do |value|
+              Curl.set_option(opt, value, handle)
+              if value
+                (@slists ||= {})[opt] = value
+              elsif @slists
+                @slists.delete(opt)
+              end
+              value
+            end
+          else
+            define_method(method_name) do |value|
+              Curl.set_option(opt, value, handle)
+              value
+            end
           end
         end
         next if props[:type] != :callback || method_defined?(opt)
         define_method(opt) do |&block|
-          @procs ||= {}
-          @procs[opt.to_sym] = block
-          Curl.set_option(opt, block, handle)
+          send(method_name, block)
           nil
         end
       end
+
+      # libcurl does not copy CURLOPT_POSTFIELDS, so keep an immutable snapshot
+      # of the bytes alive for as long as the handle may reference it. The
+      # native option takes a pointer, which lets the body contain NUL bytes.
+      # Retain the buffer only once the option was accepted. Mutating a caller's
+      # string afterwards may reallocate it, so libcurl must not point at that
+      # buffer.
+      #
+      # CURLOPT_POSTFIELDSIZE survives between requests. Updating it here keeps
+      # libcurl from reading an earlier, larger body length out of the new
+      # buffer.
+      def postfields=(value)
+        if value.nil?
+          Curl.set_option(:postfields, nil, handle)
+          @postfields = nil
+          @postfields_pointer = nil
+          @postfield_body_size = nil
+          # -1 is libcurl's default: the body ends at the first NUL.
+          Curl.set_option(:postfieldsize, -1, handle)
+          @postfieldsize_value = -1
+        else
+          string = value.to_s
+          string = string.dup.freeze unless string.frozen?
+          pointer = FFI::MemoryPointer.new(:char, string.bytesize + 1)
+          pointer.put_bytes(0, string)
+          pointer.put_char(string.bytesize, 0)
+          Curl.set_option(:postfields, pointer, handle)
+          @postfields = string
+          @postfields_pointer = pointer
+          @postfield_body_size = string.bytesize
+          Curl.set_option(:postfieldsize, string.bytesize, handle)
+          @postfieldsize_value = string.bytesize
+        end
+        value
+      end
+
+      # libcurl copies CURLOPT_COPYPOSTFIELDS, so the Ruby string does not have
+      # to stay alive. An explicit, smaller CURLOPT_POSTFIELDSIZE still selects
+      # a prefix. A larger size would make libcurl read past the copied buffer,
+      # which is how a stale size from a previous body leaked memory into the
+      # request.
+      def copypostfields=(value)
+        if value.nil?
+          Curl.set_option(:copypostfields, nil, handle)
+          @postfields = nil
+          @postfields_pointer = nil
+          @postfield_body_size = nil
+          # Clear the size too: libcurl fails the request when a non-zero size
+          # is paired with the NULL body left by COPYPOSTFIELDS.
+          Curl.set_option(:postfieldsize, -1, handle)
+          @postfieldsize_value = -1
+          return value
+        end
+
+        string = value.to_s
+        size = @postfieldsize_value
+        if size && size >= 0
+          if @postfield_body_size == size
+            # The size still describes the body that is being replaced. Keeping
+            # it would truncate a longer copy or read past a shorter one.
+            size = nil
+          elsif size > string.bytesize
+            raise Errors::InvalidValue.new(:copypostfields, value)
+          end
+        end
+
+        if size.nil? || size < 0
+          Curl.set_option(:postfieldsize, string.bytesize, handle)
+          @postfieldsize_value = string.bytesize
+        end
+        Curl.set_option(:copypostfields, string, handle)
+        @postfields = nil
+        @postfields_pointer = nil
+        @postfield_body_size = string.bytesize
+        value
+      end
+
+      # CURLOPT_POSTFIELDSIZE and CURLOPT_POSTFIELDSIZE_LARGE bound the bytes
+      # libcurl reads from CURLOPT_POSTFIELDS. Letting them exceed the retained
+      # buffer makes libcurl send adjacent process memory.
+      def postfieldsize=(value)
+        set_postfieldsize(:postfieldsize, value)
+      end
+
+      def postfieldsize_large=(value)
+        set_postfieldsize(:postfieldsize_large, value)
+      end
+
+      # Observe libcurl debug messages without replacing Ethon's internal
+      # debug callback. The block receives the native CURL_DEBUGFUNCTION
+      # arguments and is called only when verbose mode is enabled.
+      #
+      # @example Observe debug messages.
+      #   easy.debugfunction { |handle, type, data, size, user_data| }
+      #
+      # @param [ Block ] block The block to execute, or no block to clear it.
+      def debugfunction(&block)
+        @user_debug_callback = block
+        nil
+      end
+
+      private
+
+      # Validate the size against the body Ethon currently knows about before
+      # handing it to libcurl.
+      def set_postfieldsize(option, value)
+        size = value.nil? ? nil : Ethon::Curls::Options.integer_value(option, value)
+        if @postfield_body_size && size && size > @postfield_body_size
+          raise Errors::InvalidValue.new(option, value)
+        end
+
+        Curl.set_option(option, value, handle)
+        @postfieldsize_value = size unless value.nil?
+        value
+      end
+
+      def initialize_copy(other)
+        super
+        @procs = @procs.dup if @procs
+        @blobs = @blobs.dup if @blobs
+        @slists = @slists.dup if @slists
+        @on_complete = @on_complete.dup if @on_complete
+        @on_headers = @on_headers.dup if @on_headers
+        @on_body = @on_body.dup if @on_body
+        @on_progress = @on_progress.dup if @on_progress
+        @headers = @headers.dup.freeze if @headers
+      end
+
+      def tlsauth_type_value(value)
+        case value.to_s.downcase
+        when "", "none"
+          nil
+        when "srp"
+          "SRP"
+        else
+          value
+        end
+      end
+
+      def retain_callback(option, callback)
+        if option == :readfunction
+          # A callback installed directly by the user does not describe the
+          # retained body and must not be replaced when the Easy is duplicated.
+          unless callback && callback.equal?(@read_callback)
+            @request_body = nil
+            @request_body_start = nil
+          end
+          @read_callback = callback
+        end
+
+        # Setting the option that backs on_progress replaces or clears the
+        # internal callback. Other progress options lose to XFERINFOFUNCTION.
+        if option == @internal_progress_option
+          @progress_source = callback ? :custom : nil
+        end
+
+        if callback.nil?
+          @procs.delete(option) if @procs
+        else
+          (@procs ||= {})[option] = callback
+        end
+      end
     end
   end
 end