From 383832dc427e0de882f3ea91e00f637dd2834c98 Mon Sep 17 00:00:00 2001
From: Benoit Chesneau <bchesneau@gmail.com>
Date: Tue, 20 Jan 2026 19:11:08 +0100
Subject: [PATCH] docs: add documentation for auto_decompress and stream_to
 features

- Update NEWS.md with new options for #155 (auto_decompress) and #646 (stream_to)
- Add Automatic Decompression section to HTTP guide
- Add Stream to Another Process section to HTTP guide
---
 NEWS.md              |  6 ++++++
 guides/http_guide.md | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/NEWS.md b/NEWS.md
index ca555986..8474c3aa 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -67,6 +67,12 @@ The connection pool has been completely redesigned:
 - `max_per_host` - Maximum concurrent connections per host (default 50)
 - `checkout_timeout` - Timeout to acquire connection slot (default 8000ms)
 - `prewarm_count` - Warm connections per host (default 4)
+- `auto_decompress` - When `true`, automatically decompresses gzip/deflate responses (#155):
+  ```erlang
+  {ok, Status, Headers, Body} = hackney:request(get, URL, [], [],
+      [{with_body, true}, {auto_decompress, true}]).
+  ```
+- `stream_to` - For async requests, the `stream_to` process is now set as the connection owner (#646). If `stream_to` dies, the connection terminates; if the original caller dies, the connection continues as long as `stream_to` is alive.
 
 ### New Functions
 
diff --git a/guides/http_guide.md b/guides/http_guide.md
index 020b60cf..890fc302 100644
--- a/guides/http_guide.md
+++ b/guides/http_guide.md
@@ -119,6 +119,23 @@ ok = hackney:finish_send_body(Ref),
 {ok, Body} = hackney:body(Ref).
 ```
 
+### Automatic Decompression
+
+Hackney can automatically decompress gzip and deflate encoded responses:
+
+```erlang
+{ok, 200, Headers, Body} = hackney:get(URL, [], <<>>, [
+    with_body,
+    {auto_decompress, true}
+]).
+```
+
+When `auto_decompress` is enabled:
+- Adds `Accept-Encoding: gzip, deflate` header to requests
+- Automatically decompresses the response body based on `Content-Encoding`
+- Supports gzip, deflate, and x-gzip encodings
+- Non-compressed responses are returned unchanged
+
 ### Stream Response Body
 
 ```erlang
@@ -195,6 +212,24 @@ receive {hackney_response, Ref, Msg} -> ok end,
 hackney:stream_next(Ref).  %% Request next message
 ```
 
+### Stream to Another Process
+
+Use `stream_to` to send async messages to a different process:
+
+```erlang
+Receiver = spawn(fun() -> receive_loop() end),
+{ok, Ref} = hackney:get(URL, [], <<>>, [
+    async,
+    {stream_to, Receiver}
+]).
+```
+
+When `stream_to` is specified:
+- The connection is owned by the `stream_to` process, not the caller
+- If `stream_to` dies, the connection terminates
+- If the original caller dies, the connection continues as long as `stream_to` is alive
+- This ensures proper cleanup when the message recipient terminates
+
 ## Connection Pooling
 
 ### Default Pool