wreq 1.2.5-aarch64-linux → 1.2.7-aarch64-linux

data/lib/wreq_ruby/client.rb

@@ -11,6 +11,12 @@ unless defined?(Wreq)
     # The client is thread-safe and maintains an internal connection pool for
     # efficient request reuse.
     #
+    # Client and request options are limited to the keys listed below. Unknown,
+    # ambiguous, ineffective, and unavailable platform options raise
+    # ArgumentError. Known values retain the error class from their Ruby or
+    # native conversion, such as TypeError or Wreq::BuilderError. Request
+    # validation finishes before network I/O.
+    #
     # @example Basic usage
     #   client = Wreq::Client.new
     #   # Use client for HTTP requests
@@ -50,8 +56,7 @@ unless defined?(Wreq)
       #   will be returned directly to the caller.
       #
       # @param max_redirects [Integer, nil] Maximum number of redirects to
-      #   follow before returning an error. Only applies when allow_redirects
-      #   is true. Default is typically 10 if not specified.
+      #   follow before returning an error. Requires `allow_redirects: true`.
       #
       # @param cookie_store [Boolean, nil] Enable an in-memory cookie jar
       #   that automatically handles Set-Cookie headers and sends appropriate
@@ -85,7 +90,7 @@ unless defined?(Wreq)
       #
       # @param tcp_user_timeout [Integer, nil] Maximum time in seconds that
       #   transmitted data may remain unacknowledged before the connection is
-      #   forcibly closed. Linux-specific option (Android, Fuchsia, Linux only).
+      #   forcibly closed. Available on Android, Fuchsia, and Linux only.
       #
       # @param tcp_nodelay [Boolean, nil] Enable TCP_NODELAY socket option,
       #   which disables Nagle's algorithm. When true, small packets are sent
@@ -133,7 +138,9 @@ unless defined?(Wreq)
       #   Supports HTTP, HTTPS, and SOCKS5 proxies. Format: "protocol://host:port"
       #   Example: "http://proxy.example.com:8080"
       # @param local_address [String, nil] Bind the client's local source IP address (IPv4/IPv6). Useful on multi-homed hosts to originate connections from a specific address or enforce source routing. Examples: "192.168.1.10", "10.0.0.5", "2001:db8::1". The address must exist on the host and be routable.
-      # @param interface [String, nil] Bind the socket to a specific network interface via `SO_BINDTODEVICE` (e.g., "eth0", "wlan0", "tun0"). Effective only on systems that support the option (Linux/Android/Fuchsia) and typically requires privileges (root or CAP_NET_ADMIN).
+      # @param interface [String, nil] Bind sockets to a network interface on
+      #   platforms supported by the native client. Unsupported platforms raise
+      #   ArgumentError.
       #
       # @param gzip [Boolean, nil] Accept and automatically decompress gzip
       #   content encoding. When true, adds "Accept-Encoding: gzip" header.
@@ -151,10 +158,13 @@ unless defined?(Wreq)
       #
       # @return [Wreq::Client] A configured HTTP client instance ready to make requests.
       #
-      # @raise [ArgumentError] if incompatible options are specified together
-      #   (e.g., http1_only and http2_only both true).
-      # @raise [RuntimeError] if the underlying client cannot be initialized
-      #   due to system resource constraints or invalid configuration.
+      # @raise [ArgumentError] if an option is unknown, conflicting,
+      #   ineffective, or unavailable on the current platform.
+      # @raise [TypeError] if the option argument is not a Hash.
+      # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
+      #   value cannot be converted or validated.
+      # @raise [Wreq::BuilderError, Wreq::TlsError] if the native client cannot
+      #   be initialized.
       #
       # @example Minimal client
       #   client = Wreq::Client.new
@@ -179,8 +189,7 @@ unless defined?(Wreq)
       #   client = Wreq::Client.new(
       #     allow_redirects: true,
       #     max_redirects: 5,
-      #     referer: true,
-      #     history: true
+      #     referer: true
       #   )
       #
       # @example Client with compression
@@ -236,18 +245,22 @@ unless defined?(Wreq)
 
       # Send an HTTP request.
       #
