Immutable editorial

draft-ietf-httpbis-immutable.md

@@ -26,69 +26,68 @@ informative:
 
 --- abstract
 
-The immutable HTTP response Cache-Control extension allows servers to
-identify resources that will not be updated during their freshness
-lifetime. This assures that a client never needs to revalidate a
-cached fresh resource to be certain it has not been modified.
+The immutable HTTP response Cache-Control extension allows servers to identify
+resources that will not be updated during their freshness lifetime. This
+assures that a client never needs to revalidate a cached fresh resource to be
+certain it has not been modified.
 
 --- note_Note_to_Readers
 
 Discussion of this draft takes place on the HTTP working group mailing list (ietf-http-wg@w3.org),
 which is archived at <https://lists.w3.org/Archives/Public/ietf-http-wg/>.
 
-Working Group information can be found at <http://httpwg.github.io/>; source code and issues list
-for this draft can be found at <https://github.com/httpwg/http-extensions/labels/immutable>.
+Working Group information can be found at <http://httpwg.github.io/>; source
+code and issues list for this draft can be found at
+<https://github.com/httpwg/http-extensions/labels/immutable>.
 
 --- middle
 
 # Introduction
 
-The HTTP freshness lifetime [RFC7234] caching attribute
-specifies that a client may safely reuse a response to satisfy future
-requests over a specific period of time. It does not specify that the
-resource will be not be modified during that period.
-
-For instance, a front page newspaper photo with a freshness lifetime
-of one hour would mean that no user should see a photo more than one
-hour old. However, the photo could be updated at any time resulting in
-different users seeing different photos depending on the contents of
-their caches for up to one hour. This is compliant with the caching
-mechanism defined in [RFC7234].
-
-Users that need to confirm there have been no updates to their current
-cached resources typically invoke the reload (or refresh) mechanism in
-the user agent. This in turn generates a conditional request [RFC7232]
-and either a new representation or, if unmodified, a 304 response
-[RFC7231] is returned. A user agent that manages HTML and its
-dependent sub-resources may issue hundreds of conditional requests to
-refresh all portions of a common HTML page [REQPERPAGE].
-
-Through the use of the versioned URL design pattern some content
-providers never create more than one variant of a sub-resource. When
-these resources need an update they are simply published under a new URL,
-typically embedding a variant identifier in the path, and references
+HTTP's freshness lifetime mechanism [RFC7234] allows a client to safely reuse a
+stored response to satisfy future requests for a specified period of time.
+However, it is still possible that the resource will be modified during that
+period.
+
+For instance, a front page newspaper photo with a freshness lifetime of one
+hour would mean that no user would see a cached photo more than one hour old.
+However, the photo could be updated at any time resulting in different users
+seeing different photos depending on the contents of their caches for up to one
+hour. This is compliant with the caching mechanism defined in [RFC7234].
+
+Users that need to confirm there have been no updates to their cached responses
+typically use the reload (or refresh) mechanism in their user agents. This in
+turn generates a conditional request [RFC7232] and either a new representation
+or, if unmodified, a 304 (Not Modified) response [RFC7232] is returned. A user
+agent that understands HTML and fetches its dependent sub-resources might issue
+hundreds of conditional requests to refresh all portions of a common page
+[REQPERPAGE].
+
+However some content providers never create more than one variant of a
+sub-resource, because they use "versioned" URLs. When these resources need an
+update they are simply published under a new URL, typically embedding an
+identifier unique to that version of the resource in the path, and references
 to the sub-resource are updated with the new path information.
 
-For example, https://www.example.com/101016/main.css might be updated
-and republished as https://www.example.com/102026/main.css and the html that
-references it is changed at the same time. This design pattern allows
-a very large freshness lifetime to be applied to the sub-resource
-without guessing when it will be updated in the future.
+For example, `https://www.example.com/101016/main.css` might be updated and
+republished as `https://www.example.com/102026/main.css`, with any links that
+references it being changed at the same time. This design pattern allows a very
+large freshness lifetime to be used for the sub-resource without guessing
+when it will be updated in the future.
 
