wreq 1.2.4-x86_64-linux → 1.2.6-x86_64-linux

data/lib/wreq_ruby/emulate.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Profile and platform constants mirror the native enum variant names.
+# standard:disable Naming/ConstantName
+
 module Wreq
   # Browser and client fingerprint profile enumeration backed by Rust.
   #
@@ -58,6 +61,7 @@ module Wreq
       Chrome147 = nil
       Chrome148 = nil
       Chrome149 = nil
+      Chrome150 = nil
 
       Edge101 = nil
       Edge122 = nil
@@ -154,7 +158,7 @@ module Wreq
       Opera128 = nil
       Opera129 = nil
       Opera130 = nil
-      Opera131 = nils
+      Opera131 = nil
     end
 
     unless method_defined?(:to_s)
@@ -163,6 +167,29 @@ module Wreq
       def to_s
       end
     end
+
+    unless method_defined?(:==)
+      # Value-based equality.
+      # @param other [Object]
+      # @return [Boolean]
+      def ==(other)
+      end
+    end
+
+    unless method_defined?(:eql?)
+      # Strict equality for Hash key and Set member semantics.
+      # @param other [Object]
+      # @return [Boolean]
+      def eql?(other)
+      end
+    end
+
+    unless method_defined?(:hash)
+      # Hash value consistent with {#eql?} for use as Hash keys.
+      # @return [Integer]
+      def hash
+      end
+    end
   end
 
   # Operating system platform enumeration backed by Rust.
@@ -194,6 +221,36 @@ module Wreq
       def to_s
       end
     end
+
+    unless method_defined?(:to_sym)
+      # Returns the platform as a lowercase symbol (e.g. :windows, :linux).
+      # @return [Symbol]
+      def to_sym
+      end
+    end
+
+    unless method_defined?(:==)
+      # Value-based equality.
+      # @param other [Object]
+      # @return [Boolean]
+      def ==(other)
+      end
+    end
+
+    unless method_defined?(:eql?)
+      # Strict equality for Hash key and Set member semantics.
+      # @param other [Object]
+      # @return [Boolean]
+      def eql?(other)
+      end
+    end
+
+    unless method_defined?(:hash)
+      # Hash value consistent with {#eql?} for use as Hash keys.
+      # @return [Integer]
+      def hash
+      end
+    end
   end
 
   # Emulation option wrapper.
@@ -215,18 +272,31 @@ module Wreq
   #
   # @param profile [Wreq::Profile, nil] Fingerprint profile to emulate
   # @param platform [Wreq::Platform, nil] Operating system platform to emulate
-  # @param http2 [Boolean] Whether HTTP/2 support is enabled
-  # @param headers [Boolean] Whether default emulation headers are enabled
+  # @param http2 [Boolean, nil] Whether HTTP/2 emulation is enabled; defaults
+  #   to true when omitted or nil
+  # @param headers [Boolean, nil] Whether default emulation headers are enabled;
+  #   defaults to true when omitted or nil
+  # @return [Wreq::Emulation] Configured emulation settings
+  # @raise [ArgumentError] if an option is unknown or extra arguments are given
+  # @raise [TypeError] if the option argument is not a Hash or a value has the
+  #   wrong Ruby type
   class Emulation
     # Native fields and methods are set by the extension.
     # This stub is for documentation only.
-    unless method_defined?(:new)
+    unless singleton_methods(false).include?(:new)
       # @param profile [Wreq::Profile, nil] Fingerprint profile to emulate
       # @param platform [Wreq::Platform, nil] Operating system platform to emulate
-      # @param http2 [Boolean] Whether HTTP/2 support is enabled
-      # @param headers [Boolean] Whether default emulation headers are enabled
-      def self.new(profile: nil, platform: nil, http2: true, headers: true)
+      # @param http2 [Boolean, nil] Whether HTTP/2 emulation is enabled; defaults
+      #   to true when omitted or nil
+      # @param headers [Boolean, nil] Whether default emulation headers are enabled;
+      #   defaults to true when omitted or nil
+      # @return [Wreq::Emulation] Configured emulation settings
+      # @raise [ArgumentError] if an option is unknown or extra arguments are given
+      # @raise [TypeError] if an option or value has the wrong Ruby type
+      def self.new(**options)
       end
     end
   end
 end
+
+# standard:enable Naming/ConstantName

