wreq 1.2.5-x86_64-linux → 1.2.6-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ed209c7fcbba5d84bfad7fa3da9d5459a1468396bb50b21b31c99de2ecea870
-  data.tar.gz: de09533414435d3c50572e4876df5f8dfe18adb96f5504e42b0274b32b6e458b
+  metadata.gz: 92e7474db16ed2402299619c5810018fad110426be40b823dc661427febd1dec
+  data.tar.gz: 2bfa63ed7bba9967543083ebb792fa33b81398f37e9cf71fea5e718a50da56c7
 SHA512:
-  metadata.gz: 93048c3f7e37eb3952548dde41e173d69edb707cdd9ecb5e0b24d7df1cbede6684045a02c53d3b6474f42aa71eb3bba6587d2793094da21b7ef9fd0fd14fe6b4
-  data.tar.gz: 0ecedc0a7508990dc4fef408e9a191c4c657042328c6926aaa539a1ec303b03e5788a6158e4e15e06c7a45790ad943232c814ecefe3ce93e91de3f7c79cca8b2
+  metadata.gz: 8f46547e76ac3ab622c91cab11918bb720955841d9862b6a672f113cd47113f7b96f4a2b5e2ad0b66e039962c3e0ee0f5e4a7a789b1f24a0b6278c2c78840bd4
+  data.tar.gz: 856a9592e1fcb72a7c868e144040e10bd796cf7bd47b96e9755ed29fc2bcc683c36d4c0b1f2114692ef6cdf25c2b10560b41675faf1a6647e661b3e9220e3ab9

data/lib/wreq.rb

@@ -9,6 +9,7 @@ end
 
 # Load type hint definitions
 require_relative "wreq_ruby/http"
+require_relative "wreq_ruby/emulate"
 require_relative "wreq_ruby/client"
 require_relative "wreq_ruby/response"
 require_relative "wreq_ruby/body"
@@ -22,20 +23,26 @@ unless defined?(Wreq)
     # @return [String]
     VERSION = nil
 
+    # Module request methods accept only the options documented for each
+    # method. 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. Validation
+    # finishes before network I/O.
+
     # Send an HTTP request.
     #
     # @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
@@ -44,13 +51,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 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 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 self.request(method, url, **options)
     end
 
@@ -59,14 +68,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
@@ -75,13 +84,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 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 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 self.get(url, **options)
     end
 
@@ -90,14 +101,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
@@ -106,13 +117,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 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 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 self.head(url, **options)
     end
 
@@ -121,14 +134,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
@@ -137,13 +150,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 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 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 self.post(url, **options)
     end
 
@@ -152,14 +167,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
@@ -168,13 +183,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 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 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 self.put(url, **options)
     end
 
@@ -183,14 +200,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
@@ -199,13 +216,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 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 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 self.delete(url, **options)
     end
 
@@ -214,14 +233,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
@@ -230,13 +249,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 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 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 self.options(url, **options)
     end
 
@@ -245,14 +266,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
@@ -261,13 +282,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 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 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 self.trace(url, **options)
     end
 
@@ -276,14 +299,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
@@ -292,13 +315,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 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 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 self.patch(url, **options)
     end
   end

data/lib/wreq_ruby/body.rb

@@ -2,10 +2,10 @@
 
 unless defined?(Wreq)
   module Wreq
-    # BodySender: for streaming request bodies, allowing thread-safe chunked data push.
-    # Backed by a Rust channel, avoids buffering the entire payload in memory.
+    # Streams a request body through a bounded, thread-safe channel.
     #
-    # Supports multi-threaded chunk push: you can safely call `push` from multiple threads.
+    # The channel applies backpressure instead of buffering the entire request body.
+    # Multiple threads may safely push chunks while a request drains the receiving side.
     #
     # Usage:
     #   sender = Wreq::BodySender.new(8)
@@ -15,25 +15,43 @@ unless defined?(Wreq)
     #   end
     #   resp = client.post(url, body: sender)
     #
-    # Note:
-    #   - Sender is for request upload only, not for response reading.
-    #   - Each BodySender instance can only be used once (single-use):
-    #     after being consumed by a request, further push or reuse is not allowed.
+    # A sender can be attached to one request. Closing it prevents further writes but
+    # retains queued chunks so a request attached afterward can still drain them.
     class BodySender
-      # @param capacity [Integer] channel buffer size, default 8
+      # Create a bounded request-body sender.
+      #
+      # @param capacity [Integer] positive number of chunks that may wait in the channel;
+      #   defaults to 8 and must be greater than zero
       # @return [Wreq::BodySender] A streaming request body sender
+      # @raise [ArgumentError] if capacity is zero, negative, or too large
+      # @raise [TypeError] if capacity is not an Integer
       def self.new(capacity = 8)
       end
 
+      # Push one binary chunk, waiting while the channel is full.
+      #
       # @param data [String] binary chunk
-      # @return [void]
+      # @return [nil]
+      # @raise [IOError] if the sender or receiving side is closed
       def push(data)
       end
 
-      # Close the sender, signaling end of data.
-      # @return [void]
+      # Close the producer and signal EOF after all queued chunks are read.
+      #
+      # This operation is idempotent.
+      #
+      # @return [nil]
       def close
       end
+
+      # Return whether the sender can no longer accept chunks.
+      #
+      # This becomes true after {#close} or when the request stops consuming
+      # the receiving side.
+      #
+      # @return [Boolean]
+      def closed?
+      end
     end
   end
 end