ethon 0.19.1 → 0.19.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 495f7cdb119483c6c3876354aa1ceeb8ae485ac25708280104213b2df28949e8
-  data.tar.gz: 6343bc21b68edfbce32389f739880c40a3506640249341c6bbd6eeca250e958f
+  metadata.gz: 5174f0935f97734b2720d7a3445117049a2651cf2796bdfe0b85cee8742037c0
+  data.tar.gz: 14ec1a62317eff2251a2658dffb7cf8350071dee462fd1fb86c15888a78ffe31
 SHA512:
-  metadata.gz: e55248f897175f82a169ce09bb6a5b344f867027a3c3386935394adf058e0693501502ceb1cecb5748b1e1d7ca4c39eb0ce83321ee45ceb4ac73f5e0c032ba98
-  data.tar.gz: afbcbd73dc6a6e38f765d8ce89258711401b58cdda70e2b1fb7399d49b8bb0825fb400a47e489c4e23f86a222711859318550278056829fa7a87b2679e20505c
+  metadata.gz: 44c508f1dff76285672f55f80a69390ee9f5e472bba9894a0b74328af214a1c9eae9288114fcfd1dd79aa20a70911c0fa864982a9726711fb7e8757d8e4cec08
+  data.tar.gz: 85dcaebb702402a4fc45c6db9de5412496aa4cf2b0705f1d09ca702a6ad2f77a065b4abbb1654da1705a22f5fc5a6315e734b3a0cadb374a702cac4265845f85

data/CHANGELOG.md

@@ -2,7 +2,51 @@
 
 ## Master
 
