ethon 0.18.0 → 0.19.0

data/lib/ethon/curls/share.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+module Ethon
+  module Curl
+
+    # Thin wrapper around libcurl's share API.
+    class Share < OwnedPointer
+      CALLBACKS_MUTEX = Mutex.new
+
+      attr_reader :lockfunction, :unlockfunction
+
+      def self.native_release(pointer)
+        Curl.share_cleanup(pointer) if Curl.respond_to?(:share_cleanup)
+      end
+
+      # Callback functions must outlive the Share because libcurl invokes them
+      # again from curl_share_cleanup.
+      def self.callbacks
+        @callbacks ||= {}
+      end
+
+      def self.release(pointer)
+        super
+      ensure
+        key = [Process.pid, pointer.address]
+        begin
+          CALLBACKS_MUTEX.synchronize { callbacks.delete(key) }
+        rescue ThreadError, SignalException
+          # Finalizers can run in a trap context where locking is forbidden.
+          callbacks.delete(key)
+        end
+      end
+
+      # Build the dispatcher on the class so the closure does not retain the
+      # Share instance; otherwise the callback registry itself would keep every
+      # share handle alive.
+      #
+      # curl_lock_function and curl_unlock_function do not take the same
+      # arguments. An unlock callback receives the user pointer where a lock
+      # callback receives the access mode.
+      def self.lock_function(callback)
+        FFI::Function.new(:void, [:pointer, :int, :int, :pointer], proc do |handle, data, access, userp|
+          callback.call(handle, Curl::LockData[data], Curl::LockAccess[access], userp)
+        end)
+      end
+
+      def self.unlock_function(callback)
+        FFI::Function.new(:void, [:pointer, :int, :pointer], proc do |handle, data, userp|
+          callback.call(handle, Curl::LockData[data], userp)
+        end)
+      end
+
+      def initialize
+        Curl.init
+        unless Curl.respond_to?(:share_init)
+          raise NotImplementedError, "curl_share_init is not supported by this libcurl"
+        end
+
+        pointer = Curl.share_init
+        raise NoMemoryError, "curl_share_init failed" if pointer.null?
+
+        super(pointer)
+      end
+
+      # Share a data type between easy handles.
+      #
+      # @param [ Symbol, String ] data One of :cookie, :dns, :ssl_session,
+      #   :connect, :psl, or :hsts.
+      #
+      # @return [ Share ] self
+      def share(data)
+        setopt(:share, data)
+        self
+      end
+
+      # Stop sharing a data type.
+      #
+      # @param [ Symbol, String ] data The data type.
+      #
+      # @return [ Share ] self
+      def unshare(data)
+        setopt(:unshare, data)
+        self
+      end
+
+      # Set the callback libcurl calls before accessing shared data.
+      #
+      # The block receives the easy handle, the shared data type, the access
+      # mode, and the user pointer. libcurl requires lock and unlock callbacks
+      # when a share handle is used from more than one thread.
+      #
+      # @example Lock shared cookies.
+      #   share.lockfunction = proc { |handle, data, access, userp| mutex.synchronize { ... } }
+      #
+      # @param [ Proc, nil ] callback The lock callback.
+      #
+      # @return [ Proc, nil ] The callback.
+      def lockfunction=(callback)
+        set_callback(:lockfunc, callback)
+      end
+
+      # Set the callback libcurl calls before releasing a share lock.
+      #
+      # The block receives the easy handle, the shared data type, and the user
+      # pointer. libcurl's unlock callback has no access mode argument.
+      #
+      # @param [ Proc, nil ] callback The unlock callback.
+      #
+      # @return [ Proc, nil ] The callback.
+      def unlockfunction=(callback)
+        set_callback(:unlockfunc, callback)
+      end
+
+      private
+
+      def setopt(option, data)
+        check_pid!
+        unless data.is_a?(Symbol) || data.is_a?(String)
+          raise Errors::InvalidValue.new(option, data)
+        end
+
+        value = Curl::LockData[data.to_sym]
+        raise Errors::InvalidValue.new(option, data) unless value
+
+        code = Curl.share_setopt(self, option, :long, value)
+        raise Errors::Share.new(code) unless code == :ok
+
+        code
+      end
+
+      def set_callback(option, callback)
+        check_pid!
+        unless callback.nil? || callback.is_a?(Proc)
+          raise Errors::InvalidValue.new(option, callback)
+        end
+
+        # libcurl calls the lock and unlock callbacks again during
+        # curl_share_cleanup, so the FFI::Function itself must stay alive.
+        function = if callback
+          option == :lockfunc ? self.class.lock_function(callback) : self.class.unlock_function(callback)
+        end
+
+        code = Curl.share_setopt(self, option, :pointer, function)
+        raise Errors::Share.new(code) unless code == :ok
+
+        key = [Process.pid, address]
+        CALLBACKS_MUTEX.synchronize do
+          registry = self.class.callbacks[key] ||= {}
+          if function
+            registry[option] = function
+          else
+            registry.delete(option)
+            self.class.callbacks.delete(key) if registry.empty?
+          end
+        end
+
+        if option == :lockfunc
+          @lockfunction = callback
+        else
+          @unlockfunction = callback
+        end
+        callback
+      end
+    end
+  end
+end

