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) April 22, 2021 | |||
Intended status: Standards Track | Intended status: Standards Track | |||
Expires: May 5, 2020 | Expires: October 24, 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 October 24, 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/ |