data/lib/wreq_ruby/error.rb

@@ -88,7 +88,7 @@ unless defined?(Wreq)
     #
     # @example
     #   begin
-    #     client = Wreq::Client.new(max_redirects: 3)
+    #     client = Wreq::Client.new(allow_redirects: true, max_redirects: 3)
     #     client.get("https://httpbin.io/redirect/10")
     #   rescue Wreq::RedirectError => e
     #     puts "Too many redirects: #{e.message}"
@@ -139,16 +139,14 @@ unless defined?(Wreq)
 
     # Configuration and builder errors
 
-    # Client configuration is invalid.
+    # A native client or request configuration could not be built.
     #
-    # Raised when the client is configured with invalid options.
+    # Raised when validated Ruby options cannot be represented by the native
+    # builder or request body.
     #
     # @example
     #   begin
-    #     client = Wreq::Client.new(
-    #       proxy: "invalid://proxy",
-    #       timeout: -1
-    #     )
+    #     client = Wreq::Client.new(proxy: "invalid://")
     #   rescue Wreq::BuilderError => e
     #     puts "Invalid configuration: #{e.message}"
     #   end

data/lib/wreq_ruby/header.rb

@@ -2,202 +2,293 @@
 
 unless defined?(Wreq)
   module Wreq
-    # HTTP headers collection.
+    # A mutable, case-insensitive collection of HTTP headers.
     #
-    # Provides efficient access to HTTP headers with case-insensitive lookups.
-    # Headers are created by the native extension and cannot be directly instantiated.
+    # Header names are normalized by the native header map and lookups are
+    # case-insensitive. Use the `orig_headers` request option when exact wire
+    # casing or header order is required. Duplicate values are stored as
+    # separate header occurrences.
     #
-    # All header names are case-insensitive. Multiple values for the same header
-    # are supported through the `get_all` method.
+    # @example Build and query headers
+    #   headers = Wreq::Headers.new(
+    #     "Accept" => ["application/json", "text/plain"],
+    #     content_type: "application/json"
+    #   )
+    #   headers["accept"]       # => ["application/json", "text/plain"]
+    #   headers[:content_type]  # => "application/json"
     #
-    # @example Accessing response headers
-    #   response = Wreq.get("https://example.com")
-    #   headers = response.headers
-    #   content_type = headers["Content-Type"]
-    #   content_type = headers.get("content-type")  # Same, case-insensitive
-    #
-    # @example Getting all values for a header
-    #   accept_values = headers.get_all("Accept")
-    #   # => ["application/json", "text/html"]
-    #
-    # @example Modifying headers
-    #   headers.set("X-Custom-Header", "value")
-    #   headers["Authorization"] = "Bearer token"
-    #   headers.append("Accept", "application/xml")
-    #
-    # @example Iterating headers
+    # @example Iterate over every occurrence
     #   headers.each do |name, value|
     #     puts "#{name}: #{value}"
     #   end
-    #
-    # @example Converting to hash
-    #   hash = headers.to_h
-    #   hash["content-type"]  # => "text/html"
     class Headers
-      # Create a new empty Headers collection.
+      include Enumerable
+
+      # Create an empty collection or copy header pairs from a source.
       #
-      # @return [Wreq::Headers] New headers instance
+      # @param source [Hash, Wreq::Headers, Enumerable] A hash, another
+      #   headers collection, or an enumerable that yields name-value pairs.
+      #   Omit this argument to create an empty collection.
+      # @return [Wreq::Headers]
+      # @raise [Wreq::BuilderError] if the source does not contain valid pairs
       # @example
-      #   headers = Wreq::Headers.new
-      #   headers.set("Content-Type", "application/json")
-      def self.new
+      #   Wreq::Headers.new
+      #   Wreq::Headers.new("Accept" => "application/json")
+      #   Wreq::Headers.new([[:content_type, "application/json"]])
+      def self.new(*args)
       end
 
-      # Get a header value by name (case-insensitive).
+      # Return the first value for a header.
       #
-      # Returns the first value if multiple values exist for the same header.
-      #
-      # @param name [String] Header name (case-insensitive)
-      # @return [String, nil] Header value, or nil if not found
+      # @param name [String, Symbol] Header name
+      # @return [String, nil] The first value, or nil when the name is missing
       # @example
