ethon 0.18.0 → 0.19.0

data/lib/ethon/curls/codes.rb

@@ -7,7 +7,7 @@ module Ethon
     module Codes
 
       # Libcurl error codes, refer
-      # https://github.com/bagder/curl/blob/master/include/curl/curl.h for details
+      # https://github.com/curl/curl/blob/master/include/curl/curl.h for details
       def easy_codes
         [
           :ok,
@@ -18,7 +18,7 @@ module Ethon
           :couldnt_resolve_proxy,
           :couldnt_resolve_host,
           :couldnt_connect,
-          :ftp_weird_server_reply,
+          :ftp_weird_server_reply, # CURLE_WEIRD_SERVER_REPLY since 7.51.0
           :remote_access_denied,
           :ftp_accept_failed,
           :ftp_weird_pass_reply,
@@ -44,14 +44,14 @@ module Ethon
           :ftp_couldnt_use_rest,
           :obsolete32,
           :range_error,
-          :http_post_error,
+          :http_post_error, # CURLE_OBSOLETE34 since 7.56.0
           :ssl_connect_error,
           :bad_download_resume,
           :file_couldnt_read_file,
           :ldap_cannot_bind,
           :ldap_search_failed,
           :obsolete40,
-          :function_not_found,
+          :function_not_found, # CURLE_OBSOLETE41 since 7.53.0
           :aborted_by_callback,
           :bad_function_argument,
           :obsolete44,
@@ -59,7 +59,7 @@ module Ethon
           :obsolete46,
           :too_many_redirects ,
           :unknown_option,
-          :telnet_option_syntax ,
+          :telnet_option_syntax, # CURLE_SETOPT_OPTION_SYNTAX since 7.78.0
           :obsolete50,
           :obsolete51,
           :got_nothing,
@@ -72,7 +72,7 @@ module Ethon
           :ssl_cipher,
           :peer_failed_verification,
           :bad_content_encoding,
-          :ldap_invalid_url,
+          :ldap_invalid_url, # CURLE_OBSOLETE62 since 7.82.0
           :filesize_exceeded,
           :use_ssl_failed,
           :send_fail_rewind,
@@ -85,8 +85,8 @@ module Ethon
           :tftp_unknownid,
           :remote_file_exists,
           :tftp_nosuchuser,
-          :conv_failed,
-          :conv_reqd,
+          :conv_failed, # CURLE_OBSOLETE75 since 7.82.0
+          :conv_reqd, # CURLE_OBSOLETE76 since 7.82.0
           :ssl_cacert_badfile,
           :remote_file_not_found,
           :ssh,
@@ -99,12 +99,25 @@ module Ethon
           :rtsp_session_error,
           :ftp_bad_file_list,
           :chunk_failed,
+          :no_connection_available,
+          :ssl_pinnedpubkeynotmatch,
+          :ssl_invalidcertstatus,
+          :http2_stream,
+          :recursive_api_call,
+          :auth_error,
+          :http3,
+          :quic_connect_error,
+          :proxy,
+          :ssl_clientcert,
+          :unrecoverable_poll,
+          :too_large,
+          :ech_required,
           :last
         ]
       end
 
       # Curl-Multi socket error codes, refer
-      # https://github.com/bagder/curl/blob/master/include/curl/multi.h for details
+      # https://github.com/curl/curl/blob/master/include/curl/multi.h for details
       def multi_codes
         [
           :call_multi_perform, -1,
@@ -115,6 +128,12 @@ module Ethon
           :internal_error,
           :bad_socket,
           :unknown_option,
+          :added_already,
+          :recursive_api_call,
+          :wakeup_failure,
+          :bad_function_argument,
+          :aborted_by_callback,
+          :unrecoverable_poll,
           :last
         ]
       end

data/lib/ethon/curls/constants.rb

@@ -4,6 +4,34 @@ module Ethon
     # :nodoc:
     VERSION_NOW = 3
 
+    # curl_sslbackend values used by curl_global_sslset.
+    SslBackend = enum(:ssl_backend, [
+      :none,
+      :openssl,
+      :gnutls,
+      :nss,
+      :obsolete4,
+      :gskit,
+      :polarssl,
+      :wolfssl,
+      :schannel,
+      :securetransport,
+      :axtls,
+      :mbedtls,
+      :mesalink,
+      :bearssl,
+      :rustls
+    ])
+
+    # CURLsslset values returned by curl_global_sslset. These are not CURLcode
+    # values, even though both start at zero.
+    SslSetCode = enum(:ssl_set_code, [
+      :ok,
+      :unknown_backend,
+      :too_late,
+      :no_backends
+    ])
+
     # Flag. Initialize SSL.
     GLOBAL_SSL     = 0x01
     # Flag. Initialize win32 socket libraries.
