wreq 1.2.4 → 1.2.6

data/crates/wreq-util/tests/support/mod.rs

@@ -0,0 +1,55 @@
+#![allow(dead_code)]
+pub mod server;
+
+use std::{sync::LazyLock, time::Duration};
+
+use tokio::sync::Semaphore;
+use wreq::Client;
+
+// TODO: remove once done converting to new support server?
+#[allow(unused)]
+pub static DEFAULT_USER_AGENT: &str =
+    concat!(env!("CARGO_PKG_NAME"), "/", env!("CARGO_PKG_VERSION"));
+
+pub static TEST_SEMAPHORE: LazyLock<Semaphore> = LazyLock::new(|| Semaphore::new(1));
+
+pub static CLIENT: LazyLock<Client> = LazyLock::new(|| {
+    Client::builder()
+        .connect_timeout(Duration::from_secs(60))
+        .build()
+        .unwrap()
+});
+
+#[allow(unused_macros)]
+macro_rules! test_emulation {
+    ($test_name:ident, $emulation:expr, $ja4:expr, $akamai_hash:expr) => {
+        #[tokio::test]
+        async fn $test_name() {
+            let _permit = crate::support::TEST_SEMAPHORE.acquire().await.unwrap();
+
+            let resp = crate::support::CLIENT
+                .get("https://tls.browserleaks.com/")
+                .emulation($emulation)
+                .send()
+                .await
+                .unwrap();
+
+            assert_eq!(resp.status(), wreq::StatusCode::OK);
+            let content = resp.text().await.unwrap();
+
+            let conditional = $ja4.iter().any(|&ja4| content.contains(ja4));
+            if !conditional {
+                println!("{}", content);
+            }
+            assert!(conditional);
+
+            let conditional = content.contains($akamai_hash);
+            if !conditional {
+                println!("{}", content);
+            }
+            assert!(conditional);
+
+            tokio::time::sleep(std::time::Duration::from_millis(1000)).await;
+        }
+    };
+}

data/crates/wreq-util/tests/support/server.rs

