rfc 2616

• fielding, et al. standards track [page 91]
  
  rfc 2616 http/1.1 june 1999
  
  13.5 constructing responses from caches
  
  the purpose of an http cache is to store information received in
  response to requests for use in responding to future requests. in
  many cases, a cache simply returns the appropriate parts of a
  response to the requester. however, if the cache holds a cache entry
  based on a previous response, it might have to combine parts of a new
  response with what is held in the cache entry.
  
  13.5.1 end-to-end and hop-by-hop headers
  
  for the purpose of defining the behavior of caches and non-caching
  proxies, we divide http headers into two categories:
  
  - end-to-end headers, which are transmitted to the ultimate
  recipient of a request or response. end-to-end headers in
  responses must be stored as part of a cache entry and must be
  transmitted in any response formed from a cache entry.
  
  - hop-by-hop headers, which are meaningful only for a single
  transport-level connection, and are not stored by caches or
  forwarded by proxies.
  
  the following http/1.1 headers are hop-by-hop headers:
  
  - connection
  - keep-alive
  - proxy-authenticate
  - proxy-authorization
  - te
  - trailers
  - transfer-encoding
  - upgrade
  
  all other headers defined by http/1.1 are end-to-end headers.
  
  other hop-by-hop headers must be listed in a connection header,
  (section 14.10) to be introduced into http/1.1 (or later).
  
  13.5.2 non-modifiable headers
  
  some features of the http/1.1 protocol, such as digest
  authentication, depend on the value of certain end-to-end headers. a
  transparent proxy should not modify an end-to-end header unless the
  definition of that header requires or specifically allows that.
  
  fielding, et al. standards track [page 92]
  
  rfc 2616 http/1.1 june 1999
  
  a transparent proxy must not modify any of the following fields in a
  request or response, and it must not add any of these fields if not
  already present:
  
  - content-location
  
  - content-md5
  
  - etag
  
  - last-modified
  
  a transparent proxy must not modify any of the following fields in a
  response:
  
  - expires
  
  but it may add any of these fields if not already present. if an
  expires header is added, it must be given a field-value identical to
  that of the date header in that response.
  
  a proxy must not modify or add any of the following fields in a
  message that contains the no-transform cache-control directive, or in
  any request:
  
  - content-encoding
  
  - content-range
  
  - content-type
  
  a non-transparent proxy may modify or add these fields to a message
  that does not include no-transform, but if it does so, it must add a
  warning 214 (transformation applied) if one does not already appear
  in the message (see section 14.46).
  
  warning: unnecessary modification of end-to-end headers might
  cause authentication failures if stronger authentication
  mechanisms are introduced in later versions of http. such
  authentication mechanisms may rely on the values of header fields
  not listed here.
  
  the content-length field of a request or response is added or deleted
  according to the rules in section 4.4. a transparent proxy must
  preserve the entity-length (section 7.2.2) of the entity-body,
  although it may change the transfer-length (section 4.4).
  
  fielding, et al. standards track [page 93]
  
  rfc 2616 http/1.1 june 1999
  
  13.5.3 combining headers
  
  when a cache makes a validating request to a server, and the server
  provides a 304 (not modified) response or a 206 (partial content)
  response, the cache then constructs a response to send to the
  requesting client.
  
  if the status code is 304 (not modified), the cache uses the entity-
  body stored in the cache entry as the entity-body of this outgoing
  response. if the status code is 206 (partial content) and the etag or
  last-modified headers match exactly, the cache may combine the
  contents stored in the cache entry with the new contents received in
  the response and use the result as the entity-body of this outgoing
  response, (see 13.5.4).
  
  the end-to-end headers stored in the cache entry are used for the
  constructed response, except that
  
  - any stored warning headers with warn-code 1xx (see section
  14.46) must be deleted from the cache entry and the forwarded
  response.
  
  - any stored warning headers with warn-code 2xx must be retained
  in the cache entry and the forwarded response.
  
  - any end-to-end headers provided in the 304 or 206 response must
  replace the corresponding headers from the cache entry.
  
  unless the cache decides to remove the cache entry, it must also
  replace the end-to-end headers stored with the cache entry with
  corresponding headers received in the incoming response, except for
  warning headers as described immediately above. if a header field-
  name in the incoming response matches more than one header in the
  cache entry, all such old headers must be replaced.
  
  in other words, the set of end-to-end headers received in the
  incoming response overrides all corresponding end-to-end headers
  stored with the cache entry (except for stored warning headers with
  warn-code 1xx, which are deleted even if not overridden).
  
  note: this rule allows an origin server to use a 304 (not
  modified) or a 206 (partial content) response to update any header
  associated with a previous response for the same entity or sub-
  ranges thereof, although it might not always be meaningful or
  correct to do so. this rule does not allow an origin server to use
  a 304 (not modified) or a 206 (partial content) response to
  entirely delete a header that it had provided with a previous
  response.
  
  fielding, et al. standards track [page 94]
  
  rfc 2616 http/1.1 june 1999
  
  13.5.4 combining byte ranges
  
  a response might transfer only a subrange of the bytes of an entity-
  body, either because the request included one or more range
  specifications, or because a connection was broken prematurely. after
  several such transfers, a cache might have received several ranges of
  the same entity-body.
  
  if a cache has a stored non-empty set of subranges for an entity, and
  an incoming response transfers another subrange, the cache may
  combine the new subrange with the existing set if both the following
  conditions are met:
  
  - both the incoming response and the cache entry have a cache
  validator.
  
  - the two cache validators match using the strong comparison
  function (see section 13.3.3).
  
  if either requirement is not met, the cache must use only the most
  recent partial response (based on the date values transmitted with
  every response, and using the incoming response if these values are
  equal or missing), and must discard the other partial information.
  
  13.6 caching negotiated responses
  
  use of server-driven content negotiation (section 12.1), as indicated
  by the presence of a vary header field in a response, alters the
  conditions and procedure by which a cache can use the response for
  subsequent requests. see section 14.44 for use of the vary header
  field by servers.
  
  a server should use the vary header field to inform a cache of what
  request-header fields were used to select among multiple
  representations of a cacheable response subject to server-driven
  negotiation. the set of header fields named by the vary field value
  is known as the "selecting" request-headers.
  
  when the cache receives a subsequent request whose request-uri
  specifies one or more cache entries including a vary header field,
  the cache must not use such a cache entry to construct a response to
  the new request unless all of the selecting request-headers present
  in the new request match the corresponding stored request-headers in
  the original request.
  
  the selecting request-headers from two requests are defined to match
  if and only if the selecting request-headers in the first request can
  be transformed to the selecting request-headers in the second request
  
  fielding, et al. standards track [page 95]
  
  rfc 2616 http/1.1 june 1999
  
  by adding or removing linear white space (lws) at places where this
  is allowed by the corresponding bnf, and/or combining multiple
  message-header fields with the same field name following the rules
  about message headers in section 4.2.
  
  a vary header field-value of "*" always fails to match and subsequent
  requests on that resource can only be properly interpreted by the
  origin server.
  
  if the selecting request header fields for the cached entry do not
  match the selecting request header fields of the new request, then
  the cache must not use a cached entry to satisfy the request unless
  it first relays the new request to the origin server in a conditional
  request and the server responds with 304 (not modified), including an
  entity tag or content-location that indicates the entity to be used.
  
  if an entity tag was assigned to a cached representation, the
  forwarded request should be conditional and include the entity tags
  in an if-none-match header field from all its cache entries for the
  resource. this conveys to the server the set of entities currently
  held by the cache, so that if any one of these entities matches the
  requested entity, the server can use the etag header field in its 304
  (not modified) response to tell the cache which entry is appropriate.
  if the entity-tag of the new response matches that of an existing
  entry, the new response should be used to update the header fields of
  the existing entry, and the result must be returned to the client.
  
  if any of the existing cache entries contains only partial content
  for the associated entity, its entity-tag should not be included in
  the if-none-match header field unless the request is for a range that
  would be fully satisfied by that entry.
  
  if a cache receives a successful response whose content-location
  field matches that of an existing cache entry for the same request-
  ]uri, whose entity-tag differs from that of the existing entry, and
  whose date is more recent than that of the existing entry, the
  existing entry should not be returned in response to future requests
  and should be deleted from the cache.
  
  13.7 shared and non-shared caches
  
  for reasons of security and privacy, it is necessary to make a
  distinction between "shared" and "non-shared" caches. a non-shared
  cache is one that is accessible only to a single user. accessibility
  in this case should be enforced by appropriate security mechanisms.
  all other caches are considered to be "shared." other sections of
  
  fielding, et al. standards track [page 96]
  
  rfc 2616 http/1.1 june 1999
  
  this specification place certain constraints on the operation of
  shared caches in order to prevent loss of privacy or failure of
  access controls.
  
  13.8 errors or incomplete response cache behavior
  
  a cache that receives an incomplete response (for example, with fewer
  bytes of data than specified in a content-length header) may store
  the response. however, the cache must treat this as a partial
  response. partial responses may be combined as described in section
  13.5.4; the result might be a full response or might still be
  partial. a cache must not return a partial response to a client
  without explicitly marking it as such, using the 206 (partial
  content) status code. a cache must not return a partial response
  using a status code of 200 (ok).
  
  if a cache receives a 5xx response while attempting to revalidate an
  entry, it may either forward this response to the requesting client,
  or act as if the server failed to respond. in the latter case, it may
  return a previously received response unless the cached entry
  includes the "must-revalidate" cache-control directive (see section
  14.9).
  
  13.9 side effects of get and head
  
  unless the origin server explicitly prohibits the caching of their
  responses, the application of get and head methods to any resources
  should not have side effects that would lead to erroneous behavior if
  these responses are taken from a cache. they may still have side
  effects, but a cache is not required to consider such side effects in
  its caching decisions. caches are always expected to observe an
  origin server's explicit restrictions on caching.
  
  we note one exception to this rule: since some applications have
  traditionally used gets and heads with query urls (those containing a
  "?" in the rel_path part) to perform operations with significant side
  effects, caches must not treat responses to such uris as fresh unless
  the server provides an explicit expiration time. this specifically
  means that responses from http/1.0 servers for such uris should not
  be taken from a cache. see section 9.1.1 for related information.
  
  13.10 invalidation after updates or deletions
  
  the effect of certain methods performed on a resource at the origin
  server might cause one or more existing cache entries to become non-
  transparently invalid. that is, although they might continue to be
  "fresh," they do not accurately reflect what the origin server would
  return for a new request on that resource.
  
  fielding, et al. standards track [page 97]
  
  rfc 2616 http/1.1 june 1999
  
  there is no way for the http protocol to guarantee that all such
  cache entries are marked invalid. for example, the request that
  caused the change at the origin server might not have gone through
  the proxy where a cache entry is stored. however, several rules help
  reduce the likelihood of erroneous behavior.
  
  in this section, the phrase "invalidate an entity" means that the
  cache will either remove all instances of that entity from its
  storage, or will mark these as "invalid" and in need of a mandatory
  revalidation before they can be returned in response to a subsequent
  request.
  
  some http methods must cause a cache to invalidate an entity. this is
  either the entity referred to by the request-uri, or by the location
  or content-location headers (if present). these methods are:
  
  - put
  
  - delete
  
  - post
  
  in order to prevent denial of service attacks, an invalidation based
  on the uri in a location or content-location header must only be
  performed if the host part is the same as in the request-uri.
  
  a cache that passes through requests for methods it does not
  understand should invalidate any entities referred to by the
  request-uri.
  
  13.11 write-through mandatory
  
  all methods that might be expected to cause modifications to the
  origin server's resources must be written through to the origin
  server. this currently includes all methods except for get and head.
  a cache must not reply to such a request from a client before having
  transmitted the request to the inbound server, and having received a
  corresponding response from the inbound server. this does not prevent
  a proxy cache from sending a 100 (continue) response before the
  inbound server has sent its final reply.
  
  the alternative (known as "write-back" or "copy-back" caching) is not
  allowed in http/1.1, due to the difficulty of providing consistent
  updates and the problems arising from server, cache, or network
  failure prior to write-back.
  
  fielding, et al. standards track [page 98]
  
  rfc 2616 http/1.1 june 1999
  
  13.12 cache replacement
  
  if a new cacheable (see sections 14.9.2, 13.2.5, 13.2.6 and 13.8)
  response is received from a resource while any existing responses for
  the same resource are cached, the cache should use the new response
  to reply to the current request. it may insert it into cache storage
  and may, if it meets all other requirements, use it to respond to any
  future requests that would previously have caused the old response to
  be returned. if it inserts the new response into cache storage the
  rules in section 13.5.3 apply.
  
  note: a new response that has an older date header value than
  existing cached responses is not cacheable.
  
  13.13 history lists
  
  user agents often have history mechanisms, such as "back" buttons and
  history lists, which can be used to redisplay an entity retrieved
  earlier in a session.
  
  history mechanisms and caches are different. in particular history
  mechanisms should not try to show a semantically transparent view of
  the current state of a resource. rather, a history mechanism is meant
  to show exactly what the user saw at the time when the resource was
  retrieved.
  
  by default, an expiration time does not apply to history mechanisms.
  if the entity is still in storage, a history mechanism should display
  it even if the entity has expired, unless the user has specifically
  configured the agent to refresh expired history documents.
  
  this is not to be construed to prohibit the history mechanism from
  telling the user that a view might be stale.
  
  note: if history list mechanisms unnecessarily prevent users from
  viewing stale resources, this will tend to force service authors
  to avoid using http expiration controls and cache controls when
  they would otherwise like to. service authors may consider it
  important that users not be presented with error messages or
  warning messages when they use navigation controls (such as back)
  to view previously fetched resources. even though sometimes such
  resources ought not to cached, or ought to expire quickly, user
  interface considerations may force service authors to resort to
  other means of preventing caching (e.g. "once-only" urls) in order
  not to suffer the effects of improperly functioning history
  mechanisms.
  
  fielding, et al. standards track [page 99]
  
  rfc 2616 http/1.1 june 1999
  
  14 header field definitions
  
  this section defines the syntax and semantics of all standard
  http/1.1 header fields. for entity-header fields, both sender and
  recipient refer to either the client or the server, depending on who
  sends and who receives the entity.
  
  14.1 accept
  
  the accept request-header field can be used to specify certain media
  types which are acceptable for the response. accept headers can be
  used to indicate that the request is specifically limited to a small
  set of desired types, as in the case of a request for an in-line
  image.
  
  accept = "accept" ":"
  #( media-range [ accept-params ] )
  
  media-range = ( "*/*"
  | ( type "/" "*" )
  | ( type "/" subtype )
  ) *( ";" parameter )
  accept-params = ";" "q" "=" qvalue *( accept-extension )
  accept-extension = ";" token [ "=" ( token | quoted-string ) ]
  
  the asterisk "*" character is used to group media types into ranges,
  with "*/*" indicating all media types and "type/*" indicating all
  subtypes of that type. the media-range may include media type
  parameters that are applicable to that range.
  
  each media-range may be followed by one or more accept-params,
  beginning with the "q" parameter for indicating a relative quality
  factor. the first "q" parameter (if any) separates the media-range
  parameter(s) from the accept-params. quality factors allow the user
  or user agent to indicate the relative degree of preference for that
  media-range, using the qvalue scale from 0 to 1 (section 3.9). the
  default value is q=1.
  
  note: use of the "q" parameter name to separate media type
  parameters from accept extension parameters is due to historical
  practice. although this prevents any media type parameter named
  "q" from being used with a media range, such an event is believed
  to be unlikely given the lack of any "q" parameters in the iana
  media type registry and the rare usage of any media type
  parameters in accept. future media types are discouraged from
  registering any parameter named "q".
  
  fielding, et al. standards track [page 100]
  
  rfc 2616 http/1.1 june 1999
  
  the example
  
  accept: audio/*; q=0.2, audio/basic
  
  should be interpreted as "i prefer audio/basic, but send me any audio
  type if it is the best available after an 80% mark-down in quality."
  
  if no accept header field is present, then it is assumed that the
  client accepts all media types. if an accept header field is present,
  and if the server cannot send a response which is acceptable
  according to the combined accept field value, then the server should
  send a 406 (not acceptable) response.
  
  a more elaborate example is
  
  accept: text/plain; q=0.5, text/html,
  text/x-dvi; q=0.8, text/x-c
  
  verbally, this would be interpreted as "text/html and text/x-c are
  the preferred media types, but if they do not exist, then send the
  text/x-dvi entity, and if that does not exist, send the text/plain
  entity."
  
  media ranges can be overridden by more specific media ranges or
  specific media types. if more than one media range applies to a given
  type, the most specific reference has precedence. for example,
  
  accept: text/*, text/html, text/html;level=1, */*
  
  have the following precedence:
  
  1) text/html;level=1
  2) text/html
  3) text/*
  4) */*
  
  the media type quality factor associated with a given type is
  determined by finding the media range with the highest precedence
  which matches that type. for example,
  
  accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1,
  text/html;level=2;q=0.4, */*;q=0.5
  
  would cause the following values to be associated:
  
  text/html;level=1 = 1
  text/html = 0.7
  text/plain = 0.3