@@ -24,18 +52,18 @@ module Ethon
     MultiOption = enum(:multi_option, multi_options(:enum).to_a.flatten)
 
     # Used by curl_debug_callback when setting CURLOPT_DEBUGFUNCTION
-    # https://github.com/bagder/curl/blob/master/include/curl/curl.h#L378 for details
+    # https://github.com/curl/curl/blob/master/include/curl/curl.h#L378 for details
     DebugInfoType = enum(:debug_info_type, debug_info_types)
 
     # :nodoc:
     InfoType = enum(info_types.to_a.flatten)
 
     # Info details, refer
-    # https://github.com/bagder/curl/blob/master/src/tool_writeout.c#L66 for details
+    # https://github.com/curl/curl/blob/master/src/tool_writeout.c#L66 for details
     Info = enum(:info, infos.to_a.flatten)
 
     # Form options, used by FormAdd for temporary storage, refer
-    # https://github.com/bagder/curl/blob/master/lib/formdata.h#L51 for details
+    # https://github.com/curl/curl/blob/master/lib/formdata.h#L51 for details
     FormOption = enum(:form_option, form_options)
 
     # :nodoc:
@@ -59,8 +87,26 @@ module Ethon
     VERSION_NTLM_WB = (1<<15) # NTLM delegating to winbind helper
     VERSION_HTTP2 = (1<<16) # HTTP2 support built
     VERSION_GSSAPI = (1<<17) # GSS-API is supported
+    VERSION_KERBEROS5 = (1<<18) # Kerberos V5 auth is supported
+    VERSION_UNIX_SOCKETS = (1<<19) # Unix domain sockets support
+    VERSION_PSL = (1<<20) # Public Suffix List support
+    VERSION_HTTPS_PROXY = (1<<21) # HTTPS-proxy support built-in
+    VERSION_MULTI_SSL = (1<<22) # Multiple SSL backends available
+    VERSION_BROTLI = (1<<23) # Brotli features are present
+    VERSION_ALTSVC = (1<<24) # Alt-Svc handling built-in
+    VERSION_HTTP3 = (1<<25) # HTTP3 support built-in
+    VERSION_ZSTD = (1<<26) # zstd features are present
+    VERSION_UNICODE = (1<<27) # Unicode support on Windows
+    VERSION_HSTS = (1<<28) # HSTS is supported
+    VERSION_GSASL = (1<<29) # libgsasl is supported
+    VERSION_THREADSAFE = (1<<30) # libcurl API is thread-safe
 
-    SOCKET_BAD = -1
+    # curl_socket_t is int on Unix and SOCKET (UINT_PTR) on Windows.
+    SOCKET_BAD = if Curl.windows?
+      (1 << (::FFI.type_size(:size_t) * 8)) - 1
+    else
+      -1
+    end
     SOCKET_TIMEOUT = SOCKET_BAD
 
     PollAction = enum(:poll_action, [
@@ -76,5 +122,16 @@ module Ethon
       :out, # CURL_CSELECT_OUT - 0x02 (bit 1)
       :err, # CURL_CSELECT_ERR - 0x04 (bit 2)
     ])
+
+    # Bitmasks for curl_easy_pause.
+    PAUSE_RECV = (1<<0)
+    PAUSE_SEND = (1<<2)
+    PAUSE_ALL = (PAUSE_RECV | PAUSE_SEND)
+    PAUSE_CONT = 0
+
+    # Event bits for curl_multi_wait/curl_multi_poll.
+    WAIT_POLLIN = 0x0001
+    WAIT_POLLPRI = 0x0002
+    WAIT_POLLOUT = 0x0004
   end
 end

data/lib/ethon/curls/form_options.rb

@@ -6,7 +6,7 @@ module Ethon
     module FormOptions
 
       # Form options, used by FormAdd for temporary storage, refer
-      # https://github.com/bagder/curl/blob/master/lib/formdata.h#L51 for details
+      # https://github.com/curl/curl/blob/master/lib/formdata.h#L51 for details
       def form_options
         [
           :none,
@@ -29,6 +29,7 @@ module Ethon
           :end,
           :obsolete2,
           :stream,
+          :contentlen,
           :last
         ]
       end

