not-cache control by HTTP headers are differences between on the actual behavior and on the document

[nozomi1773]

traffic server control whether to cache or not by client's request headers or origin's response headers , and this control are differences between on the actual behavior and on the document.

For explaining about actual behavior, I built trafficserver from latest source code ( commit: 05a6f19f99cebc4ec3210467fb9a5527b21c7d8d ) on master branch, and did gold_tests on my repo ( nozomi1773/trafficserver-test-docker--headers-to-not-cache ).
I entered detailed "via" informations in this *.test.py files.
Could you check this behavior?
Is this behavior unexpected? Or is the description of the document wrong?
If the latter, I will make a PR to correct it.

Information　

client's request headers

client's request headers ( document )

latest document notes following :

Client Directives
By default, Traffic Server does not cache objects with the following request headers:
・Authorization
・Cache-Control: no-store
・Cache-Control: no-cache
To configure Traffic Server to ignore this request header, refer to Configuring Traffic Server to Ignore Client no-cache Headers.
・Cookie (for text objects)
By default, Traffic Server caches objects served in response to requests that contain cookies (even if the object is text). You can configure Traffic Server to not cache cookied content of any type, cache all cookied content, or cache cookied content that is of image type only. For more information, refer to Caching Cookied Objects.

and
Configuring Traffic Server to Ignore Client no-cache Headers notes configure Traffic Server to ignore Client no-cache Headers:

CONFIG proxy.config.http.cache.ignore_client_no_cache INT 1

but latest traffic server's default is already 1 .

client's request headers ( actual behavior on my gold_tests )

I checked behavior when origin's response header have cacheable "Cache-Control: max-age=5" with proxy.config.http.cache.required_headers is default(2) .

CONFIG OPTION	client's request header	origin's response header	origin's status code	behavior
default	-	-	-	-
//	-	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, must-revalidate	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, proxy-revalidate	200	cached , and cache-lookup is hit
//	"Authorization: Basic ******"	"Cache-Control: max-age=5"	200,200	cached , but cache-lookup is miss
//	"Authorization: Basic ******"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	"Authorization: Basic ******"	"Cache-Control: max-age=5, must-revalidate	200,304	cached , but cache-lookup is stale, cache-lookup-result is method forces revalidated , always update cache
//	"Authorization: Basic ******"	"Cache-Control: max-age=5, proxy-revalidate	200,304	cached , but cache-lookup is stale, cache-lookup-result is method forces revalidated , always update cache
//	"Cache-Control: no-store"	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	"Cache-Control: no-store"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	"Cache-Control: no-cache"	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	"Cache-Control: no-cache"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	"Cookie:foo=777"	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	"Cookie:foo=777"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
proxy.config.http.cache.cache_responses_to_cookies : 0	-	-	-
//	-	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, must-revalidate	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, proxy-revalidate	200	cached , and cache-lookup is hit
//	"Authorization: Basic ******"	"Cache-Control: max-age=5"	200,200	cached , but cache-lookup is miss
//	"Authorization: Basic ******"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	"Authorization: Basic ******"	"Cache-Control: max-age=5, must-revalidate	200,304	cached , but cache-lookup is stale, cache-lookup-result is method forces revalidated , always update cache
//	"Authorization: Basic ******"	"Cache-Control: max-age=5, proxy-revalidate	200,304	cached , but cache-lookup is stale, cache-lookup-result is method forces revalidated , always update cache
//	"Cache-Control: no-store"	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	"Cache-Control: no-store"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	"Cache-Control: no-cache"	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	"Cache-Control: no-cache"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	"Cookie:foo=777"	"Cache-Control: max-age=5"	200	● not cached (●Change from Default)
//	"Cookie:foo=777"	"Cache-Control: max-age=5, public"	200	● not cached (●Change from Default)
proxy.config.http.cache.ignore_client_no_cache : 0	-	-	-
//	-	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, must-revalidate	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, proxy-revalidate	200	cached , and cache-lookup is hit
//	"Authorization: Basic ******"	"Cache-Control: max-age=5"	200,200	cached , but cache-lookup is miss
//	"Authorization: Basic ******"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	"Authorization: Basic ******"	"Cache-Control: max-age=5, must-revalidate	200,304	cached , but cache-lookup is stale, cache-lookup-result is method forces revalidated , always update cache
//	"Authorization: Basic ******"	"Cache-Control: max-age=5, proxy-revalidate	200,304	cached , but cache-lookup is stale, cache-lookup-result is method forces revalidated , always update cache
//	"Cache-Control: no-store"	"Cache-Control: max-age=5"	200	● not cached (●Change from Default)
//	"Cache-Control: no-store"	"Cache-Control: max-age=5, public"	200	● not cached (●Change from Default)
//	"Cache-Control: no-cache"	"Cache-Control: max-age=5"	200,304	cached , but cache-lookup is stale, cache-lookup-result is client forces revalidate , always update cache (●Change from Default)
//	"Cache-Control: no-cache"	"Cache-Control: max-age=5, public"	200,304	cached , but cache-lookup is stale, cache-lookup-result is client forces revalidate , always update cache (●Change from Default)
//	"Cookie:foo=777"	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	"Cookie:foo=777"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
proxy.config.http.cache.ignore_authentication : 1	-	-	-
//	-	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, must-revalidate	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, proxy-revalidate	200	cached , and cache-lookup is hit
//	"Authorization: Basic ******"	"Cache-Control: max-age=5"	200,200	cached , and cache-lookup is hit (●Change from Default)
//	"Authorization: Basic ******"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	"Authorization: Basic ******"	"Cache-Control: max-age=5, must-revalidate	200,304	cached , and cache-lookup is hit (●Change from Default)
//	"Authorization: Basic ******"	"Cache-Control: max-age=5, proxy-revalidate	200,304	cached , and cache-lookup is hit (●Change from Default)
//	"Cache-Control: no-store"	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	"Cache-Control: no-store"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	"Cache-Control: no-cache"	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	"Cache-Control: no-cache"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit
//	"Cookie:foo=777"	"Cache-Control: max-age=5"	200	cached , and cache-lookup is hit
//	"Cookie:foo=777"	"Cache-Control: max-age=5, public"	200	cached , and cache-lookup is hit

