draft-ietf-httpbis-variants-00.txt   draft-ietf-httpbis-variants-01.txt 
HTTP M. Nottingham HTTP M. Nottingham
Internet-Draft Fastly Internet-Draft Fastly
Updates: 7234 (if approved) April 1, 2018 Updates: 7234 (if approved) May 1, 2018
Intended status: Standards Track Intended status: Standards Track
Expires: October 3, 2018 Expires: November 2, 2018
HTTP Representation Variants HTTP Representation Variants
draft-ietf-httpbis-variants-00 draft-ietf-httpbis-variants-01
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 October 3, 2018. This Internet-Draft will expire on November 2, 2018.
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 27 skipping to change at page 2, line 27
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
2. The "Variants" HTTP Header Field . . . . . . . . . . . . . . 5 2. The "Variants" HTTP Header Field . . . . . . . . . . . . . . 5
2.1. Relationship to Vary . . . . . . . . . . . . . . . . . . 6 2.1. Relationship to Vary . . . . . . . . . . . . . . . . . . 6
3. The "Variant-Key" HTTP Header Field . . . . . . . . . . . . . 6 3. The "Variant-Key" HTTP Header Field . . . . . . . . . . . . . 6
3.1. Generating a Normalised Variant-Key . . . . . . . . . . . 7 3.1. Generating a Variant-Key List . . . . . . . . . . . . . . 7
4. Cache Behaviour . . . . . . . . . . . . . . . . . . . . . . . 8 4. Cache Behaviour . . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Find Available Keys . . . . . . . . . . . . . . . . . . . 9 4.1. Compute Possible Keys . . . . . . . . . . . . . . . . . . 9
4.2. Check Vary . . . . . . . . . . . . . . . . . . . . . . . 10 4.2. Check Vary . . . . . . . . . . . . . . . . . . . . . . . 10
4.3. Example of Cache Behaviour . . . . . . . . . . . . . . . 10 4.3. Example of Cache Behaviour . . . . . . . . . . . . . . . 11
5. Origin Server Behaviour . . . . . . . . . . . . . . . . . . . 11 5. Origin Server Behaviour . . . . . . . . . . . . . . . . . . . 11
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 . . . . . . . . . . . . . . . . . . 13 5.1.3. Partial Coverage . . . . . . . . . . . . . . . . . . 13
6. Defining Content Negotiation Using Variants . . . . . . . . . 14 6. Defining Content Negotiation Using Variants . . . . . . . . . 14
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
8. Security Considerations . . . . . . . . . . . . . . . . . . . 15 8. Security Considerations . . . . . . . . . . . . . . . . . . . 15
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15
10.1. Normative References . . . . . . . . . . . . . . . . . . 15 10.1. Normative References . . . . . . . . . . . . . . . . . . 16
10.2. Informative References . . . . . . . . . . . . . . . . . 16 10.2. Informative References . . . . . . . . . . . . . . . . . 16
10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 16 10.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 . . . . . . . . . . . . . . . . . . . . . 17 A.2. Accept-Encoding . . . . . . . . . . . . . . . . . . . . . 18
A.3. Accept-Language . . . . . . . . . . . . . . . . . . . . . 18 A.3. Accept-Language . . . . . . . . . . . . . . . . . . . . . 18
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19
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
Content-Language and for newer ones (for example, see Content-Language and for newer ones (for example, see
[I-D.ietf-httpbis-client-hints]). [I-D.ietf-httpbis-client-hints]).
skipping to change at page 3, line 32 skipping to change at page 3, line 32
Even when the headers' semantics are understood, a cache does not Even when the headers' semantics are understood, a cache does not
know enough about the possible alternative representations available know enough about the possible alternative representations available
on the origin server to make an appropriate decision. on the origin server to make an appropriate decision.
For example, if a cache has stored the following request/response For example, if a cache has stored the following request/response
pair: pair:
GET /foo HTTP/1.1 GET /foo HTTP/1.1
Host: www.example.com Host: www.example.com
Accept-Language: en;q=1.0, fr;q=0.5 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: fr Content-Language: fr
Vary: Accept-Language Vary: Accept-Language
Transfer-Encoding: chunked Transfer-Encoding: chunked
[French content] [French content]
Provided that the cache has full knowledge of the semantics of Provided that the cache has full knowledge of the semantics of
skipping to change at page 4, line 7 skipping to change at page 4, line 7
example) whether a Japanese representation is available without example) whether a Japanese representation is available without
making another request, incurring possibly unnecessary latency. making another 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
origin server, to provide clients and caches with enough information origin server, to provide clients and caches with enough information
to properly satisfy requests - either by selecting a response from to properly satisfy requests - either by selecting a response from
cache or by forwarding the request towards the origin - by following cache or by forwarding the request towards the origin - by following
the algorithm defined in Section 4. the algorithm defined in Section 4.
Its companion the Variant-Key response header field (Section 3) Its companion Variant-Key response header field (Section 3) indicates
indicates which representation was selected, so that it can be the applicable key(s) that the response is associated with, so that
reliably reused in the future. When this specification is in use, it can be reliably reused in the future. When this specification is
the example above might become: 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=1.0, fr;q=0.5 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: fr Content-Language: fr
Vary: Accept-Language Vary: Accept-Language
Variants: Accept-Language;fr;de;en;jp Variants: Accept-Language;fr;de;en;jp
Variant-Key: fr Variant-Key: fr
Transfer-Encoding: chunked Transfer-Encoding: chunked
[French content] [French content]
skipping to change at page 6, line 51 skipping to change at page 6, line 51
In practice, implementation of Vary varies considerably. As a In practice, implementation of Vary varies considerably. As a
result, cache efficiency might drop considerably when Variants does result, cache efficiency might drop considerably when Variants does
not contain all of the headers referenced by Vary, because some not contain all of the headers referenced by Vary, because some
implementations might choose to disable Variants processing when this implementations might choose to disable Variants processing when this
is the case. is the case.
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
value(s) 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-value Variant-Key = available-values
available-values = available-value *( ";" available-value )
Each value indicates the selected available-value, in the same order Each member of the list contains the selected available-value(s), in
as the variants listed in the Variants header field. the same order as the variants listed in the Variants header field.
Therefore, Variant-Key MUST be the same length (in comma-separated Therefore, Variant-Key MUST be the same length (in comma-separated
members) as Variants, and each member MUST correspond in position to members) as Variants, and each member MUST correspond in position to
its companion in Variants. its companion in Variants.
For example: For example:
Variants: Content-Encoding;gzip;br, Content-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.
Note that Variant-Key is only used to indicate what request A more complex example involves listing multiple available-values in
attributes are associated with the response containing it; this is a list member, to indicate that the response can be used to satisfy
different from headers like Content-Encoding, which indicate requests with any of those values. For example:
attributes of the response itself. In the example above, it might be
that a gzip'd version of the French content is not available, in
which case the response will include:
Variant-Key: gzip, fr Variants: Content-Encoding;gzip;br, Content-Language;en ;fr
Variant-Key: gzip;identity, fr
even though Content-Encoding does not contain "gzip". indicates that this response can be used for requests whose Content-
Encoding algorithm selects "gzip" or "identity", as long as the
Content-Language algorithm selects "fr" - perhaps because there is no
gzip-compressed French representation.
3.1. Generating a Normalised Variant-Key This highlights an important aspect of Variant-Key; it is only used
to indicate what request attributes are associated with the response
containing it; this is different from headers like Content-Encoding,
which indicate attributes of the response itself.
This algorithm generates a normalised string for Variant-Key, 3.1. Generating a Variant-Key List
suitable for comparison with values generated by Section 4.
This algorithm generates a list of normalised strings from Variant-
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 variant-key for that message can be generated by: normalised list of variant-keys for that message can be generated by:
1. Let variant-key-header be a string, the result of selecting all 1. Let variant-keys be an empty list.
2. Let variant-key-header be a string, the result of selecting all
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 (",").
2. Remove all whitespace from variant-key-header. 3. Let value-list be the result of splitting variant-key-header on
commas (",").
3. Return variant-key-header. 4. For each value in value-list:
1. Remove all whitespace from value.
2. Let items be the result of splitting value on ";".
3. append items to variant-keys.
5. Return the result of running Compute Possible Keys (Section 4.1)
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 9, line 11 skipping to change at page 9, line 27
mechanism with request-value and available-values. mechanism with request-value and available-values.
4. Append sorted-values to sorted-variants. 4. Append sorted-values to sorted-variants.
At this point, sorted-variants will be a list of lists, each At this point, sorted-variants will be a list of lists, each
member of the top-level list corresponding to a variant-item member of the top-level list corresponding to a variant-item
in the Variants header field-value, containing zero or more in the Variants header field-value, containing zero or more
items indicating available-values that are acceptable to the items indicating available-values that are acceptable to the
client, in order of preference, greatest to least. client, in order of preference, greatest to least.
5. Return result of running Find Available Keys (Section 4.1) on 5. Return result of running Compute Possible Keys (Section 4.1) on
sorted-variants, an empty string and an empty list. sorted-variants, an empty string and an empty list.
This returns a list of strings suitable for comparing to normalised This returns a list of strings suitable for comparing to normalised
Variant-Keys (Section 3.1) that represent possible responses on the Variant-Keys (Section 3.1) that represent possible responses on the
server that can be used to satisfy the request, in preference order, server that can be used to satisfy the request, in preference order,
provided that their secondary cache key (after removing the headers provided that their secondary cache key (after removing the headers
covered by Variants) matches. Section 4.2 illustrates one way to do covered by Variants) matches. Section 4.2 illustrates one way to do
this. this.
4.1. Find Available Keys 4.1. Compute Possible Keys
Given sorted-variants, a list of lists, and key-stub, a string Given key-facets, a list of lists, and key-stub, a string
representing a partial key, and possible-keys, a list: representing a partial key, and possible-keys, a list:
1. Let sorted-values be the first member of sorted-variants. 1. Let values be the first member of key-facets.
2. For each sorted-value in sorted-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
sorted-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 comma (",") to this-key.
3. Append sorted-value to this-key. 3. Append value to this-key.
3. Let remaining-variants be a copy of all of the members of 3. Let remaining-facets be a copy of all of the members of key-
sorted-variants except the first. facets except the first.
4. If remaining-variants is empty, append this-key to possible- 4. If remaining-facets is empty, append this-key to possible-
keys. keys.
5. Otherwise, run Find Available Keys on remaining-variants, 5. Otherwise, run Find Available Keys on remaining-facets, this-
this-key and possible-keys. key and possible-keys.
3. Return possible-keys. 3. Return possible-keys.
4.2. Check Vary 4.2. Check Vary
This algorithm is an example of how an implementation can meet the This algorithm is an example of how an implementation can meet the
requirement to apply the members of the Vary header field that are requirement to apply the members of the Vary header field that are
not covered by Variants. not covered by Variants.
Given a stored response, stored-response: Given a stored response, stored-response:
skipping to change at page 12, line 23 skipping to change at page 12, line 36
Given a request/response pair: Given a request/response pair:
GET /clancy HTTP/1.1 GET /clancy HTTP/1.1
Host: www.example.com Host: www.example.com
Accept-Language: en;q=1.0, fr;q=0.5 Accept-Language: en;q=1.0, fr;q=0.5
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: image/gif Content-Type: image/gif
Content-Language: en Content-Language: en
Cache-Control: max-age=3600 Cache-Control: max-age=3600
Variants: Content-Language;en;de Variants: Accept-Language;en;de
Variant-Key: en Variant-Key: en
Vary: Accept-Language Vary: Accept-Language
Transfer-Encoding: chunked Transfer-Encoding: chunked
Upon receipt of this response, the cache knows that two Upon receipt of this response, the cache knows that two
representations of this resource are available, one with a Content- representations of this resource are available, one with a Content-
Language of "en", and another whose Content-Language is "de". Language of "en", and another whose Content-Language is "de".
Subsequent requests (while this response is fresh) will cause the Subsequent requests (while this response is fresh) will cause the
cache to either reuse this response or forward the request, depending cache to either reuse this response or forward the request, depending
skipping to change at page 13, line 18 skipping to change at page 13, line 29
GET /murray HTTP/1.1 GET /murray HTTP/1.1
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: Content-Language;en;jp;de Variants: Accept-Language;en;jp;de
Variants: Content-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; Content-Language and Content-Encoding. Thus, there are varies upon; Content-Language and Content-Encoding. Thus, there are
a total of nine possible representations for the resource (including a total of nine possible representations for the resource (including
the identity encoding), and the cache needs to consider the selection the identity encoding), and the cache needs to consider the selection
algorithms for both axes. algorithms for both axes.
Upon a subsequent request, if both selection algorithms return a Upon a subsequent request, if both selection algorithms return a
stored representation, it can be served from cache; otherwise, the stored representation, it can be served from cache; otherwise, the
request will need to be forwarded to origin. request will need to be forwarded to origin.
5.1.3. Partial Coverage 5.1.3. Partial Coverage
Now, consider the previous example, but where only one of the Vary'd Now, consider the previous example, but where only one of the Vary'd
axes is listed in Variants: axes (Content-Encoding) is listed in Variants:
GET /bar HTTP/1.1 GET /bar HTTP/1.1
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: Content-Encoding;br;gzip Variants: Accept-Encoding;br;gzip
Variant-Key: br Variant-Key: br
Vary: Accept-Language, Accept-Encoding Vary: Accept-Language, Accept-Encoding
Transfer-Encoding: chunked Transfer-Encoding: chunked
Here, the cache will need to calculate a secondary cache key as per Here, the cache will need to calculate a secondary cache key as per
[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:
 End of changes. 41 change blocks. 
53 lines changed or deleted 73 lines changed or added

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