< draft-ietf-httpbis-cache-header-06.txt   draft-ietf-httpbis-cache-header-07.txt >
HTTP M. Nottingham HTTP M. Nottingham
Internet-Draft Fastly Internet-Draft Fastly
Intended status: Standards Track 13 January 2021 Intended status: Standards Track 26 January 2021
Expires: 17 July 2021 Expires: 30 July 2021
The Cache-Status HTTP Response Header Field The Cache-Status HTTP Response Header Field
draft-ietf-httpbis-cache-header-06 draft-ietf-httpbis-cache-header-07
Abstract Abstract
To aid debugging, HTTP caches often append header fields to a To aid debugging, HTTP caches often append header fields to a
response explaining how they handled the request. This specification response explaining how they handled the request. This specification
codifies that practice and updates it to align with HTTP's current codifies that practice and updates it to align with HTTP's current
caching model. caching model.
Note to Readers Note to Readers
skipping to change at page 1, line 48 skipping to change at page 1, line 48
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 17 July 2021. This Internet-Draft will expire on 30 July 2021.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at page 2, line 27 skipping to change at page 2, line 27
provided without warranty as described in the Simplified BSD License. provided without warranty as described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
2. The Cache-Status HTTP Response Header Field . . . . . . . . . 3 2. The Cache-Status HTTP Response Header Field . . . . . . . . . 3
2.1. The hit parameter . . . . . . . . . . . . . . . . . . . . 4 2.1. The hit parameter . . . . . . . . . . . . . . . . . . . . 4
2.2. The fwd parameter . . . . . . . . . . . . . . . . . . . . 4 2.2. The fwd parameter . . . . . . . . . . . . . . . . . . . . 4
2.3. The fwd-status parameter . . . . . . . . . . . . . . . . 5 2.3. The fwd-status parameter . . . . . . . . . . . . . . . . 5
2.4. The ttl parameter . . . . . . . . . . . . . . . . . . . . 5 2.4. The ttl parameter . . . . . . . . . . . . . . . . . . . . 6
2.5. The stored parameter . . . . . . . . . . . . . . . . . . 5 2.5. The stored parameter . . . . . . . . . . . . . . . . . . 6
2.6. The collapsed parameter . . . . . . . . . . . . . . . . . 5 2.6. The collapsed parameter . . . . . . . . . . . . . . . . . 6
2.7. The key parameter . . . . . . . . . . . . . . . . . . . . 5 2.7. The key parameter . . . . . . . . . . . . . . . . . . . . 6
2.8. The detail parameter . . . . . . . . . . . . . . . . . . 6 2.8. The detail parameter . . . . . . . . . . . . . . . . . . 6
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4. Defining New Proxy-Status Parameters . . . . . . . . . . . . 7 4. Defining New Proxy-Status Parameters . . . . . . . . . . . . 7
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.1. Normative References . . . . . . . . . . . . . . . . . . 8 7.1. Normative References . . . . . . . . . . . . . . . . . . 9
7.2. Informative References . . . . . . . . . . . . . . . . . 9 7.2. Informative References . . . . . . . . . . . . . . . . . 9
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9
1. Introduction 1. Introduction
To aid debugging, HTTP caches often append header fields to a To aid debugging, HTTP caches often append header fields to a
response explaining how they handled the request. Unfortunately, the response explaining how they handled the request. Unfortunately, the
semantics of these headers are often unclear, and both the semantics semantics of these headers are often unclear, and both the semantics
and syntax used vary between implementations. and syntax used vary between implementations.
skipping to change at page 3, line 32 skipping to change at page 3, line 32
Its value is a List [I-D.ietf-httpbis-header-structure], Section 3.1: Its value is a List [I-D.ietf-httpbis-header-structure], Section 3.1:
Cache-Status = sf-list Cache-Status = sf-list
Each member of the list represents a cache that has handled the Each member of the list represents a cache that has handled the
request. The first member of the list represents the cache closest request. The first member of the list represents the cache closest
to the origin server, and the last member of the list represents the to the origin server, and the last member of the list represents the
cache closest to the user (possibly including the user agent's cache cache closest to the user (possibly including the user agent's cache
itself, if it appends a value). itself, if it appends a value).
The Cache-Status header field is only applicable to responses that
are generated by an origin server. An intermediary SHOULD NOT append
a Cache-Status member to responses that it generates, even if that
intermediary contains a cache, except when the generated response is
based upon a stored response (e.g., a 304 Not Modified or 206 Partial
Content).
Caches determine when it is appropriate to add the Cache-Status Caches determine when it is appropriate to add the Cache-Status
header field to a response. Some might add it to all responses, header field to a response. Some might add it to all responses,
whereas others might only do so when specifically configured to, or whereas others might only do so when specifically configured to, or
when the request contains a header field that activates a debugging when the request contains a header field that activates a debugging
mode. mode.
When adding a value to the Cache-Status header field, caches SHOULD When adding a value to the Cache-Status header field, caches SHOULD
preserve the existing field value, to allow debugging of the entire preserve the existing field value, to allow debugging of the entire
chain of caches handling the request. chain of caches handling the request.
skipping to change at page 4, line 20 skipping to change at page 4, line 31
ttl = sf-integer ttl = sf-integer
stored = sf-boolean stored = sf-boolean
collapsed = sf-boolean collapsed = sf-boolean
key = sf-string key = sf-string
detail = sf-token / sf-string detail = sf-token / sf-string
2.1. The hit parameter 2.1. The hit parameter
"hit", when true, indicates that the request was satisfied by the "hit", when true, indicates that the request was satisfied by the
cache; i.e., it was not forwarded, and the response was obtained from cache; i.e., it was not forwarded, and the response was obtained from
the cache. A response that was originally produced by the origin but the cache.
was modified by the cache (for example, a 304 or 206 status code) is
A response that was originally produced by the origin but was
modified by the cache (for example, a 304 or 206 status code) is
still considered a hit, as long as it did not go forward (e.g., for still considered a hit, as long as it did not go forward (e.g., for
validation). validation).
A response that was in cache but not able to be used without going
forward (e.g., because it was stale, or partial) is not considered a
hit. Note that a stale response that is used without going forward
(e.g., because the origin server is not available) can be considered
a hit.
"hit" and "fwd" are exclusive; only one of them should appear on each "hit" and "fwd" are exclusive; only one of them should appear on each
list member. list member.
2.2. The fwd parameter 2.2. The fwd parameter
"fwd" indicates that the request went forward towards the origin, and "fwd" indicates that the request went forward towards the origin, and
why. why.
The following parameter values are defined to explain why the request The following parameter values are defined to explain why the request
went forward, from most specific to least: went forward, from most specific to least:
* bypass - The cache was configured to not handle this request * bypass - The cache was configured to not handle this request
* method - The request method's semantics require the request to be * method - The request method's semantics require the request to be
forwarded forwarded
* request - The cache was able to select a fresh response for the
request, but the request's semantics (e.g., Cache-Control request
directives) did not allow its use
* stale - The cache was able to select a response for the request,
but it was stale
* uri-miss - The cache did not contain any responses that matched * uri-miss - The cache did not contain any responses that matched
the request URI the request URI
* vary-miss - The cache contained a response that matched the * vary-miss - The cache contained a response that matched the
request URI, but could not select a response based upon this request URI, but could not select a response based upon this
request's headers and stored Vary headers. request's headers and stored Vary headers.
* miss - The cache did not contain any responses that could be used * miss - The cache did not contain any responses that could be used
to satisfy this request (to be used when an implementation cannot to satisfy this request (to be used when an implementation cannot
distinguish between uri-miss and vary-miss) distinguish between uri-miss and vary-miss)
* request - The cache was able to select a fresh response for the
request, but the request's semantics (e.g., Cache-Control request
directives) did not allow its use
* stale - The cache was able to select a response for the request,
but it was stale
* partial - The cache was able to select a partial response for the
request, but it did not contain all of the requested ranges (or
the request was for the complete response)
The most specific reason that the cache is aware of SHOULD be used. The most specific reason that the cache is aware of SHOULD be used.
2.3. The fwd-status parameter 2.3. The fwd-status parameter
"fwd-status" indicates what status code the next hop server returned "fwd-status" indicates what status code the next hop server returned
in response to the request. Only meaningful when "fwd" is present; in response to the request. Only meaningful when "fwd" is present;
if "fwd-status" is not present but "fwd" is, it defaults to the if "fwd-status" is not present but "fwd" is, it defaults to the
status code sent in the response. status code sent in the response.
This parameter is useful to distinguish cases when the next hop This parameter is useful to distinguish cases when the next hop
 End of changes. 12 change blocks. 
21 lines changed or deleted 40 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/