+      # Only the options listed here are accepted. Body options (`body`, `form`,
+      # `json`) and authentication options (`auth`, `bearer_auth`, `basic_auth`)
+      # are mutually exclusive. `max_redirects` requires `allow_redirects: true`.
+      #
       # @param method [Wreq::Method] HTTP method to use
       # @param url [String] Target URL
       # @param headers [Wreq::Headers, Hash{String=>String}, nil] Custom headers for this request
       # @param orig_headers [Array<String>, nil] Original header names used to preserve raw header order and HTTP/1 case-sensitive header handling
-      # @param default_headers [Boolean, nil] Whether to apply default emulation headers
+      # @param default_headers [Boolean, nil] Whether to apply native default headers
       # @param query [Hash, nil] URL query parameters
       # @param auth [String, nil] Authorization header value
       # @param bearer_auth [String, nil] Bearer token for Authorization header
       # @param basic_auth [Array<String>, nil] Username and password for basic auth
       # @param cookies [Hash{String=>String}, String, nil] Cookies to send
       # @param allow_redirects [Boolean, nil] Whether to follow redirects
-      # @param max_redirects [Integer, nil] Maximum number of redirects to follow
+      # @param max_redirects [Integer, nil] Maximum redirects; requires allow_redirects: true
       # @param gzip [Boolean, nil] Enable gzip compression
       # @param brotli [Boolean, nil] Enable Brotli compression
       # @param deflate [Boolean, nil] Enable deflate compression
@@ -256,13 +269,17 @@ unless defined?(Wreq)
       # @param read_timeout [Integer, nil] Per-chunk read timeout (seconds)
       # @param proxy [String, nil] Proxy server URI
       # @param local_address [String, nil] Bind the request's local source IP address (IPv4/IPv6). Useful on multi-homed hosts to originate connections from a specific address or enforce source routing. Examples: "192.168.1.10", "10.0.0.5", "2001:db8::1". The address must exist on the host and be routable or the connection may fail.
-      # @param interface [String, nil] Bind the socket to a specific network interface via `SO_BINDTODEVICE` (e.g., "eth0", "wlan0", "tun0"). Effective only on systems that support the option (Linux/Android/Fuchsia) and typically requires privileges (root or CAP_NET_ADMIN).
+      # @param interface [String, nil] Bind to an interface on supported platforms; unsupported platforms raise ArgumentError.
       # @param emulation [Wreq::Emulation, nil] Device/OS emulation for this request
       # @param version [Wreq::Version, nil] HTTP version to use
       # @param form [Hash{String=>String}, nil] Form data (application/x-www-form-urlencoded)
-      # @param json [Object, nil] JSON body (will be serialized)
-      # @param body [String, Wreq::BodySender, nil] Request body bytes or streaming body sender
+      # @param json [Object, nil] JSON body serialized by the native encoder; Integer values retain arbitrary precision
+      # @param body [String, Wreq::BodySender, nil] Raw or streaming request body
       # @return [Wreq::Response] HTTP response
+      # @raise [ArgumentError] if options are unknown, conflicting, ineffective,
+      #   or unavailable on the current platform
+      # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
+      #   value cannot be converted, validated, or built
       def request(method, url, **options)
       end
 
@@ -271,14 +288,14 @@ unless defined?(Wreq)
       # @param url [String] Target URL
       # @param headers [Wreq::Headers, Hash{String=>String}, nil] Custom headers for this request
       # @param orig_headers [Array<String>, nil] Original header names used to preserve raw header order and HTTP/1 case-sensitive header handling
-      # @param default_headers [Boolean, nil] Whether to apply default emulation headers
+      # @param default_headers [Boolean, nil] Whether to apply native default headers
       # @param query [Hash, nil] URL query parameters
       # @param auth [String, nil] Authorization header value
       # @param bearer_auth [String, nil] Bearer token for Authorization header
       # @param basic_auth [Array<String>, nil] Username and password for basic auth
       # @param cookies [Hash{String=>String}, String, nil] Cookies to send
       # @param allow_redirects [Boolean, nil] Whether to follow redirects
-      # @param max_redirects [Integer, nil] Maximum number of redirects to follow
+      # @param max_redirects [Integer, nil] Maximum redirects; requires allow_redirects: true
       # @param gzip [Boolean, nil] Enable gzip compression
       # @param brotli [Boolean, nil] Enable Brotli compression
       # @param deflate [Boolean, nil] Enable deflate compression
