This is an automated email from the ASF dual-hosted git repository.
bcall pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 4dd4c8c493 Docs: Fix misleading compress plugin cache option
description (#12946)
4dd4c8c493 is described below
commit 4dd4c8c49368ca960e74aa251b87c77a4cce1881
Author: Bryan Call <[email protected]>
AuthorDate: Mon Mar 9 16:34:22 2026 -0700
Docs: Fix misleading compress plugin cache option description (#12946)
* Correct `compress` plugin `cache` option docs to match implementation:
`cache true` stores transformed compressed responses, while `cache false`
stores only untransformed responses.
* Clarify that `Vary: Accept-Encoding` controls alternate cache keys by
request header value, but stored body representation still depends on the
`cache` option.
* Update `sample.compress.config` comments so operator guidance matches
runtime cache behavior.
Fixes: #8989
---
doc/admin-guide/plugins/compress.en.rst | 27 +++++++++++++++++++++------
plugins/compress/sample.compress.config | 3 ++-
2 files changed, 23 insertions(+), 7 deletions(-)
diff --git a/doc/admin-guide/plugins/compress.en.rst
b/doc/admin-guide/plugins/compress.en.rst
index 77d2bb8286..f8058a2d31 100644
--- a/doc/admin-guide/plugins/compress.en.rst
+++ b/doc/admin-guide/plugins/compress.en.rst
@@ -64,8 +64,9 @@ It can be enabled globally for |TS| by adding the following
to your
With no further options, this will enable the following default behavior:
-* Enable caching of both compressed and uncompressed versions of origin
- responses as :term:`alternates <alternate>`.
+* Enable caching of compressed responses. Uncompressed and compressed versions
+ are maintained as separate :term:`alternates <alternate>` via
+ ``Vary: Accept-Encoding``.
* Compress objects with `text/*` content types for every origin.
@@ -98,10 +99,24 @@ Per site configuration for remap plugin should be ignored.
cache
-----
-When set to ``true``, causes |TS| to cache both the compressed and uncompressed
-versions of the content as :term:`alternates <alternate>`. When set to
-``false``, |TS| will cache only the compressed or decompressed variant returned
-by the origin. Enabled by default.
+Controls which version of the response is stored in cache when the compress
+transform runs (i.e., when the client sends ``Accept-Encoding``).
+
+When set to ``true``, the compressed (transformed) response is cached. When set
+to ``false``, the uncompressed (untransformed) response is cached and
+compression is performed on-the-fly for subsequent cache hits.
+
+.. note::
+
+ The plugin always adds ``Vary: Accept-Encoding`` to compressible responses.
+ This causes |TS| to use separate cache :term:`alternates <alternate>` (keys)
+ for requests with different ``Accept-Encoding`` values. Which body
+ representation is actually stored in cache still depends on the ``cache``
+ option: with ``cache true`` the compressed response is cached, while with
+ ``cache false`` only the uncompressed response is cached and compression is
+ performed on-the-fly for clients that send ``Accept-Encoding``.
+
+Enabled by default.
range-request
-------------
diff --git a/plugins/compress/sample.compress.config
b/plugins/compress/sample.compress.config
index 451f895834..8cfaf2d9c8 100644
--- a/plugins/compress/sample.compress.config
+++ b/plugins/compress/sample.compress.config
@@ -25,7 +25,8 @@
# - for when the proxy parses responses, and the resulting
compression/decompression
# is wasteful
#
-# cache: when set, the plugin stores the uncompressed and compressed response
as alternates
+# cache: when true, caches the compressed response; when false, caches only
the uncompressed
+# response and compresses on-the-fly from cache. Vary: Accept-Encoding
handles alternates.
#
# compressible-content-type: wildcard pattern for matching compressible
content types
#
