idnits 2.17.1 draft-grigorik-http-client-hints-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 6, 2013) is 3794 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'I-D.nottingham-http-browser-hints' is defined on line 357, but no explicit reference was found in the text == Unused Reference: 'RFC5226' is defined on line 365, but no explicit reference was found in the text == Outdated reference: A later version (-03) exists of draft-fielding-http-key-02 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-25 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-25 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group I. Grigorik 3 Internet-Draft December 6, 2013 4 Intended status: Informational 5 Expires: June 9, 2014 7 HTTP Client Hints 8 draft-grigorik-http-client-hints-01 10 Abstract 12 An increasing diversity of Web-connected device form factors and 13 software capabilities has created a need to deliver varying, or 14 optimized content for each device. 16 HTTP Client Hints can be used as input to proactive content 17 negotiation; just as the Accept header allowed clients to indicate 18 what formats they prefer, Client Hints allow clients to indicate a 19 list of device and agent specific preferences. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on June 9, 2014. 38 Copyright Notice 40 Copyright (c) 2013 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 57 2. Client Hint Request Header Fields . . . . . . . . . . . . . . . 3 58 2.1. Hint Values . . . . . . . . . . . . . . . . . . . . . . . . 4 59 2.2. Sending Client Hints . . . . . . . . . . . . . . . . . . . 4 60 2.3. Server Processing of Client Hints . . . . . . . . . . . . . 5 61 2.3.1. Advertising Support for Client Hints . . . . . . . . . 5 62 2.3.2. Interaction with Caches . . . . . . . . . . . . . . . . 5 63 3. The CH-DPR Client Hint . . . . . . . . . . . . . . . . . . . . 6 64 4. The CH-RW Client Hint . . . . . . . . . . . . . . . . . . . . . 6 65 4.1. Confirming Selected DPR . . . . . . . . . . . . . . . . . . 6 66 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 67 5.1. Relationship to the User-Agent Request Header . . . . . . . 7 68 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 69 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 70 8. Normative References . . . . . . . . . . . . . . . . . . . . . 8 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 1. Introduction 75 There are thousands of different devices accessing the web, each with 76 different device capabilities and preference information. These 77 device capabilities include hardware and software characteristics, as 78 well as dynamic user and client preferences. 80 One way to infer some of these capabilities is through User-Agent 81 (UA) detection against an established database of client signatures. 82 However, this technique requires acquiring such a database, 83 integrating it into the serving path, and keeping it up to date. 84 However, even once this infrastructure is deployed, UA sniffing has 85 numerous limitations: 87 o UA detection cannot reliably identify all static variables 88 o UA detection cannot infer any dynamic client preferences 89 o UA detection requires an external device database 90 o UA detection is not cache friendly 92 A popular alternative strategy is to use HTTP cookies to communicate 93 some information about the client. However, this approach is also 94 not cache friendly, bound by same origin policy, and imposes 95 additional client-side latency by requiring JavaScript execution to 96 create and manage HTTP cookies. 98 This document defines a set of new request header fields that allow 99 the client to perform proactive content negotiation 100 [I-D.ietf-httpbis-p2-semantics] by indicating a list of device and 101 agent specific preferences, through a mechanism similar to the Accept 102 header which is used to indicate preferred response formats. 104 1.1. Notational Conventions 106 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 107 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 108 document are to be interpreted as described in [RFC2119]. 110 This document uses the Augmented Backus-Naur Form (ABNF) notation of 111 [RFC5234] with the list rule extension defined in 112 [I-D.ietf-httpbis-p1-messaging], Appendix B. It includes by 113 reference the OWS, field-name and quoted-string rules from that 114 document, and the parameter rule from 115 [I-D.ietf-httpbis-p2-semantics]. 117 2. Client Hint Request Header Fields 119 A Client Hint request header field is a HTTP header field that is 120 used by HTTP clients to indicate configuration data that can be used 121 by the server to select an appropriate response. Each one conveys a 122 list of client preferences that the server can use to adapt and 123 optimize the response. 125 Client Hint request headers share a common syntax. As a convention, 126 those defined in this specification have names prefixed with "CH-", 127 but this is only a convenience. 129 This document defines a selection of Client Hint request header 130 fields, and can be referenced by other specifications wishing to use 131 the same syntax and processing model. 133 2.1. Hint Values 135 Client-Hint field-values consist of either a token or a comma- 136 delimited list of parameters. 138 client-hint-value = token | 1#parameter 140 When the value is a token, it can either be boolean or a numeric 141 value. Where possible, this form SHOULD be used, so that the hints 142 don't consume too much space in requests. 144 Boolean values are indicated by the presence of the hint field-name 145 in the request headers. If the hint name is absent in the last 146 message containing the client hint header field, it is considered 147 false. 149 Numeric values are indicated by the full field-value contents (single 150 value), or by the digits after "=" of the hint name (parameter 151 value), up to the first non-digit character. If the hint does not 152 have an argument, its value is assumed to be 0. 154 Note that HTTP allows headers with comma-separated values to be 155 conveyed using multiple instances of the same header field; as a 156 result, the hints are collected from all instances of the same header 157 on the message in question before being considered complete. If the 158 same hint is used more than once, then the last hint overrides all 159 previous occurrences, and the final ordering of unique hints is not 160 significant. 162 2.2. Sending Client Hints 164 Clients control which Client Hint headers and their respective header 165 fields are communicated, based on their default settings, user 166 configuration and/or preferences. The user may be given the choice 167 to enable, disable, or override specific hints. 169 The client and server, or an intermediate proxy, may use an opt-in 170 mechanism to negotiate which fields should be reported to allow for 171 efficient content adaption. 173 2.3. Server Processing of Client Hints 175 Servers can modify the response sent based upon Client Hints. When 176 doing so, it MUST confirm the selection for certain hints and 177 indicate the value of selected resource via corresponding response 178 header. For example, this specification defines "DPR" that 179 corresponds to the "CH-DPR" request header field. 181 2.3.1. Advertising Support for Client Hints 183 Servers can advertise support for Client Hints using the Accept-CH 184 header or an equivalent HTML meta element with http-equiv attribute. 186 Accept-CH = #token 188 For example: 190 Accept-CH: DPR, RW 192 When a client receives Accept-CH, it SHOULD append the Client Hint 193 headers that match the advertised field-values. For example, based 194 on Accept-CH example above, the client would append CH-DPR and CH-RW 195 headers to subsequent requests. 197 2.3.2. Interaction with Caches 199 Client Hints MAY be combined with Key ([I-D.fielding-http-key]) to 200 enable fine-grained control of the cache key for improved cache 201 efficiency. For example, the server may return the following set of 202 instructions: 204 Key: CH-DPR;r=[1.5:] 206 Above examples indicates that the cache key should be based on the 207 CH-DPR header, and the resource should be cached and made available 208 for any client whose device pixel ratio is 1.5, or higher. 210 Key: CH-RW;r=[320:640] 212 Above example indicates that the cache key should be based on the 213 CH-RW header, and the resource should be cached and made available 214 for any request whose display width falls between 320 and 640px. 216 In absence of support for fine-grained control of the cache key via 217 the Key header field, Vary response header can be used to indicate 218 that served resource has been adapted based on specified Client Hint 219 preferences. 221 Vary: CH-DPR 223 Above example indicates that the cache key should be based on the CH- 224 DPR header. 226 Vary: CH-DPR, CH-RW 228 Above example indicates that the cache key should be based on the CH- 229 DPR and CH-RW headers. 231 3. The CH-DPR Client Hint 233 The "CH-DPR" header field indicates the client's current Device Pixel 234 Ratio (DPR), the ratio between physical pixels and density 235 independent pixels on the device. 237 CH-DPR = 1*DIGIT [ "." 1*DIGIT ] 239 4. The CH-RW Client Hint 241 The "CH-RW" header field indicates the client's current Resource 242 Width (RW), the display width of the requested resource in density 243 independent pixels on the device. 245 CH-RW = 1*DIGIT 247 4.1. Confirming Selected DPR 249 The "DPR" header field indicates the ratio between physical pixels 250 and density independent pixels of the selected response. 252 DPR = 1*DIGIT [ "." 1*DIGIT ] 254 DPR ratio affects the calculation of intrinsic size of the image on 255 the client (i.e. typically, the client automatically scales the 256 natural size of the image by the DPR ratio to derive its display 257 dimensions). As a result, the server must explicitly indicate the 258 DPR of the resource whenever CH-DPR hint is used, and the client must 259 use the DPR value returned by the server to perform its calculations. 260 In case the server returned DPR value contradicts previous client- 261 side DPR indication, the server returned value must take precedence. 263 The server does not need to confirm resource width (RW) selection as 264 this value can be derived from the resource itself once it is decoded 265 by the client. 267 5. Examples 269 For example, given the following request header: 271 CH-DPR: 2.0 272 CH-RW: 160 274 The server knows that the device pixel ratio is 2.0, and that the 275 intended display width of requested resource is 160px, as measured by 276 density independent pixels on the device. 278 If the server uses above hints to perform resource selection, it must 279 confirm its selection via the DPR response header to allow the client 280 to calculate the appropriate intrinsic size of the image resource. 281 The server does not need to confirm resource width, only the ratio 282 between physical pixels and density independent pixels of the 283 selected image resource: 285 DPR: 1.0 287 The DPR response header indicates to the client that the server has 288 selected resource with DPR ratio of 1.0. The client may use this 289 information to perform additional processing on the resource - for 290 example, calculate the appropriate intrinsic size of the image 291 resource such that it is displayed at the correct resolution. 293 5.1. Relationship to the User-Agent Request Header 295 Client Hints does not supersede or replace User-Agent. Existing 296 device detection mechanisms can continue to use both mechanisms if 297 necessary. By advertising its capabilities within a request header, 298 Client Hints allows for cache friendly and proactive content 299 negotiation. 301 6. IANA Considerations 303 This document defines the "Accept-CH", "CH-DPR", "CH-RW", and "DPR" 304 HTTP request fields, and registers them in the Permanent Message 305 Headers registry. 307 o Header field name: CH-DPR 308 o Applicable protocol: HTTP 309 o Status: Informational 310 o Author/Change controller: Ilya Grigorik, ilya@igvita.com 311 o Specification document(s): [this document] 312 o Related information: for Client Hints 313 o Header field name: CH-RW 314 o Applicable protocol: HTTP 315 o Status: Informational 316 o Author/Change controller: Ilya Grigorik, ilya@igvita.com 317 o Specification document(s): [this document] 318 o Related information: for Client Hints 319 o Header field name: DPR 320 o Applicable protocol: HTTP 321 o Status: Informational 322 o Author/Change controller: Ilya Grigorik, ilya@igvita.com 323 o Specification document(s): [this document] 324 o Related information: for Client Hints 325 o Header field name: Accept-CH 326 o Applicable protocol: HTTP 327 o Status: Informational 328 o Author/Change controller: Ilya Grigorik, ilya@igvita.com 329 o Specification document(s): [this document] 330 o Related information: for Client Hints 332 7. Security Considerations 334 The client controls which header fields are communicated and when. 335 In cases such as incognito or anonymous profile browsing, the header 336 can be omitted if necessary. 338 8. Normative References 340 [I-D.fielding-http-key] 341 Fielding, R. and M. Nottingham, "The Key HTTP Response 342 Header Field", draft-fielding-http-key-02 (work in 343 progress), February 2013. 345 [I-D.ietf-httpbis-p1-messaging] 346 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 347 (HTTP/1.1): Message Syntax and Routing", 348 draft-ietf-httpbis-p1-messaging-25 (work in progress), 349 November 2013. 351 [I-D.ietf-httpbis-p2-semantics] 352 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 353 (HTTP/1.1): Semantics and Content", 354 draft-ietf-httpbis-p2-semantics-25 (work in progress), 355 November 2013. 357 [I-D.nottingham-http-browser-hints] 358 Nottingham, M., "HTTP Origin and Hop Hints", 359 draft-nottingham-http-browser-hints-05 (work in progress), 360 February 2013. 362 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 363 Requirement Levels", BCP 14, RFC 2119, March 1997. 365 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 366 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 367 May 2008. 369 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 370 Specifications: ABNF", STD 68, RFC 5234, January 2008. 372 Author's Address 374 Ilya Grigorik 376 Email: ilya@igvita.com 377 URI: http://www.igvita.com/