draft-ietf-httpbis-variants-03.txt   draft-ietf-httpbis-variants-04.txt 
HTTP M. Nottingham HTTP M. Nottingham
Internet-Draft Fastly Internet-Draft Fastly
Updates: 7234 (if approved) July 1, 2018 Updates: 7234 (if approved) October 22, 2018
Intended status: Standards Track Intended status: Standards Track
Expires: January 2, 2019 Expires: April 25, 2019
HTTP Representation Variants HTTP Representation Variants
draft-ietf-httpbis-variants-03 draft-ietf-httpbis-variants-04
Abstract Abstract
This specification introduces an alternative way to communicate a This specification introduces an alternative way to communicate a
secondary cache key for a HTTP resource, using the HTTP "Variants" secondary cache key for a HTTP resource, using the HTTP "Variants"
and "Variant-Key" response header fields. Its aim is to make HTTP and "Variant-Key" response header fields. Its aim is to make HTTP
proactive content negotiation more cache-friendly. 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 January 2, 2019. This Internet-Draft will expire on April 25, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 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 40 skipping to change at page 2, line 40
4.2. Check Vary . . . . . . . . . . . . . . . . . . . . . . . 10 4.2. Check Vary . . . . . . . . . . . . . . . . . . . . . . . 10
4.3. Example of Cache Behaviour . . . . . . . . . . . . . . . 11 4.3. Example of Cache Behaviour . . . . . . . . . . . . . . . 11
5. Origin Server Behaviour . . . . . . . . . . . . . . . . . . . 12 5. Origin Server Behaviour . . . . . . . . . . . . . . . . . . . 12
5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 12 5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 12
5.1.1. Single Variant . . . . . . . . . . . . . . . . . . . 12 5.1.1. Single Variant . . . . . . . . . . . . . . . . . . . 12
5.1.2. Multiple Variants . . . . . . . . . . . . . . . . . . 13 5.1.2. Multiple Variants . . . . . . . . . . . . . . . . . . 13
5.1.3. Partial Coverage . . . . . . . . . . . . . . . . . . 14 5.1.3. Partial Coverage . . . . . . . . . . . . . . . . . . 14
6. Defining Content Negotiation Using Variants . . . . . . . . . 14 6. Defining Content Negotiation Using Variants . . . . . . . . . 14
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
8. Security Considerations . . . . . . . . . . . . . . . . . . . 15 8. Security Considerations . . . . . . . . . . . . . . . . . . . 15
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
9.1. Normative References . . . . . . . . . . . . . . . . . . 16 9.1. Normative References . . . . . . . . . . . . . . . . . . 16
9.2. Informative References . . . . . . . . . . . . . . . . . 16 9.2. Informative References . . . . . . . . . . . . . . . . . 16
9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 17 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Appendix A. Variants for Existing Content Negotiation Mechanisms 17 Appendix A. Variants for Existing Content Negotiation Mechanisms 17
A.1. Accept . . . . . . . . . . . . . . . . . . . . . . . . . 17 A.1. Accept . . . . . . . . . . . . . . . . . . . . . . . . . 17
A.2. Accept-Encoding . . . . . . . . . . . . . . . . . . . . . 18 A.2. Accept-Encoding . . . . . . . . . . . . . . . . . . . . . 18
A.3. Accept-Language . . . . . . . . . . . . . . . . . . . . . 19 A.3. Accept-Language . . . . . . . . . . . . . . . . . . . . . 19
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 19 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 19
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20
skipping to change at page 3, line 40 skipping to change at page 3, line 40
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
Transfer-Encoding: chunked Transfer-Encoding: chunked
[French content] [English content]
Provided that the cache has full knowledge of the semantics of Provided that the cache has full knowledge of the semantics of
Accept-Language and Content-Language, it will know that an English Accept-Language and Content-Language, it will know that an English
representation is available and might be able to infer that a French representation is available and might be able to infer that a French
representation is not available. But, it does not know (for example) representation is not available. But, it does not know (for example)
whether a Japanese representation is available without making another whether a Japanese representation is available without making another
request, incurring possibly unnecessary latency. request, incurring possibly unnecessary latency.
This specification introduces the HTTP Variants response header field This specification introduces the HTTP Variants response header field
(Section 2) to enumerate the available variant representations on the (Section 2) to enumerate the available variant representations on the
skipping to change at page 4, line 25 skipping to change at page 4, line 25
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
[French 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.
Variants also works best when content negotiation takes place over a Variants also works best when content negotiation takes place over a
constrained set of representations; since each variant needs to be constrained set of representations; since each variant needs to be
listed in the header field, it is ill-suited for open-ended sets of listed in the header field, it is ill-suited for open-ended sets of
representations. representations.
skipping to change at page 7, line 14 skipping to change at page 7, line 14
3. The "Variant-Key" HTTP Header Field 3. The "Variant-Key" HTTP Header Field
The Variant-Key HTTP response header field is used to indicate the The Variant-Key HTTP response header field is used to indicate the
values from the Variants header field that identify the values from the Variants header field that identify the
representation it occurs within. representation it occurs within.
Variant-Key = 1#available-values Variant-Key = 1#available-values
available-values = available-value *( ";" available-value ) available-values = available-value *( ";" available-value )
Each member of the list contains the selected available-value(s), in Each member of the list contains a set of selected available-value(s)
the same order as the variants listed in the Variants header field. that identify this representation, in the same order as the variants
listed in the Variants header field.
Therefore, Variant-Key MUST be the same length (in comma-separated Therefore, each member of Variant-Key MUST be the same length (in
members) as Variants, and each member MUST correspond in position to semicolon-separated members) as Variants, and each member's
its companion in Variants. available-values MUST correspond in position to their companions in
Variants.
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.
A more complex example involves listing multiple available-values in If the response can be used to satisfy more than one request), they
a list member, to indicate that the response can be used to satisfy can be listed in additional members. For example:
requests with any of those values. For example:
Variants: Accept-Encoding;gzip;br, Accept-Language;en ;fr Variants: Accept-Encoding;gzip;br, Accept-Language;en ;fr
Variant-Key: gzip;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.
This highlights an important aspect of Variant-Key; it is only used When more than one Variant-Key value is in a response, the first one
to indicate what request attributes are associated with the response present MUST indicate the variant-key for the response it occurs
containing it; this is different from headers like Content-Encoding, within.
which indicate attributes of the response itself.
3.1. Generating a Variant-Key List 3.1. Generating a Variant-Key List
This algorithm generates a list of normalised strings from Variant- This algorithm generates a list of normalised strings from Variant-
Key, suitable for comparison with values generated by Section 4. Key, suitable for comparison with values generated by Section 4.
Given stored-headers (a set of headers from a stored response), a Given stored-headers (a set of headers from a stored response), a
normalised list of variant-keys for that message can be generated by normalised list of variant-keys for that message can be generated by
following this algorithm: following this algorithm:
skipping to change at page 8, line 22 skipping to change at page 8, line 22
field-values of stored-headers whose field-name is "Variant-Key" field-values of stored-headers whose field-name is "Variant-Key"
and joining them with a comma (","). and joining them with a comma (",").
3. Let value-list be the result of splitting variant-key-header on 3. Let value-list be the result of splitting variant-key-header on
commas (","). commas (",").
4. For each value in value-list: 4. For each value in value-list:
1. Remove all whitespace from value. 1. Remove all whitespace from value.
2. Let items be the result of splitting value on ";". 2. Append value to variant-keys.
3. append items to variant-keys.
5. Return the result of running Compute Possible Keys (Section 4.1) 5. Return variant-keys.
on variant-keys, an empty string and an empty list.
4. Cache Behaviour 4. Cache Behaviour
Caches that implement the Variants header field and the relevant Caches that implement the Variants header field and the relevant
semantics of the field-name it contains can use that knowledge to semantics of the field-name it contains can use that knowledge to
either select an appropriate stored representation, or forward the either select an appropriate stored representation, or forward the
request if no appropriate representation is stored. request if no appropriate representation is stored.
They do so by running this algorithm (or its functional equivalent) They do so by running this algorithm (or its functional equivalent)
upon receiving a request: upon receiving a request:
skipping to change at page 10, line 16 skipping to change at page 10, line 14
2. For each value in values: 2. For each value in values:
1. If key-stub is an empty string, let this-key be a copy of 1. If key-stub is an empty string, let this-key be a copy of
value. value.
2. Otherwise: 2. Otherwise:
1. Let this-key be a copy of key-stub. 1. Let this-key be a copy of key-stub.
2. Append a comma (",") to this-key. 2. Append a semicolon (";") to this-key.
3. Append value to this-key. 3. Append value to this-key.
3. Let remaining-facets be a copy of all of the members of key- 3. Let remaining-facets be a copy of all of the members of key-
facets except the first. facets except the first.
4. If remaining-facets is empty, append this-key to possible- 4. If remaining-facets is empty, append this-key to possible-
keys. keys.
5. Otherwise, run Compute Possible Keys on remaining-facets, 5. Otherwise, run Compute Possible Keys on remaining-facets,
skipping to change at page 11, line 19 skipping to change at page 11, line 17
Note that implementation of the Vary header field varies in practice, Note that implementation of the Vary header field varies in practice,
and the algorithm above illustrates only one way to apply it. It is and the algorithm above illustrates only one way to apply it. It is
equally viable to forward the request if there is a request header equally viable to forward the request if there is a request header
listed in Vary but not Variants. listed in Vary but not Variants.
4.3. Example of Cache Behaviour 4.3. Example of Cache Behaviour
For example, if the selected variants-header was: For example, if the selected variants-header was:
Variants: Accept-Language;en;fr,de, Accept-Encoding;gzip;br Variants: Accept-Language;en;fr;de, Accept-Encoding;gzip;br
and the request contained the headers: and the request contained the headers:
Accept-Language: fr;q=1.0, en;q=0.1 Accept-Language: fr;q=1.0, en;q=0.1
Accept-Encoding: gzip Accept-Encoding: gzip
Then the sorted-variants would be: Then the sorted-variants would be:
[ [
["fr", "en"] // prefers French, will accept English ["fr", "en"] // prefers French, will accept English
skipping to change at page 13, line 42 skipping to change at page 13, line 42
Host: www.example.net Host: www.example.net
Accept-Language: en;q=1.0, fr;q=0.5 Accept-Language: en;q=1.0, fr;q=0.5
Accept-Encoding: gzip, br Accept-Encoding: gzip, br
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: image/gif Content-Type: image/gif
Content-Language: en Content-Language: en
Content-Encoding: br Content-Encoding: br
Variants: Accept-Language;en;jp;de Variants: Accept-Language;en;jp;de
Variants: Accept-Encoding;br;gzip Variants: Accept-Encoding;br;gzip
Variant-Key: en, br Variant-Key: en;br
Vary: Accept-Language, Accept-Encoding Vary: Accept-Language, Accept-Encoding
Transfer-Encoding: chunked Transfer-Encoding: chunked
Here, the cache knows that there are two axes that the response Here, the cache knows that there are two axes that the response
varies upon; language and encoding. Thus, there are a total of nine varies upon; language and encoding. Thus, there are a total of nine
possible representations for the resource (including the identity possible representations for the resource (including the identity
encoding), and the cache needs to consider the selection algorithms encoding), and the cache needs to consider the selection algorithms
for both axes. for both axes.
Upon a subsequent request, if both selection algorithms return a Upon a subsequent request, if both selection algorithms return a
skipping to change at page 15, line 10 skipping to change at page 15, line 10
order of preference, given the value of the request header order of preference, given the value of the request header
nominated above and an available-values list from the Variants nominated above and an available-values list from the Variants
header. If the result is an empty list, it implies that the cache header. If the result is an empty list, it implies that the cache
cannot satisfy the request. cannot satisfy the request.
Appendix A fulfils these requirements for some existing proactive Appendix A fulfils these requirements for some existing proactive
content negotiation mechanisms in HTTP. content negotiation mechanisms in HTTP.
7. IANA Considerations 7. IANA Considerations
This specification registers two values in the Permanent Message This specification registers the following entry in the Permanent
Header Field Names registry established by [RFC3864]: Message Header Field Names registry established by [RFC3864]:
o Header field name: Variants o Header field name: Variants
o Applicable protocol: http o Applicable protocol: http
o Status: standard o Status: standard
o Author/Change Controller: IETF o Author/Change Controller: IETF
o Specification document(s): [this document] o Specification document(s): [this document]
o Related information: o Related information:
This specification registers the following entry in the Permanent
Message Header Field Names registry established by [RFC3864]:
o Header field name: Variant-Key o Header field name: Variant-Key
o Applicable protocol: http o Applicable protocol: http
o Status: standard o Status: standard
o Author/Change Controller: IETF o Author/Change Controller: IETF
o Specification document(s): [this document] o Specification document(s): [this document]
skipping to change at page 16, line 43 skipping to change at page 16, line 46
<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., "HTTP Client Hints", draft-ietf-httpbis-
client-hints-05 (work in progress), January 2018. client-hints-06 (work in progress), July 2018.
[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 20, line 5 skipping to change at page 20, line 5
Acknowledgements Acknowledgements
This protocol is conceptually similar to, but simpler than, This protocol is conceptually similar to, but simpler than,
Transparent Content Negotiation [RFC2295]. Thanks to its authors for Transparent Content Negotiation [RFC2295]. Thanks to its authors for
their inspiration. their inspiration.
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 and Jeffrey Yasskin for Thanks to Hooman Beheshti, Ilya Grigorik, Leif Hedstrom, and Jeffrey
their review and input. Yasskin for their review and input.
Author's Address Author's Address
Mark Nottingham Mark Nottingham
Fastly Fastly
Email: mnot@mnot.net Email: mnot@mnot.net
URI: https://www.mnot.net/ URI: https://www.mnot.net/
 End of changes. 22 change blocks. 
34 lines changed or deleted 34 lines changed or added

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