I don't understand the must-understand directive of the HTTP Cache-Control header. What are some examples of when this would be used, and what sort of status code might a server use that a cache may or may not understand?
The
must-understandresponse directive indicates that a cache should store the response only if it understands the requirements for caching based on status code.
must-understandshould be coupled withno-storefor fallback behavior.Cache-Control: must-understand, no-storeIf a cache doesn't support
must-understand, it will be ignored. Ifno-storeis also present, the response isn't stored.If a cache supports
must-understand, it stores the response with an understanding of cache requirements based on its status code.
It is also formally described in RFC 9111:
The must-understand response directive limits caching of the response to a cache that understands and conforms to the requirements for that response's status code.
A response that contains the must-understand directive SHOULD also contain the no-store directive. When a cache that implements the must-understand directive receives a response that includes it, the cache SHOULD ignore the no-store directive if it understands and implements the status code's caching requirements.
Despite these descriptions, I still have no idea in what situations this directive would be useful.
The issue that lead to the introduction of the must-understand directive can be found at github. The status quo was that any final (non-1XX) status could be cached, and a cache implementation would cache any response with a status defined as cacheable by default or sent with a caching header. However, some statuses do require some extra handling (most notably 206 and 304), some statuses should never be cached (like 421 or 502).
[…] deployed implementations do cache responses with explicit freshness, even without understanding the status code.
The problem that we're trying to solve here is that many caches have a long deployment cycle, and having them align their behaviour upon a list of specified status codes rather than an in-protocol signal isn't great.
[…] a new status code with operation similar to
206 Partial Contentwould be cached incorrectly if the cache directives in it don't apply to the response it occurs within.In the (unlikely) even that we want to introduce a new partial-like response status in the future, we just need to have those responses include this [proposed
must-understand] cache-control directive to explicitly mark that response as different.
So they introduced this solely for forward-compatibility purposes, to handle the definition of new status codes. There no longer is (or will never be) a list of exceptions, instead the old behaviour is enshrined explicitly:
The definition of a new final status code ought to specify whether or not it is heuristically cacheable [previously: cacheable by default]. Note that any response with a final status code can be cached if the response has explicit freshness information. A status code defined as heuristically cacheable is allowed to be cached without explicit freshness information. Likewise, the definition of a status code can place constraints upon cache behavior if the must-understand cache directive is used.
I cannot give an example of such a new status code. The hope is that they never will exist and define exotic caching requirements. To quote Mark Nottingham again:
My reaction to that is that we shouldn't be designing new mechanisms like partial content that mess with the HTTP so deeply; I hope we've learned by now that they don't work well.
But you never know. Also, the existence of this directive alone allows cache implementations to decide that they will cache responses with status codes unknown to them, without fear of breaking in the future. This eases the introduction of new status codes, with normal caching semantics, and ensures that they will get cached properly right from the beginning without having to update the web infrastructure.