Subject: Editorial notes on p6

From: Mark Nottingham <[email-masked]>
Date: Mon, 29 Apr 2013 11:49:51 +1000

[ Yes, I'm talking to myself here... if anyone has a problem with the proposed edits below, please say so; if I don't hear otherwise, I'll incorporate ]

* 1.1 Purpose doesn't need to be separate from 1 Introduction; suggest combining them into Introduction.

* 1.1 "message storage, retrieval, and deletion" --> "storage, retrieval, and deletion of messages"

* 1.1 "A fresh cache response" --> "A fresh response"

* 1.1 s/transfers/overhead/

* 1.1 last sentence needs a reference to "serving stale responses"

* 1.2 p6 is the only part with a separate 'terminology' section; the definitions should be distributed to first use, like the other parts.

* 1.2 "private cache" is defined as being "dedicated to a single user."  I suspect this should be "... single user agent" to be in keeping with our separation from user concerns.

* 1.2 "The age of a response is the time since it was sent..." --> "The time since a response was sent..."

* 1.2 Move the parenthetical "(either explicit or heuristic)" from the definition of "stale" to "freshness lifetime"

* 1.2 The definition of "strong validator" is too detailed; it should (mostly) rely on the definition in p4.

* 2. s/locally-desired/local/

* 2. "Therefore, HTTP cache requirements are focused on preventing..." needs something like this appended to the sentence: "...rather than mandating that caches always store and reuse particular responses."

* 2. "The default cache key consists of..." --> "The primary cache key consists of..."

* 2. "...use only the URI as the key." --> "Use only the URI as the primary cache key."

* 3. bullet point "contains a s-maxage response cache directive..." needs a reference.

* 3. "...and implements any cache-specific behavior." --> "...and implements all specified caching-related behavior."

* 3. "...many caches will not store a response..."  s/many/some

* 4. "For a presented request, a cache MUST NOT use a stored response, unless:"  --> "When presented with a request, a cache MUST NOT reuse a stored response, unless:"

* 4. "...a cache MUST send a single Age header field..." --> "...a cache MUST generate an Age header field, replacing any present..."

* 4. "...also forward a request with..." --> "...also forward the request with..."

* 4. "...revalidating them on every use."  s/on/upon/

* 4.1 Title "Freshness Model" should just be "Freshness"

* 4.1 "The freshness_lifetime is defined in Section 4.1.1; the current_age is..."  s/the//

* 4.1 "...it is considered invalid."  --> "...that directive's value is considered invalid."

* 4.1.2 "Therefore, servers are encouraged to send explicit directives..." --> "Therefore, origin servers are encouraged to generate explicit directives..."

* 4.1.3 The text at the end regarding problems in date parsing is not specific to calculating age; it needs to be moved up to the next highest level (freshness), possibly in a new subsection.

* 4.1.4 Para "If a cache receives..." should be prefixed with "Note that..."

* 4.2 Title "Validation Model" should just be "Validation"

* 4.2 "When sending such a conditional request..."  This and the following paragraph are awkward.

* 4.2 "...whose value is that of the ETag header field(s) from all responses stored..."  s/all/relevant/

* 4.2.1 "...identifies the selected representation."  append "for update" (3 occurrences) 

* 4.4 This section should either be incorporated into 3.3, or made a subsection of it.

* 6 "For example, the request that caused the change at the origin server might not have gone through the cache where a response is stored."  --> "For example, a state-changing request might invalidate responses in the caches it travels through, but responses still might be stored in other caches that is has not."

* 7.2 "Note: HTTP/1.0 caches might not implement Cache-Control, and might only implement Pragma: no-cache." --> "Note: some HTTP/1.0 caches might not implement Cache-Control."

* 7.2.1 Request Cache-Control directives should be alphabetically ordered.

* 7.2.1.4 "expiration time" --> "freshness lifetime" (two instances)

* 7.2.2 Response Cache-Control directives should be alphabetically ordered.

* 7.2.2.2 s/standard//  (two instances)

* 7.2.2.2 "Many HTTP/1.0 caches will not recognize or obey this directive."  --> "Although it has been back-ported to many implementations, some HTTP/1.0 caches will not..."

* 7.2.3 Split into multiple paragraphs.

--
Mark Nottingham   http://www.mnot.net/

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 29 Apr 2013 15:13:08 +1000

* 4.1.1 says "When there is more than one value present for a given directive (e.g., two Expires header fields, multiple Cache-Control: max-age directives), it is considered invalid. Caches are encouraged to consider responses that have invalid freshness information to be stale."

This should be moved to or repeated in the various subsections that define those directives, rather than hidden only here.

* 4.2 "... from all responses stored fort he requested URI, if present."  "requested URI" needs to be "primary cache key."

* 4.3 A better section title would be "Calculating Secondary Keys with Vary". Also, this section should probably be higher up, e.g., 4.1.

* 7.2.3 "Whether the directive is specific to requests, responses, or used in both" should be added to the list of considerations for cache control extensions.

* I think that both 
  4.2.1 Freshening Responses with 304 Not Modified
and
  4.4 Combining Partial Content
would sit better as subsections of 
  3.   Storing Responses in Caches
... because they're about how an incoming response affects the cache, not how to satisfy a request from it.