#307 (untangle Cache-Control ABNF)

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

Received on Sunday, 10 June 2012 19:52:49 UTC