-[Full Changelog](https://github.com/typhoeus/ethon/compare/v0.19.1...master)
+[Full Changelog](https://github.com/typhoeus/ethon/compare/v0.19.2...master)
+
+## 0.19.2
+
+[Full Changelog](https://github.com/typhoeus/ethon/compare/v0.19.1...v0.19.2)
+
+### Fixes and hardening
+
+* Clear `CURLOPT_POSTFIELDSIZE` to 0 instead of -1 when `Easy#postfields=` or
+  `Easy#copypostfields=` clears the body. With a size of -1 libcurl treats the
+  body as indeterminate, sends the POST chunked, and reads it from the default
+  read callback, which is stdin, so the request waited until stdin was closed.
+  ([#463](https://github.com/typhoeus/ethon/issues/463))
+
+### Enhancements
+
+* Mirror `certinfo`, so the certificate chain read with `certinfo: true`
+  survives the handle reset and reaches Typhoeus responses
+  ([typhoeus/typhoeus#427](https://github.com/typhoeus/typhoeus/issues/427))
+
+* Expose `Easy#primary_port`, `Easy#local_ip`, `Easy#local_port`,
+  `Easy#ssl_verifyresult`, `Easy#num_connects`, `Easy#os_errno`,
+  `Easy#http_connectcode`, `Easy#proxyauth_avail`, `Easy#condition_unmet`,
+  `Easy#header_size` and `Easy#content_type`. They are also included in the
+  mirror, so they survive the handle reset and show up in response options.
+  Everything in the mirror is read for every response, so the deprecated
+  `filetime`, `lastsocket` and `content_length_*` values and the RTSP and FTP
+  entry informations are left out in favour of the `_t` and `activesocket`
+  variants that are already exposed.
+  ([#460](https://github.com/typhoeus/ethon/pull/460))
+
+* Add `Ethon::Multipart::Part` for setting the content type and, optionally,
+  the filename of a single `multipart/form-data` part. Plain body values keep
+  their existing behavior.
+  ([typhoeus/typhoeus#494](https://github.com/typhoeus/typhoeus/issues/494))
+
+* Add `Ethon::Curl.allow_handles_after_fork!`, an opt-in for servers that fork
+  workers from a process that has already used libcurl and cannot `exec`.
+  Called in the child before its first handle, it lets the child create new
+  handles on the libcurl state it inherited instead of raising
+  `Ethon::Errors::ForkSafety`. Handles created before the fork are still
+  rejected, as is `Ethon::Curl.cleanup` in the child, and the default is
+  unchanged. The opt-in is not supported on macOS, where it raises
+  `Ethon::Errors::ForkSafety` in a child whose parent initialized libcurl.
+  ([#462](https://github.com/typhoeus/ethon/issues/462))
 
 ## 0.19.1
 

data/README.md

@@ -75,7 +75,29 @@ easy.perform
 
 File values in a `:body` hash are sent as `multipart/form-data`. Ethon loads
 the optional `mime-types` gem on the first upload to detect each part's content
-type; without it, parts use `application/octet-stream`.
+type; with it absent, files fall back to `application/octet-stream`.
+
+Wrap a value in `Ethon::Multipart::Part` to set the content type for that part,
+and optionally the filename. A String with a filename is sent as an in-memory
+upload.
+
+```ruby
+easy.http_request(
+  "www.example.com",
+  :post,
+  body: {
+    metadata: Ethon::Multipart::Part.new(
+      '{"a":1}',
+      content_type: "application/json"
+    ),
+    file: Ethon::Multipart::Part.new(
+      File.open("photo.jpg"),
+      filename: "avatar.png",
+      content_type: "image/png"
+    )
+  }
+)
+```
 
 ## Parallel requests
 
@@ -228,13 +250,38 @@ With libcurl older than 7.84.0, create an Ethon handle before starting other
 application threads so libcurl's global initialization happens while the
 process is still single-threaded.
 
-Ethon handles and initialized libcurl state must not be inherited across a
-`fork`. If any `Easy` or `Multi` was created before forking, libcurl is already
-initialized and the child cannot create new handles either; use `fork` followed
-by `exec` in that case. If libcurl was not initialized before forking, create
-all `Easy` and `Multi` instances after the fork. Ethon raises
-`Ethon::Errors::ForkSafety` when a child process tries to use inherited libcurl
-state.
+Ethon handles and, by default, initialized libcurl state must not be inherited
+across a `fork`. If any `Easy` or `Multi` was created before forking, libcurl
+is already initialized and the child cannot create new handles either; use
+`fork` followed by `exec` in that case, or opt in as described below. If
+libcurl was not initialized before forking, create all `Easy` and `Multi`
+instances after the fork. Ethon raises `Ethon::Errors::ForkSafety` when a child
+process tries to use an inherited handle, or to use inherited libcurl state
+without opting in.
+
+A server that forks workers from a process that has already used libcurl, such
+as Pitchfork with reforking or Puma with `fork_worker`, cannot `exec` without
+losing the memory its workers share with that process. Instead, each worker can
+opt in to creating new handles on the libcurl state it inherited. Call
+`Ethon::Curl.allow_handles_after_fork!` in the worker before it creates its
+first handle and before any other thread uses Ethon, for example from
+Pitchfork's `after_worker_fork` hook:
+
+```ruby
+after_worker_fork do |_server, _worker|
+  Ethon::Curl.allow_handles_after_fork!
+end
+```
+
+Puma's equivalent hook is `before_worker_boot` (`on_worker_boot` before
+Puma 7). Repeat calls in the same worker do nothing. The worker does not
+initialize libcurl again, and it cannot clean up the libcurl state it
+inherited: `Ethon::Curl.cleanup` raises `Ethon::Errors::ForkSafety` there, as
+handles created before the fork still do. On macOS, system frameworks are not
+safe to use after `fork` without `exec`, and libcurl can use them, for example
+for TLS. The opt-in is not supported there and raises
+`Ethon::Errors::ForkSafety` in a worker whose parent initialized libcurl, so
+use `fork` followed by `exec` on macOS.
 
 ## License
 

data/lib/ethon/curl.rb

@@ -26,6 +26,11 @@ module Ethon
       Libc.windows?
     end
 
+    # :nodoc:
+    def self.macos?
+      Libc.macos?
+    end
+
     require 'ethon/curls/constants'
     require 'ethon/curls/introspection_constants'
     require 'ethon/curls/settings'
@@ -36,6 +41,7 @@ module Ethon
     @blocking = true
 
     @@initialized = false
+    @@initialized_pid = nil
     @@loaded_pid = Process.pid
     @@curl_mutex = Mutex.new
 
@@ -70,6 +76,7 @@ module Ethon
           if not @@initialized
             raise Errors::GlobalInit.new if Curl.global_init(GLOBAL_ALL) != 0
             @@initialized = true
+            @@initialized_pid = Process.pid
             Ethon.logger.debug("ETHON: Libcurl initialized") if Ethon.logger
           end
         }
@@ -85,10 +92,19 @@ module Ethon
       # any other thread that uses these other libraries.
       # See the description in libcurl of global environment requirements
       # for details of how to use this function.
+      #
+      # @raise [ Ethon::Errors::ForkSafety ] In a child that opted in with
+      #   allow_handles_after_fork! and inherited libcurl initialized by its
+      #   parent.
       def cleanup
         check_pid!
         @@curl_mutex.synchronize {
           if @@initialized
+            if @@initialized_pid != Process.pid
+              raise Errors::ForkSafety.new(
+                "Ethon cannot clean up libcurl initialized before a fork; clean it up in the process that initialized it"
+              )
+            end
             Curl.global_cleanup()
             @@initialized = false
             Ethon.logger.debug("ETHON: Libcurl cleanup") if Ethon.logger
@@ -105,6 +121,34 @@ module Ethon
         @@curl_mutex = Mutex.new
       end
 
+      # Let a forked child create new handles on the libcurl state it
+      # inherited. Call it in the child before its first handle; repeat calls
+      # do nothing. Handles created before the fork still raise ForkSafety,
+      # and so does cleanup, because the child did not initialize libcurl.
+      #
+      # @example Opt in from a Pitchfork worker's after_worker_fork hook.
+      #   Ethon::Curl.allow_handles_after_fork!
+      #
+      # @raise [ Ethon::Errors::ForkSafety ] On macOS, in a child whose parent
+      #   initialized libcurl.
+      #
+      # @api public
+      def allow_handles_after_fork!
+        return if @@loaded_pid == Process.pid
+
+        if @@initialized && macos?
+          raise Errors::ForkSafety.new(
+            "Ethon cannot use libcurl inherited across a fork on macOS; use fork+exec"
+          )
+        end
+
+        # Leave @@initialized set: the child inherited the parent's libcurl
+        # global state, so it must not run curl_global_init again.
+        @@loaded_pid = Process.pid
+        @@curl_mutex = Mutex.new
+        nil
+      end
+
     end
   end
 end

data/lib/ethon/easy/form.rb

@@ -48,8 +48,10 @@ module Ethon
         @last ||= FFI::MemoryPointer.new(:pointer)
       end
 
-      # Return if form is multipart. The form is multipart
-      # when it contains a file or multipart option is set on the form during creation.
+      # Return if form is multipart. The form is multipart when the multipart
+      # option is set, when it contains a file, or when a value is wrapped in a
+      # Multipart::Part that carries a content type or a filename. A wrapped
+      # plain value is encoded like an unwrapped one.
       #
       # @example Return if form is multipart.
       #   form.multipart?
@@ -57,7 +59,7 @@ module Ethon
       # @return [ Boolean ] True if form is multipart, else false.
       def multipart?
         return true if @multipart
-        contains_file?(@params)
+        contains_multipart_part?(@params)
       end
 
       # Add form elements to libcurl.
@@ -88,13 +90,7 @@ module Ethon
             part = structure.addpart
             name, content = pair
             part.name = name.to_s
-            if content.is_a?(Queryable::FileInfo)
-              part.file = content[2]
-              part.filename = content[0]
-              part.type = content[1]
-            else
-              part.data = content.to_s
-            end
+            add_mime_part(part, content)
           end
           structure
         end
@@ -111,48 +107,147 @@ module Ethon
         raise ArgumentError, "multipart bodies require a Hash of fields"
       end
 
-      def contains_file?(value)
+      def contains_multipart_part?(value)
         case value
+        when Multipart::Part
+          value.upload? || !value.content_type.nil?
         when Hash
-          value.values.any? { |item| contains_file?(item) }
+          value.values.any? { |item| contains_multipart_part?(item) }
         when Array
-          value.any? { |item| contains_file?(item) }
+          value.any? { |item| contains_multipart_part?(item) }
         else
-          value.is_a?(File) || (defined?(Tempfile) && value.is_a?(Tempfile))
+          Multipart::Part.file?(value)
         end
       end
 
+      def add_mime_part(part, content)
+        case content
+        when Multipart::Part
+          add_mime_part_from_part(part, content)
+        when Queryable::FileInfo
+          part.file = content[2]
+          part.filename = content[0]
+          part.type = content[1]
+        else
+          part.data = content.to_s
+        end
+      end
+
+      def add_mime_part_from_part(part, content)
+        unless content.upload?
+          part.data = content.value.to_s
+          part.type = content.content_type unless content.content_type.nil?
+          return
+        end
+
+        filename = part_filename(content)
+        content_type = part_content_type(content, filename)
+
+        if content.file?
+          part.file = part_path(content)
+        else
+          part.data = content.value.to_s
+        end
+        part.filename = filename
+        part.type = content_type
+      end
+
       def form_add(name, content)
         name = validate_header_line(:name, name.to_s)
-        code = case content
+        options = [
+          :form_option, :copyname, :pointer, name,
+          :form_option, :namelength, :long, name.bytesize
+        ]
+
+        case content
+        when Multipart::Part
+          add_form_options_for_part(options, content)
         when Queryable::FileInfo
-          # The form API writes these into Content-Disposition headers. Older
-          # libcurl versions do not escape them.
-          filename = validate_header_line(:filename, content[0].to_s)
-          content_type = validate_header_line(:content_type, content[1].to_s)
-          Curl.formadd(first, last,
-                       :form_option, :copyname, :pointer, name,
-                       :form_option, :namelength, :long, name.bytesize,
-                       :form_option, :file, :string, content[2],
-                       :form_option, :filename, :string, filename,
-                       :form_option, :contenttype, :string, content_type,
-                       :form_option, :end
-                      )
+          add_form_file_options(options, content[2], content[0], content[1])
         else
-          Curl.formadd(first, last,
-                       :form_option, :copyname, :pointer, name,
-                       :form_option, :namelength, :long, name.bytesize,
-                       :form_option, :copycontents, :pointer, content.to_s,
-                       :form_option, :contentslength, :long, content ? content.to_s.bytesize : 0,
-                       :form_option, :end
-                      )
+          data = content.to_s
+          options.concat([
+            :form_option, :copycontents, :pointer, data,
+            :form_option, :contentslength, :long, data.bytesize
+          ])
         end
 
+        options << :form_option << :end
+        code = Curl.formadd(first, last, *options)
+
         raise Errors::FormAdd.new(code) unless code == 0
 
         setup_garbage_collection
       end
 
+      def add_form_options_for_part(options, content)
+        unless content.upload?
+          data = content.value.to_s
+          options.concat([
+            :form_option, :copycontents, :pointer, data,
+            :form_option, :contentslength, :long, data.bytesize
+          ])
+          return if content.content_type.nil?
+
+          content_type = validate_header_line(:content_type, content.content_type.to_s)
+          options.concat([:form_option, :contenttype, :string, content_type])
+          return
+        end
+
+        filename = part_filename(content)
+        content_type = part_content_type(content, filename)
+
+        if content.file?
+          add_form_file_options(options, part_path(content), filename, content_type)
+        else
+          add_form_buffer_options(options, content.value.to_s, filename, content_type)
+        end
+      end
+
+      # libcurl keeps the path and opens the file when the form is sent, so
+      # make it absolute in case the process changes directory in between.
+      def part_path(part)
+        File.expand_path(part.value.path)
+      end
+
+      def part_filename(part)
+        part.filename || File.basename(part.value.path)
+      end
+
+      def part_content_type(part, filename)
+        part.content_type || mime_type(filename)
+      end
+
+      def add_form_file_options(options, path, filename, content_type)
+        # The form API writes these into Content-Disposition headers. Older
+        # libcurl versions do not escape them.
+        filename = validate_header_line(:filename, filename.to_s)
+        content_type = validate_header_line(:content_type, content_type.to_s)
+        options.concat([
+          :form_option, :file, :string, path,
+          :form_option, :filename, :string, filename,
+          :form_option, :contenttype, :string, content_type
+        ])
+      end
+
+      def add_form_buffer_options(options, data, filename, content_type)
+        filename = validate_header_line(:filename, filename.to_s)
+        content_type = validate_header_line(:content_type, content_type.to_s)
+
+        # CURLFORM_BUFFERPTR does not copy the data, so keep a stable copy
+        # alive until libcurl has read the form during perform. The caller's
+        # String can be changed after setup, and the GC can move it.
+        buffer = FFI::MemoryPointer.from_string(data)
+        (@form_buffers ||= []) << buffer
+
+        options.concat([
+          :form_option, :buffer, :string, filename,
+          :form_option, :bufferptr, :pointer, buffer,
+          :form_option, :bufferlength, :long, data.bytesize,
+          :form_option, :contenttype, :string, content_type
+        ])
+      end
+
       def setup_garbage_collection
         # first is a pointer to a pointer. Since it's a MemoryPointer it will
         # auto clean itself up, but we need to clean up the object it points

data/lib/ethon/easy/informations.rb

@@ -9,6 +9,19 @@ module Ethon
 
       # Holds available informations and their type, which is needed to
       # request the informations from libcurl.
+      #
+      # Everything listed here is read for every response that builds a
+      # Mirror, so it stays limited to values that are cheap, not deprecated,
+      # and not tied to a single protocol. Deliberately left out:
+      #
+      # * CURLINFO_PRIVATE returns the pointer set with CURLOPT_PRIVATE, not a
+      #   C string, so a string getter would read freed memory.
+      # * CURLINFO_FILETIME, CURLINFO_CONTENT_LENGTH_DOWNLOAD,
+      #   CURLINFO_CONTENT_LENGTH_UPLOAD and CURLINFO_LASTSOCKET are superseded
+      #   by filetime_t, content_length_*_t and activesocket, which are listed
+      #   above.
+      # * The RTSP informations and CURLINFO_FTP_ENTRY_PATH are only set for
+      #   those protocols.
       AVAILABLE_INFORMATIONS = {
         # The _T variants use curl_off_t and do not lose precision for large
         # values or long-running transfers.
@@ -39,13 +52,24 @@ module Ethon
         :httpauth_used => :long,
         :proxyauth_used => :long,
         :proxy_ssl_verifyresult => :long,
+        # Result of the SSL peer certificate verification. Zero means the
+        # certificate was verified successfully. (Added in 7.19.0)
+        :ssl_verifyresult => :long,
         :proxy_error => :long,
         :used_proxy => :long,
+        :local_port => :long,
+        :num_connects => :long,
+        :os_errno => :long,
+        :http_connectcode => :long,
+        :proxyauth_avail => :long,
+        :condition_unmet => :long,
+        :header_size => :long,
         :scheme => :string,
         :effective_method => :string,
         :referer => :string,
         :cainfo => :string,
         :capath => :string,
+        :content_type => :string,
         :activesocket => :socket,
         :tls_ssl_ptr => :ptr,
 
@@ -100,6 +124,12 @@ module Ethon
         # may be IPv6 if that's enabled.
         :primary_ip => :string,
 
+        # Return the local IP address of the most recent connection.
+        :local_ip => :string,
+
+        # Return the destination port of the most recent connection.
+        :primary_port => :long,
+
         # Return the last received HTTP, FTP or SMTP response code.
         # The value will be zero if no server response code has
         # been received. Note that a proxy's CONNECT response should

data/lib/ethon/easy/mirror.rb

@@ -8,9 +8,15 @@ module Ethon
       # Raw pointers cannot be marshaled and point into native state that can
       # go away when the handle is reset. Applications serialize a mirror (for
       # example as a cached Typhoeus response), so leave them on the Easy.
+      #
+      # certinfo is appended by hand because libcurl returns a list of lists
+      # for it rather than a scalar, so it is not part of
+      # AVAILABLE_INFORMATIONS. It is read on every mirror like the rest,
+      # which costs one getinfo call that returns NULL when the Easy was not
+      # asked for the chain.
       INFORMATIONS_TO_MIRROR = Informations::AVAILABLE_INFORMATIONS.
           reject { |_, type| type == :ptr }.keys +
-          [:return_code, :response_headers, :response_body, :debug_info, :error_message]
+          [:return_code, :response_headers, :response_body, :debug_info, :error_message, :certinfo]
 
       INFORMATIONS_TO_LOG = [:effective_url, :response_code, :return_code, :total_time]
 

data/lib/ethon/easy/options.rb

@@ -219,9 +219,12 @@ module Ethon
           @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
+          # A zero size keeps libcurl on the null reader, which sends
+          # Content-Length: 0. With the size left at -1 libcurl treats the
+          # body as indeterminate, sends it chunked, and reads it from the
+          # default read callback, which is stdin.
+          Curl.set_option(:postfieldsize, 0, handle)
+          @postfieldsize_value = nil
         else
           string = value.to_s
           string = string.dup.freeze unless string.frozen?
@@ -249,10 +252,11 @@ module Ethon
           @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
+          # Clear the size too, otherwise libcurl keeps describing the copy
+          # that is being removed. Zero rather than -1 for the same reason as
+          # in #postfields=.
+          Curl.set_option(:postfieldsize, 0, handle)
+          @postfieldsize_value = nil
           return value
         end
 

data/lib/ethon/easy/queryable.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
+require 'ethon/multipart'
+
 module Ethon
   class Easy
 
@@ -186,6 +188,9 @@ module Ethon
 
       def pairs_for(v, key, pairs)
         case v
+        when Multipart::Part
+          # The form builders need the metadata, so keep the part intact.
+          pairs << [key, v]
         when Hash, Array
           recursively_generate_pairs(v, key, pairs)
         when File, Tempfile

data/lib/ethon/errors/fork_safety.rb

@@ -2,8 +2,8 @@
 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")
+      def initialize(message = "Ethon cannot use libcurl initialized before a fork; use fork+exec or initialize libcurl after forking")
+        super(message)
       end
     end
   end

data/lib/ethon/libc.rb

@@ -15,6 +15,11 @@ module Ethon
       Gem.win_platform?
     end
 
+    # :nodoc:
+    def self.macos?
+      FFI::Platform.mac?
+    end
+
     def self.open_max
       value = Etc.sysconf(Etc::SC_OPEN_MAX)
       return value if value && value > 0

data/lib/ethon/multipart.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Ethon
+  # Multipart form data support.
+  module Multipart
+    # A single part of a multipart form body.
+    #
+    # Wrap a value to control the content type, and optionally the filename,
+    # that Ethon sends for that field. Values that are not wrapped keep the
+    # existing behaviour: files are detected with mime-types and plain values
+    # have no content type.
+    #
+    # @example A JSON field.
+    #   Ethon::Multipart::Part.new('{"a":1}', content_type: "application/json")
+    #
+    # @example A file with an explicit filename and content type.
+    #   Ethon::Multipart::Part.new(
+    #     File.open("photo.jpg"),
+    #     filename: "avatar.png",
+    #     content_type: "image/png"
+    #   )
+    #
+    # @example An in-memory upload.
+    #   Ethon::Multipart::Part.new(
+    #     "file contents",
+    #     filename: "notes.txt",
+    #     content_type: "text/plain"
+    #   )
+    class Part
+      # @return [ String, File, Tempfile ] The value sent for this field.
+      attr_reader :value
+
+      # @return [ String, nil ] The filename sent for an upload.
+      attr_reader :filename
+
+      # @return [ String, nil ] The content type sent for this part.
+      attr_reader :content_type
+
+      # Create a new multipart part.
+      #
+      # A value that responds to #read must be a File or Tempfile. Ethon
+      # sends files by path; other IO objects have to be read by the caller.
+      #
+      # @param [ String, File, Tempfile ] value The value of the part.
+      # @param [ String, nil ] filename The filename to send. Setting it turns
+      #   a String value into a file part.
+      # @param [ String, nil ] content_type The content type for this part.
+      #
+      # @raise [ ArgumentError ] If value is an IO that Ethon cannot upload.
+      def initialize(value, filename: nil, content_type: nil)
+        if value.respond_to?(:read) && !self.class.file?(value)
+          raise ArgumentError,
+            "multipart parts take a String or a File, not #{value.class}; read the IO first"
+        end
+
+        @value = value
+        @filename = filename
+        @content_type = content_type
+      end
+
+      # Return whether the value is a file Ethon can read by path.
+      #
+      # @return [ Boolean ] True for File and Tempfile values.
+      def file?
+        self.class.file?(value)
+      end
+
+      # Return whether this part is an upload rather than a regular field.
+      # A filename turns in-memory data into an upload, matching curl's
+      # "-F name=value;filename=..." behaviour.
+      #
+      # @return [ Boolean ] True when the part has a file or a filename.
+      def upload?
+        file? || !filename.nil?
+      end
+
+      # @api private
+      def self.file?(value)
+        value.is_a?(File) || (defined?(Tempfile) && value.is_a?(Tempfile))
+      end
+
+      # Return the value as a string, so a part can still be encoded like a
+      # plain form value when a caller asks for a non-multipart body.
+      #
+      # @return [ String ] The string representation of the value.
+      def to_s
+        value.to_s
+      end
+
+      def ==(other)
+        other.is_a?(Part) &&
+          value_key == other.value_key &&
+          filename == other.filename &&
+          content_type == other.content_type
+      end
+      alias eql? ==
+
+      def hash
+        [Part, value_key, filename, content_type].hash
+      end
+
+      # The value used by #== and #hash. Files compare by path because File
+      # itself compares by identity.
+      #
+      # @api private
+      def value_key
+        file? ? value.path : value
+      end
+
+      def inspect
+        "#<#{self.class} value=#{value.inspect} filename=#{filename.inspect} content_type=#{content_type.inspect}>"
+      end
+    end
+  end
+end

data/lib/ethon/version.rb

@@ -2,5 +2,5 @@
 module Ethon
 
   # Ethon version.
-  VERSION = '0.19.1'
+  VERSION = '0.19.2'
 end

data/lib/ethon.rb

@@ -7,6 +7,7 @@ require 'tempfile'
 require 'ethon/libc'
 require 'ethon/curl'
 require 'ethon/curls/mime'
+require 'ethon/multipart'
 require 'ethon/easy'
 require 'ethon/easy/url'
 require 'ethon/easy/mime'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ethon
 version: !ruby/object:Gem::Version
-  version: 0.19.1
+  version: 0.19.2
 platform: ruby
 authors:
 - Hans Hasselberg
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-28 00:00:00.000000000 Z
+date: 2026-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -128,16 +128,17 @@ files:
 - lib/ethon/multi/operations.rb
 - lib/ethon/multi/options.rb
 - lib/ethon/multi/stack.rb
+- lib/ethon/multipart.rb
 - lib/ethon/version.rb
 homepage: https://github.com/typhoeus/ethon
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/typhoeus/ethon/issues
-  changelog_uri: https://github.com/typhoeus/ethon/blob/v0.19.1/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/ethon/0.19.1
+  changelog_uri: https://github.com/typhoeus/ethon/blob/v0.19.2/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/ethon/0.19.2
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/typhoeus/ethon/tree/v0.19.1
+  source_code_uri: https://github.com/typhoeus/ethon/tree/v0.19.2
 post_install_message:
 rdoc_options: []
 require_paths: