wreq 1.2.4 → 1.2.6

data/lib/wreq_ruby/cookie.rb

@@ -1,45 +1,77 @@
 unless defined?(Wreq)
   module Wreq
-    # Cookie SameSite attribute.
+    # SameSite values for HTTP cookies.
     #
-    # Values follow the Rust enum exposed by the native extension.
+    # The constant names match the native Rust variants.
+    # standard:disable Naming/ConstantName
     class SameSite
-      # Lax same-site policy.
-      Strict = nil
       # Strict same-site policy.
+      Strict = nil
+      # Lax same-site policy.
       Lax = nil
       # None same-site policy.
       None = nil
+
+      # Returns the SameSite attribute name (e.g. "Strict", "Lax", "None").
+      # @return [String]
+      def to_s
+      end
+
+      # Returns the SameSite attribute as a lowercase symbol (e.g. :strict, :lax, :none).
+      # @return [Symbol]
+      def to_sym
+      end
+
+      # Value-based equality.
+      # @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
+    # standard:enable Naming/ConstantName
 
-    # A single HTTP cookie.
+    # A single HTTP cookie backed by an immutable native value.
     #
-    # Thread-safe: instances are backed by an immutable Rust value and can be
-    # shared across threads safely. This mirrors the native `Wreq::Cookie`.
-    # Constructor accepts `name`, `value`, plus optional keyword arguments for
-    # other attributes.
+    # Cookie instances can be shared safely between threads. Pass optional
+    # attributes as keywords to {.new}.
     class Cookie
-      # Create a new Cookie instance.
+      # Creates a Cookie instance.
       #
-      # Note: This matches the native binding which defines `new` (not `initialize`).
+      # The native extension defines `.new` directly instead of `#initialize`.
       #
       # @param name [String] Cookie name
       # @param value [String] Cookie value
       # @param options [Hash] Optional keyword arguments
       # @option options [String] :domain Domain attribute
       # @option options [String] :path Path attribute
-      # @option options [Integer] :max_age Max-Age in seconds
-      # @option options [Float] :expires Unix timestamp (seconds, float)
+      # @option options [Integer] :max_age Signed Max-Age in seconds.
+      #   Zero or negative values expire the cookie immediately.
+      # @option options [Time, Numeric] :expires A Time or finite Unix timestamp in seconds
       # @option options [Boolean] :http_only HttpOnly flag
       # @option options [Boolean] :secure Secure flag
       # @option options [Wreq::SameSite] :same_site SameSite attribute
       # @return [Wreq::Cookie]
+      # @raise [ArgumentError] if an option is unknown or duplicated, or if :expires is not finite
+      # @raise [RangeError] if :max_age or :expires is outside the supported range
+      # @raise [TypeError] if an option has the wrong type
       # @example
       #   c = Wreq::Cookie.new(
       #     "sid", "abc",
       #     domain: "example.com",
       #     path: "/",
       #     max_age: 3600,
+      #     expires: Time.utc(2030, 1, 1),
       #     http_only: true,
       #     secure: true,
       #     same_site: Wreq::SameSite::Lax
@@ -85,6 +117,11 @@ unless defined?(Wreq)
       def same_site_strict?
       end
 
+      # Returns the SameSite setting, or nil if it was omitted.
+      # @return [Wreq::SameSite, nil]
+      def same_site
+      end
+
       # @return [String, nil] Path attribute
       def path
       end
@@ -93,31 +130,50 @@ unless defined?(Wreq)
       def domain
       end
 
-      # @return [Integer, nil] Max-Age in seconds
+      # Returns the signed Max-Age lifetime in seconds.
+      #
+      # Zero and negative values expire the cookie immediately.
+      # @return [Integer, nil]
       def max_age
       end
 
-      # @return [Float, nil] Expires as Unix timestamp (seconds)
+      # Returns the expiration time in UTC.
+      # @return [Time, nil]
+      def expires_at
+      end
+
+      # Returns the expiration as a Unix timestamp with fractional seconds.
+      # The Float return value may lose precision for large timestamps.
+      # @deprecated Use {#expires_at}, which returns Time.
+      # @return [Float, nil]
       def expires
       end
+
+      # Returns the cookie formatted as a Set-Cookie value.
+      # @return [String]
+      def to_s
+      end
     end
 
-    # A cookie store (jar) used by the client to manage cookies across requests.
+    # Stores cookies for reuse across requests.
+    #
+    # Pass a Jar to Wreq::Client as `cookie_provider` to share its cookies.
     class Jar
-      # Create a new, empty cookie jar.
+      # Creates an empty cookie jar.
       # @return [Wreq::Jar]
       def self.new
       end
 
-      # Get all cookies currently stored.
+      # Returns all stored cookies.
       # @return [Array<Wreq::Cookie>]
       def get_all
       end
 
-      # Add a cookie from a Set-Cookie string for the given URL.
-      # @param cookie [String, Wreq::Cookie] A Set-Cookie string
-      # @param url [String]
+      # Adds a Cookie object or Set-Cookie string for the given URL.
+      # @param cookie [String, Wreq::Cookie] Cookie to store
+      # @param url [String] URL that scopes the cookie
       # @return [void]
+      # @raise [TypeError] if cookie is neither a String nor Wreq::Cookie
       def add(cookie, url)
       end
 
@@ -138,6 +194,8 @@ end
 
 module Wreq
   class Cookie
+    # Returns a short representation for debugging.
+    # @return [String]
     def inspect
       parts = ["#<Wreq::Cookie", name]
       parts << "domain=#{domain}" if domain
@@ -149,6 +207,8 @@ module Wreq
   end
 
   class Jar
+    # Returns a short representation with the number of stored cookies.
+    # @return [String]
     def inspect
       "#<Wreq::Jar [#{get_all.length} cookies]>"
     end

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