Re: #307 (untangle Cache-Control ABNF)

+1; do you have a diff?

On 11/06/2012, at 5:52 AM, Julian Reschke wrote:

> This is a left-over TODO from previous ABNF discussions -- Cache-Control currently defines directives as part of it's value ABNF; which makes it look as if generic parsers need to special-case the predefined directives. Hopefully we all agree that parsers should be generic (as we suggest for new header fields in P2).
> 
> Thus I'd like to simplify the Cache-Control ABNF to the bare minimum, and then define the individual directives in separate subsections. Here's how this might look:
> 
> 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.
> 
>   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.  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.
> 
> 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.
> 
> 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.
> 
> 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.
> 
> 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 this directive, 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: For compatibility with non-robust recipients, even a single-
>   entry list of field names SHOULD be sent using the quoted-string
>   syntax.
> 
> 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: For compatibility with non-robust recipients, even a single-
>   entry list of field names SHOULD be sent using the quoted-string
>   syntax.
> 
> 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.
> 
> 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.
> 
> 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.
> 
> 
> 3.3 ...
> 
> Feedback appreciated, Julian
> 

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

Received on Monday, 11 June 2012 12:36:56 UTC