draft-ietf-httpbis-variants-06.txt		draft-ietf-httpbis-variants-latest.txt
	HTTP Working Group M. Nottingham		HTTP Working Group M. Nottingham
	Internet-Draft Fastly		Internet-Draft Fastly
	Updates: 7234 (if approved) November 2, 2019		Updates: 7234 (if approved) January 15, 2021
	Intended status: Standards Track		Intended status: Standards Track
	Expires: May 5, 2020		Expires: July 19, 2021
	HTTP Representation Variants		HTTP Representation Variants
	draft-ietf-httpbis-variants-06		draft-ietf-httpbis-variants-latest
	Abstract		Abstract
	This specification introduces an alternative way to select a HTTP		This specification introduces an alternative way to select a HTTP
	response from a cache based upon its request headers, using the HTTP		response from a cache based upon its request headers, using the HTTP
	"Variants" and "Variant-Key" response header fields. Its aim is to		"Variants" and "Variant-Key" response header fields. Its aim is to
	make HTTP proactive content negotiation more cache-friendly.		make HTTP proactive content negotiation more cache-friendly.
	Note to Readers		Note to Readers
	skipping to change at page 1, line 49 ¶		skipping to change at page 1, line 49 ¶
	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 May 5, 2020.		This Internet-Draft will expire on July 19, 2021.
	Copyright Notice		Copyright Notice
	Copyright (c) 2019 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		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
	carefully, as they describe your rights and restrictions with respect		carefully, as they describe your rights and restrictions with respect
	to this document. Code Components extracted from this document must		to this document. Code Components extracted from this document must
	include Simplified BSD License text as described in Section 4.e of		include Simplified BSD License text as described in Section 4.e of
	the Trust Legal Provisions and are provided without warranty as		the Trust Legal Provisions and are provided without warranty as
	skipping to change at page 2, line 44 ¶		skipping to change at page 2, line 44 ¶
	5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 14		5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 14
	5.1.1. Single Variant . . . . . . . . . . . . . . . . . . . 14		5.1.1. Single Variant . . . . . . . . . . . . . . . . . . . 14
	5.1.2. Multiple Variants . . . . . . . . . . . . . . . . . . 15		5.1.2. Multiple Variants . . . . . . . . . . . . . . . . . . 15
	5.1.3. Partial Coverage . . . . . . . . . . . . . . . . . . 15		5.1.3. Partial Coverage . . . . . . . . . . . . . . . . . . 15
	6. Defining Content Negotiation Using Variants . . . . . . . . . 16		6. Defining Content Negotiation Using Variants . . . . . . . . . 16
	7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16		7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
	8. Security Considerations . . . . . . . . . . . . . . . . . . . 17		8. Security Considerations . . . . . . . . . . . . . . . . . . . 17
	9. References . . . . . . . . . . . . . . . . . . . . . . . . . 17		9. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
	9.1. Normative References . . . . . . . . . . . . . . . . . . 17		9.1. Normative References . . . . . . . . . . . . . . . . . . 17
	9.2. Informative References . . . . . . . . . . . . . . . . . 18		9.2. Informative References . . . . . . . . . . . . . . . . . 18
	9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 18		9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 19
	Appendix A. Variants for Existing Content Negotiation Mechanisms 19		Appendix A. Variants for Existing Content Negotiation Mechanisms 19
	A.1. Accept . . . . . . . . . . . . . . . . . . . . . . . . . 19		A.1. Accept . . . . . . . . . . . . . . . . . . . . . . . . . 19
	A.2. Accept-Encoding . . . . . . . . . . . . . . . . . . . . . 20		A.2. Accept-Encoding . . . . . . . . . . . . . . . . . . . . . 20
	A.3. Accept-Language . . . . . . . . . . . . . . . . . . . . . 20		A.3. Accept-Language . . . . . . . . . . . . . . . . . . . . . 21
	A.4. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 21		A.4. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 21
	Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 22		Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 23
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 23		Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 23
	1. Introduction		1. Introduction
	HTTP proactive content negotiation ([RFC7231], Section 3.4.1) is		HTTP proactive content negotiation ([RFC7231], Section 3.4.1) is
	seeing renewed interest, both for existing request headers like		seeing renewed interest, both for existing request headers like
	Accept-Language and for newer ones (for example, see		Accept-Language and for newer ones (for example, see
	[I-D.ietf-httpbis-client-hints]).		[I-D.ietf-httpbis-client-hints]).
	Successfully reusing negotiated responses that have been stored in a		Successfully reusing negotiated responses that have been stored in a
	skipping to change at page 4, line 28 ¶		skipping to change at page 4, line 28 ¶
	When this specification is in use, the example above might become:		When this specification is in use, the example above might become:
	GET /foo HTTP/1.1		GET /foo HTTP/1.1
	Host: www.example.com		Host: www.example.com
	Accept-Language: en;q=0.5, fr;q=1.0		Accept-Language: en;q=0.5, fr;q=1.0
	HTTP/1.1 200 OK		HTTP/1.1 200 OK
	Content-Type: text/html		Content-Type: text/html
	Content-Language: en		Content-Language: en
	Vary: Accept-Language		Vary: Accept-Language
	Variants: Accept-Language;de;en;jp		Variants: accept-language;de;en;jp
	Variant-Key: en		Variant-Key: en
	Transfer-Encoding: chunked		Transfer-Encoding: chunked
	[English content]		[English content]
	Proactive content negotiation mechanisms that wish to be used with		Proactive content negotiation mechanisms that wish to be used with
	Variants need to define how to do so explicitly; see Section 6. As a		Variants need to define how to do so explicitly; see Section 6. As a
	result, it is best suited for negotiation over request headers that		result, it is best suited for negotiation over request headers that
	are well-understood.		are well-understood.
	skipping to change at page 5, line 40 ¶		skipping to change at page 5, line 40 ¶
	[I-D.ietf-httpbis-header-structure]). Its ABNF is:		[I-D.ietf-httpbis-header-structure]). Its ABNF is:
	Variants = sh-dict		Variants = sh-dict
	Each member-name represents the field-name of a request header that		Each member-name represents the field-name of a request header that
	is part of the secondary cache key; each member-value is an inner-		is part of the secondary cache key; each member-value is an inner-
	list of strings or tokens that convey representations of potential		list of strings or tokens that convey representations of potential
	values for that header field, hereafter referred to as "available-		values for that header field, hereafter referred to as "available-
	values".		values".
	If Structured Header parsing fails or a member's value does have the		If Structured Header parsing fails or a member's value does not have
	structure outlined above, the client MUST treat the representation as		the structure outlined above, the client MUST treat the
	having no Variants header field.		representation as having no Variants header field.
	Note that an available-value that is a token is interpreted as a		Note that an available-value that is a token is interpreted as a
	string containing the same characters, and vice versa.		string containing the same characters, and vice versa.
	So, given this example header field:		So, given this example header field:
	Variants: Accept-Encoding=(gzip)		Variants: accept-encoding=(gzip)
	a recipient can infer that the only content-coding available for that		a recipient can infer that the only content-coding available for that
	resource is "gzip" (along with the "identity" non-encoding; see		resource is "gzip" (along with the "identity" non-encoding; see
	Appendix A.2).		Appendix A.2).
	Given:		Given:
	Variants: accept-encoding=()		Variants: accept-encoding=()
	a recipient can infer that no content-codings (beyond identity) are		a recipient can infer that no content-codings (beyond identity) are
	supported. Note that as always, field-name is case-insensitive.		supported. Note that as always, field-name is case-insensitive.
	A more complex example:		A more complex example:
	Variants: Accept-Encoding=(gzip br), Accept-Language=(en fr)		Variants: accept-encoding=(gzip br), accept-language=(en fr)
	Here, recipients can infer that two content-codings in addition to		Here, recipients can infer that two content-codings in addition to
	"identity" are available, as well as two content languages. Note		"identity" are available, as well as two content languages. Note
	that, as with all Structured Header dictionaries, they might occur in		that, as with all Structured Header dictionaries, they might occur in
	the same header field or separately, like this:		the same header field or separately, like this:
	Variants: Accept-Encoding=(gzip brotli)		Variants: accept-encoding=(gzip brotli)
	Variants: Accept-Language=(en fr)		Variants: accept-language=(en fr)
	The ordering of available-values is significant, as it might be used		The ordering of available-values is significant, as it might be used
	by the header's algorithm for selecting a response (in this example,		by the header's algorithm for selecting a response (in this example,
	the first language is the default; see Appendix A.3).		the first language is the default; see Appendix A.3).
	The ordering of the request header fields themselves indicates		The ordering of the request header fields themselves indicates
	descending application of preferences; in the example above, a cache		descending application of preferences; in the example above, a cache
	that has all of the possible permutations stored will honour the		that has all of the possible permutations stored will honour the
	client's preferences for Accept-Encoding before honouring Accept-		client's preferences for Accept-Encoding before honouring Accept-
	Language.		Language.
	skipping to change at page 8, line 11 ¶		skipping to change at page 8, line 11 ¶
	the Variants header field; they can be interpreted by the algorithm		the Variants header field; they can be interpreted by the algorithm
	specific to processing that field. For example, Accept-Encoding		specific to processing that field. For example, Accept-Encoding
	defines an implicit "identity" available-value (Appendix A.2).		defines an implicit "identity" available-value (Appendix A.2).
	Each inner-list member is treated as identifying an available-value		Each inner-list member is treated as identifying an available-value
	for the corresponding variant-axis' field-name. Any list-member that		for the corresponding variant-axis' field-name. Any list-member that
	is a token is interpreted as a string containing the same characters.		is a token is interpreted as a string containing the same characters.
	For example:		For example:
	Variants: Accept-Encoding=(gzip br), Accept-Language=(en fr)		Variants: accept-encoding=(gzip br), accept-language=(en fr)
	Variant-Key: (gzip fr)		Variant-Key: (gzip fr)
	This header pair indicates that the representation has a "gzip"		This header pair indicates that the representation has a "gzip"
	content-coding and "fr" content-language.		content-coding and "fr" content-language.
	If the response can be used to satisfy more than one request, they		If the response can be used to satisfy more than one request, they
	can be listed in additional members. For example:		can be listed in additional members. For example:
	Variants: Accept-Encoding=(gzip br), Accept-Language=(en fr)		Variants: accept-encoding=(gzip br), accept-language=(en fr)
	Variant-Key: (gzip fr), ("identity" fr)		Variant-Key: (gzip fr), ("identity" fr)
	indicates that this response can be used for requests whose Accept-		indicates that this response can be used for requests whose Accept-
	Encoding algorithm selects "gzip" or "identity", as long as the		Encoding algorithm selects "gzip" or "identity", as long as the
	Accept-Language algorithm selects "fr" - perhaps because there is no		Accept-Language algorithm selects "fr" - perhaps because there is no
	gzip-compressed French representation.		gzip-compressed French representation.
	When more than one Variant-Key value is in a response, the first one		When more than one Variant-Key value is in a response, the first one
	present MUST correspond to the request that caused that response to		present MUST correspond to the request that caused that response to
	be generated. For example:		be generated. For example:
	Variants: Accept-Encoding=(gzip br), Accept-Language=(en fr)		Variants: accept-encoding=(gzip br), accept-language=(en fr)
	Variant-Key: (gzip fr), (identity fr), (br fr oops)		Variant-Key: (gzip fr), (identity fr), (br fr oops)
	is treated as if the Variant-Key header were completely absent, which		is treated as if the Variant-Key header were completely absent, which
	will tend to disable caching for the representation that contains it.		will tend to disable caching for the representation that contains it.
	Note that in		Note that in
	Variant-Key: (gzip fr)		Variant-Key: (gzip fr)
	Variant-Key: ("gzip " fr)		Variant-Key: ("gzip " fr)
	skipping to change at page 16, line 24 ¶		skipping to change at page 16, line 24 ¶
	[RFC7234], Section 4.1 - but considering only Accept-Language to be		[RFC7234], Section 4.1 - but considering only Accept-Language to be
	in its field-value - and then continue processing Variants for the		in its field-value - and then continue processing Variants for the
	set of stored responses that the algorithm described there selects.		set of stored responses that the algorithm described there selects.
	6. Defining Content Negotiation Using Variants		6. Defining Content Negotiation Using Variants
	To be usable with Variants, proactive content negotiation mechanisms		To be usable with Variants, proactive content negotiation mechanisms
	need to be specified to take advantage of it. Specifically, they:		need to be specified to take advantage of it. Specifically, they:
	o MUST define a request header field that advertises the clients		o MUST define a request header field that advertises the clients
	preferences or capabilities, whose field-name SHOULD begin with		preferences or capabilities. Often, its field-name will begin
	"Accept-".		with "Accept-", but this is not required.
	o MUST define the syntax of an available-value that will occur in		o MUST define the syntax of an available-value that will occur in
	Variants and Variant-Key.		Variants and Variant-Key.
	o MUST define an algorithm for selecting a result. It MUST return a		o MUST define an algorithm for selecting a result. It MUST return a
	list of available-values that are suitable for the request, in		list of available-values that are suitable for the request, in
	order of preference, given the value of the request header		order of preference, given the value of the request header
	nominated above (or null if the request header is absent) and an		nominated above (or null if the request header is absent) and an
	available-values list from the Variants header. If the result is		available-values list from the Variants header. If the result is
	an empty list, it implies that the cache cannot satisfy the		an empty list, it implies that the cache cannot satisfy the
	skipping to change at page 17, line 40 ¶		skipping to change at page 17, line 40 ¶
	Note that the Variants header is not a commitment to make		Note that the Variants header is not a commitment to make
	representations of a certain nature available; the runtime behaviour		representations of a certain nature available; the runtime behaviour
	of the server always overrides hints like Variants.		of the server always overrides hints like Variants.
	9. References		9. References
	9.1. Normative References		9.1. Normative References
	[I-D.ietf-httpbis-header-structure]		[I-D.ietf-httpbis-header-structure]
	Nottingham, M. and P. Kamp, "Structured Headers for HTTP",		Nottingham, M. and P. Kamp, "Structured Field Values for
	draft-ietf-httpbis-header-structure-13 (work in progress),		HTTP", draft-ietf-httpbis-header-structure-19 (work in
	August 2019.		progress), June 2020.
	[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>.
	[RFC4647] Phillips, A. and M. Davis, "Matching of Language Tags",		[RFC4647] Phillips, A. and M. Davis, "Matching of Language Tags",
	BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 2006,		BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 2006,
	<https://www.rfc-editor.org/info/rfc4647>.		<https://www.rfc-editor.org/info/rfc4647>.
	skipping to change at page 18, line 36 ¶		skipping to change at page 18, line 36 ¶
	RFC 7234, DOI 10.17487/RFC7234, June 2014,		RFC 7234, DOI 10.17487/RFC7234, June 2014,
	<https://www.rfc-editor.org/info/rfc7234>.		<https://www.rfc-editor.org/info/rfc7234>.
	[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC		[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
	2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,		2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
	May 2017, <https://www.rfc-editor.org/info/rfc8174>.		May 2017, <https://www.rfc-editor.org/info/rfc8174>.
	9.2. Informative References		9.2. Informative References
	[I-D.ietf-httpbis-client-hints]		[I-D.ietf-httpbis-client-hints]
	Grigorik, I., "HTTP Client Hints", draft-ietf-httpbis-		Grigorik, I. and Y. Weiss, "HTTP Client Hints", draft-
	client-hints-07 (work in progress), March 2019.		ietf-httpbis-client-hints-15 (work in progress), July
			2020.
	[RFC2295] Holtman, K. and A. Mutz, "Transparent Content Negotiation		[RFC2295] Holtman, K. and A. Mutz, "Transparent Content Negotiation
	in HTTP", RFC 2295, DOI 10.17487/RFC2295, March 1998,		in HTTP", RFC 2295, DOI 10.17487/RFC2295, March 1998,
	<https://www.rfc-editor.org/info/rfc2295>.		<https://www.rfc-editor.org/info/rfc2295>.
	[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration		[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
	Procedures for Message Header Fields", BCP 90, RFC 3864,		Procedures for Message Header Fields", BCP 90, RFC 3864,
	DOI 10.17487/RFC3864, September 2004,		DOI 10.17487/RFC3864, September 2004,
	<https://www.rfc-editor.org/info/rfc3864>.		<https://www.rfc-editor.org/info/rfc3864>.
	skipping to change at page 23, line 9 ¶		skipping to change at page 23, line 25 ¶
	It is also a generalisation of a Fastly VCL feature designed by		It is also a generalisation of a Fastly VCL feature designed by
	Rogier 'DocWilco' Mulhuijzen.		Rogier 'DocWilco' Mulhuijzen.
	Thanks to Hooman Beheshti, Ilya Grigorik, Leif Hedstrom, and Jeffrey		Thanks to Hooman Beheshti, Ilya Grigorik, Leif Hedstrom, and Jeffrey
	Yasskin for their review and input.		Yasskin for their review and input.
	Author's Address		Author's Address
	Mark Nottingham		Mark Nottingham
	Fastly		Fastly
			made in
			Prahran, VIC
			Australia
	Email: mnot@mnot.net		Email: mnot@mnot.net
	URI: https://www.mnot.net/		URI: https://www.mnot.net/
End of changes. 20 change blocks.
	26 lines changed or deleted		30 lines changed or added
This html diff was produced by rfcdiff 1.44jr. The latest version is available from http://tools.ietf.org/tools/rfcdiff/