@@ -287,13 +304,15 @@ unless defined?(Wreq)
       # @param read_timeout [Integer, nil] Per-chunk read timeout (seconds)
       # @param proxy [String, nil] Proxy server URI
       # @param local_address [String, nil] Bind the request's local source IP address (IPv4/IPv6). Useful on multi-homed hosts to originate connections from a specific address or enforce source routing. Examples: "192.168.1.10", "10.0.0.5", "2001:db8::1". The address must exist on the host and be routable or the connection may fail.
-      # @param interface [String, nil] Bind the socket to a specific network interface via `SO_BINDTODEVICE` (e.g., "eth0", "wlan0", "tun0"). Effective only on systems that support the option (Linux/Android/Fuchsia) and typically requires privileges (root or CAP_NET_ADMIN).
+      # @param interface [String, nil] Bind to an interface on supported platforms; unsupported platforms raise ArgumentError.
       # @param emulation [Wreq::Emulation, nil] Device/OS emulation for this request
       # @param version [Wreq::Version, nil] HTTP version to use
       # @param form [Hash{String=>String}, nil] Form data (application/x-www-form-urlencoded)
-      # @param json [Object, nil] JSON body (will be serialized)
-      # @param body [String, Wreq::BodySender, nil] Request body bytes or streaming body sender
+      # @param json [Object, nil] JSON body serialized by the native encoder; Integer values retain arbitrary precision
+      # @param body [String, Wreq::BodySender, nil] Raw or streaming request body
       # @return [Wreq::Response] HTTP response
+      # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
+      #   value cannot be converted, validated, or built
       def get(url, **options)
       end
 
@@ -302,14 +321,14 @@ unless defined?(Wreq)
       # @param url [String] Target URL
       # @param headers [Wreq::Headers, Hash{String=>String}, nil] Custom headers for this request
       # @param orig_headers [Array<String>, nil] Original header names used to preserve raw header order and HTTP/1 case-sensitive header handling
-      # @param default_headers [Boolean, nil] Whether to apply default emulation headers
+      # @param default_headers [Boolean, nil] Whether to apply native default headers
       # @param query [Hash, nil] URL query parameters
       # @param auth [String, nil] Authorization header value
       # @param bearer_auth [String, nil] Bearer token for Authorization header
       # @param basic_auth [Array<String>, nil] Username and password for basic auth
       # @param cookies [Hash{String=>String}, String, nil] Cookies to send
       # @param allow_redirects [Boolean, nil] Whether to follow redirects
-      # @param max_redirects [Integer, nil] Maximum number of redirects to follow
+      # @param max_redirects [Integer, nil] Maximum redirects; requires allow_redirects: true
       # @param gzip [Boolean, nil] Enable gzip compression
       # @param brotli [Boolean, nil] Enable Brotli compression
       # @param deflate [Boolean, nil] Enable deflate compression
@@ -318,13 +337,15 @@ unless defined?(Wreq)
       # @param read_timeout [Integer, nil] Per-chunk read timeout (seconds)
       # @param proxy [String, nil] Proxy server URI
       # @param local_address [String, nil] Bind the request's local source IP address (IPv4/IPv6). Useful on multi-homed hosts to originate connections from a specific address or enforce source routing. Examples: "192.168.1.10", "10.0.0.5", "2001:db8::1". The address must exist on the host and be routable or the connection may fail.
-      # @param interface [String, nil] Bind the socket to a specific network interface via `SO_BINDTODEVICE` (e.g., "eth0", "wlan0", "tun0"). Effective only on systems that support the option (Linux/Android/Fuchsia) and typically requires privileges (root or CAP_NET_ADMIN).
+      # @param interface [String, nil] Bind to an interface on supported platforms; unsupported platforms raise ArgumentError.
       # @param emulation [Wreq::Emulation, nil] Device/OS emulation for this request
       # @param version [Wreq::Version, nil] HTTP version to use
       # @param form [Hash{String=>String}, nil] Form data (application/x-www-form-urlencoded)
-      # @param json [Object, nil] JSON body (will be serialized)
-      # @param body [String, Wreq::BodySender, nil] Request body bytes or streaming body sender
+      # @param json [Object, nil] JSON body serialized by the native encoder; Integer values retain arbitrary precision
+      # @param body [String, Wreq::BodySender, nil] Raw or streaming request body
       # @return [Wreq::Response] HTTP response
+      # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
+      #   value cannot be converted, validated, or built
       def head(url, **options)
       end
 
