Re: #307 (untangle Cache-Control ABNF)

Works for me.

On 25/06/2012, at 4:30 AM, Julian Reschke wrote:

> On 2012-06-19 08:11, Julian Reschke wrote:
>> ...
> 
> In the meantime, we have opened and resolved issue #361, by adding text that requires recipients to process all syntax variations allowed by the ABNF (see <http://trac.tools.ietf.org/wg/httpbis/trac/changeset/1682>).
> 
> With that, I'd like to go back to this issue; here's the text I proposed before we discussed #361, with a few inline comments prefixed "JR:".
> 
> 3.2.  Cache-Control
> 
>   The "Cache-Control" header field is used to specify directives for
>   caches along the request/response chain.  Such cache directives are
>   unidirectional in that the presence of a directive in a request does
>   not imply that the same directive is to be given in the response.
> 
>   A cache MUST obey the requirements of the Cache-Control directives
>   defined in this section.  See Section 3.2.3 for information about how
>   Cache-Control directives defined elsewhere are handled.
> 
>      Note: HTTP/1.0 caches might not implement Cache-Control and might
>      only implement Pragma: no-cache (see Section 3.4).
> 
>   A proxy, whether or not it implements a cache, MUST pass cache
>   directives through in forwarded messages, regardless of their
>   significance to that application, since the directives might be
>   applicable to all recipients along the request/response chain.  It is
>   not possible to target a directive to a specific cache.
> 
> JR: text below is new:
> 
>   Cache directives are identified by a token, to be compared case-
>   insensitively, and have an optional argument, that can use both token
>   and quoted-string syntax.  For the directives defined below that
>   define arguments, recipients ought to accept both forms, even if one
>   is documented to be preferred.  For any directive not defined by this
>   specification, recipients MUST accept both forms.
> 
>     Cache-Control   = 1#cache-directive
> 
>     cache-directive = token [ "=" ( token / quoted-string ) ]
> 
>   For the cache directives defined below, no argument is defined (nor
>   allowed) otherwise stated otherwise.
> 
> JR: I believe Mark wasn't happy with: "For any directive not defined by this specification, recipients MUST accept both forms."
> 
> Given what we did for issue #361, this would now repeat what we said about recipient requirements based on the ABNF. I still think it's good to state, because previously the ABNF was ambigouos; for instance,
> 
>  max-age=5
> 
> would have two ABNF paths match (as both "max-age" and "cache-extension"), while
> 
>  max-age="5"
> 
> would match just "cache-extension", and the spec didn't really say what that means.
> 
> We need to address this problem for the existing directives, and SHOULD avoid it for new directives; this proposal is my attempt to do so).
> 
> JR: remaining text is almost the same; except for the introduction of subsections, ABNF for parameter values, and notes about the "preferred" notation.
> 
> 
> 3.2.1.  Request Cache-Control Directives
> 
> 3.2.1.1.  no-cache
> 
>   The no-cache request directive indicates that a cache MUST NOT use a
>   stored response to satisfy the request without successful validation
>   on the origin server.
> 
> 3.2.1.2.  no-store
> 
>   The no-store request directive indicates that a cache MUST NOT store
>   any part of either this request or any response to it.  This
>   directive applies to both private and shared caches.  "MUST NOT
>   store" in this context means that the cache MUST NOT intentionally
>   store the information in non-volatile storage, and MUST make a best-
>   effort attempt to remove the information from volatile storage as
>   promptly as possible after forwarding it.
> 
>   This directive is NOT a reliable or sufficient mechanism for ensuring
>   privacy.  In particular, malicious or compromised caches might not
>   recognize or obey this directive, and communications networks might
>   be vulnerable to eavesdropping.
> 
>   Note that if a request containing this directive is satisfied from a
>   cache, the no-store request directive does not apply to the already
>   stored response.
> 
> 3.2.1.3.  max-age
> 
>   Argument syntax:
> 
>      delta-seconds (see Section 1.5)
> 
>   The max-age request directive indicates that the client is unwilling
>   to accept a response whose age is greater than the specified number
>   of seconds.  Unless the max-stale request directive is also present,
>   the client is not willing to accept a stale response.
> 
>   Note: This directive uses the token form of the argument syntax;
>   e.g., 'max-age=5', not 'max-age="5"'.  Senders SHOULD NOT use the
>   quoted-string form.
> 
> 3.2.1.4.  max-stale
> 
>   Argument syntax:
> 
>      delta-seconds (see Section 1.5)
> 
>   The max-stale request directive indicates that the client is willing
>   to accept a response that has exceeded its expiration time.  If max-
>   stale is assigned a value, then the client is willing to accept a
>   response that has exceeded its expiration time by no more than the
>   specified number of seconds.  If no value is assigned to max-stale,
>   then the client is willing to accept a stale response of any age.
> 
>   Note: This directive uses the token form of the argument syntax;
>   e.g., 'max-stale=10', not 'max-stale="10"'.  Senders SHOULD NOT use
>   the quoted-string form.
> 
> 3.2.1.5.  min-fresh
> 
>   Argument syntax:
> 
>      delta-seconds (see Section 1.5)
> 
>   The min-fresh request directive indicates that the client is willing
>   to accept a response whose freshness lifetime is no less than its
>   current age plus the specified time in seconds.  That is, the client
>   wants a response that will still be fresh for at least the specified
>   number of seconds.
> 
>   Note: This directive uses the token form of the argument syntax;
>   e.g., 'min-fresh=20', not 'min-fresh="20"'.  Senders SHOULD NOT use
>   the quoted-string form.
> 
> 3.2.1.6.  no-transform
> 
>   The no-transform request directive indicates that an intermediary
>   (whether or not it implements a cache) MUST NOT change the Content-
>   Encoding, Content-Range or Content-Type request header fields, nor
>   the request representation.
> 
> 3.2.1.7.  only-if-cached
> 
>   The only-if-cached request directive indicates that the client only
>   wishes to obtain a stored response.  If it receives 3ive, a cache
>   SHOULD either respond using a stored response that is consistent with
>   the other constraints of the request, or respond with a 504 (Gateway
>   Timeout) status code.  If a group of caches is being operated as a
>   unified system with good internal connectivity, a member cache MAY
>   forward such a request within that group of caches.
> 
> 3.2.2.  Response Cache-Control Directives
> 
> 3.2.2.1.  public
> 
>   The public response directive indicates that a response whose
>   associated request contains an 'Authentication' header MAY be stored
>   (see Section 2.7).
> 
> 3.2.2.2.  private
> 
>   Argument syntax:
> 
>      #field-name
> 
>   The private response directive indicates that the response message is
>   intended for a single user and MUST NOT be stored by a shared cache.
>   A private cache MAY store the response.
> 
>   If the private response directive specifies one or more field-names,
>   this requirement is limited to the field-values associated with the
>   listed response header fields.  That is, a shared cache MUST NOT
>   store the specified field-names(s), whereas it MAY store the
>   remainder of the response message.
> 
>   The field-names given are not limited to the set of standard header
>   fields defined by this specification.  Field names are case-
>   insensitive.
> 
>   Note: This usage of the word "private" only controls where the
>   response can be stored; it cannot ensure the privacy of the message
>   content.  Also, private response directives with field-names are
>   often handled by implementations as if an unqualified private
>   directive was received; i.e., the special handling for the qualified
>   form is not widely implemented.
> 
>   Note: This directive uses the quoted-string form of the argument
>   syntax.  Senders SHOULD NOT use the token form (even if quoting
>   appears not to be needed for single-entry lists).
> 
> 3.2.2.3.  no-cache
> 
>   Argument syntax:
> 
>      #field-name
> 
>   The no-cache response directive indicates that the response MUST NOT
>   be used to satisfy a subsequent request without successful validation
>   on the origin server.  This allows an origin server to prevent a
>   cache from using it to satisfy a request without contacting it, even
>   by caches that have been configured to return stale responses.
> 
>   If the no-cache response directive specifies one or more field-names,
>   then a cache MAY use the response to satisfy a subsequent request,
>   subject to any other restrictions on caching.  However, any header
>   fields in the response that have the field-name(s) listed MUST NOT be
>   sent in the response to a subsequent request without successful
>   revalidation with the origin server.  This allows an origin server to
>   prevent the re-use of certain header fields in a response, while
>   still allowing caching of the rest of the response.
> 
>   The field-names given are not limited to the set of standard header
>   fields defined by this specification.  Field names are case-
>   insensitive.
> 
>   Note: Most HTTP/1.0 caches will not recognize or obey this directive.
>   Also, no-cache response directives with field-names are often handled
>   by implementations as if an unqualified no-cache directive was
>   received; i.e., the special handling for the qualified form is not
>   widely implemented.
> 
>   Note: This directive uses the quoted-string form of the argument
>   syntax.  Senders SHOULD NOT use the token form (even if quoting
>   appears not to be needed for single-entry lists).
> 
> 3.2.2.4.  no-store
> 
>   The no-store response directive indicates that a cache MUST NOT store
>   any part of either the immediate request or response.  This directive
>   applies to both private and shared caches.  "MUST NOT store" in this
>   context means that the cache MUST NOT intentionally store the
>   information in non-volatile storage, and MUST make a best-effort
>   attempt to remove the information from volatile storage as promptly
>   as possible after forwarding it.
> 
>   This directive is NOT a reliable or sufficient mechanism for ensuring
>   privacy.  In particular, malicious or compromised caches might not
>   recognize or obey this directive, and communications networks might
>   be vulnerable to eavesdropping.
> 
> 3.2.2.5.  must-revalidate
> 
>   The must-revalidate response directive indicates that once it has
>   become stale, a cache MUST NOT use the response to satisfy subsequent
>   requests without successful validation on the origin server.
> 
>   The must-revalidate directive is necessary to support reliable
>   operation for certain protocol features.  In all circumstances a
>   cache MUST obey the must-revalidate directive; in particular, if a
>   cache cannot reach the origin server for any reason, it MUST generate
>   a 504 (Gateway Timeout) response.
> 
>   The must-revalidate directive ought to be used by servers if and only
>   if failure to validate a request on the representation could result
>   in incorrect operation, such as a silently unexecuted financial
>   transaction.
> 
> 3.2.2.6.  proxy-revalidate
> 
>   The proxy-revalidate response directive has the same meaning as the
>   must-revalidate response directive, except that it does not apply to
>   private caches.
> 
> 3.2.2.7.  max-age
> 
>   Argument syntax:
> 
>      delta-seconds (see Section 1.5)
> 
>   The max-age response directive indicates that the response is to be
>   considered stale after its age is greater than the specified number
>   of seconds.
> 
>   Note: This directive uses the token form of the argument syntax;
>   e.g., 'max-age=5', not 'max-age="5"'.  Senders SHOULD NOT use the
>   quoted-string form.
> 
> 3.2.2.8.  s-maxage
> 
>   Argument syntax:
> 
>      delta-seconds (see Section 1.5)
> 
>   The s-maxage response directive indicates that, in shared caches, the
>   maximum age specified by this directive overrides the maximum age
>   specified by either the max-age directive or the Expires header
>   field.  The s-maxage directive also implies the semantics of the
>   proxy-revalidate response directive.
> 
>   Note: This directive uses the token form of the argument syntax;
>   e.g., 's-maxage=10', not 's-maxage="10"'.  Senders SHOULD NOT use the
>   quoted-string form.
> 
> 3.2.2.9.  no-transform
> 
>   The no-transform response directive indicates that an intermediary
>   (regardless of whether it implements a cache) MUST NOT change the
>   Content-Encoding, Content-Range or Content-Type response header
>   fields, nor the response representation.
> 
> 
> Best regards, Julian
> 

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

Received on Sunday, 24 June 2012 23:30:22 UTC