data/lib/ethon/curls/functions.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require 'ethon/curls/optional'
 module Ethon
   module Curls
 
@@ -12,8 +13,14 @@ module Ethon
         base.attach_function :global_cleanup,             :curl_global_cleanup,      [],                             :void
         base.attach_function :free,                       :curl_free,                [:pointer],                     :void
 
+        Ethon::Curls::Optional.attach(base, :easy_header, :curl_easy_header, [:pointer, :string, :size_t, :uint, :int, :pointer], :header_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :easy_nextheader, :curl_easy_nextheader, [:pointer, :uint, :int, :pointer], Curl::HeaderData.ptr, blocking: false)
+        Ethon::Curls::Optional.attach(base, :easy_option_by_name, :curl_easy_option_by_name, [:string], Curl::EasyOptionInfo.ptr, blocking: false)
+        Ethon::Curls::Optional.attach(base, :easy_option_by_id, :curl_easy_option_by_id, [:easy_option], Curl::EasyOptionInfo.ptr, blocking: false)
+        Ethon::Curls::Optional.attach(base, :easy_option_next, :curl_easy_option_next, [:pointer], Curl::EasyOptionInfo.ptr, blocking: false)
+
         base.attach_function :easy_init,                  :curl_easy_init,           [],                             :pointer
-        base.attach_function :easy_cleanup,               :curl_easy_cleanup,        [:pointer],                     :void
+        base.attach_function :easy_cleanup,               :curl_easy_cleanup,        [:pointer],                     :void, blocking: true
         base.attach_function :easy_getinfo,               :curl_easy_getinfo,        [:pointer, :info, :varargs],    :easy_code
         base.attach_function :easy_setopt,                :curl_easy_setopt,         [:pointer, :easy_option, :varargs], :easy_code
         base.instance_variable_set(:@blocking, true)
@@ -21,38 +28,80 @@ module Ethon
         base.attach_function :easy_strerror,              :curl_easy_strerror,       [:easy_code],                   :string
         base.attach_function :easy_escape,                :curl_easy_escape,         [:pointer, :pointer, :int],     :pointer
         base.attach_function :easy_reset,                 :curl_easy_reset,          [:pointer],                     :void
-        base.attach_function :easy_duphandle,             :curl_easy_duphandle,      [:pointer],                     :pointer
+        Ethon::Curls::Optional.attach(base, :easy_duphandle, :curl_easy_duphandle, [:pointer], :pointer, blocking: false)
+
+        Ethon::Curls::Optional.attach(base, :url, :curl_url, [], :pointer, blocking: false)
+        Ethon::Curls::Optional.attach(base, :url_cleanup, :curl_url_cleanup, [:pointer], :void, blocking: false)
+        Ethon::Curls::Optional.attach(base, :url_dup, :curl_url_dup, [:pointer], :pointer, blocking: false)
+        Ethon::Curls::Optional.attach(base, :url_get, :curl_url_get, [:pointer, :url_part, :pointer, :url_flags], :url_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :url_set, :curl_url_set, [:pointer, :url_part, :string, :url_flags], :url_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :url_strerror, :curl_url_strerror, [:url_code], :string, blocking: false)
 
-        base.attach_function :formadd,                    :curl_formadd,             [:pointer, :pointer, :varargs], :int
-        base.attach_function :formfree,                   :curl_formfree,            [:pointer],                     :void
+        # The form API is deprecated and absent from builds configured with
+        # --disable-form-api. Attach it when present so Ethon still loads.
+        Ethon::Curls::Optional.attach(base, :formadd, :curl_formadd, [:pointer, :pointer, :varargs], :int)
+        Ethon::Curls::Optional.attach(base, :formfree, :curl_formfree, [:pointer], :void)
+
+        Ethon::Curls::Optional.attach(base, :share_init, :curl_share_init, [], :pointer, blocking: false)
+        Ethon::Curls::Optional.attach(base, :share_cleanup, :curl_share_cleanup, [:pointer], :share_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :share_setopt, :curl_share_setopt, [:pointer, :share_option, :varargs], :share_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :share_strerror, :curl_share_strerror, [:share_code], :string, blocking: false)
 
         base.attach_function :multi_init,                 :curl_multi_init,          [],                             :pointer