@@ -333,14 +354,14 @@ unless defined?(Wreq)
       # @param url [String] Target URL
       # @param headers [Wreq::Headers, Hash{String=>String}, nil] Custom headers for this request
       # @param orig_headers [Array<String>, nil] Original header names used to preserve raw header order and HTTP/1 case-sensitive header handling
-      # @param default_headers [Boolean, nil] Whether to apply default emulation headers
+      # @param default_headers [Boolean, nil] Whether to apply native default headers
       # @param query [Hash, nil] URL query parameters
       # @param auth [String, nil] Authorization header value
       # @param bearer_auth [String, nil] Bearer token for Authorization header
       # @param basic_auth [Array<String>, nil] Username and password for basic auth
       # @param cookies [Hash{String=>String}, String, nil] Cookies to send
       # @param allow_redirects [Boolean, nil] Whether to follow redirects
-      # @param max_redirects [Integer, nil] Maximum number of redirects to follow
+      # @param max_redirects [Integer, nil] Maximum redirects; requires allow_redirects: true
       # @param gzip [Boolean, nil] Enable gzip compression
       # @param brotli [Boolean, nil] Enable Brotli compression
       # @param deflate [Boolean, nil] Enable deflate compression
@@ -349,13 +370,15 @@ unless defined?(Wreq)
       # @param read_timeout [Integer, nil] Per-chunk read timeout (seconds)
       # @param proxy [String, nil] Proxy server URI
       # @param local_address [String, nil] Bind the request's local source IP address (IPv4/IPv6). Useful on multi-homed hosts to originate connections from a specific address or enforce source routing. Examples: "192.168.1.10", "10.0.0.5", "2001:db8::1". The address must exist on the host and be routable or the connection may fail.
-      # @param interface [String, nil] Bind the socket to a specific network interface via `SO_BINDTODEVICE` (e.g., "eth0", "wlan0", "tun0"). Effective only on systems that support the option (Linux/Android/Fuchsia) and typically requires privileges (root or CAP_NET_ADMIN).
+      # @param interface [String, nil] Bind to an interface on supported platforms; unsupported platforms raise ArgumentError.
       # @param emulation [Wreq::Emulation, nil] Device/OS emulation for this request
       # @param version [Wreq::Version, nil] HTTP version to use
       # @param form [Hash{String=>String}, nil] Form data (application/x-www-form-urlencoded)
-      # @param json [Object, nil] JSON body (will be serialized)
-      # @param body [String, Wreq::BodySender, nil] Request body bytes or streaming body sender
+      # @param json [Object, nil] JSON body serialized by the native encoder; Integer values retain arbitrary precision
+      # @param body [String, Wreq::BodySender, nil] Raw or streaming request body
       # @return [Wreq::Response] HTTP response
+      # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
+      #   value cannot be converted, validated, or built
       def post(url, **options)
       end
 
@@ -364,14 +387,14 @@ unless defined?(Wreq)
       # @param url [String] Target URL
       # @param headers [Wreq::Headers, Hash{String=>String}, nil] Custom headers for this request
       # @param orig_headers [Array<String>, nil] Original header names used to preserve raw header order and HTTP/1 case-sensitive header handling
-      # @param default_headers [Boolean, nil] Whether to apply default emulation headers
+      # @param default_headers [Boolean, nil] Whether to apply native default headers
       # @param query [Hash, nil] URL query parameters
       # @param auth [String, nil] Authorization header value
       # @param bearer_auth [String, nil] Bearer token for Authorization header
       # @param basic_auth [Array<String>, nil] Username and password for basic auth
       # @param cookies [Hash{String=>String}, String, nil] Cookies to send
       # @param allow_redirects [Boolean, nil] Whether to follow redirects
-      # @param max_redirects [Integer, nil] Maximum number of redirects to follow
+      # @param max_redirects [Integer, nil] Maximum redirects; requires allow_redirects: true
       # @param gzip [Boolean, nil] Enable gzip compression
       # @param brotli [Boolean, nil] Enable Brotli compression
       # @param deflate [Boolean, nil] Enable deflate compression
@@ -380,13 +403,15 @@ unless defined?(Wreq)
       # @param read_timeout [Integer, nil] Per-chunk read timeout (seconds)
       # @param proxy [String, nil] Proxy server URI
       # @param local_address [String, nil] Bind the request's local source IP address (IPv4/IPv6). Useful on multi-homed hosts to originate connections from a specific address or enforce source routing. Examples: "192.168.1.10", "10.0.0.5", "2001:db8::1". The address must exist on the host and be routable or the connection may fail.
