diff --git a/draft-ietf-httpbis-bcp56bis.md b/draft-ietf-httpbis-bcp56bis.md index 28847ee5a..c7c0daf1e 100644 --- a/draft-ietf-httpbis-bcp56bis.md +++ b/draft-ietf-httpbis-bcp56bis.md @@ -103,6 +103,7 @@ It is written primarily to guide IETF efforts to define application protocols us deployment on the Internet, but might be applicable in other situations. Note that the requirements herein do not necessarily apply to the development of generic HTTP extensions. + ## Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", @@ -232,7 +233,6 @@ specific features to be used, since the appropriate design tradeoffs are highly situation. However, following the practices in {{bp}} will help make them available. - # Best Practices for Using HTTP {#bp} This section contains best practices regarding the use of HTTP by applications, including practices @@ -305,6 +305,7 @@ For example, an application might specify: related information in the link indicated by the Link header field value with the "example-other-info" link relation type. + ## Specifying Client Behaviours {#clients} HTTP does not mandate some behaviours that have nevertheless become very common; if these are not @@ -385,11 +386,9 @@ caveats to keep in mind: * Web features that require a secure context {{?SECCTXT=W3C.CR-secure-contexts-20160915}} will likely treat a new scheme as insecure. - See {{?RFC7595}} for more information about minting new URL schemes. - ### Transport Ports Applications that use HTTP can use the applicable default port (80 for HTTP, 443 for HTTPS), or @@ -456,7 +455,6 @@ to allow parsers to be generic; as per {{!RFC7231}}, Section 4.3.1, a body on a and will be either ignored or rejected by generic HTTP software. - ## HTTP Status Codes Applications that use HTTP MUST only use registered HTTP status codes. @@ -528,7 +526,8 @@ cannot specify that the `Location` header has a special meaning in a certain con See {{caching}} for the interaction between headers and HTTP caching; in particular, request headers that are used to "select" a response have impact there, and need to be carefully considered. -See {{state}} for considerations regarding header fields that carry application state (e.g., Cookie). +See {{state}} for considerations regarding header fields that carry application state (e.g., +Cookie). ## Defining Message Payloads {#payload} @@ -640,7 +639,6 @@ exploits are possible. Mitigations include using a request-specific token to ass the client. - ## Co-Existing with Web Browsing {#browser} Even if there is not an intent for an application that uses HTTP to be used with a Web browser, its @@ -725,6 +723,7 @@ cross-origin data to browsers will need to implement the CORS protocol; see {{FE This document has no requirements for IANA. + # Security Considerations {{state}} discusses the impact of using stateful mechanisms in the protocol as ambient authority, diff --git a/draft-ietf-httpbis-variants.md b/draft-ietf-httpbis-variants.md index 7d09f9280..35a75aaf3 100644 --- a/draft-ietf-httpbis-variants.md +++ b/draft-ietf-httpbis-variants.md @@ -79,7 +79,7 @@ Provided that the cache has full knowledge of the semantics of Accept-Language a This specification introduces the HTTP Variants response header field ({{variants}}) to enumerate the available variant representations on the origin server, to provide clients and caches with enough information to properly satisfy requests -- either by selecting a response from cache or by forwarding the request towards the origin -- by following the algorithm defined in {{cache}}. -Its companion the Variant-Key response header field ({{variant-key}}) indicates which representation was selected, so that it can be reliably reused in the future. When this specification is in use, the example above might become: +Its companion Variant-Key response header field ({{variant-key}}) indicates the applicable key(s) that the response is associated with, so that it can be reliably reused in the future. When this specification is in use, the example above might become: ~~~ GET /foo HTTP/1.1 @@ -179,13 +179,14 @@ In practice, implementation of Vary varies considerably. As a result, cache effi # The "Variant-Key" HTTP Header Field {#variant-key} -The Variant-Key HTTP response header field is used to indicate the value(s) from the Variants header field that identify the representation it occurs within. +The Variant-Key HTTP response header field is used to indicate the values from the Variants header field that identify the 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 as the variants listed in the Variants header field. +Each member of the list contains the selected available-value(s), in the same order as the variants listed in the Variants header field. Therefore, Variant-Key MUST be the same length (in comma-separated members) as Variants, and each member MUST correspond in position to its companion in Variants. @@ -198,24 +199,33 @@ Variant-Key: gzip, fr This header pair indicates that the representation has a "gzip" content-coding and "fr" content-language. -Note that Variant-Key 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. 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: +A more complex example involves listing multiple available-values in a list member, to indicate that the response can be used to satisfy requests with any of those values. For example: ~~~ -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. + +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. -## Generating a Normalised Variant-Key {#gen-variant-key} +## Generating a Variant-Key List {#gen-variant-key} -This algorithm generates a normalised string for Variant-Key, suitable for comparison with values generated by {{cache}}. +This algorithm generates a list of normalised strings from Variant-Key, suitable for comparison with +values generated by {{cache}}. -Given stored-headers, a set of headers from a stored response, a normalised variant-key for that message can be generated by: +Given stored-headers, a set of headers from a stored response, a 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 field-values of stored-headers whose field-name is "Variant-Key" and joining them with a comma (","). -2. Remove all whitespace from variant-key-header. -3. Return variant-key-header. +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" and joining them with a comma (","). +3. Let value-list be the result of splitting variant-key-header on commas (","). +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 ({{find}}) on variant-keys, an empty string and an empty list. # Cache Behaviour {#cache} @@ -240,25 +250,25 @@ Given incoming-request, a mapping of field-names to lists of field values, and s At this point, sorted-variants will be a list of lists, each member of the top-level list corresponding to a variant-item in the Variants header field-value, containing zero or more items indicating available-values that are acceptable to the client, in order of preference, greatest to least. -5. Return result of running Find Available Keys ({{find}}) on sorted-variants, an empty string and an empty list. +5. Return result of running Compute Possible Keys ({{find}}) on sorted-variants, an empty string and an empty list. This returns a list of strings suitable for comparing to normalised Variant-Keys ({{gen-variant-key}}) that represent possible responses on the server that can be used to satisfy the request, in preference order, provided that their secondary cache key (after removing the headers covered by Variants) matches. {{check_vary}} illustrates one way to do this. -## Find Available Keys {#find} +## Compute Possible Keys {#find} -Given sorted-variants, a list of lists, and key-stub, a string representing a partial key, and possible-keys, a list: +Given key-facets, a list of lists, and key-stub, a string representing a partial key, and possible-keys, a list: -1. Let sorted-values be the first member of sorted-variants. -2. For each sorted-value in sorted-values: - 1. If key-stub is an empty string, let this-key be a copy of sorted-value. +1. Let values be the first member of key-facets. +2. For each value in values: + 1. If key-stub is an empty string, let this-key be a copy of value. 1. Otherwise: 1. Let this-key be a copy of key-stub. 2. Append a comma (",") to this-key. - 3. Append sorted-value to this-key. - 3. Let remaining-variants be a copy of all of the members of sorted-variants except the first. - 4. If remaining-variants is empty, append this-key to possible-keys. - 5. Otherwise, run Find Available Keys on remaining-variants, this-key and possible-keys. + 3. Append value to this-key. + 3. Let remaining-facets be a copy of all of the members of key-facets except the first. + 4. If remaining-facets is empty, append this-key to possible-keys. + 5. Otherwise, run Find Available Keys on remaining-facets, this-key and possible-keys. 3. Return possible-keys.