@@ -0,0 +1,232 @@
+#![cfg(not(target_arch = "wasm32"))]
+use std::{
+    convert::Infallible, future::Future, net, sync::mpsc as std_mpsc, thread, time::Duration,
+};
+
+use tokio::{io::AsyncReadExt, net::TcpStream, runtime, sync::oneshot};
+
+pub struct Server {
+    addr: net::SocketAddr,
+    panic_rx: std_mpsc::Receiver<()>,
+    events_rx: std_mpsc::Receiver<Event>,
+    shutdown_tx: Option<oneshot::Sender<()>>,
+}
+
+#[non_exhaustive]
+pub enum Event {
+    ConnectionClosed,
+}
+
+impl Server {
+    pub fn addr(&self) -> net::SocketAddr {
+        self.addr
+    }
+
+    #[allow(unused)]
+    pub fn events(&mut self) -> Vec<Event> {
+        let mut events = Vec::new();
+        while let Ok(event) = self.events_rx.try_recv() {
+            events.push(event);
+        }
+        events
+    }
+}
+
+impl Drop for Server {
+    fn drop(&mut self) {
+        if let Some(tx) = self.shutdown_tx.take() {
+            let _ = tx.send(());
+        }
+
+        if !::std::thread::panicking() {
+            self.panic_rx
+                .recv_timeout(Duration::from_secs(3))
+                .expect("test server should not panic");
+        }
+    }
+}
+
+pub fn http<F, Fut>(func: F) -> Server
+where
+    F: Fn(http::Request<hyper::body::Incoming>) -> Fut + Clone + Send + 'static,
+    Fut: Future<Output = http::Response<wreq::Body>> + Send + 'static,
+{
+    http_with_config(func, |_builder| {})
+}
+
+type Builder = hyper_util::server::conn::auto::Builder<hyper_util::rt::TokioExecutor>;
+
+pub fn http_with_config<F1, Fut, F2, Bu>(func: F1, apply_config: F2) -> Server
+where
+    F1: Fn(http::Request<hyper::body::Incoming>) -> Fut + Clone + Send + 'static,
+    Fut: Future<Output = http::Response<wreq::Body>> + Send + 'static,
+    F2: FnOnce(&mut Builder) -> Bu + Send + 'static,
+{
+    // Spawn new runtime in thread to prevent reactor execution context conflict
+    let test_name = thread::current().name().unwrap_or("<unknown>").to_string();
+    thread::spawn(move || {
+        let rt = runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("new rt");
+        let listener = rt.block_on(async move {
+            tokio::net::TcpListener::bind(&std::net::SocketAddr::from(([127, 0, 0, 1], 0)))
+                .await
+                .unwrap()
+        });
+        let addr = listener.local_addr().unwrap();
+
+        let (shutdown_tx, mut shutdown_rx) = oneshot::channel();
+        let (panic_tx, panic_rx) = std_mpsc::channel();
+        let (events_tx, events_rx) = std_mpsc::channel();
+        let tname = format!(
+            "test({})-support-server",
+            test_name,
+        );
+        thread::Builder::new()
+            .name(tname)
+            .spawn(move || {
+                rt.block_on(async move {
+                    let mut builder =
+                        hyper_util::server::conn::auto::Builder::new(hyper_util::rt::TokioExecutor::new());
+                    apply_config(&mut builder);
+
+                    loop {
+                        tokio::select! {
+                            _ = &mut shutdown_rx => {
+                                break;
+                            }
+                            accepted = listener.accept() => {
+                                let (io, _) = accepted.expect("accepted");
+                                let func = func.clone();
+                                let svc = hyper::service::service_fn(move |req| {
+                                    let fut = func(req);
+                                    async move { Ok::<_, Infallible>(fut.await) }
+                                });
+                                let builder = builder.clone();
+                                let events_tx = events_tx.clone();
+                                tokio::spawn(async move {
+                                    let _ = builder.serve_connection_with_upgrades(hyper_util::rt::TokioIo::new(io), svc).await;
+                                    let _ = events_tx.send(Event::ConnectionClosed);
+                                });
+                            }
+                        }
+                    }
+                    let _ = panic_tx.send(());
+                });
+            })
+            .expect("thread spawn");
+        Server {
+            addr,
+            panic_rx,
+            events_rx,
+            shutdown_tx: Some(shutdown_tx),
+        }
+    })
+    .join()
+    .unwrap()
+}
+
+#[allow(unused)]
+pub fn low_level_with_response<F>(do_response: F) -> Server
+where
+    for<'c> F: Fn(&'c [u8], &'c mut TcpStream) -> Box<dyn Future<Output = ()> + Send + 'c>
+        + Clone
+        + Send
+        + 'static,
+{
+    // Spawn new runtime in thread to prevent reactor execution context conflict
+    let test_name = thread::current().name().unwrap_or("<unknown>").to_string();
+    thread::spawn(move || {
+        let rt = runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("new rt");
+        let listener = rt.block_on(async move {
+            tokio::net::TcpListener::bind(&std::net::SocketAddr::from(([127, 0, 0, 1], 0)))
+                .await
+                .unwrap()
+        });
+        let addr = listener.local_addr().unwrap();
+
+        let (shutdown_tx, mut shutdown_rx) = oneshot::channel();
+        let (panic_tx, panic_rx) = std_mpsc::channel();
+        let (events_tx, events_rx) = std_mpsc::channel();
+        let tname = format!("test({})-support-server", test_name,);
+        thread::Builder::new()
+            .name(tname)
+            .spawn(move || {
+                rt.block_on(async move {
+                    loop {
+                        tokio::select! {
+                            _ = &mut shutdown_rx => {
+                                break;
+                            }
+                            accepted = listener.accept() => {
+                                let (io, _) = accepted.expect("accepted");
+                                let do_response = do_response.clone();
+                                let events_tx = events_tx.clone();
+                                tokio::spawn(async move {
+                                    low_level_server_client(io, do_response).await;
+                                    let _ = events_tx.send(Event::ConnectionClosed);
+                                });
+                            }
+                        }
+                    }
+                    let _ = panic_tx.send(());
+                });
+            })
+            .expect("thread spawn");
+        Server {
+            addr,
+            panic_rx,
+            events_rx,
+            shutdown_tx: Some(shutdown_tx),
+        }
+    })
+    .join()
+    .unwrap()
+}
+
+#[allow(unused)]
+async fn low_level_server_client<F>(mut client_socket: TcpStream, do_response: F)
+where
+    for<'c> F: Fn(&'c [u8], &'c mut TcpStream) -> Box<dyn Future<Output = ()> + Send + 'c>,
+{
+    loop {
+        let request = low_level_read_http_request(&mut client_socket)
+            .await
+            .expect("read_http_request failed");
+        if request.is_empty() {
+            // connection closed by client
+            break;
+        }
+
+        Box::into_pin(do_response(&request, &mut client_socket)).await;
+    }
+}
+
+#[allow(unused)]
+async fn low_level_read_http_request(
+    client_socket: &mut TcpStream,
+) -> core::result::Result<Vec<u8>, std::io::Error> {
+    let mut buf = Vec::new();
+
+    // Read until the delimiter "\r\n\r\n" is found
+    loop {
+        let mut temp_buffer = [0; 1024];
+        let n = client_socket.read(&mut temp_buffer).await?;
+
+        if n == 0 {
+            break;
+        }
+
+        buf.extend_from_slice(&temp_buffer[..n]);
+
+        if let Some(pos) = buf.windows(4).position(|window| window == b"\r\n\r\n") {
+            return Ok(buf.drain(..pos + 4).collect());
+        }
+    }
+
+    Ok(buf)
+}