-        base.attach_function :multi_cleanup,              :curl_multi_cleanup,       [:pointer],                     :void
+        base.attach_function :multi_cleanup,              :curl_multi_cleanup,       [:pointer],                     :void, blocking: true
         base.attach_function :multi_add_handle,           :curl_multi_add_handle,    [:pointer, :pointer],           :multi_code
-        base.attach_function :multi_remove_handle,        :curl_multi_remove_handle, [:pointer, :pointer],           :multi_code
+        base.attach_function :multi_remove_handle,        :curl_multi_remove_handle, [:pointer, :pointer],           :multi_code, blocking: true
         base.attach_function :multi_info_read,            :curl_multi_info_read,     [:pointer, :pointer],           Curl::Msg.ptr
-        base.attach_function :multi_perform,              :curl_multi_perform,       [:pointer, :pointer],           :multi_code
+        base.attach_function :multi_perform,              :curl_multi_perform,       [:pointer, :pointer],           :multi_code, blocking: true
         base.attach_function :multi_timeout,              :curl_multi_timeout,       [:pointer, :pointer],           :multi_code
         base.attach_function :multi_fdset,                :curl_multi_fdset,         [:pointer, Curl::FDSet.ptr, Curl::FDSet.ptr, Curl::FDSet.ptr, :pointer], :multi_code
-        base.attach_function :multi_strerror,             :curl_multi_strerror,      [:int],                         :string
+        base.attach_function :multi_strerror,             :curl_multi_strerror,      [:multi_code],                  :string
         base.attach_function :multi_setopt,               :curl_multi_setopt,        [:pointer, :multi_option, :varargs], :multi_code
-        base.attach_function :multi_socket_action,        :curl_multi_socket_action, [:pointer, :int, :socket_readiness, :pointer], :multi_code
+        base.attach_function :multi_socket_action,        :curl_multi_socket_action, [:pointer, :curl_socket_t, :socket_readiness, :pointer], :multi_code, blocking: true
+        base.attach_function :multi_assign,               :curl_multi_assign,        [:pointer, :curl_socket_t, :pointer], :multi_code
+
+        Ethon::Curls::Optional.attach(base, :multi_get_handles, :curl_multi_get_handles, [:pointer], :pointer, blocking: false)
+        Ethon::Curls::Optional.attach(base, :global_sslset, :curl_global_sslset, [:ssl_backend, :string, :pointer], :ssl_set_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :global_trace, :curl_global_trace, [:string], :easy_code, blocking: false)
 
         base.attach_function :version,                    :curl_version,             [],                             :string
-        base.attach_function :version_info,               :curl_version_info,        [],                             Curl::VersionInfoData.ptr
+        base.attach_function :curl_version_info,          :curl_version_info,        [:int],                         Curl::VersionInfoData.ptr
+
+        Ethon::Curls::Optional.attach(base, :mime_init, :curl_mime_init, [:pointer], :pointer, blocking: false)
+        Ethon::Curls::Optional.attach(base, :mime_free, :curl_mime_free, [:pointer], :void, blocking: false)
+        Ethon::Curls::Optional.attach(base, :mime_addpart, :curl_mime_addpart, [:pointer], :pointer, blocking: false)
+        Ethon::Curls::Optional.attach(base, :mime_name, :curl_mime_name, [:pointer, :string], :easy_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :mime_filename, :curl_mime_filename, [:pointer, :string], :easy_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :mime_type, :curl_mime_type, [:pointer, :string], :easy_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :mime_encoder, :curl_mime_encoder, [:pointer, :string], :easy_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :mime_data, :curl_mime_data, [:pointer, :pointer, :size_t], :easy_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :mime_filedata, :curl_mime_filedata, [:pointer, :string], :easy_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :mime_headers, :curl_mime_headers, [:pointer, :pointer, :int], :easy_code, blocking: false)
 
         base.attach_function :slist_append,               :curl_slist_append,        [:pointer, :string],            :pointer
         base.attach_function :slist_free_all,             :curl_slist_free_all,      [:pointer],                     :void
         base.instance_variable_set(:@blocking, true)
 
