algesten · algesten · Apr 21, 2025 · Apr 21, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,7 @@
 # Unreleased
 
+ * Improve doc for 10MB limit (#1061)
+
 # 3.0.11
 
   * Fix CONNECT proxy bug (#1057)

diff --git a/src/body/mod.rs b/src/body/mod.rs
@@ -31,6 +31,22 @@ const MAX_BODY_SIZE: u64 = 10 * 1024 * 1024;
 
 /// A response body returned as [`http::Response<Body>`].
 ///
+/// # Default size limit
+///
+/// Methods like `read_to_string()`, `read_to_vec()`, and `read_json()` have a **default 10MB limit**
+/// to prevent memory exhaustion. To download larger files, use `with_config().limit(new_size)`:
+///
+/// ```
+/// // Download a 20MB file
+/// let bytes = ureq::get("http://httpbin.org/bytes/200000000")
+///     .call()?
+///     .body_mut()
+///     .with_config()
+///     .limit(20 * 1024 * 1024) // 20MB
+///     .read_to_vec()?;
+/// # Ok::<_, ureq::Error>(())
+/// ```
+///
 /// # Body lengths
 ///
 /// HTTP/1.1 has two major modes of transfering body data. Either a `Content-Length`
@@ -251,6 +267,19 @@ impl Body {
     /// assert_eq!(s, "User-agent: *\nDisallow: /deny\n");
     /// # Ok::<_, ureq::Error>(())
     /// ```
+    ///
+    /// For larger text files, you must explicitly increase the limit:
+    ///
+    /// ```
+    /// // Read a large text file (25MB)
+    /// let text = ureq::get("http://httpbin.org/get")
+    ///     .call()?
+    ///     .body_mut()
+    ///     .with_config()
+    ///     .limit(25 * 1024 * 1024) // 25MB
+    ///     .read_to_string()?;
+    /// # Ok::<_, ureq::Error>(())
+    /// ```
     pub fn read_to_string(&mut self) -> Result<String, Error> {
         self.with_config()
             .limit(MAX_BODY_SIZE)
@@ -271,6 +300,19 @@ impl Body {
     /// assert_eq!(bytes.len(), 100);
     /// # Ok::<_, ureq::Error>(())
     /// ```
+    ///
+    /// For larger files, you must explicitly increase the limit:
+    ///
+    /// ```
+    /// // Download a larger file (50MB)
+    /// let bytes = ureq::get("http://httpbin.org/bytes/200000000")
+    ///     .call()?
+    ///     .body_mut()
+    ///     .with_config()
+    ///     .limit(50 * 1024 * 1024) // 50MB
+    ///     .read_to_vec()?;
+    /// # Ok::<_, ureq::Error>(())
+    /// ```
     pub fn read_to_vec(&mut self) -> Result<Vec<u8>, Error> {
         self.with_config()
             //
@@ -308,6 +350,21 @@ impl Body {
     /// assert_eq!(body.slideshow.author, "Yours Truly");
     /// # Ok::<_, ureq::Error>(())
     /// ```
+    ///
+    /// For larger JSON files, you must explicitly increase the limit:
+    ///
+    /// ```
+    /// use serde_json::Value;
+    ///
+    /// // Parse a large JSON file (30MB)
+    /// let json: Value = ureq::get("https://httpbin.org/json")
+    ///     .call()?
+    ///     .body_mut()
+    ///     .with_config()
+    ///     .limit(30 * 1024 * 1024) // 30MB
+    ///     .read_json()?;
+    /// # Ok::<_, ureq::Error>(())
+    /// ```
     #[cfg(feature = "json")]
     pub fn read_json<T: serde::de::DeserializeOwned>(&mut self) -> Result<T, Error> {
         let reader = self.with_config().limit(MAX_BODY_SIZE).reader();
@@ -369,6 +426,21 @@ impl Body {
 /// * [Body::with_config()]
 /// * [Body::into_with_config()]
 ///
+/// # Handling large responses
+///
+/// The `BodyWithConfig` is the primary way to increase the default 10MB size limit
+/// when downloading large files to memory:
+///
+/// ```
+/// // Download a 50MB file
+/// let large_data = ureq::get("http://httpbin.org/bytes/200000000")
+///     .call()?
+///     .body_mut()
+///     .with_config()
+///     .limit(50 * 1024 * 1024) // 50MB
+///     .read_to_vec()?;
+/// # Ok::<_, ureq::Error>(())
+/// ```
 pub struct BodyWithConfig<'a> {
     handler: BodySourceRef<'a>,
     info: Arc<ResponseInfo>,

diff --git a/src/unversioned/transport/test.rs b/src/unversioned/transport/test.rs
@@ -192,6 +192,21 @@ fn setup_default_handlers(handlers: &mut Vec<TestHandler>) {
         handlers,
     );
 
+    maybe_add(
+        TestHandler::new("/bytes/200000000", |_uri, _req, w| {
+            write!(
+                w,
+                "HTTP/1.1 200 OK\r\n\
+                Content-Type: application/octet-stream\r\n\
+                Content-Length: 100\r\n\
+                \r\n"
+            )?;
+            // We don't actually want 200MB of data in memory.
+            write!(w, "{}", "1".repeat(100))
+        }),
+        handlers,
+    );
+
     maybe_add(
         TestHandler::new("/get", |_uri, req, w| {
             write!(