draft-ietf-httpbis-cache-04.txt		draft-ietf-httpbis-cache-05.txt
	HTTP Working Group R. Fielding, Ed.		HTTP Working Group R. Fielding, Ed.
	Internet-Draft Adobe		Internet-Draft Adobe
	Obsoletes: 7234 (if approved) M. Nottingham, Ed.		Obsoletes: 7234 (if approved) M. Nottingham, Ed.
	Intended status: Standards Track Fastly		Intended status: Standards Track Fastly
	Expires: September 10, 2019 J. Reschke, Ed.		Expires: January 9, 2020 J. Reschke, Ed.
	greenbytes		greenbytes
	March 9, 2019		July 8, 2019
	HTTP Caching		HTTP Caching
	draft-ietf-httpbis-cache-04		draft-ietf-httpbis-cache-05
	Abstract		Abstract
	The Hypertext Transfer Protocol (HTTP) is a stateless application-		The Hypertext Transfer Protocol (HTTP) is a stateless application-
	level protocol for distributed, collaborative, hypertext information		level protocol for distributed, collaborative, hypertext information
	systems. This document defines HTTP caches and the associated header		systems. This document defines HTTP caches and the associated header
	fields that control cache behavior or indicate cacheable response		fields that control cache behavior or indicate cacheable response
	messages.		messages.
	This document obsoletes RFC 7234.		This document obsoletes RFC 7234.
	skipping to change at page 1, line 36 ¶		skipping to change at page 1, line 36 ¶
	This note is to be removed before publishing as an RFC.		This note is to be removed before publishing as an RFC.
	Discussion of this draft takes place on the HTTP working group		Discussion of this draft takes place on the HTTP working group
	mailing list (ietf-http-wg@w3.org), which is archived at		mailing list (ietf-http-wg@w3.org), which is archived at
	<https://lists.w3.org/Archives/Public/ietf-http-wg/>.		<https://lists.w3.org/Archives/Public/ietf-http-wg/>.
	Working Group information can be found at <https://httpwg.org/>;		Working Group information can be found at <https://httpwg.org/>;
	source code and issues list for this draft can be found at		source code and issues list for this draft can be found at
	<https://github.com/httpwg/http-core>.		<https://github.com/httpwg/http-core>.
	The changes in this draft are summarized in Appendix C.5.		The changes in this draft are summarized in Appendix C.6.
	Status of This Memo		Status of This Memo
	This Internet-Draft is submitted in full conformance with the		This Internet-Draft is submitted in full conformance with the
	provisions of BCP 78 and BCP 79.		provisions of BCP 78 and BCP 79.
	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 September 10, 2019.		This Internet-Draft will expire on January 9, 2020.
	Copyright Notice		Copyright Notice
	Copyright (c) 2019 IETF Trust and the persons identified as the		Copyright (c) 2019 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		Provisions Relating to IETF Documents
	(https://trustee.ietf.org/license-info) in effect on the date of		(https://trustee.ietf.org/license-info) in effect on the date of
	publication of this document. Please review these documents		publication of this document. Please review these documents
	skipping to change at page 2, line 41 ¶		skipping to change at page 2, line 41 ¶
	outside the IETF Standards Process, and derivative works of it may		outside the IETF Standards Process, and derivative works of it may
	not be created outside the IETF Standards Process, except to format		not be created outside the IETF Standards Process, except to format
	it for publication as an RFC or to translate it into languages other		it for publication as an RFC or to translate it into languages other
	than English.		than English.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
	1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5		1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5
	1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5		1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5
	1.3. Delta Seconds . . . . . . . . . . . . . . . . . . . . . . 6		1.3. Delta Seconds . . . . . . . . . . . . . . . . . . . . . . 5
	2. Overview of Cache Operation . . . . . . . . . . . . . . . . . 6		2. Overview of Cache Operation . . . . . . . . . . . . . . . . . 6
	3. Storing Responses in Caches . . . . . . . . . . . . . . . . . 7		3. Storing Responses in Caches . . . . . . . . . . . . . . . . . 7
	3.1. Storing Incomplete Responses . . . . . . . . . . . . . . 8		3.1. Storing Incomplete Responses . . . . . . . . . . . . . . 8
	3.2. Storing Responses to Authenticated Requests . . . . . . . 9		3.2. Storing Responses to Authenticated Requests . . . . . . . 8
	3.3. Combining Partial Content . . . . . . . . . . . . . . . . 9		3.3. Combining Partial Content . . . . . . . . . . . . . . . . 9
	4. Constructing Responses from Caches . . . . . . . . . . . . . 9		4. Constructing Responses from Caches . . . . . . . . . . . . . 9
	4.1. Calculating Secondary Keys with Vary . . . . . . . . . . 10		4.1. Calculating Secondary Keys with Vary . . . . . . . . . . 10
	4.2. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 11		4.2. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 11
	4.2.1. Calculating Freshness Lifetime . . . . . . . . . . . 13		4.2.1. Calculating Freshness Lifetime . . . . . . . . . . . 13
	4.2.2. Calculating Heuristic Freshness . . . . . . . . . . . 13		4.2.2. Calculating Heuristic Freshness . . . . . . . . . . . 13
	4.2.3. Calculating Age . . . . . . . . . . . . . . . . . . . 14		4.2.3. Calculating Age . . . . . . . . . . . . . . . . . . . 14
	4.2.4. Serving Stale Responses . . . . . . . . . . . . . . . 15		4.2.4. Serving Stale Responses . . . . . . . . . . . . . . . 15
	4.3. Validation . . . . . . . . . . . . . . . . . . . . . . . 16		4.3. Validation . . . . . . . . . . . . . . . . . . . . . . . 16
	4.3.1. Sending a Validation Request . . . . . . . . . . . . 16		4.3.1. Sending a Validation Request . . . . . . . . . . . . 16
	skipping to change at page 4, line 8 ¶		skipping to change at page 4, line 8 ¶
	9.1. Normative References . . . . . . . . . . . . . . . . . . 32		9.1. Normative References . . . . . . . . . . . . . . . . . . 32
	9.2. Informative References . . . . . . . . . . . . . . . . . 33		9.2. Informative References . . . . . . . . . . . . . . . . . 33
	Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 35		Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 35
	Appendix B. Changes from RFC 7234 . . . . . . . . . . . . . . . 35		Appendix B. Changes from RFC 7234 . . . . . . . . . . . . . . . 35
	Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 35		Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 35
	C.1. Between RFC7234 and draft 00 . . . . . . . . . . . . . . 35		C.1. Between RFC7234 and draft 00 . . . . . . . . . . . . . . 35
	C.2. Since draft-ietf-httpbis-cache-00 . . . . . . . . . . . . 36		C.2. Since draft-ietf-httpbis-cache-00 . . . . . . . . . . . . 36
	C.3. Since draft-ietf-httpbis-cache-01 . . . . . . . . . . . . 36		C.3. Since draft-ietf-httpbis-cache-01 . . . . . . . . . . . . 36
	C.4. Since draft-ietf-httpbis-cache-02 . . . . . . . . . . . . 36		C.4. Since draft-ietf-httpbis-cache-02 . . . . . . . . . . . . 36
	C.5. Since draft-ietf-httpbis-cache-03 . . . . . . . . . . . . 37		C.5. Since draft-ietf-httpbis-cache-03 . . . . . . . . . . . . 37
			C.6. Since draft-ietf-httpbis-cache-04 . . . . . . . . . . . . 37
	Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37		Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
	Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 39		Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 39
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39
	1. Introduction		1. Introduction
	The Hypertext Transfer Protocol (HTTP) is a stateless application-		The Hypertext Transfer Protocol (HTTP) is a stateless application-
	level request/response protocol that uses extensible semantics and		level request/response protocol that uses extensible semantics and
	self-descriptive messages for flexible interaction with network-based		self-descriptive messages for flexible interaction with network-based
	hypertext information systems. HTTP is defined by a series of		hypertext information systems. HTTP is defined by a series of
	skipping to change at page 5, line 45 ¶		skipping to change at page 5, line 46 ¶
	feed), OCTET (any 8-bit sequence of data), SP (space), and VCHAR (any		feed), OCTET (any 8-bit sequence of data), SP (space), and VCHAR (any
	visible [USASCII] character).		visible [USASCII] character).
	The rules below are defined in [Semantics]:		The rules below are defined in [Semantics]:
	HTTP-date = <HTTP-date, see [Semantics], Section 10.1.1.1>		HTTP-date = <HTTP-date, see [Semantics], Section 10.1.1.1>
	OWS = <OWS, see [Semantics], Section 4.3>		OWS = <OWS, see [Semantics], Section 4.3>
	field-name = <field-name, see [Semantics], Section 4.2>		field-name = <field-name, see [Semantics], Section 4.2>
	quoted-string = <quoted-string, see [Semantics], Section 4.2.3>		quoted-string = <quoted-string, see [Semantics], Section 4.2.3>
	token = <token, see [Semantics], Section 4.2.3>		token = <token, see [Semantics], Section 4.2.3>
	uri-host = <host, see [RFC3986], Section 3.2.2>
	port = <port, see [RFC3986], Section 3.2.3>
	pseudonym = <pseudonym, see [Semantics], Section 5.5.1>
	1.3. Delta Seconds		1.3. Delta Seconds
	The delta-seconds rule specifies a non-negative integer, representing		The delta-seconds rule specifies a non-negative integer, representing
	time in seconds.		time in seconds.
	delta-seconds = 1*DIGIT		delta-seconds = 1*DIGIT
	A recipient parsing a delta-seconds value and converting it to binary		A recipient parsing a delta-seconds value and converting it to binary
	form ought to use an arithmetic type of at least 31 bits of non-		form ought to use an arithmetic type of at least 31 bits of non-
	skipping to change at page 21, line 15 ¶		skipping to change at page 21, line 15 ¶
	+-------------------+-----------+--------------+		+-------------------+-----------+--------------+
	| Header Field Name | Status | Reference |		| Header Field Name | Status | Reference |
	+-------------------+-----------+--------------+		+-------------------+-----------+--------------+
	| Age | standard | Section 5.1 |		| Age | standard | Section 5.1 |
	| Cache-Control | standard | Section 5.2 |		| Cache-Control | standard | Section 5.2 |
	| Expires | standard | Section 5.3 |		| Expires | standard | Section 5.3 |
	| Pragma | standard | Section 5.4 |		| Pragma | standard | Section 5.4 |
	| Warning | obsoleted | Section 5.5 |		| Warning | obsoleted | Section 5.5 |
	+-------------------+-----------+--------------+		+-------------------+-----------+--------------+
			Table 1
	5.1. Age		5.1. Age
	The "Age" header field conveys the sender's estimate of the amount of		The "Age" header field conveys the sender's estimate of the amount of
	time since the response was generated or successfully validated at		time since the response was generated or successfully validated at
	the origin server. Age values are calculated as specified in		the origin server. Age values are calculated as specified in
	Section 4.2.3.		Section 4.2.3.
	Age = delta-seconds		Age = delta-seconds
	The Age field-value is a non-negative integer, representing time in		The Age field-value is a non-negative integer, representing time in
	skipping to change at page 22, line 19 ¶		skipping to change at page 22, line 19 ¶
	is documented to be preferred. For any directive not defined by this		is documented to be preferred. For any directive not defined by this
	specification, a recipient MUST accept both forms.		specification, a recipient MUST accept both forms.
	Cache-Control = 1#cache-directive		Cache-Control = 1#cache-directive
	cache-directive = token [ "=" ( token / quoted-string ) ]		cache-directive = token [ "=" ( token / quoted-string ) ]
	For the cache directives defined below, no argument is defined (nor		For the cache directives defined below, no argument is defined (nor
	allowed) unless stated otherwise.		allowed) unless stated otherwise.
	+------------------------+-----------------------------------+		+------------------+-----------------------------------+
	| Cache Directive | Reference |		| Cache Directive | Reference |
	+------------------------+-----------------------------------+		+------------------+-----------------------------------+
	| max-age | Section 5.2.1.1, Section 5.2.2.8 |		| max-age | Section 5.2.1.1, Section 5.2.2.8 |
	| max-stale | Section 5.2.1.2 |		| max-stale | Section 5.2.1.2 |
	| min-fresh | Section 5.2.1.3 |		| min-fresh | Section 5.2.1.3 |
	| must-revalidate | Section 5.2.2.1 |		| must-revalidate | Section 5.2.2.1 |
	| no-cache | Section 5.2.1.4, Section 5.2.2.2 |		| no-cache | Section 5.2.1.4, Section 5.2.2.2 |
	| no-store | Section 5.2.1.5, Section 5.2.2.3 |		| no-store | Section 5.2.1.5, Section 5.2.2.3 |
	| no-transform | Section 5.2.1.6, Section 5.2.2.4 |		| no-transform | Section 5.2.1.6, Section 5.2.2.4 |
	| only-if-cached | Section 5.2.1.7 |		| only-if-cached | Section 5.2.1.7 |
	| private | Section 5.2.2.6 |		| private | Section 5.2.2.6 |
	| proxy-revalidate | Section 5.2.2.7 |		| proxy-revalidate | Section 5.2.2.7 |
	| public | Section 5.2.2.5 |		| public | Section 5.2.2.5 |
	| s-maxage | Section 5.2.2.9 |		| s-maxage | Section 5.2.2.9 |
	| stale-if-error | [RFC5861], Section 4 |		+------------------+-----------------------------------+
	| stale-while-revalidate | [RFC5861], Section 3 |
	+------------------------+-----------------------------------+		Table 2
	5.2.1. Request Cache-Control Directives		5.2.1. Request Cache-Control Directives
	This section defines cache request directives. They are advisory;		This section defines cache request directives. They are advisory;
	caches MAY implement them, but are not required to.		caches MAY implement them, but are not required to.
	5.2.1.1. max-age		5.2.1.1. max-age
	Argument syntax:		Argument syntax:
	skipping to change at page 32, line 43 ¶		skipping to change at page 32, line 43 ¶
	Please add a note to the "Hypertext Transfer Protocol (HTTP) Warn		Please add a note to the "Hypertext Transfer Protocol (HTTP) Warn
	Codes" registry at <https://www.iana.org/assignments/http-warn-codes>		Codes" registry at <https://www.iana.org/assignments/http-warn-codes>
	to the effect that Warning is obsoleted.		to the effect that Warning is obsoleted.
	9. References		9. References
	9.1. Normative References		9.1. Normative References
	[Messaging]		[Messaging]
	Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,		Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
	Ed., "HTTP/1.1 Messaging", draft-ietf-httpbis-messaging-04		Ed., "HTTP/1.1 Messaging", draft-ietf-httpbis-messaging-05
	(work in progress), March 2019.		(work in progress), July 2019.
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119,		Requirement Levels", BCP 14, RFC 2119,
	DOI 10.17487/RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
	<https://www.rfc-editor.org/info/rfc2119>.		<https://www.rfc-editor.org/info/rfc2119>.
	[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform		[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
	Resource Identifier (URI): Generic Syntax", STD 66,		Resource Identifier (URI): Generic Syntax", STD 66,
	RFC 3986, DOI 10.17487/RFC3986, January 2005,		RFC 3986, DOI 10.17487/RFC3986, January 2005,
	<https://www.rfc-editor.org/info/rfc3986>.		<https://www.rfc-editor.org/info/rfc3986>.
	skipping to change at page 33, line 21 ¶		skipping to change at page 33, line 21 ¶
	Specifications: ABNF", STD 68, RFC 5234,		Specifications: ABNF", STD 68, RFC 5234,
	DOI 10.17487/RFC5234, January 2008,		DOI 10.17487/RFC5234, January 2008,
	<https://www.rfc-editor.org/info/rfc5234>.		<https://www.rfc-editor.org/info/rfc5234>.
	[RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",		[RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",
	RFC 7405, DOI 10.17487/RFC7405, December 2014,		RFC 7405, DOI 10.17487/RFC7405, December 2014,
	<https://www.rfc-editor.org/info/rfc7405>.		<https://www.rfc-editor.org/info/rfc7405>.
	[Semantics]		[Semantics]
	Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,		Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
	Ed., "HTTP Semantics", draft-ietf-httpbis-semantics-04		Ed., "HTTP Semantics", draft-ietf-httpbis-semantics-05
	(work in progress), March 2019.		(work in progress), July 2019.
	[USASCII] American National Standards Institute, "Coded Character		[USASCII] American National Standards Institute, "Coded Character
	Set -- 7-bit American Standard Code for Information		Set -- 7-bit American Standard Code for Information
	Interchange", ANSI X3.4, 1986.		Interchange", ANSI X3.4, 1986.
	9.2. Informative References		9.2. Informative References
	[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,		[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
	Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext		Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
	Transfer Protocol -- HTTP/1.1", RFC 2616,		Transfer Protocol -- HTTP/1.1", RFC 2616,
	skipping to change at page 35, line 12 ¶		skipping to change at page 35, line 12 ¶
	RFC 8126, DOI 10.17487/RFC8126, June 2017,		RFC 8126, DOI 10.17487/RFC8126, June 2017,
	<https://www.rfc-editor.org/info/rfc8126>.		<https://www.rfc-editor.org/info/rfc8126>.
	Appendix A. Collected ABNF		Appendix A. Collected ABNF
	In the collected ABNF below, list rules are expanded as per		In the collected ABNF below, list rules are expanded as per
	Section 11 of [Semantics].		Section 11 of [Semantics].
	Age = delta-seconds		Age = delta-seconds
	Cache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS		Cache-Control = [ cache-directive ] *( OWS "," OWS [ cache-directive
	cache-directive ] )		] )
	Expires = HTTP-date		Expires = HTTP-date
	HTTP-date = <HTTP-date, see [Semantics], Section 10.1.1.1>		HTTP-date = <HTTP-date, see [Semantics], Section 10.1.1.1>
	OWS = <OWS, see [Semantics], Section 4.3>		OWS = <OWS, see [Semantics], Section 4.3>
	cache-directive = token [ "=" ( token / quoted-string ) ]		cache-directive = token [ "=" ( token / quoted-string ) ]
	delta-seconds = 1*DIGIT		delta-seconds = 1*DIGIT
	field-name = <field-name, see [Semantics], Section 4.2>		field-name = <field-name, see [Semantics], Section 4.2>
	port = <port, see [RFC3986], Section 3.2.3>
	pseudonym = <pseudonym, see [Semantics], Section 5.5.1>
	quoted-string = <quoted-string, see [Semantics], Section 4.2.3>		quoted-string = <quoted-string, see [Semantics], Section 4.2.3>
	token = <token, see [Semantics], Section 4.2.3>		token = <token, see [Semantics], Section 4.2.3>
	uri-host = <host, see [RFC3986], Section 3.2.2>
	Appendix B. Changes from RFC 7234		Appendix B. Changes from RFC 7234
	The Warning response header was obsoleted. Much of the information		The Warning response header was obsoleted. Much of the information
	supported by Warning could be gleaned by examining the response), and		supported by Warning could be gleaned by examining the response), and
	the remaining warn-codes -- although potentially useful -- were		the remaining warn-codes -- although potentially useful -- were
	entirely advisory, and in practice were not added by caches or		entirely advisory, and in practice were not added by caches or
	intermediaries. (Section 5.5)		intermediaries. (Section 5.5)
	Appendix C. Change Log		Appendix C. Change Log
	skipping to change at page 37, line 33 ¶		skipping to change at page 37, line 27 ¶
	o Remove requirements around cache request directives		o Remove requirements around cache request directives
	(<https://github.com/httpwg/http-core/issues/129>)		(<https://github.com/httpwg/http-core/issues/129>)
	o Deprecate Pragma (<https://github.com/httpwg/http-core/		o Deprecate Pragma (<https://github.com/httpwg/http-core/
	issues/140>)		issues/140>)
	o In Section 3.2 and Section 5.2.2, note effect of some directives		o In Section 3.2 and Section 5.2.2, note effect of some directives
	on authenticated requests (<https://github.com/httpwg/http-core/		on authenticated requests (<https://github.com/httpwg/http-core/
	issues/161>)		issues/161>)
			C.6. Since draft-ietf-httpbis-cache-04
			o In Section 5.2, remove the registrations for stale-if-error and
			stale-while-revalidate which happened in RFC 7234
			(<https://github.com/httpwg/http-core/issues/207>)
	Index		Index
	A		A
	Age header field 21		Age header field 21
	age 11		age 11
	C		C
	Cache-Control header field 21		Cache-Control header field 21
	cache 4		cache 4
	cache entry 6		cache entry 6
	cache key 6-7		cache key 6
	E		E
	Expires header field 29		Expires header field 29
	explicit expiration time 11		explicit expiration time 11
	F		F
	fresh 11		fresh 11
	freshness lifetime 11		freshness lifetime 11
	G		G
End of changes. 18 change blocks.
	40 lines changed or deleted		41 lines changed or added
This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/