-      # @param interface [String, nil] Bind the socket to a specific network interface via `SO_BINDTODEVICE` (e.g., "eth0", "wlan0", "tun0"). Effective only on systems that support the option (Linux/Android/Fuchsia) and typically requires privileges (root or CAP_NET_ADMIN).
+      # @param interface [String, nil] Bind to an interface on supported platforms; unsupported platforms raise ArgumentError.
       # @param emulation [Wreq::Emulation, nil] Device/OS emulation for this request
       # @param version [Wreq::Version, nil] HTTP version to use
       # @param form [Hash{String=>String}, nil] Form data (application/x-www-form-urlencoded)
-      # @param json [Object, nil] JSON body (will be serialized)
-      # @param body [String, Wreq::BodySender, nil] Request body bytes or streaming body sender
+      # @param json [Object, nil] JSON body serialized by the native encoder; Integer values retain arbitrary precision
+      # @param body [String, Wreq::BodySender, nil] Raw or streaming request body
       # @return [Wreq::Response] HTTP response
+      # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
+      #   value cannot be converted, validated, or built
       def put(url, **options)
       end
 
@@ -395,14 +420,14 @@ unless defined?(Wreq)
       # @param url [String] Target URL
       # @param headers [Wreq::Headers, Hash{String=>String}, nil] Custom headers for this request
       # @param orig_headers [Array<String>, nil] Original header names used to preserve raw header order and HTTP/1 case-sensitive header handling
-      # @param default_headers [Boolean, nil] Whether to apply default emulation headers
+      # @param default_headers [Boolean, nil] Whether to apply native default headers
       # @param query [Hash, nil] URL query parameters
       # @param auth [String, nil] Authorization header value
       # @param bearer_auth [String, nil] Bearer token for Authorization header
       # @param basic_auth [Array<String>, nil] Username and password for basic auth
       # @param cookies [Hash{String=>String}, String, nil] Cookies to send
       # @param allow_redirects [Boolean, nil] Whether to follow redirects
-      # @param max_redirects [Integer, nil] Maximum number of redirects to follow
+      # @param max_redirects [Integer, nil] Maximum redirects; requires allow_redirects: true
       # @param gzip [Boolean, nil] Enable gzip compression
       # @param brotli [Boolean, nil] Enable Brotli compression
       # @param deflate [Boolean, nil] Enable deflate compression
@@ -411,13 +436,15 @@ unless defined?(Wreq)
       # @param read_timeout [Integer, nil] Per-chunk read timeout (seconds)
       # @param proxy [String, nil] Proxy server URI
       # @param local_address [String, nil] Bind the request's local source IP address (IPv4/IPv6). Useful on multi-homed hosts to originate connections from a specific address or enforce source routing. Examples: "192.168.1.10", "10.0.0.5", "2001:db8::1". The address must exist on the host and be routable or the connection may fail.
-      # @param interface [String, nil] Bind the socket to a specific network interface via `SO_BINDTODEVICE` (e.g., "eth0", "wlan0", "tun0"). Effective only on systems that support the option (Linux/Android/Fuchsia) and typically requires privileges (root or CAP_NET_ADMIN).
+      # @param interface [String, nil] Bind to an interface on supported platforms; unsupported platforms raise ArgumentError.
       # @param emulation [Wreq::Emulation, nil] Device/OS emulation for this request
       # @param version [Wreq::Version, nil] HTTP version to use
       # @param form [Hash{String=>String}, nil] Form data (application/x-www-form-urlencoded)
-      # @param json [Object, nil] JSON body (will be serialized)
-      # @param body [String, Wreq::BodySender, nil] Request body bytes or streaming body sender
+      # @param json [Object, nil] JSON body serialized by the native encoder; Integer values retain arbitrary precision
+      # @param body [String, Wreq::BodySender, nil] Raw or streaming request body
       # @return [Wreq::Response] HTTP response
+      # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
+      #   value cannot be converted, validated, or built
       def delete(url, **options)
       end
 
