idnits 2.17.1 draft-grigorik-http-client-hints-03.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 (August 24, 2015) is 3167 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-03) exists of draft-fielding-http-key-02 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group I. Grigorik 3 Internet-Draft Google 4 Intended status: Informational August 24, 2015 5 Expires: February 25, 2016 7 HTTP Client Hints 8 draft-grigorik-http-client-hints-03 10 Abstract 12 An increasing diversity of Web-connected devices and software 13 capabilities has created a need to deliver optimized content for each 14 device. 16 This specification defines a set of HTTP request header fields, 17 colloquially known as Client Hints, to address this. They are 18 intended to be used as input to proactive content negotiation; just 19 as the Accept header allows clients to indicate what formats they 20 prefer, Client Hints allow clients to indicate a list of device and 21 agent specific preferences. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on February 25, 2016. 40 Copyright Notice 42 Copyright (c) 2015 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 59 2. Client Hint Request Header Fields . . . . . . . . . . . . . . 4 60 2.1. Sending Client Hints . . . . . . . . . . . . . . . . . . . 4 61 2.2. Server Processing of Client Hints . . . . . . . . . . . . 4 62 2.2.1. Advertising Support for Client Hints . . . . . . . . . 4 63 2.2.2. Interaction with Caches . . . . . . . . . . . . . . . 5 64 3. The DPR Client Hint . . . . . . . . . . . . . . . . . . . . . 6 65 3.1. Confirming Selected DPR . . . . . . . . . . . . . . . . . 6 66 4. The Width Client Hint . . . . . . . . . . . . . . . . . . . . 6 67 5. The Viewport-Width Client Hint . . . . . . . . . . . . . . . . 7 68 6. The Downlink Client Hint . . . . . . . . . . . . . . . . . . . 7 69 7. The Save-Data Hint . . . . . . . . . . . . . . . . . . . . . . 7 70 8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 9. Security Considerations . . . . . . . . . . . . . . . . . . . 8 72 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 73 11. Normative References . . . . . . . . . . . . . . . . . . . . . 10 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 76 1. Introduction 78 There are thousands of different devices accessing the web, each with 79 different device capabilities and preference information. These 80 device capabilities include hardware and software characteristics, as 81 well as dynamic user and client preferences. 83 One way to infer some of these capabilities is through User-Agent 84 (UA) detection against an established database of client signatures. 85 However, this technique requires acquiring such a database, 86 integrating it into the serving path, and keeping it up to date. 87 However, even once this infrastructure is deployed, UA sniffing has 88 numerous limitations: 90 o UA detection cannot reliably identify all static variables 91 o UA detection cannot infer any dynamic client preferences 92 o UA detection requires an external device database 93 o UA detection is not cache friendly 95 A popular alternative strategy is to use HTTP cookies to communicate 96 some information about the client. However, this approach is also 97 not cache friendly, bound by same origin policy, and imposes 98 additional client-side latency by requiring JavaScript execution to 99 create and manage HTTP cookies. 101 This document defines a set of new request header fields that allow 102 the client to perform proactive content negotiation [RFC7231] by 103 indicating a list of device and agent specific preferences, through a 104 mechanism similar to the Accept header which is used to indicate 105 preferred response formats. 107 Client Hints does not supersede or replace the User-Agent header 108 field. Existing device detection mechanisms can continue to use both 109 mechanisms if necessary. By advertising its capabilities within a 110 request header field, Client Hints allows for cache friendly and 111 proactive content negotiation. 113 1.1. Notational Conventions 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 117 document are to be interpreted as described in [RFC2119]. 119 This document uses the Augmented Backus-Naur Form (ABNF) notation of 120 [RFC5234] with the list rule extension defined in [RFC7230], Appendix 121 B. It includes by reference the DIGIT rule from [RFC5234]; the OWS, 122 field-name and quoted-string rules from [RFC7230]; and the parameter 123 rule from [RFC7231]. 125 2. Client Hint Request Header Fields 127 A Client Hint request header field is a HTTP header field that is 128 used by HTTP clients to indicate configuration data that can be used 129 by the server to select an appropriate response. Each one conveys a 130 list of client preferences that the server can use to adapt and 131 optimize the response. 133 This document defines a selection of Client Hint request header 134 fields, and can be referenced by other specifications wishing to use 135 the same syntax and processing model. 137 2.1. Sending Client Hints 139 Clients control which Client Hint headers and their respective header 140 fields are communicated, based on their default settings, user 141 configuration and/or preferences. The user may be given the choice 142 to enable, disable, or override specific hints. 144 The client and server, or an intermediate proxy, may use an opt-in 145 mechanism to negotiate which fields should be reported to allow for 146 efficient content adaption. 148 2.2. Server Processing of Client Hints 150 Servers MAY respond with an optimized response based on one or more 151 received hints from the client. When doing so, and if the resource 152 is cacheable, the server MUST also emit a Vary response header field 153 ([RFC7234]), and optionally Key ([I-D.fielding-http-key]), to 154 indicate which hints were used and whether the selected response is 155 appropriate for a later request. 157 Further, depending on the used hint, the server MAY also need to emit 158 additional response header fields to confirm the property of the 159 response, such that the client can adjust its processing. For 160 example, this specification defines "Content-DPR" response header 161 field that MUST be returned by the server when the "DPR" hint is used 162 to select the response. 164 2.2.1. Advertising Support for Client Hints 166 Servers can advertise support for Client Hints using the Accept-CH 167 header or an equivalent HTML meta element with http-equiv attribute. 169 Accept-CH = #token 171 For example: 173 Accept-CH: DPR, Width, Viewport-Width, Downlink 175 When a client receives Accept-CH, it SHOULD append the Client Hint 176 headers that match the advertised field-values. For example, based 177 on Accept-CH example above, the client would append DPR, Width, 178 Viewport-Width, and Downlink headers to all subsequent requests. 180 2.2.2. Interaction with Caches 182 When selecting an optimized response based on one or more Client 183 Hints, and if the resource is cacheable, the server MUST also emit a 184 Vary response header field ([RFC7234]) to indicate which hints were 185 used and whether the selected response is appropriate for a later 186 request. 188 Vary: DPR 190 Above example indicates that the cache key should be based on the DPR 191 header. 193 Vary: DPR, Width, Downlink 195 Above example indicates that the cache key should be based on the 196 DPR, Width, and Downlink headers. 198 Client Hints MAY be combined with Key ([I-D.fielding-http-key]) to 199 enable fine-grained control of the cache key for improved cache 200 efficiency. For example, the server MAY return the following set of 201 instructions: 203 Key: DPR;r=[1.5:] 205 Above examples indicates that the cache key should be based on the 206 DPR header, and the resource should be cached and made available for 207 any client whose device pixel ratio is 1.5, or higher. 209 Key: Width;r=[320:640] 211 Above example indicates that the cache key should be based on the 212 Width header, and the resource should be cached and made available 213 for any request whose display width falls between 320 and 640px. 215 Key: Downlink;r=[0.384:] 217 Above example indicates that the cache key should be based on the 218 Downlink header, and the resource should be cached and made available 219 for any request whose advertised maxim downlink speed is 0.384Mbps 220 (GPRS EDGE), or higher. 222 3. The DPR Client Hint 224 The "DPR" header field is a number that, in requests, indicates the 225 client's current Device Pixel Ratio (DPR), which is the ratio of 226 physical pixels over CSS px of the layout viewport on the device. 228 DPR = 1*DIGIT [ "." 1*DIGIT ] 230 If DPR occurs in a message more than once, the last value overrides 231 all previous occurrences. 233 3.1. Confirming Selected DPR 235 The "Content-DPR" header field is a number that indicates the ratio 236 between physical pixels over CSS px of the selected image response. 238 Content-DPR = 1*DIGIT [ "." 1*DIGIT ] 240 DPR ratio affects the calculation of intrinsic size of image 241 resources on the client - i.e. typically, the client automatically 242 scales the natural size of the image by the DPR ratio to derive its 243 display dimensions. As a result, the server must explicitly indicate 244 the DPR of the selected image response whenever the DPR hint is used, 245 and the client must use the DPR value returned by the server to 246 perform its calculations. In case the server returned Content-DPR 247 value contradicts previous client-side DPR indication, the server 248 returned value must take precedence. 250 Note that DPR confirmation is only required for image responses, and 251 the server does not need to confirm the resource width as this value 252 can be derived from the resource itself once it is decoded by the 253 client. 255 If Content-DPR occurs in a message more than once, the last value 256 overrides all previous occurrences. 258 4. The Width Client Hint 260 The "Width" header field is a number that, in requests, indicates the 261 resource width in CSS px (e.g. display width of an image). The 262 provided CSS px value is a number rounded to the largest smallest 263 following integer (i.e. ceiling value). 265 Width = 1*DIGIT 267 If the resource width is not known at the time of the request or the 268 resource does not have a display width, the Width header field may be 269 omitted. If Width occurs in a message more than once, the last value 270 overrides all previous occurrences. 272 5. The Viewport-Width Client Hint 274 The "Viewport-Width" header field is a number that, in requests, 275 indicates the layout viewport width in CSS px. The provided CSS px 276 value is a number rounded to the largest smallest following integer 277 (i.e. ceiling value). 279 Viewport-Width = 1*DIGIT 281 If Viewport-Width occurs in a message more than once, the last value 282 overrides all previous occurrences. 284 6. The Downlink Client Hint 286 The "Downlink" header field is a number that, in requests, indicates 287 the client's maximum downlink speed in megabits per second (Mbps), as 288 defined by the "downlinkMax" attribute in the W3C Network Information 289 API. 291 Downlink = 1*DIGIT [ "." 1*DIGIT ] 293 If Downlink occurs in a message more than once, the minimum value 294 should be used to override other occurrences. 296 7. The Save-Data Hint 298 The "Save-Data" header field is a boolean that, in requests, 299 indicates client's preference for reduced data usage, due to high 300 transfer costs, slow connection speeds, or other reasons. 302 Save-Data = 1 304 The boolean is a signal indicating explicit user opt-in into a 305 reduced data usage mode on the client, and when communicated to 306 origins allows them to deliver alternate content honoring such 307 preference - e.g. smaller image and video resources, alternate 308 markup, and so on. 310 8. Examples 312 For example, given the following request headers: 314 DPR: 2.0 315 Width: 160 316 Viewport-Width: 320 318 The server knows that the device pixel ratio is 2.0, that the 319 intended display width of requested resource is 160 CSS px, and that 320 the viewport width is 320 CSS px. 322 If the server uses above hints to perform resource selection for an 323 image asset, it must confirm its selection via the Content-DPR 324 response header to allow the client to calculate the appropriate 325 intrinsic size of the image response. The server does not need to 326 confirm resource width, only the ratio between physical pixels and 327 CSS px of the selected image resource: 329 Content-DPR: 1.0 331 The Content-DPR response header indicates to the client that the 332 server has selected resource with DPR ratio of 1.0. The client may 333 use this information to perform additional processing on the resource 334 - for example, calculate the appropriate intrinsic size of the image 335 resource such that it is displayed at the correct resolution. 337 Alternatively, the server could select an alternate resource based on 338 the maximum downlink speed advertised in the request headers: 340 Downlink: 0.384 342 The server knows that the client's maximum downlink speed is 343 0.384Mbps (GPRS EDGE), and it may use this information to select an 344 optimized resource - for example, an alternate image asset, 345 stylesheet, HTML document, media stream, and so on. 347 9. Security Considerations 349 Client Hints defined in this specification do not expose any new 350 information about the user's environment beyond what is already 351 available to, and may be communicated by, the application at runtime 352 via JavaScript - e.g. viewport and image display width, device pixel 353 ratio, and so on. 355 However, implementors should consider the privacy implications of 356 various methods to enable delivery of Client Hints - see "Sending 357 Client Hints" section. For example, sending Client Hints on all 358 requests may make information about the user's environment available 359 to origins that otherwise did not have access to this data (e.g. 360 origins hosting non-script resources), which may or not be the 361 desired outcome. The implementors may want to provide mechanisms to 362 control such behavior via explicit opt-in, or other mechanisms. 363 Similarly, the implementors should consider how and whether delivery 364 of Client Hints is affected when the user is in "incognito" or 365 similar privacy mode. 367 10. IANA Considerations 369 This document defines the "Accept-CH", "DPR", "Width", and "Downlink" 370 HTTP request fields, "Content-DPR" HTTP response field, and registers 371 them in the Permanent Message Header Fields registry. 373 o Header field name: DPR 374 o Applicable protocol: HTTP 375 o Status: standard 376 o Author/Change controller: Ilya Grigorik, ilya@igvita.com 377 o Specification document(s): [this document] 378 o Related information: for Client Hints 379 o Header field name: Width 380 o Applicable protocol: HTTP 381 o Status: standard 382 o Author/Change controller: Ilya Grigorik, ilya@igvita.com 383 o Specification document(s): [this document] 384 o Related information: for Client Hints 385 o Header field name: Viewport-Width 386 o Applicable protocol: HTTP 387 o Status: standard 388 o Author/Change controller: Ilya Grigorik, ilya@igvita.com 389 o Specification document(s): [this document] 390 o Related information: for Client Hints 391 o Header field name: Downlink 392 o Applicable protocol: HTTP 393 o Status: standard 394 o Author/Change controller: Ilya Grigorik, ilya@igvita.com 395 o Specification document(s): [this document] 396 o Related information: for Client Hints 397 o Header field name: Content-DPR 398 o Applicable protocol: HTTP 399 o Status: standard 400 o Author/Change controller: Ilya Grigorik, ilya@igvita.com 401 o Specification document(s): [this document] 402 o Related information: for Client Hints 403 o Header field name: Accept-CH 404 o Applicable protocol: HTTP 405 o Status: standard 406 o Author/Change controller: Ilya Grigorik, ilya@igvita.com 407 o Specification document(s): [this document] 408 o Related information: for Client Hints 409 o Header field name: Save-Data 410 o Applicable protocol: HTTP 411 o Status: standard 412 o Author/Change controller: Ilya Grigorik, ilya@igvita.com 413 o Specification document(s): [this document] 414 o Related information: for Client Hints 416 11. Normative References 418 [I-D.fielding-http-key] 419 Fielding, R. and M. Nottingham, "The Key HTTP Response 420 Header Field", draft-fielding-http-key-02 (work in 421 progress), February 2013. 423 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 424 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 425 RFC2119, March 1997, 426 . 428 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 429 Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ 430 RFC5234, January 2008, 431 . 433 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 434 Protocol (HTTP/1.1): Message Syntax and Routing", 435 RFC 7230, DOI 10.17487/RFC7230, June 2014, 436 . 438 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 439 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 440 DOI 10.17487/RFC7231, June 2014, 441 . 443 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 444 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 445 RFC 7234, DOI 10.17487/RFC7234, June 2014, 446 . 448 Author's Address 450 Ilya Grigorik 451 Google 453 Email: ilya@igvita.com 454 URI: https://www.igvita.com/