-      #   headers.get("Content-Type")       # => "application/json"
-      #   headers.get("content-type")       # => "application/json" (same)
-      #   headers.get("X-Nonexistent")      # => nil
+      #   headers.get("content-type")  # => "application/json"
+      #   headers.get(:missing)        # => nil
       def get(name)
       end
 
-      # Get all values for a header name (case-insensitive).
+      # Return a header using collection-style value semantics.
+      #
+      # A missing name returns nil, one occurrence returns a String, and
+      # multiple occurrences return an Array<String>.
       #
-      # Useful when a header can have multiple values (e.g., Accept, Set-Cookie).
+      # @param name [String, Symbol] Header name
+      # @return [String, Array<String>, nil]
+      # @example
+      #   headers["accept"]      # => "application/json"
+      #   headers["set-cookie"]  # => ["a=1", "b=2"]
+      def [](name)
+      end
+
+      # Return every value for a header.
       #
-      # @param name [String] Header name (case-insensitive)
-      # @return [Array<String>] All values for this header (empty array if not found)
+      # @param name [String, Symbol] Header name
+      # @return [Array<String>] Values in insertion order, or an empty array
       # @example
-      #   headers.get_all("Accept")
-      #   # => ["application/json", "text/html", "application/xml"]
-      #   headers.get_all("X-Nonexistent")  # => []
+      #   headers.get_all("set-cookie")  # => ["a=1", "b=2"]
+      #   headers.get_all(:missing)       # => []
       def get_all(name)
       end
 
-      # Set a header value, replacing any existing values.
+      # Set one or more values, replacing every existing occurrence.
+      #
+      # Array values are stored as separate occurrences and are not joined. An
+      # empty Array removes the header.
       #
-      # @param name [String] Header name
-      # @param value [String] Header value
+      # @param name [String, Symbol] Header name
+      # @param value [String, Array<String>] Header value or values
       # @return [void]
-      # @raise [Wreq::BuilderError] if name or value contains invalid characters
+      # @raise [Wreq::BuilderError] if a name or value is invalid
       # @example
-      #   headers.set("Content-Type", "application/json")
-      #   headers.set("X-Custom-Header", "my-value")
+      #   headers.set("Accept", ["application/json", "text/plain"])
       def set(name, value)
       end
 
-      # Append a header value without replacing existing values.
+      # Set one or more values and return the assigned value.
       #
-      # Adds a new value for the header, preserving any existing values.
-      # Useful for headers that can have multiple values.
+      # @param name [String, Symbol] Header name
+      # @param value [String, Array<String>] Header value or values
+      # @return [String, Array<String>] The assigned value
+      # @example
+      #   headers[:content_type] = "application/json"
+      def []=(name, value)
+      end
+
+      # Append one or more values without replacing existing occurrences.
       #
-      # @param name [String] Header name
-      # @param value [String] Header value to append
+      # @param name [String, Symbol] Header name
+      # @param value [String, Array<String>] Header value or values
       # @return [void]
-      # @raise [Wreq::BuilderError] if name or value contains invalid characters
+      # @raise [Wreq::BuilderError] if a name or value is invalid
       # @example
-      #   headers.set("Accept", "application/json")
-      #   headers.append("Accept", "text/html")
-      #   headers.get_all("Accept")  # => ["application/json", "text/html"]
+      #   headers.append("Set-Cookie", ["a=1", "b=2"])
       def append(name, value)
       end
 
-      # Remove all values for a header name.
+      # Return a header value, a fallback, or the result of a block.
       #
-      # @param name [String] Header name (case-insensitive)
-      # @return [String, nil] The removed value (first one if multiple), or nil
+      # @param name [String, Symbol] Header name
+      # @param default [Object] Optional fallback for a missing name
+      # @yieldparam name [String, Symbol] The missing name
+      # @return [String, Array<String>, Object]
+      # @raise [KeyError] if the name is missing and no fallback is provided
       # @example
-      #   headers.remove("Authorization")  # => "Bearer token"
-      #   headers.remove("X-Nonexistent")  # => nil
-      def remove(name)
+      #   headers.fetch("accept", "*/*")
+      #   headers.fetch(:missing) { |name| "missing: #{name}" }
+      def fetch(name, default = nil)
       end
 
-      # Check if a header exists (case-insensitive).
+      # Remove every occurrence for a header.
       #