@@ -426,14 +453,14 @@ unless defined?(Wreq)
       # @param url [String] Target URL
       # @param headers [Wreq::Headers, Hash{String=>String}, nil] Custom headers for this request
       # @param orig_headers [Array<String>, nil] Original header names used to preserve raw header order and HTTP/1 case-sensitive header handling
-      # @param default_headers [Boolean, nil] Whether to apply default emulation headers
+      # @param default_headers [Boolean, nil] Whether to apply native default headers
       # @param query [Hash, nil] URL query parameters
       # @param auth [String, nil] Authorization header value
       # @param bearer_auth [String, nil] Bearer token for Authorization header
       # @param basic_auth [Array<String>, nil] Username and password for basic auth
       # @param cookies [Hash{String=>String}, String, nil] Cookies to send
       # @param allow_redirects [Boolean, nil] Whether to follow redirects
-      # @param max_redirects [Integer, nil] Maximum number of redirects to follow
+      # @param max_redirects [Integer, nil] Maximum redirects; requires allow_redirects: true
       # @param gzip [Boolean, nil] Enable gzip compression
       # @param brotli [Boolean, nil] Enable Brotli compression
       # @param deflate [Boolean, nil] Enable deflate compression
@@ -442,13 +469,15 @@ unless defined?(Wreq)
       # @param read_timeout [Integer, nil] Per-chunk read timeout (seconds)
       # @param proxy [String, nil] Proxy server URI
       # @param local_address [String, nil] Bind the request's local source IP address (IPv4/IPv6). Useful on multi-homed hosts to originate connections from a specific address or enforce source routing. Examples: "192.168.1.10", "10.0.0.5", "2001:db8::1". The address must exist on the host and be routable or the connection may fail.
-      # @param interface [String, nil] Bind the socket to a specific network interface via `SO_BINDTODEVICE` (e.g., "eth0", "wlan0", "tun0"). Effective only on systems that support the option (Linux/Android/Fuchsia) and typically requires privileges (root or CAP_NET_ADMIN).
+      # @param interface [String, nil] Bind to an interface on supported platforms; unsupported platforms raise ArgumentError.
       # @param emulation [Wreq::Emulation, nil] Device/OS emulation for this request
       # @param version [Wreq::Version, nil] HTTP version to use
       # @param form [Hash{String=>String}, nil] Form data (application/x-www-form-urlencoded)
-      # @param json [Object, nil] JSON body (will be serialized)
-      # @param body [String, Wreq::BodySender, nil] Request body bytes or streaming body sender
+      # @param json [Object, nil] JSON body serialized by the native encoder; Integer values retain arbitrary precision
+      # @param body [String, Wreq::BodySender, nil] Raw or streaming request body
       # @return [Wreq::Response] HTTP response
+      # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
+      #   value cannot be converted, validated, or built
       def options(url, **options)
       end
 
@@ -457,14 +486,14 @@ unless defined?(Wreq)
       # @param url [String] Target URL
       # @param headers [Wreq::Headers, Hash{String=>String}, nil] Custom headers for this request
       # @param orig_headers [Array<String>, nil] Original header names used to preserve raw header order and HTTP/1 case-sensitive header handling
-      # @param default_headers [Boolean, nil] Whether to apply default emulation headers
+      # @param default_headers [Boolean, nil] Whether to apply native default headers
       # @param query [Hash, nil] URL query parameters
       # @param auth [String, nil] Authorization header value
       # @param bearer_auth [String, nil] Bearer token for Authorization header
       # @param basic_auth [Array<String>, nil] Username and password for basic auth
       # @param cookies [Hash{String=>String}, String, nil] Cookies to send
       # @param allow_redirects [Boolean, nil] Whether to follow redirects
-      # @param max_redirects [Integer, nil] Maximum number of redirects to follow
+      # @param max_redirects [Integer, nil] Maximum redirects; requires allow_redirects: true
       # @param gzip [Boolean, nil] Enable gzip compression
       # @param brotli [Boolean, nil] Enable Brotli compression
       # @param deflate [Boolean, nil] Enable deflate compression
@@ -473,13 +502,15 @@ unless defined?(Wreq)
       # @param read_timeout [Integer, nil] Per-chunk read timeout (seconds)
       # @param proxy [String, nil] Proxy server URI
       # @param local_address [String, nil] Bind the request's local source IP address (IPv4/IPv6). Useful on multi-homed hosts to originate connections from a specific address or enforce source routing. Examples: "192.168.1.10", "10.0.0.5", "2001:db8::1". The address must exist on the host and be routable or the connection may fail.