data/lib/ethon/curls/share_constants.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+module Ethon
+  module Curl
+    # CURLSHcode values.
+    ShareCode = enum(:share_code, [
+      :ok,
+      :bad_option,
+      :in_use,
+      :invalid,
+      :nomem,
+      :not_built_in,
+      :last
+    ])
+
+    # CURLSHoption values.
+    ShareOption = enum(:share_option, [
+      :none,
+      :share,
+      :unshare,
+      :lockfunc,
+      :unlockfunc,
+      :userdata,
+      :last
+    ])
+
+    # curl_lock_data values.
+    LockData = enum(:lock_data, [
+      :none,
+      :share,
+      :cookie,
+      :dns,
+      :ssl_session,
+      :connect,
+      :psl,
+      :hsts,
+      :last
+    ])
+
+    # curl_lock_access values.
+    LockAccess = enum(:lock_access, [
+      :none,
+      :shared,
+      :single,
+      :last
+    ])
+  end
+end

data/lib/ethon/curls/url.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+module Ethon
+  module Curl
+
+    # CURLOPT_CURLU takes a CURLU handle.
+    Ethon::Curls::Options.option(:easy, :curlu, :ffipointer, 282)
+
+    # Thin wrapper around libcurl's URL API (curl_url).
+    class Url < OwnedPointer
+      def self.native_release(pointer)
+        Curl.url_cleanup(pointer) if Curl.respond_to?(:url_cleanup)
+      end
+
+      # Create a URL handle, optionally parsing a URL string.
+      #
+      # @param [ String, Url, FFI::Pointer, nil ] url The URL, a URL handle
+      #   to copy, or a native handle.
+      # @param [ Integer, Symbol, Array ] flags CURLU_* flags. These are only
+      #   applied when parsing a String; a copied handle already has its parts.
+      def initialize(url = nil, flags = 0)
+        Curl.init
+        unless Curl.respond_to?(:url)
+          raise NotImplementedError, "curl_url is not supported by this libcurl"
+        end
+
+        copying = url.is_a?(Ethon::Curl::Url)
+        if copying
+          url.check_pid!
+          if normalize_flags(flags) != 0
+            raise ArgumentError, "flags cannot be applied when copying an Ethon::Curl::Url"
+          end
+          # Parsing the copied handle's string form would fail for partial
+          # handles and could normalize a complete one. Duplicate the parts
+          # instead.
+          pointer = Curl.url_dup(url)
+          raise NoMemoryError, "curl_url_dup failed" if pointer.null?
+        elsif url.is_a?(::FFI::Pointer)
+          pointer = url
+        else
+          pointer = Curl.url
+          raise NoMemoryError, "curl_url failed" if pointer.null?
+        end
+
+        super(pointer)
+        begin
+          set(:url, url, flags) if url && !url.is_a?(::FFI::Pointer) && !copying
+        rescue Exception
+          # A rejected URL must not leave the native handle to the finalizer.
+          free
+          raise
+        end
+      end
+
+      # Set a URL part.
+      #
+      # @param [ Symbol, String, Integer ] part The CURLUPart name or value.
+      # @param [ String, nil ] value The new value, or nil to clear the part.
+      # @param [ Integer, Symbol, Array ] flags CURLU_* flags.
+      #
+      # @raise [ Errors::InvalidValue ] If the part or a flag is unknown, or
+      #   the value contains a NUL byte, CR, or LF.
+      #
+      # @return [ Url ] self
+      def set(part, value, flags = 0)
+        check_pid!
+        code = Curl.url_set(self, normalize_part(part), normalize_value(value),
+                            normalize_flags(flags))
+        raise Errors::Url.new(code) unless code == :ok
+
+        self
+      end
+
+      # Get a URL part.
+      #
+      # @param [ Symbol, String, Integer ] part The CURLUPart name or value.
+      # @param [ Integer, Symbol, Array ] flags CURLU_* flags.
+      #
+      # @raise [ Errors::InvalidValue ] If the part or a flag is unknown.
+      #
+      # @return [ String ] The part value.
+      def get(part, flags = 0)
+        check_pid!
+        output = ::FFI::MemoryPointer.new(:pointer)
+        code = Curl.url_get(self, normalize_part(part), output, normalize_flags(flags))
+        raise Errors::Url.new(code) unless code == :ok
+
+        pointer = output.read_pointer
+        begin
+          pointer.read_string
+        ensure
+          Curl.free(pointer)
+        end
+      end
+
+      # Duplicate the URL handle.
+      #
+      # @return [ Url ] The copied URL.
+      def dup
+        check_pid!
+        pointer = Curl.url_dup(self)
+        raise NoMemoryError, "curl_url_dup failed" if pointer.null?
+
+        self.class.new(pointer)
+      end
+
+      # Cloning shares the native handle in Ruby, so route it through #dup.
+      def clone(freeze: true)
+        copy = dup
+        copy.freeze if freeze && frozen?
+        copy
+      end
+
+      def to_s
+        get(:url)
+      end
+
+      private
+
+      # Only names that exist in CURLUPart reach libcurl. FFI would raise its
+      # own ArgumentError for anything else. Direct enum values stay supported,
+      # like the named option setters.
+      def normalize_part(part)
+        name = part.is_a?(String) ? part.to_sym : part
+        values = Curl::UrlPart.to_h
+        unless values.key?(name) || (name.is_a?(Integer) && values.value?(name))
+          raise Errors::InvalidValue.new(:url_part, part)
+        end
+
+        name
+      end
+
+      # libcurl takes a C string, so an embedded NUL would silently truncate
+      # the value. nil clears the part.
+      #
+      # The URL API also accepts CR and LF, which libcurl writes verbatim into
+      # the request line or query. A path or query containing CRLF can add
+      # attackers' headers to the request, so reject them here just like the
+      # string URL parser does. Callers that need such bytes in a URL must
+      # percent-encode them.
+      def normalize_value(value)
+        return if value.nil?
+
+        string = value.to_s
+        if string.include?("\0") || string.include?("\r") || string.include?("\n")
+          raise Errors::InvalidValue.new(:url_value, value)
+        end
+
+        string
+      end
+
+      # Only CURLU_* flag names reach libcurl. FFI would raise its own
+      # ArgumentError for anything else. Direct bit values stay supported, like
+      # the named option setters.
+      def normalize_flags(flags)
+        return flags if flags.is_a?(Integer)
+
+        Array(flags).inject(0) { |mask, flag| mask | normalize_flag(flag) }
+      end
+
+      def normalize_flag(flag)
+        return flag if flag.is_a?(Integer)
+
+        name = flag.is_a?(String) ? flag.to_sym : flag
+        value = name.is_a?(Symbol) && Curl::UrlFlags.to_h[name]
+        raise Errors::InvalidValue.new(:url_flags, flag) unless value
+
+        value
+      end
+    end
+  end
+end

