The Key HTTP Response Header FieldAdobe Systems Incorporatedfielding@gbiv.comhttp://roy.gbiv.com/mnot@mnot.nethttp://www.mnot.net/
General
Internet-DraftThe ‘Key’ header field for HTTP responses allows an origin server to describe
the cache key for a negotiated response: a short algorithm that can be used
upon later requests to determine if the same response is reusable.Key has the advantage of avoiding an additional round trip for validation
whenever a new request differs slightly, but not significantly, from prior
requests.Key also informs user agents of the request characteristics that might result
in different content, which can be useful if the user agent is not sending
Accept* fields in order to reduce the risk of fingerprinting.In HTTP caching , the Vary response header field
effectively modifies the key used to store and access a response to include
information from the request’s headers. This allows proactive content
negotiation to work with caches.However, Vary’s operation is coarse-grained; although caches are allowed to
normalise the values of headers based upon their semantics, doing so requires
the cache to understand those semantics, and is still quite limited.For example, if a response is cached with the response header field:and and its associated request is:then a subsequent request with the following header is (in a strict reading of
HTTP) not a match, resulting in a cache miss:This document defines a new response header field, “Key”, that allows servers
to describe the cache key in a much more fine-grained manner, leading to
improved cache efficiency.The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”,
“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this
document are to be interpreted as described in .This document uses the Augmented Backus-Naur Form (ABNF) notation of
with the list rule extension defined in
, Appendix B. It includes by reference the
OWS, field-name and quoted-string rules from that document, and the
parameter rule from .The “Key” response header field describes the request attributes that the
server has used to select the current representation. As such, its semantics are similar to the “Vary” response header field, but it
allows more fine-grained description, using “key modifiers”.Caches can use this information as part of determining whether a stored
response can be used to satisfy a given request. When a cache fully
implements this mechanism, it MAY ignore the Vary response header field.Additionally, user agents can use this information to discover if additional
request header fields might influence the resulting response.The Key field-value is a comma-delimited list of selecting header fields
(similar to Vary), with zero to many modifiers to each, delimited by
semicolons. Whitespace is not allowed in the field-value between each
field-name and its parameter set.The following header fields therefore have identical semantics:However, Key’s use of modifiers allows:to indicate that the response it occurs in is allowed to be reused for
requests that contain the token “gzip” (in any case) in the Accept-Encoding
header field and an Accept-Language header field value that starts with “fr”
(in any case).Note that both the field-name and modifier names themselves are case
insensitive.When used by a cache to determine whether a stored response can be used to
satisfy a presented request, each field-name identifies a potential request
header, just as with the Vary response header field.However, each of these can have zero to many “key modifiers” that change how
the response selection process (as defined in ,
Section 4.3)) works.In particular, a cache that implements the Key header field MUST NOT use a
stored response unless all of the selecting header fields nominated by the
Key header field match in both the original request (i.e., that associated
with the stored response) and the presented request.Modifiers operate on a list of zero to many field-values. This list is
constructed by:Starting with the field-values of all header fields that have the given
field-name.Splitting each field-value on commas, excluding any that occur inside of
a quoted-string production.Flattening the list of lists into a single list that represents the
individual header field-values.Case-normalising each value in both lists to lowercase.Trimming any OWS from the start and end of the field-values.For example, given the set of headers:A modifier for “Foo” would operate on the list of presented values ‘1’, ‘2’,
‘a=”b,c”’.Note that step 2 of this algorithm optimistically assumes that double-quotes
in a header field value denote the use of the quoted-string as defined by
; the cache does not need to “understand”
the specific header field. Once the appropriate header fields from both the original request and the
stored request are processed in this manner, the result is two (possibly
empty) lists of values for each specified header field.The key modifiers (as specified in the Key header field) are then applied to
the lists in the order they appear in Key (left to right). If any modifier
does not return a match (as per its definition), the headers are said not to
match. If all of the modifiers return a match, the headers are said to match.Note that some types of modifiers are said to always match; they can be used
to alter the input lists, or to alter the semantics of subsequent matches.Unrecognised modifiers MUST result in a failure to match.This document defines the following key modifiers:The “w” modifier matches if the parameter value (after unquoting) matches
(character-for-character) any whole value in both lists.The “s” modifier matches if the parameter value (after unquoting) is
contained as a sequence of characters within both lists.The “b” modifier matches if both lists contain a value that begins with the
same sequence of characters as the parameter value (after unquoting).The “p” modifier matches if the parameter value (after unquoting) matches
(character-for-character) the sequence of characters up to (but not including)
the first semi-colon (“;”) in both lists, after any whitespace is removed.For example, given the key:then each of the following header fields is a match:The “c” modifier always matches, and has the side effect of reverting the case
normalisation of the header lists (see #4 in the list above), so that
subsequent matches become case sensitive.The “n” modifier always matches, and has the side effect of modifying the
semantics of subsequent modifiers (i.e., the match modifiers to its right,
lexically) so that they will be considered to match if they do not, and
likewise they will be considered not to match if they do.For example, given a response with:then the presented header:would match, whilewould not (because it contains “b”).For example, this response header field:would allow the cache to reuse the response it occurs in if the presented
request contains:A Cookie header containing both ID=”Roy” (in that case) and _sess=fhd378
(evaluated case insensitively), andAn Accept-Encoding header containing the token “gzip” (evaluated case
insensitively).Less convoluted examples include matching any request with a User-Agent field
value containing “MSIE” in any combination of case:And an Accept-Language field value for French:TBDTBDKey words for use in RFCs to Indicate Requirement LevelsHarvard University1350 Mass. Ave.CambridgeMA 02138- +1 617 495 3864sob@harvard.edu
General
keyword
In many standards track documents several words are used to signify
the requirements in the specification. These words are often
capitalized. This document defines these words as they should be
interpreted in IETF documents. Authors who follow these guidelines
should incorporate this phrase near the beginning of their document:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
Note that the force of these words is modified by the requirement
level of the document in which they are used.
Augmented BNF for Syntax Specifications: ABNFInternet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK]Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and RoutingThe Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypertext information systems. HTTP has been in use by the World Wide Web global information initiative since 1990. This document provides an overview of HTTP architecture and its associated terminology, defines the "http" and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes general security concerns for implementations.Hypertext Transfer Protocol (HTTP/1.1): Semantics and ContentThe Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypertext information systems. This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation.Hypertext Transfer Protocol (HTTP/1.1): CachingThe Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypertext information systems. This document defines requirements on HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages.