Confused by --compressed documentation

[dbanty]

At https://curl.se/docs/manpage.html#--compressed the document states that "Headers are not modified" which led me to believe that if I did not pass an Accept-Encoding that no compression would actually happen. However, it seems that if no Accept-Encoding is passed, then a default of "deflate, gzip, br, zstd" will be set.

On a second read, with this knowledge in mind, it seems more clear that the header will be added if missing, but not modified if present. Maybe there is a rewording of this paragraph that better indicates the behavior? My suggestion:

(HTTP) Request a compressed response using one of the algorithms curl supports, and automatically decompress the content. Existing headers are not modified, but required headers (like Accept-Encoding) will be added if missing.

Someone who is more familiar with the feature could probably explain it better 😅

[bagder]

Headers are not modified

This (comes from #5217) means that curl does not remove any headers from the response when it decompresses the content and passes on/saves the headers. It could possibly be clarified further, perhaps to say "response headers".

[bagder]

Maybe this makes it clearer?

diff --git a/docs/cmdline-opts/compressed.d b/docs/cmdline-opts/compressed.d
index 97ab1b10b..4921bdb47 100644
--- a/docs/cmdline-opts/compressed.d
+++ b/docs/cmdline-opts/compressed.d
@@ -8,10 +8,14 @@ Example: --compressed $URL
 See-also: compressed-ssh
 Added: 7.10
 Multi: boolean
 ---
 Request a compressed response using one of the algorithms curl supports, and
-automatically decompress the content. Headers are not modified.
+automatically decompress the content.
+
+Response headers are not modified when saved, so if they are "interpreted"
+separately again at a later point they might appear to be saying that the
+content is (still) compressed; while in fact it has already been decompressed.
 
 If this option is used and the server sends an unsupported encoding, curl will
 report an error. This is a request, not an order; the server may or may not
 deliver data compressed.

[dbanty]

Oh that's much clearer, thanks!

[bagder]

I'll turn into a PR then!

[shvchk]

Just to confirm what's exactly going on for future lurkers:

> nc -l 9999 & curl localhost:9999 -m 1
GET / HTTP/1.1
Host: localhost:9999
User-Agent: curl/7.88.1
Accept: */*

> nc -l 9999 & curl localhost:9999 -m 1 --compressed
GET / HTTP/1.1
Host: localhost:9999
User-Agent: curl/7.88.1
Accept: */*
Accept-Encoding: deflate, gzip, br, zstd