- From: Julian Reschke <julian.reschke@gmx.de>
- Date: Sun, 10 Jun 2012 21:52:16 +0200
- To: HTTP Working Group <ietf-http-wg@w3.org>
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