-      # @param name [String] Header name
-      # @return [Boolean] true if the header exists
+      # @param name [String, Symbol] Header name
+      # @return [String, nil] The first removed value, or nil when missing
       # @example
-      #   headers.contains?("Content-Type")  # => true
-      #   headers.contains?("X-Missing")     # => false
+      #   headers.remove("authorization")  # => "Bearer token"
+      def remove(name)
+      end
+
+      # Remove every occurrence for a header. Alias for {#remove}.
+      #
+      # @param name [String, Symbol] Header name
+      # @return [String, nil] The first removed value, or nil when missing
+      def delete(name)
+      end
+
+      # Check whether a header exists.
+      #
+      # @param name [String, Symbol] Header name
+      # @return [Boolean]
       def contains?(name)
       end
 
-      # Check if a header key exists (alias for {#contains?}).
+      # Check whether a header exists. Alias for {#contains?}.
       #
-      # @param name [String] Header name
-      # @return [Boolean] true if the header exists
-      # @example
-      #   headers.key?("Accept")  # => true
+      # @param name [String, Symbol] Header name
+      # @return [Boolean]
       def key?(name)
       end
 
-      # Get the number of headers.
+      # Return the number of header occurrences.
       #
-      # @return [Integer] Total number of unique header names
-      # @example
-      #   headers.length  # => 12
+      # This can be greater than `keys.length` when a name has multiple values.
+      #
+      # @return [Integer]
       def length
       end
 
-      # Check if there are no headers.
+      # Return the number of header occurrences. Alias for {#length}.
       #
-      # @return [Boolean] true if no headers exist
-      # @example
-      #   headers.empty?  # => false
+      # @return [Integer]
+      def size
+      end
+
+      # Check whether the collection has no header occurrences.
+      #
+      # @return [Boolean]
       def empty?
       end
 
-      # Remove all headers.
+      # Remove every header occurrence.
       #
-      # @return [void]
-      # @example
-      #   headers.clear
-      #   headers.empty?  # => true
+      # @return [Wreq::Headers] self
       def clear
       end
 
-      # Get all header names.
+      # Return each unique header name.
       #
-      # @return [Array<String>] Array of header names (lowercase)
-      # @example
-      #   headers.keys
-      #   # => ["content-type", "accept", "user-agent", "authorization"]
+      # @return [Array<String>]
       def keys
       end
 
-      # Get all header values.
-      #
-      # Returns one value per header (the first if multiple values exist).
+      # Return every header value.
       #
-      # @return [Array<String>] Array of header values
-      # @example
-      #   headers.values
-      #   # => ["application/json", "text/html", "Mozilla/5.0", "Bearer token"]
+      # @return [Array<String>]
       def values
       end
 
-      # Iterate over headers.
-      #
-      # Yields each header name and value pair. If a header has multiple values,
-      # only the first is yielded.
+      # Iterate over every header occurrence.
       #
-      # @yieldparam name [String] Header name (lowercase)
+      # @yieldparam name [String] Normalized lowercase header name
       # @yieldparam value [String] Header value
-      # @return [Enumerator, self] Returns enumerator if no block given, self otherwise
-      # @example With block
-      #   headers.each do |name, value|
-      #     puts "#{name}: #{value}"
-      #   end
-      # @example Without block
-      #   enum = headers.each
-      #   enum.to_a  # => [["content-type", "text/html"], ...]
+      # @return [Enumerator, Wreq::Headers] An Enumerator without a block,
+      #   otherwise self
+      # @example
+      #   headers.each.to_a
       def each
       end
 
+      # Convert every occurrence to name-value pairs.
+      #
+      # @return [Array<Array(String, String)>]
+      # @example
+      #   headers.to_a  # => [["accept", "application/json"], ...]
+      def to_a
+      end
+
+      # Convert unique names to a Hash.
+      #
+      # Hash values use the same nil, String, or Array shape as {#[]}.
+      #
+      # @return [Hash{String => String, Array<String>}]
+      # @example
+      #   headers.to_h  # => {"accept" => "application/json"}
+      def to_h
+      end
+
+      # Convert unique names to a Hash. Alias for {#to_h}.
+      #
+      # @return [Hash{String => String, Array<String>}]
+      def to_hash
+      end
+
       # Convert headers to a string representation.
+      #
+      # @return [String] String representation of the headers
       def to_s
       end
