From f3fb531ef2960b02c9ee109bbe071b7fc006178e Mon Sep 17 00:00:00 2001
From: Mark Nottingham <mnot@mnot.net>
Date: Fri, 3 Feb 2017 13:06:49 +1100
Subject: [PATCH 1/3] Introduction

---
 draft-ietf-httpbis-immutable.md | 74 ++++++++++++++++-----------------
 1 file changed, 36 insertions(+), 38 deletions(-)

diff --git a/draft-ietf-httpbis-immutable.md b/draft-ietf-httpbis-immutable.md
index c56e8263b..747dc1d26 100644
--- a/draft-ietf-httpbis-immutable.md
+++ b/draft-ietf-httpbis-immutable.md
@@ -43,48 +43,46 @@ for this draft can be found at <https://github.com/httpwg/http-extensions/labels
 
 # 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
 

From 7e6650f7afca2cc47e69313e6960a5cb8c54131f Mon Sep 17 00:00:00 2001
From: Mark Nottingham <mnot@mnot.net>
Date: Fri, 3 Feb 2017 13:08:36 +1100
Subject: [PATCH 2/3] cc: extesion section

---
 draft-ietf-httpbis-immutable.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/draft-ietf-httpbis-immutable.md b/draft-ietf-httpbis-immutable.md
index 747dc1d26..ff24c5b91 100644
--- a/draft-ietf-httpbis-immutable.md
+++ b/draft-ietf-httpbis-immutable.md
@@ -86,16 +86,16 @@ 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
-extension indicates that the origin server MUST NOT update the representation
-of that resource during the freshness lifetime of the response.
+When present in an HTTP response, the `immutable` Cache-Control extension
+indicates that the origin server MUST NOT update the representation of that
+resource during the freshness lifetime of the response.
 
-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.
 

From 4923ad83f38d0b278a1823b40d7000073db1a679 Mon Sep 17 00:00:00 2001
From: Mark Nottingham <mnot@mnot.net>
Date: Fri, 3 Feb 2017 13:11:59 +1100
Subject: [PATCH 3/3] should -> SHOULD, light tweaking

---
 draft-ietf-httpbis-immutable.md | 63 ++++++++++++++++-----------------
 1 file changed, 31 insertions(+), 32 deletions(-)

diff --git a/draft-ietf-httpbis-immutable.md b/draft-ietf-httpbis-immutable.md
index ff24c5b91..c4f2748a4 100644
--- a/draft-ietf-httpbis-immutable.md
+++ b/draft-ietf-httpbis-immutable.md
@@ -26,18 +26,19 @@ 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
 
@@ -101,12 +102,11 @@ Cache-Control extension in a request has no effect.
 
 ## About Intermediaries
 
-An immutable response has the same semantic meaning for proxy clients
-as it does for User-Agent based clients and they therefore MAY also
-presume a conditional revalidation for a response marked immutable
-would return 304. A proxy client who uses immutable to anticipate a
-304 response may choose whether to reply with a 304 or 200 to its
-requesting client.
+An immutable response has the same semantic meaning for proxy clients as it
+does for User-Agent based clients and they therefore MAY also presume a
+conditional revalidation for a response marked immutable would return 304. A
+proxy client who uses immutable to anticipate a 304 response may choose whether
+to reply with a 304 or 200 to its requesting client.
 
 ## Example
 
@@ -116,35 +116,34 @@ 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\]
 
 # Acknowledgments
 
-Thank you to Ben Maurer for partnership in developing and testing this
-idea. Thank you to Amos Jeffries for help with proxy interactions.
+Thank you to Ben Maurer for partnership in developing and testing this idea.
+Thank you to Amos Jeffries for help with proxy interactions.