-      # @param interface [String, nil] Bind the socket to a specific network interface via `SO_BINDTODEVICE` (e.g., "eth0", "wlan0", "tun0"). Effective only on systems that support the option (Linux/Android/Fuchsia) and typically requires privileges (root or CAP_NET_ADMIN).
+      # @param interface [String, nil] Bind to an interface on supported platforms; unsupported platforms raise ArgumentError.
       # @param emulation [Wreq::Emulation, nil] Device/OS emulation for this request
       # @param version [Wreq::Version, nil] HTTP version to use
       # @param form [Hash{String=>String}, nil] Form data (application/x-www-form-urlencoded)
-      # @param json [Object, nil] JSON body (will be serialized)
-      # @param body [String, Wreq::BodySender, nil] Request body bytes or streaming body sender
+      # @param json [Object, nil] JSON body serialized by the native encoder; Integer values retain arbitrary precision
+      # @param body [String, Wreq::BodySender, nil] Raw or streaming request body
       # @return [Wreq::Response] HTTP response
+      # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
+      #   value cannot be converted, validated, or built
       def trace(url, **options)
       end
 
@@ -488,14 +519,14 @@ unless defined?(Wreq)
       # @param url [String] Target URL
       # @param headers [Wreq::Headers, Hash{String=>String}, nil] Custom headers for this request
       # @param orig_headers [Array<String>, nil] Original header names used to preserve raw header order and HTTP/1 case-sensitive header handling
-      # @param default_headers [Boolean, nil] Whether to apply default emulation headers
+      # @param default_headers [Boolean, nil] Whether to apply native default headers
       # @param query [Hash, nil] URL query parameters
       # @param auth [String, nil] Authorization header value
       # @param bearer_auth [String, nil] Bearer token for Authorization header
       # @param basic_auth [Array<String>, nil] Username and password for basic auth
       # @param cookies [Hash{String=>String}, String, nil] Cookies to send
       # @param allow_redirects [Boolean, nil] Whether to follow redirects
-      # @param max_redirects [Integer, nil] Maximum number of redirects to follow
+      # @param max_redirects [Integer, nil] Maximum redirects; requires allow_redirects: true
       # @param gzip [Boolean, nil] Enable gzip compression
       # @param brotli [Boolean, nil] Enable Brotli compression
       # @param deflate [Boolean, nil] Enable deflate compression
@@ -504,13 +535,15 @@ unless defined?(Wreq)
       # @param read_timeout [Integer, nil] Per-chunk read timeout (seconds)
       # @param proxy [String, nil] Proxy server URI
       # @param local_address [String, nil] Bind the request's local source IP address (IPv4/IPv6). Useful on multi-homed hosts to originate connections from a specific address or enforce source routing. Examples: "192.168.1.10", "10.0.0.5", "2001:db8::1". The address must exist on the host and be routable or the connection may fail.
-      # @param interface [String, nil] Bind the socket to a specific network interface via `SO_BINDTODEVICE` (e.g., "eth0", "wlan0", "tun0"). Effective only on systems that support the option (Linux/Android/Fuchsia) and typically requires privileges (root or CAP_NET_ADMIN).
+      # @param interface [String, nil] Bind to an interface on supported platforms; unsupported platforms raise ArgumentError.
       # @param emulation [Wreq::Emulation, nil] Device/OS emulation for this request
       # @param version [Wreq::Version, nil] HTTP version to use
       # @param form [Hash{String=>String}, nil] Form data (application/x-www-form-urlencoded)
-      # @param json [Object, nil] JSON body (will be serialized)
-      # @param body [String, Wreq::BodySender, nil] Request body bytes or streaming body sender
+      # @param json [Object, nil] JSON body serialized by the native encoder; Integer values retain arbitrary precision
+      # @param body [String, Wreq::BodySender, nil] Raw or streaming request body
       # @return [Wreq::Response] HTTP response
+      # @raise [TypeError, ArgumentError, Wreq::BuilderError] if a known option
+      #   value cannot be converted, validated, or built
       def patch(url, **options)
       end
     end

data/lib/wreq_ruby/cookie.rb

@@ -1,8 +1,9 @@
 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
       # Strict same-site policy.
       Strict = nil
@@ -10,36 +11,67 @@ unless defined?(Wreq)
       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