+        Ethon::Curls::Optional.attach(base, :easy_unescape, :curl_easy_unescape, [:pointer, :pointer, :int, :pointer], :pointer, blocking: false)
+        Ethon::Curls::Optional.attach(base, :easy_pause, :curl_easy_pause, [:pointer, :int], :easy_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :easy_send, :curl_easy_send, [:pointer, :pointer, :size_t, :pointer], :easy_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :easy_recv, :curl_easy_recv, [:pointer, :pointer, :size_t, :pointer], :easy_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :multi_wait, :curl_multi_wait, [:pointer, :pointer, :uint, :int, :pointer], :multi_code, blocking: true)
+        Ethon::Curls::Optional.attach(base, :easy_upkeep, :curl_easy_upkeep, [:pointer], :easy_code, blocking: false)
+        Ethon::Curls::Optional.attach(base, :multi_poll, :curl_multi_poll, [:pointer, :pointer, :uint, :int, :pointer], :multi_code, blocking: true)
+        Ethon::Curls::Optional.attach(base, :multi_wakeup, :curl_multi_wakeup, [:pointer], :multi_code, blocking: false)
+
         if Curl.windows?
             base.ffi_lib 'ws2_32'
         else
             base.ffi_lib ::FFI::Library::LIBC
         end
 
-        base.attach_function :select,                                            [:int, Curl::FDSet.ptr, Curl::FDSet.ptr, Curl::FDSet.ptr, Curl::Timeval.ptr], :int
+        # select() blocks for the multi timeout. Release the GVL so other Ruby
+        # threads can run while the select fallback is waiting.
+        base.attach_function :select,                                            [:int, Curl::FDSet.ptr, Curl::FDSet.ptr, Curl::FDSet.ptr, Curl::Timeval.ptr], :int, blocking: true
       end
+
     end
   end
 end

data/lib/ethon/curls/infos.rb

@@ -17,12 +17,15 @@ module Ethon
           :string =>0x100000,
           :long =>  0x200000,
           :double =>0x300000,
-          :slist => 0x400000
+          :slist => 0x400000,
+          :ptr =>   0x400000,
+          :socket =>0x500000,
+          :off_t => 0x600000
         }
       end
 
-      # http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTDEBUGFUNCTION
-      # https://github.com/bagder/curl/blob/master/include/curl/curl.h#L378
+      # https://curl.se/libcurl/c/CURLOPT_DEBUGFUNCTION.html
+      # https://github.com/curl/curl/blob/master/include/curl/curl.h#L378
       #
       # @example Return debug info types.
       #   Ethon::Curl.debug_info_types
@@ -41,7 +44,7 @@ module Ethon
       end
 
       # Return Info details, refer
-      # https://github.com/bagder/curl/blob/master/src/tool_writeout.c#L66 for details
+      # https://github.com/curl/curl/blob/master/src/tool_writeout.c#L66 for details
       #
       # @example Return infos.
       #   Ethon::Curl.infos
@@ -49,6 +52,40 @@ module Ethon
       # @return [ Hash ] The infos.
       def infos
         {
+          :size_upload_t =>          info_types[:off_t]  + 7,
+          :size_download_t =>        info_types[:off_t]  + 8,
+          :speed_download_t =>       info_types[:off_t]  + 9,
+          :speed_upload_t =>         info_types[:off_t]  + 10,
+          :filetime_t =>             info_types[:off_t]  + 14,
+          :content_length_download_t =>info_types[:off_t] + 15,
+          :content_length_upload_t =>info_types[:off_t]  + 16,
+          :http_version =>           info_types[:long]   + 46,
+          :proxy_ssl_verifyresult => info_types[:long]   + 47,
+          :scheme =>                 info_types[:string] + 49,
+          :total_time_t =>           info_types[:off_t]  + 50,
+          :namelookup_time_t =>      info_types[:off_t]  + 51,
+          :connect_time_t =>         info_types[:off_t]  + 52,
+          :pretransfer_time_t =>     info_types[:off_t]  + 53,
+          :starttransfer_time_t =>   info_types[:off_t]  + 54,
+          :redirect_time_t =>        info_types[:off_t]  + 55,
+          :appconnect_time_t =>      info_types[:off_t]  + 56,
+          :retry_after =>            info_types[:off_t]  + 57,
+          :effective_method =>       info_types[:string] + 58,
+          :proxy_error =>            info_types[:long]   + 59,
+          :referer =>                info_types[:string] + 60,
+          :cainfo =>                 info_types[:string] + 61,
+          :capath =>                 info_types[:string] + 62,
+          :xfer_id =>                info_types[:off_t]  + 63,
+          :conn_id =>                info_types[:off_t]  + 64,
+          :queue_time_t =>           info_types[:off_t]  + 65,
+          :used_proxy =>             info_types[:long]   + 66,
+          :posttransfer_time_t =>    info_types[:off_t]  + 67,
+          :earlydata_sent_t =>       info_types[:off_t]  + 68,
+          :httpauth_used =>          info_types[:long]   + 69,
+          :proxyauth_used =>         info_types[:long]   + 70,
+          :size_delivered =>         info_types[:off_t]  + 71,
+          :activesocket =>           info_types[:socket] + 44,
+          :tls_ssl_ptr =>            info_types[:ptr]    + 45,
           :effective_url =>          info_types[:string] + 1,
           :response_code =>          info_types[:long]   + 2,
           :total_time =>             info_types[:double] + 3,
@@ -91,7 +128,7 @@ module Ethon
           :primary_port =>           info_types[:long]   + 40,
           :local_ip =>               info_types[:string] + 41,
           :local_port =>             info_types[:long]   + 42,
-          :last =>42
+          :last =>71
         }
       end
 