origin's response headers

origin's response headers ( document )

latest document notes following :

Origin Server Directives
By default, Traffic Server does not cache objects with the following response headers:
・Cache-Control: no-store
・Cache-Control: private
・WWW-Authenticate
To configure Traffic Server to ignore WWW-Authenticate headers, refer to Configuring Traffic Server to Ignore WWW-Authenticate Headers.
・Set-Cookie
・Cache-Control: no-cache
To configure Traffic Server to ignore no-cache headers, refer to Configuring Traffic Server to Ignore Server no-cache Headers.
・Expires header with a value of 0 (zero) or a past date.

and Configuring Traffic Server to Ignore WWW-Authenticate Headers notes configure Traffic Server to ignore server WWW-Authenticate headers:

CONFIG proxy.config.http.cache.ignore_authentication INT 1

and Configuring Traffic Server to Ignore Server no-cache Header notes configure Traffic Server to ignore server no-cache headers:

CONFIG proxy.config.http.cache.ignore_server_no_cache INT 1

origin's response headers ( actual behavior on my gold_tests )

I checked behavior when origin's response header have cacheable "Cache-Control: max-age=5" with proxy.config.http.cache.required_headers is default(2) .

CONFIG OPTION	client's request header	origin's response header	origin's status code	behavior
default	-	-	-	-
//	-	"Cache-Control: max-age=5"	401	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, no-store"	200	● not cached
//	-	"Cache-Control: max-age=5, private"	200	● not cached
//	-	"Cache-Control: max-age=5" , "WWW-Authenticate: Basic realm="test""	401	● not cached
//	-	"Cache-Control: max-age=5" , "WWW-Authenticate: Basic realm="test""	200	● not cached
//	-	"Cache-Control: max-age=5, public" , "WWW-Authenticate: Basic realm="test""	401	● not cached
//	-	"Cache-Control: max-age=5" , "Set-Cookie: hoge=fuga"	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, no-cache"	200,304	cached , but cache-lookup is stale, cache-lookup-result is expired , always update cache
//	-	"Cache-Control: max-age=5" , "Expires: 0"	200	cached , and cache-lookup is hit
proxy.config.http.cache.ignore_authentication : 1	-	-	-	-
//	-	"Cache-Control: max-age=5"	401	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, no-store"	200	● not cached
//	-	"Cache-Control: max-age=5, private"	200	● not cached
//	-	"Cache-Control: max-age=5" , "WWW-Authenticate: Basic realm="test""	401	cached , and cache-lookup is hit (●Change from Default)
//	-	"Cache-Control: max-age=5" , "WWW-Authenticate: Basic realm="test""	200	cached , and cache-lookup is hit (●Change from Default)
//	-	"Cache-Control: max-age=5, public" , "WWW-Authenticate: Basic realm="test""	401	cached , and cache-lookup is hit (●Change from Default)
//	-	"Cache-Control: max-age=5" , "Set-Cookie: hoge=fuga"	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, no-cache"	200,304	cached , but cache-lookup is stale, cache-lookup-result is expired , always update cache
//	-	"Cache-Control: max-age=5" , "Expires: 0"	200	cached , and cache-lookup is hit
proxy.config.http.cache.ignore_server_no_cache : 1	-	-	-	-
//	-	"Cache-Control: max-age=5"	401	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, no-store"	200	● not cached
//	-	"Cache-Control: max-age=5, private"	200	● not cached
//	-	"Cache-Control: max-age=5" , "WWW-Authenticate: Basic realm="test""	401	● not cached
//	-	"Cache-Control: max-age=5" , "WWW-Authenticate: Basic realm="test""	200	● not cached
//	-	"Cache-Control: max-age=5, public" , "WWW-Authenticate: Basic realm="test""	401	● not cached
//	-	"Cache-Control: max-age=5" , "Set-Cookie: hoge=fuga"	200	cached , and cache-lookup is hit
//	-	"Cache-Control: max-age=5, no-cache"	200	cached , and cache-lookup is hit (●Change from Default)
//	-	"Cache-Control: max-age=5" , "Expires: 0"	200	cached , and cache-lookup is hit

[bneradt]

Thank you @nozomi1773 . I'm assiging this to @lzx404243 who did a series of patches addressing these issues. I think the documentation is both updated and test coverage is added for your concerns.

Can we close this issue?

[lzx404243]

Thanks for reporting this @nozomi1773. I've updated the docs on caching mechanism to address the discrepancies pointed out above. Please check it out and re-open if you notice any other issues.

[nozomi1773]

Thanks a lot for the updates and improvements.