-Unfortunately, the user-agent is not aware of the versioned URL design
-pattern. User driven refresh events still translate into wasted
-conditional requests for each sub-resource as each will return 304
-responses.
+Unfortunately, the user agent does not know when this versioned URL design
+pattern is used. As a result, user-driven refreshes still translate into wasted
+conditional requests for each sub-resource as each will return 304 responses.
 
-The immutable HTTP response Cache-Control extension allows servers to
-identify resources that will not be updated during their freshness
-lifetime. This effectively instructs the client that any conditional
-request for a previously served variant of that resource may be safely
-skipped without worrying that it has been updated.
+The `immutable` HTTP response Cache-Control extension allows servers to
+identify responses that will not be updated during their freshness lifetimes.
+
+This effectively informs clients that any conditional request for that response
+can be safely skipped without worrying that it has been updated.
 
 # The immutable Cache-Control extension
 
-When present in an HTTP response, the immutable Cache-Control
+When present in an HTTP response, the `immutable` Cache-Control
 extension indicates that the origin server will not update the representation
 of that resource during the freshness lifetime of the
 response.
@@ -97,12 +96,12 @@ Clients SHOULD NOT issue a conditional request during the
 response's freshness lifetime (e.g. upon a reload) unless explicitly
 overridden by the user (e.g. a force reload).
 
-The immutable extension only applies during the freshness lifetime of
-the response. Stale responses SHOULD be revalidated as they normally
-would be in the absence of immutable.
+The immutable extension only applies during the freshness lifetime of the
+stored response. Stale responses SHOULD be revalidated as they normally would
+be in the absence of immutable.
 
-The immutable extension takes no arguments and if any arguments are
-present they have no meaning. Multiple instances of the immutable
+The immutable extension takes no arguments. If any arguments are present, they
+have no meaning, and MUST be ignored. Multiple instances of the immutable
 extension are equivalent to one instance. The presence of an immutable
 Cache-Control extension in a request has no effect.
 
@@ -127,30 +126,29 @@ Cache-Control: max-age=31536000, immutable
 
 # Security Considerations
 
-The immutable mechanism acts as form of soft pinning and, as with all
-pinning mechanisms, creates a vector for amplification of cache
-corruption incidents. These incidents include cache poisoning
-attacks. Three mechanisms are suggested for mitigation of this risk:
+The immutable mechanism acts as form of soft pinning and, as with all pinning
+mechanisms, creates a vector for amplification of cache corruption incidents.
+These incidents include cache poisoning attacks. Three mechanisms are suggested
+for mitigation of this risk:
 
-* Clients should ignore immutable for resources that are not
- part of an authenticated context such as HTTPS. Authenticated resources are less
- vulnerable to cache poisoning.
+* Clients SHOULD ignore immutable from resources that are not part of an
+  authenticated context such as HTTPS. Authenticated resources are less
+  vulnerable to cache poisoning.
 
-* User-Agents often provide two different refresh mechanismss: reload
-  and some form of force-reload. The latter is used to rectify
-  interrupted loads and other corruption. These reloads, typically
-  indicated through no-cache request attributes, should ignore
-  immutable as well.
+* User-Agents often provide two different refresh mechanisms: reload and some
+  form of force-reload. The latter is used to rectify interrupted loads and
+  other corruption. These reloads, typically indicated through no-cache request
+  attributes, SHOULD ignore immutable as well.
 
-* Clients should ignore immutable for resources that do not provide a
- strong indication that the stored response size is the correct
- response size such as responses delimited by connection close.
+* Clients SHOULD ignore immutable for resources that do not provide a strong
+  indication that the stored response size is the correct response size such as
+  responses delimited by connection close.
 
 # IANA Considerations
 
-[RFC7234] sections 7.1 and 7.1.2 require registration of the
-immutable extension in the "Hypertext Transfer Protocol (HTTP) Cache
-Directive Registry" with IETF Review.
+[RFC7234] sections 7.1 and 7.1.2 require registration of the immutable
+extension in the "Hypertext Transfer Protocol (HTTP) Cache Directive Registry"
+with IETF Review.
 
 * Cache-Directive: immutable
 * Pointer to specification text: \[this document\]