@@ -146,6 +183,68 @@ module Ethon
           double_ptr.read_double
         end
       end
+
+      # Return info as a 64-bit integer (curl_off_t).
+      def get_info_off_t(option, handle)
+        int64_ptr = ::FFI::MemoryPointer.new(:int64)
+
+        if easy_getinfo(handle, option, :pointer, int64_ptr) == :ok
+          int64_ptr.read_int64
+        end
+      end
+
+      # Return info as a curl_socket_t.
+      def get_info_socket(option, handle)
+        if Curl.windows?
+          ptr = ::FFI::MemoryPointer.new(:size_t)
+          return unless easy_getinfo(handle, option, :pointer, ptr) == :ok
+          ::FFI.type_size(:size_t) == 8 ? ptr.read_uint64 : ptr.read_uint32
+        else
+          ptr = ::FFI::MemoryPointer.new(:int)
+          ptr.read_int if easy_getinfo(handle, option, :pointer, ptr) == :ok
+        end
+      end
+
+      # Return info as a raw pointer.
+      def get_info_ptr(option, handle)
+        ptr = ::FFI::MemoryPointer.new(:pointer)
+
+        if easy_getinfo(handle, option, :pointer, ptr) == :ok
+          value = ptr.read_pointer
+          value unless value.null?
+        end
+      end
+
+      # Return info as array of strings.
+      #
+      # @example Return info.
+      #   Curl.get_info_slist(:ssl_engines, easy)
+      #
+      # @param [ Symbol ] option The option name.
+      # @param [ ::FFI::Pointer ] handle The easy handle.
+      #
+      # @return [ Array ] The info.
+      def get_info_slist(option, handle)
+        result = ::FFI::MemoryPointer.new(:pointer)
+        return unless easy_getinfo(handle, option, :pointer, result) == :ok
+
+        pointer = result.read_pointer
+        return [] if pointer.null?
+
+        list = Curl::Slist.new(pointer)
+        list.to_a
+      ensure
+        list.free if list
+      end
+
+      # Return certificate information copied from libcurl-owned memory.
+      def get_info_certinfo(option, handle)
+        result = ::FFI::MemoryPointer.new(:pointer)
+        return unless easy_getinfo(handle, option, :pointer, result) == :ok
+
+        pointer = result.read_pointer
+        pointer.null? ? [] : Curl::Certinfo.new(pointer).to_a
+      end
     end
   end
 end