data/lib/ethon/curls/url_constants.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+module Ethon
+  module Curl
+    # CURLUPart values from curl/urlapi.h.
+    UrlPart = enum(:url_part, [
+      :url,
+      :scheme,
+      :user,
+      :password,
+      :options,
+      :host,
+      :port,
+      :path,
+      :query,
+      :fragment,
+      :zoneid
+    ])
+
+    # CURLUcode values from curl/urlapi.h.
+    UrlCode = enum(:url_code, [
+      :ok,
+      :bad_handle,
+      :bad_partpointer,
+      :malformed_input,
+      :bad_port_number,
+      :unsupported_scheme,
+      :urldecode,
+      :out_of_memory,
+      :user_not_allowed,
+      :unknown_part,
+      :no_scheme,
+      :no_user,
+      :no_password,
+      :no_options,
+      :no_host,
+      :no_port,
+      :no_query,
+      :no_fragment,
+      :no_zoneid,
+      :bad_file_url,
+      :bad_fragment,
+      :bad_hostname,
+      :bad_ipv6,
+      :bad_login,
+      :bad_password,
+      :bad_path,
+      :bad_query,
+      :bad_scheme,
+      :bad_slashes,
+      :bad_user,
+      :lacks_idn,
+      :too_large,
+      :backslash,
+      :last
+    ])
+
+    # CURLU_* flag bits from curl/urlapi.h.
+    UrlFlags = bitmask(:url_flags, [
+      nil,
+      :default_port,
+      :no_default_port,
+      :default_scheme,
+      :non_support_scheme,
+      :path_as_is,
+      :disallow_user,
+      :urldecode,
+      :urlencode,
+      :appendquery,
+      :guess_scheme,
+      :no_authority,
+      :allow_space,
+      :punycode,
+      :puny2idn,
+      :get_empty,
+      :no_guess_scheme
+    ])
+  end
+end