Describe Vary operation more clearly

[mnot]

This confuses many people.

[mnot]

Currently:

2. Overview of Cache Operation

The primary cache key consists of the request method and target URI. However, since HTTP caches in common use today are typically limited to caching responses to GET, many caches simply decline other methods and use only the URI as the primary cache key.

If a request target is subject to content negotiation, its cache entry might consist of multiple stored responses, each differentiated by a secondary key for the values of the original request's selecting header fields (Section 4.1).

... but the cache key terms aren't used anywhere else except 4.3.4. It would be good to use this consistently in 3, 4 and especially 4.1.

[mnot]

OTOH, since POST can be reused for GET, the definition of "cache key" is misleading. Perhaps the best thing to do would be to remove these terms completely.

[mnot]

It would also be good to note that in practice, some implementations "flap" between having Vary and none; this should be clarified and mitigated.

[wsargent]

The thing that's always confused me about the spec is not even "cache key" but "secondary cache key." I understand what the spec is getting at, but it's very odd to have a cache which returns two different entries:

val singleEntry: Response = cache(key)

or if there's a value entry:

val multipleEntries: Map[SecondaryKey, Response) = cache(key)

[mnot]

I think this has improved enough to close the issue; if anyone has a suggestion for further improvement, please comment.