data/lib/ethon/curls/introspection.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+module Ethon
+  module Curl
+    class << self
+      # Look up a libcurl option by name.
+      #
+      # @param [ String, Symbol ] name The CURLOPT name.
+      #
+      # @return [ EasyOptionInfo, nil ] The option metadata.
+      def easy_option(name)
+        return unless respond_to?(:easy_option_by_name)
+
+        info = easy_option_by_name(name.to_s)
+        info.null? ? nil : info
+      end
+
+      # Look up a libcurl option by numeric id.
+      #
+      # @param [ Integer, Symbol ] id The CURLoption id or name.
+      #
+      # @return [ EasyOptionInfo, nil ] The option metadata.
+      def option_by_id(id)
+        return unless respond_to?(:easy_option_by_id)
+
+        info = easy_option_by_id(id)
+        info.null? ? nil : info
+      end
+
+      # Enumerate all libcurl option metadata.
+      #
+      # @return [ Enumerator, Array ] The metadata.
+      def each_easy_option
+        unless respond_to?(:easy_option_next)
+          raise NotImplementedError, "curl_easy_option_next is not supported by this libcurl"
+        end
+        return enum_for(:each_easy_option) unless block_given?
+
+        info = easy_option_next(::FFI::Pointer::NULL)
+        until info.null?
+          yield info
+          info = easy_option_next(info)
+        end
+        self
+      end
+
+      def easy_option_list
+        each_easy_option.to_a
+      end
+
+      # The full version info struct when the runtime supports it.
+      #
+      # @return [ VersionInfoDataFull, nil ] The full version metadata.
+      def version_info_full
+        info = version_info
+        return unless info && info[:curl_version] >= CURLVERSION_ELEVENTH
+
+        VersionInfoDataFull.new(info.to_ptr)
+      end
+
+      # Protocols supported by the loaded libcurl.
+      #
+      # @return [ Array<String> ] Protocol names.
+      def protocols
+        string_array(version_info[:protocols])
+      end
+
+      # Return whether libcurl knows an option.
+      #
+      # Easy options are checked against libcurl's own option table on 7.73.0
+      # and newer. Older versions cannot answer that question, so it returns
+      # `true` for every option Ethon knows. Multi options are only checked
+      # against Ethon's table, because libcurl does not expose multi option
+      # metadata.
+      #
+      # @param [ String, Symbol ] name The CURLOPT_* name without the prefix.
+      # @param [ Symbol ] type :easy or :multi.
+      #
+      # @return [ Boolean ] True when the option is available.
+      def supports_option?(name, type = :easy)
+        name = name.to_sym if name.is_a?(String)
+        options = type == :multi ? multi_options(nil) : easy_options(nil)
+        option = options[name]
+        return false unless option
+
+        if type == :easy && respond_to?(:easy_option_by_id)
+          # Resolve by id so Ethon aliases such as :unix_socket are reported
+          # correctly; libcurl's by-name lookup only knows canonical names.
+          !easy_option_by_id(option[:opt]).null?
+        else
+          true
+        end
+      end
+
+      # Check the loaded libcurl version against a dotted version number.
+      #
+      # @example
+      #   Ethon::Curl.version_at_least?("7.66.0")
+      #
+      # @param [ String ] version The version to compare, for example "7.66.0".
+      #
+      # @return [ Boolean ] True when libcurl is at least that version.
+      def version_at_least?(version)
+        parts = version.to_s.split(".").map(&:to_i)
+        required = (parts[0].to_i << 16) | (parts[1].to_i << 8) | parts[2].to_i
+        version_info[:version_num] >= required
+      end
+
+      # Feature names supported by the loaded libcurl.
+      #
+      # @return [ Array<String> ] Feature names.
+      def feature_names
+        info = version_info_full
+        return [] unless info
+
+        string_array(info[:feature_names])
+      end
+
+      # Read a NULL-terminated array of C strings.
+      #
+      # @param [ FFI::Pointer, nil ] pointer The array pointer.
+      #
+      # @return [ Array<String> ] The strings.
+      def string_array(pointer)
+        return [] if pointer.nil? || pointer.null?
+
+        strings = []
+        offset = 0
+        loop do
+          string = pointer.get_pointer(offset)
+          break if string.null?
+
+          strings << string.read_string
+          offset += ::FFI.type_size(:pointer)
+        end
+        strings
+      end
+    end
+  end
+end

data/lib/ethon/curls/introspection_constants.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+module Ethon
+  module Curl
+    # The struct age at which curl_version_info_data exposes feature_names.
+    CURLVERSION_ELEVENTH = 10
+
+    # CURLHcode values.
+    HeaderCode = enum(:header_code, [
+      :ok,
+      :badindex,
+      :missing,
+      :noheaders,
+      :norequest,
+      :out_of_memory,
+      :bad_argument,
+      :not_built_in
+    ])
+
+    # CURLH_* origin bits.
+    HeaderOrigin = bitmask(:header_origin, [
+      nil,
+      :header,
+      :trailer,
+      :connect,
+      :"1xx",
+      :pseudo
+    ])
+
+    # curl_easytype values used by curl_easy_option_*.
+    EasyType = enum(:easy_type, [
+      :long,
+      :values,
+      :off_t,
+      :object,
+      :string,
+      :slist,
+      :cbptr,
+      :blob,
+      :function
+    ])
+  end
+end