data/examples/emulate_request.rb

@@ -11,7 +11,7 @@ require_relative "../lib/wreq"
 #   Set when creating the Wreq::Client instance.
 #   All requests from this client will use the specified emulation unless overridden.
 client = Wreq::Client.new(emulation: Wreq::Emulation.new(
-  profile: Wreq::Profile::Chrome149,
+  profile: Wreq::Profile::Chrome150,
   platform: Wreq::Platform::MacOS,
   http2: true,
   headers: true

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"
@@ -18,22 +19,30 @@ require_relative "wreq_ruby/cookie"
 
 unless defined?(Wreq)
   module Wreq
+    # Current wreq gem version.
+    # @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 [Hash{String=>String}, nil] Default headers to merge
+    # @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
@@ -42,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, IO, nil] Raw request body (string or stream)
+    # @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
 
@@ -57,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 [Hash{String=>String}, nil] Default headers to merge
+    # @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
@@ -73,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, IO, nil] Raw request body (string or stream)
+    # @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
 
@@ -88,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 [Hash{String=>String}, nil] Default headers to merge
+    # @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
@@ -104,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, IO, nil] Raw request body (string or stream)
+    # @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
 
@@ -119,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 [Hash{String=>String}, nil] Default headers to merge
+    # @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
@@ -135,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, IO, nil] Raw request body (string or stream)
+    # @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
 
@@ -150,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 [Hash{String=>String}, nil] Default headers to merge
+    # @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
@@ -166,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, IO, nil] Raw request body (string or stream)
+    # @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
 
@@ -181,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 [Hash{String=>String}, nil] Default headers to merge
+    # @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
@@ -197,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, IO, nil] Raw request body (string or stream)
+    # @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
 
@@ -212,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 [Hash{String=>String}, nil] Default headers to merge
+    # @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
@@ -228,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, IO, nil] Raw request body (string or stream)
+    # @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
 
@@ -243,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 [Hash{String=>String}, nil] Default headers to merge
+    # @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
@@ -259,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, IO, nil] Raw request body (string or stream)
+    # @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
 
@@ -274,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 [Hash{String=>String}, nil] Default headers to merge
+    # @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
@@ -290,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, IO, nil] Raw request body (string or stream)
+    # @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