Re: #307 (untangle Cache-Control ABNF)

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

Received on Sunday, 24 June 2012 18:31:42 UTC