+
+      # Return a compact representation for debugging.
+      #
+      # @return [String]
+      # @example
+      #   headers.inspect  # => "#<Wreq::Headers [2 headers]>"
+      def inspect
+      end
     end
   end
 end
 
+# ======================== Ruby API Extensions ========================
+
 module Wreq
   class Headers
+    FETCH_UNDEFINED = Object.new.freeze
+    private_constant :FETCH_UNDEFINED
+
+    alias delete remove
+    alias size length
+
+    # Return a header value, a fallback, or the result of a block.
+    #
+    # The block takes precedence when both a default and block are provided.
+    #
+    # @param name [String, Symbol] Header name
+    # @param default [Object] Optional fallback for a missing name
+    # @yieldparam name [String, Symbol] The missing name
+    # @return [String, Array<String>, Object]
+    # @raise [KeyError] if the name is missing and no fallback is provided
+    def fetch(name, default = FETCH_UNDEFINED)
+      value = self[name]
+      return value unless value.nil?
+      return yield(name) if block_given?
+      return default unless default.equal?(FETCH_UNDEFINED)
+
+      raise KeyError, "key not found: #{name.inspect}"
+    end
+
+    # Convert every header occurrence to a name-value pair.
+    #
+    # @return [Array<Array(String, String)>]
+    def to_a
+      each.to_a
+    end
+
+    # Convert unique normalized names to a Hash.
+    #
+    # A name with one occurrence maps to a String, while multiple occurrences
+    # map to an Array<String>.
+    #
+    # @return [Hash{String => String, Array<String>}]
+    def to_h
+      keys.to_h { |name| [name, self[name]] }
+    end
+
+    alias to_hash to_h
+
+    # Return a compact representation for debugging.
+    #
+    # @return [String]
     def inspect
       "#<Wreq::Headers [#{length} headers]>"
     end

data/lib/wreq_ruby/http.rb

@@ -25,6 +25,43 @@ module Wreq
       TRACE = nil # @return [Wreq::Method] HTTP TRACE method
       PATCH = nil # @return [Wreq::Method] HTTP PATCH method
     end
+
+    # Returns the HTTP method token (e.g. "GET", "POST").
+    # @return [String]
+    unless method_defined?(:to_s)
+      def to_s
+      end
+    end
+
+    # Returns the HTTP method as a lowercase symbol (e.g. :get, :post).
+    # @return [Symbol]
+    unless method_defined?(:to_sym)
+      def to_sym
+      end
+    end
+
+    # Value-based equality. Returns true when both represent the same HTTP method.
+    # @param other [Object]
+    # @return [Boolean]    
+    unless method_defined?(:==)
+      def ==(other)
+      end
+    end
+
+    # Strict equality for Hash key and Set member semantics.
+    # @param other [Object]
+    # @return [Boolean]
+    unless method_defined?(:eql?)
+      def eql?(other)
+      end
+    end
+
+    # Hash value consistent with {#eql?} for use as Hash keys.
+    # @return [Integer]
+    unless method_defined?(:hash)
+      def hash
+      end
+    end
   end
 
   # HTTP version enumeration backed by Rust.
@@ -63,6 +100,21 @@ module Wreq
       def ==(other)
       end
     end
+
+    # Strict equality for Hash key and Set member semantics.
+    # @param other [Object]
+    # @return [Boolean]
+    unless method_defined?(:eql?)
+      def eql?(other)
+      end
+    end
+
+    # Hash value consistent with {#eql?} for use as Hash keys.
+    # @return [Integer]
+    unless method_defined?(:hash)
+      def hash
+      end
+    end
   end
 
   # HTTP status code wrapper.
@@ -141,6 +193,28 @@ module Wreq
       # @return [String] Status code as string
       def to_s
       end
+
+      # Returns the status code as an integer.
+      # @return [Integer] the numeric HTTP status code
+      def to_i
+      end
+
+      # Value-based equality. Only compares with other StatusCode instances.
+      # @param other [Object]
+      # @return [Boolean]
+      def ==(other)
+      end
+
+      # Strict equality for Hash key and Set member semantics.
+      # @param other [Object]
+      # @return [Boolean]
+      def eql?(other)
+      end
+
+      # Hash value consistent with {#eql?} for use as Hash keys.
+      # @return [Integer]
+      def hash
+      end
     end
   end
 end