idnits 2.17.1 draft-ietf-httpbis-client-hints-00.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 (November 24, 2015) is 3075 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-01) exists of draft-ietf-httpbis-key-00 ** 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: Standards Track November 24, 2015 5 Expires: May 27, 2016 7 HTTP Client Hints 8 draft-ietf-httpbis-client-hints-00 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 Note to Readers 25 The issues list for this draft can be found at 26 https://github.com/httpwg/http-extensions/labels/client-hints . 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on May 27, 2016. 45 Copyright Notice 47 Copyright (c) 2015 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 63 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 64 2. Client Hint Request Header Fields . . . . . . . . . . . . . . 3 65 2.1. Sending Client Hints . . . . . . . . . . . . . . . . . . 4 66 2.2. Server Processing of Client Hints . . . . . . . . . . . . 4 67 2.2.1. Advertising Support for Client Hints . . . . . . . . 4 68 2.2.2. Interaction with Caches . . . . . . . . . . . . . . . 5 69 3. The DPR Client Hint . . . . . . . . . . . . . . . . . . . . . 6 70 3.1. Confirming Selected DPR . . . . . . . . . . . . . . . . . 6 71 4. The Width Client Hint . . . . . . . . . . . . . . . . . . . . 6 72 5. The Viewport-Width Client Hint . . . . . . . . . . . . . . . 7 73 6. The Downlink Client Hint . . . . . . . . . . . . . . . . . . 7 74 7. The Save-Data Hint . . . . . . . . . . . . . . . . . . . . . 7 75 8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8 76 9. Security Considerations . . . . . . . . . . . . . . . . . . . 8 77 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 78 11. Normative References . . . . . . . . . . . . . . . . . . . . 10 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 81 1. Introduction 83 There are thousands of different devices accessing the web, each with 84 different device capabilities and preference information. These 85 device capabilities include hardware and software characteristics, as 86 well as dynamic user and client preferences. 88 One way to infer some of these capabilities is through User-Agent 89 (UA) detection against an established database of client signatures. 90 However, this technique requires acquiring such a database, 91 integrating it into the serving path, and keeping it up to date. 93 However, even once this infrastructure is deployed, UA sniffing has 94 numerous limitations: 96 o UA detection cannot reliably identify all static variables 97 o UA detection cannot infer any dynamic client preferences 98 o UA detection requires an external device database 99 o UA detection is not cache friendly 101 A popular alternative strategy is to use HTTP cookies to communicate 102 some information about the client. However, this approach is also 103 not cache friendly, bound by same origin policy, and imposes 104 additional client-side latency by requiring JavaScript execution to 105 create and manage HTTP cookies. 107 This document defines a set of new request header fields that allow 108 the client to perform proactive content negotiation [RFC7231] by 109 indicating a list of device and agent specific preferences, through a 110 mechanism similar to the Accept header which is used to indicate 111 preferred response formats. 113 Client Hints does not supersede or replace the User-Agent header 114 field. Existing device detection mechanisms can continue to use both 115 mechanisms if necessary. By advertising its capabilities within a 116 request header field, Client Hints allows for cache friendly and 117 proactive content negotiation. 119 1.1. Notational Conventions 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 123 document are to be interpreted as described in [RFC2119]. 125 This document uses the Augmented Backus-Naur Form (ABNF) notation of 126 [RFC5234] with the list rule extension defined in [RFC7230], 127 Appendix B. It includes by reference the DIGIT rule from [RFC5234]; 128 the OWS, field-name and quoted-string rules from [RFC7230]; and the 129 parameter rule from [RFC7231]. 131 2. Client Hint Request Header Fields 133 A Client Hint request header field is a HTTP header field that is 134 used by HTTP clients to indicate configuration data that can be used 135 by the server to select an appropriate response. Each one conveys a 136 list of client preferences that the server can use to adapt and 137 optimize the response. 139 This document defines a selection of Client Hint request header 140 fields, and can be referenced by other specifications wishing to use 141 the same syntax and processing model. 143 2.1. Sending Client Hints 145 Clients control which Client Hint headers and their respective header 146 fields are communicated, based on their default settings, user 147 configuration and/or preferences. The user may be given the choice 148 to enable, disable, or override specific hints. 150 The client and server, or an intermediate proxy, may use an opt-in 151 mechanism to negotiate which fields should be reported to allow for 152 efficient content adaption. 154 2.2. Server Processing of Client Hints 156 Servers MAY respond with an optimized response based on one or more 157 received hints from the client. When doing so, and if the resource 158 is cacheable, the server MUST also emit a Vary response header field 159 ([RFC7234]), and optionally Key ([I-D.ietf-httpbis-key]), to indicate 160 which hints were used and whether the selected response is 161 appropriate for a later request. 163 Further, depending on the used hint, the server MAY also need to emit 164 additional response header fields to confirm the property of the 165 response, such that the client can adjust its processing. For 166 example, this specification defines "Content-DPR" response header 167 field that MUST be returned by the server when the "DPR" hint is used 168 to select the response. 170 2.2.1. Advertising Support for Client Hints 172 Servers can advertise support for Client Hints using the Accept-CH 173 header or an equivalent HTML meta element with http-equiv attribute. 175 Accept-CH = #token 177 For example: 179 Accept-CH: DPR, Width, Viewport-Width, Downlink 181 When a client receives Accept-CH, it SHOULD append the Client Hint 182 headers that match the advertised field-values. For example, based 183 on Accept-CH example above, the client would append DPR, Width, 184 Viewport-Width, and Downlink headers to all subsequent requests. 186 2.2.2. Interaction with Caches 188 When selecting an optimized response based on one or more Client 189 Hints, and if the resource is cacheable, the server MUST also emit a 190 Vary response header field ([RFC7234]) to indicate which hints were 191 used and whether the selected response is appropriate for a later 192 request. 194 Vary: DPR 196 Above example indicates that the cache key should be based on the DPR 197 header. 199 Vary: DPR, Width, Downlink 201 Above example indicates that the cache key should be based on the 202 DPR, Width, and Downlink headers. 204 Client Hints MAY be combined with Key ([I-D.ietf-httpbis-key]) to 205 enable fine-grained control of the cache key for improved cache 206 efficiency. For example, the server MAY return the following set of 207 instructions: 209 Key: DPR;partition=1.5:2.5:4.0 211 Above example indicates that the cache key should be based on the 212 value of the DPR header with three segments: less than 1.5, 1.5 to 213 less than 2.5, and 4.0 or greater. 215 Key: Width;div=320 217 Above example indicates that the cache key should be based on the 218 value of the Width header and be partitioned into groups of 320: 219 0-320, 320-640, and so on. 221 Key: Downlink;partition=0.5:1.0:3.0:5.0:10 223 Above example indicates that the cache key should be based on the 224 (Mbps) value of the Downlink header with six segments: less than 0.5, 225 0.5 to less than 1.0, 1.0 to less than 3.0, 3.0 to less than 5.0, 5.0 226 to less than 10; 10 or higher. 228 3. The DPR Client Hint 230 The "DPR" header field is a number that, in requests, indicates the 231 client's current Device Pixel Ratio (DPR), which is the ratio of 232 physical pixels over CSS px of the layout viewport on the device. 234 DPR = 1*DIGIT [ "." 1*DIGIT ] 236 If DPR occurs in a message more than once, the last value overrides 237 all previous occurrences. 239 3.1. Confirming Selected DPR 241 The "Content-DPR" header field is a number that indicates the ratio 242 between physical pixels over CSS px of the selected image response. 244 Content-DPR = 1*DIGIT [ "." 1*DIGIT ] 246 DPR ratio affects the calculation of intrinsic size of image 247 resources on the client - i.e. typically, the client automatically 248 scales the natural size of the image by the DPR ratio to derive its 249 display dimensions. As a result, the server must explicitly indicate 250 the DPR of the selected image response whenever the DPR hint is used, 251 and the client must use the DPR value returned by the server to 252 perform its calculations. In case the server returned Content-DPR 253 value contradicts previous client-side DPR indication, the server 254 returned value must take precedence. 256 Note that DPR confirmation is only required for image responses, and 257 the server does not need to confirm the resource width as this value 258 can be derived from the resource itself once it is decoded by the 259 client. 261 If Content-DPR occurs in a message more than once, the last value 262 overrides all previous occurrences. 264 4. The Width Client Hint 266 The "Width" header field is a number that, in requests, indicates the 267 resource width in physical px (i.e. intrinsic size of an image). The 268 provided physical px value is a number rounded to the largest 269 smallest following integer (i.e. ceiling value). 271 Width = 1*DIGIT 273 If the resource width is not known at the time of the request or the 274 resource does not have a display width, the Width header field may be 275 omitted. If Width occurs in a message more than once, the last value 276 overrides all previous occurrences. 278 5. The Viewport-Width Client Hint 280 The "Viewport-Width" header field is a number that, in requests, 281 indicates the layout viewport width in CSS px. The provided CSS px 282 value is a number rounded to the largest smallest following integer 283 (i.e. ceiling value). 285 Viewport-Width = 1*DIGIT 287 If Viewport-Width occurs in a message more than once, the last value 288 overrides all previous occurrences. 290 6. The Downlink Client Hint 292 The "Downlink" header field is a number that, in requests, indicates 293 the client's maximum downlink speed in megabits per second (Mbps), as 294 defined by the "downlinkMax" attribute in the W3C Network Information 295 API. 297 Downlink = 1*DIGIT [ "." 1*DIGIT ] 299 If Downlink occurs in a message more than once, the minimum value 300 should be used to override other occurrences. 302 7. The Save-Data Hint 304 The "Save-Data" header field is a token that, in requests, indicates 305 client's preference for reduced data usage, due to high transfer 306 costs, slow connection speeds, or other reasons. 308 Save-Data = "on" 310 The token is a signal indicating explicit user opt-in into a reduced 311 data usage mode on the client, and when communicated to origins 312 allows them to deliver alternate content honoring such preference - 313 e.g. smaller image and video resources, alternate markup, and so on. 315 8. Examples 317 For example, given the following request headers: 319 DPR: 2.0 320 Width: 320 321 Viewport-Width: 320 323 The server knows that the device pixel ratio is 2.0, that the 324 intended display width of requested resource is 160 CSS px (320 325 physical pixels at 2x resolution), and that the viewport width is 320 326 CSS px. 328 If the server uses above hints to perform resource selection for an 329 image asset, it must confirm its selection via the Content-DPR 330 response header to allow the client to calculate the appropriate 331 intrinsic size of the image response. The server does not need to 332 confirm resource width, only the ratio between physical pixels and 333 CSS px of the selected image resource: 335 Content-DPR: 1.0 337 The Content-DPR response header indicates to the client that the 338 server has selected resource with DPR ratio of 1.0. The client may 339 use this information to perform additional processing on the resource 340 - for example, calculate the appropriate intrinsic size of the image 341 resource such that it is displayed at the correct resolution. 343 Alternatively, the server could select an alternate resource based on 344 the maximum downlink speed advertised in the request headers: 346 Downlink: 0.384 348 The server knows that the client's maximum downlink speed is 349 0.384Mbps (GPRS EDGE), and it may use this information to select an 350 optimized resource - for example, an alternate image asset, 351 stylesheet, HTML document, media stream, and so on. 353 9. Security Considerations 355 Client Hints defined in this specification do not expose any new 356 information about the user's environment beyond what is already 357 available to, and may be communicated by, the application at runtime 358 via JavaScript - e.g. viewport and image display width, device pixel 359 ratio, and so on. 361 However, implementors should consider the privacy implications of 362 various methods to enable delivery of Client Hints - see "Sending 363 Client Hints" section. For example, sending Client Hints on all 364 requests may make information about the user's environment available 365 to origins that otherwise did not have access to this data (e.g. 366 origins hosting non-script resources), which may or not be the 367 desired outcome. The implementors may want to provide mechanisms to 368 control such behavior via explicit opt-in, or other mechanisms. 369 Similarly, the implementors should consider how and whether delivery 370 of Client Hints is affected when the user is in "incognito" or 371 similar privacy mode. 373 10. IANA Considerations 375 This document defines the "Accept-CH", "DPR", "Width", and "Downlink" 376 HTTP request fields, "Content-DPR" HTTP response field, and registers 377 them in the Permanent Message Header Fields registry. 379 o Header field name: DPR 380 o Applicable protocol: HTTP 381 o Status: standard 382 o Author/Change controller: IETF 383 o Specification document(s): [this document] 384 o Related information: for Client Hints 385 o Header field name: Width 386 o Applicable protocol: HTTP 387 o Status: standard 388 o Author/Change controller: IETF 389 o Specification document(s): [this document] 390 o Related information: for Client Hints 391 o Header field name: Viewport-Width 392 o Applicable protocol: HTTP 393 o Status: standard 394 o Author/Change controller: IETF 395 o Specification document(s): [this document] 396 o Related information: for Client Hints 397 o Header field name: Downlink 398 o Applicable protocol: HTTP 399 o Status: standard 400 o Author/Change controller: IETF 401 o Specification document(s): [this document] 402 o Related information: for Client Hints 403 o Header field name: Content-DPR 404 o Applicable protocol: HTTP 405 o Status: standard 406 o Author/Change controller: IETF 407 o Specification document(s): [this document] 408 o Related information: for Client Hints 409 o Header field name: Accept-CH 410 o Applicable protocol: HTTP 411 o Status: standard 412 o Author/Change controller: IETF 413 o Specification document(s): [this document] 414 o Related information: for Client Hints 415 o Header field name: Save-Data 416 o Applicable protocol: HTTP 417 o Status: standard 418 o Author/Change controller: IETF 419 o Specification document(s): [this document] 420 o Related information: for Client Hints 422 11. Normative References 424 [I-D.ietf-httpbis-key] 425 Fielding, R. and m. mnot, "The Key HTTP Response Header 426 Field", draft-ietf-httpbis-key-00 (work in progress), 427 October 2015. 429 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 430 Requirement Levels", BCP 14, RFC 2119, 431 DOI 10.17487/RFC2119, March 1997, 432 . 434 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 435 Specifications: ABNF", STD 68, RFC 5234, 436 DOI 10.17487/RFC5234, January 2008, 437 . 439 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 440 Protocol (HTTP/1.1): Message Syntax and Routing", 441 RFC 7230, DOI 10.17487/RFC7230, June 2014, 442 . 444 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 445 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 446 DOI 10.17487/RFC7231, June 2014, 447 . 449 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 450 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 451 RFC 7234, DOI 10.17487/RFC7234, June 2014, 452 . 454 Author's Address 456 Ilya Grigorik 457 Google 459 Email: ilya@igvita.com 460 URI: https://www.igvita.com/