Cache-Control: I don't understand `must-understand`

Question

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?

Documentation from MDN:

The must-understand response directive indicates that a cache should store the response only if it understands the requirements for caching based on status code.

must-understand should be coupled with no-store for fallback behavior.

Cache-Control: must-understand, no-store

If a cache doesn't support must-understand, it will be ignored. If no-store is 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.

Answer 1

Found a good explanation of the rationales for the must-understand directive, including use cases, here (it is in Japanese, so you might need a translator). At the end of that page, there is a reference to the ticket/discussion of the HTTP Working Group re: must-understand.

To summarize both:

• (Old) RFC 7234 conflicts with itself in the caching behavior for new http status codes:
  • On the one hand, it says (a) "The definition of a new status code ought to specify whether or not it is cacheable."
  • On the other hand, it says (b) "all status codes can be cached if the response they occur in has explicit freshness information"
• For the new RFC 9111, the editors wanted to clarify the behaviour for new status codes, without having to wait for the final specification of these new status codes and their cache behaviour, because cache implementations have long deployment cycles.
• So they kept (b) above, but introduced a new limitation and mechanism for (a) that works regardless of specification status:
  • If a response carries Cache-Control: must-understand, a cache MUST NOT store a response unless it understands and implements the relevant semantics of the status code.

How that changes things when new status codes are introduced:

• Before: new / not specified status codes unknown to implementations sometimes get cached, and sometimes they don't
• Now: By providing Cache-Control: must-understand, servers can explicitly specify that responses should only be cached if the cache supports the semantics of the status code.