idnits 2.17.00 (12 Aug 2021) /tmp/idnits54663/draft-nottingham-http-browser-hints-04.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 : ---------------------------------------------------------------------------- -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 15, 2012) is 3504 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 5785 (Obsoleted by RFC 8615) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft October 15, 2012 4 Intended status: Informational 5 Expires: April 18, 2013 7 HTTP Browser Hints 8 draft-nottingham-http-browser-hints-04 10 Abstract 12 Over time, Web browsers have adapted how they use HTTP based upon 13 common server configurations and behaviours. While this is necessary 14 in the common case, it can be detrimental for performance and 15 interoperability. 17 This document establishes a mechanism whereby origin servers can make 18 available hints for browsers about their preferences and 19 capabilities, without imposing overhead on their interactions or 20 requiring support for them. 22 This is intended to allow browsers to safely optimise connections to 23 servers. 25 Note to Readers 27 Feedback for this draft should take place on the 28 apps-discuss@ietf.org mailing list 29 . 31 Status of this Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on April 18, 2013. 48 Copyright Notice 49 Copyright (c) 2012 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3 66 3. A file format for Browser Hints . . . . . . . . . . . . . . . 3 67 3.1. The 'prefixlist' Value Type . . . . . . . . . . . . . . . 4 68 4. Discovering Browser Hints for a Web site . . . . . . . . . . . 4 69 4.1. Notifying Clients with the BH Response Header Field . . . 5 70 4.2. Interaction with HTTP Proxies . . . . . . . . . . . . . . 6 71 5. Pre-defined Browser Hints . . . . . . . . . . . . . . . . . . 6 72 5.1. max-conns . . . . . . . . . . . . . . . . . . . . . . . . 6 73 5.2. pconn-ip . . . . . . . . . . . . . . . . . . . . . . . . . 6 74 5.3. ip-balance . . . . . . . . . . . . . . . . . . . . . . . . 7 75 5.4. connect-timeout . . . . . . . . . . . . . . . . . . . . . 7 76 5.5. read-timeout . . . . . . . . . . . . . . . . . . . . . . . 8 77 5.6. max-pipeline-depth . . . . . . . . . . . . . . . . . . . . 8 78 5.7. small-hdrs . . . . . . . . . . . . . . . . . . . . . . . . 8 79 5.8. relative-referer . . . . . . . . . . . . . . . . . . . . . 8 80 5.9. chunk-req-bodies . . . . . . . . . . . . . . . . . . . . . 9 81 5.10. omit-cookies . . . . . . . . . . . . . . . . . . . . . . . 9 82 5.11. cookie-whitelist . . . . . . . . . . . . . . . . . . . . . 9 83 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 84 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 85 7.1. The 'browser-hints' Well-Known URI . . . . . . . . . . . . 9 86 7.2. The BH HTTP Response Header Field . . . . . . . . . . . . 10 87 7.3. The HTTP Browser Hints Registry . . . . . . . . . . . . . 10 88 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 89 8.1. Normative References . . . . . . . . . . . . . . . . . . . 11 90 8.2. Informative References . . . . . . . . . . . . . . . . . . 11 91 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 92 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 94 1. Introduction 96 HTTP [RFC2616] clients -- especially browsers -- typically use 97 hardcoded values or heuristics to determine how many TCP connections 98 to use to a server, based on common-case server behaviours and 99 limitations. 101 Likewise, they often send voluminous request headers (e.g., in User- 102 Agent and Allow) because they fear that changing those headers' 103 values will break some sites that depend upon specific values. 105 These are just two examples of common, conservative behaviour by 106 browsers that is good for interoperability, but potentially bad for 107 performance in certain circumstances. 109 This document specifies a mechanism whereby a HTTP server can 110 advertise hints for browsers (and other clients), so that 111 communication with them can be optimised. 113 It does so by defining a file format for such Browser Hints 114 Section 3, and defining how clients can discover it for a given Web 115 site Section 4. Finally, an extensible vocabulary of hints is 116 defined Section 5. 118 2. Requirements 120 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 122 document are to be interpreted as described in [RFC2119]. 124 3. A file format for Browser Hints 126 Browser hints are conveyed in a JSON [RFC4627] formatted file, 127 containing a single object whose member's names are browser hints, as 128 defined by the registry Section 7.3. 130 For example; 132 { 133 "max-conns": 5, 134 "small-hdrs": true 135 } 137 By their nature, all browser hints are optional; i.e., browsers are 138 free to ignore them. 140 3.1. The 'prefixlist' Value Type 142 Each browser hint is defined to have a JSON-derived value type; e.g., 143 'string' or 'array'. This section defines a special value type, 144 'prefixlist' that is an array containing one or more arrays, each 145 containing a path prefix followed by either 'true' or 'false' to 146 indicate whether the hint applies to that path. 148 Prefixlists are evaluated in order, with the first case-sensitive, 149 character-by-character prefix match for a given URI's path 150 determining whether the hint applies. 152 For example, given the following hint document: 154 { 155 "omit-cookies": [ 156 ["/images/users/", false], 157 ["/images/", true] 158 ] 159 } 161 We can tell that "omit-cookies" applies to resources under the 162 "/images/" path (such as "/images/123.jpg"), except for those under 163 "/images/users/" (such as "/images/users/bob.jpg"). 165 If a value specified to be a prefixlist is either 'true' or 'false' 166 that indicates that the hint applies to the whole site, or does not 167 apply to the whole site, respectively. 169 For example, 171 { 172 "omit-cookies": true 173 } 175 Indicates that the "omit-cookies" hint applies to the entire site. 177 Prefixlists can only be used when the browser hint's registration 178 nominates their use. 180 4. Discovering Browser Hints for a Web site 182 The hints relevant to a given site can be determined by fetching the 183 URI path "/.well-known/browser-hints" for that site. 185 Typically, clients (especially browsers) will not block other 186 requests to a site while fetching the browser hints (because they're 187 optional); instead, it will usually be done concurrently with other 188 requests, or on idle connections for future use. 190 In this specification, "site" is scoped by the URI scheme and 191 authority. As such, all of the following are considered to be 192 different sites, and therefore have different browser hints: 194 o http://foo.com/ 195 o https://foo.com/ 196 o http://foo.com:8000/ 197 o http://www.foo.com/ 199 Clients SHOULD follow HTTP 3xx redirects when retrieving hints. 201 A successful response is valid for its associated site for as long as 202 it can be cached in HTTP. 204 If the response has a 200 status code but no explicit freshness 205 (e.g., a Cache-Control: max-age or Expires: header), clients SHOULD 206 cache the response heuristically for a generous fixed period (e.g., 207 14 days). 209 If the response has a 404 status code but no explicit freshness, 210 clients SHOULD cache the response heuristically for a generous fixed 211 period (e.g., 14 days). 213 4.1. Notifying Clients with the BH Response Header Field 215 It is anticipated that Browser Hints will be used by some, but not 216 all, Web sites. Because clients might be reluctant to optimistically 217 request the well-known URI, this document defines a new HTTP response 218 header field, BH, to indicate that hints are available on a site. 220 For example, 222 HTTP/1.1 200 OK 223 Content-Type: text/html 224 Content-Length: 324 225 BH: 1 227 The presence of the BH header field in a response indicates that the 228 origin associated with the effective request URI has a Browser Hints 229 resource available at the well-known URI. 231 The header field value MAY be "0" or "1". 233 Origin servers that wish to indicate to clients that Browser Hints 234 are available SHOULD include a BH header in all responses with a 235 value of "1". 237 Proxy servers that wish to suppress the use of certain Browser Hints 238 MAY set (or reset) the BH header's value to "0". 240 4.2. Interaction with HTTP Proxies 242 Browser Hints are intended to optimise the connection between a 243 client and the origin server. However, HTTP allows proxies to be 244 interposed between browsers and origin servers, meaning that careless 245 use of some hints -- especially those that are connection-oriented -- 246 might not be applicable, and might even be harmful to the proxy. 248 To mitigate these risks, some hints identify additional requirements 249 for clients consuming browser hints when there is evidence of a proxy 250 in use. 252 A proxy is considered to be in use if: 254 o A proxy is explicitly configured by the client, or 255 o The BH response header field has a value of "0". 257 Note that the presence of the Via header is not considered, because 258 it can also be generated by intermediaries working on behalf of the 259 origin server ("reverse proxies"). 261 Proxies MAY modify the value of the BH header field to be "0", or 262 insert a BH header field with the value "0" if it is not present. 263 Proxies MUST NOT modify a response so that the BH header field is "1" 264 where it was previously not. 266 5. Pre-defined Browser Hints 268 5.1. max-conns 270 o Browser Hint Name: max-conns 271 o Description: When present, this hint indicates the maximum number 272 of concurrent persistent connections that the site would like 273 clients to use. 274 o Value Type: number 275 o Contact: mnot@mnot.net 276 o Notes: Not to be used when there is evidence of a proxy. 278 5.2. pconn-ip 279 o Browser Hint Name: pconn-ip 280 o Description: When true, this hint indicates that the site allows 281 clients to reuse persistent connections keyed by IP address, 282 rather than by hostname. Note that all sites that are sharing the 283 connection MUST declare this hint for it to be used, and if a 284 transport-layer certificate is in use (e.g., for TLS [RFC5246]), 285 it MUST be valid for all sites. 286 o Value Type: true | false 287 o Contact: mnot@mnot.net 288 o Specification: [this document] 289 o Notes: Not to be used when there is evidence of a proxy. 291 In other words, if both www.example.com and foo.example.org resolve 292 to the address 192.0.2.5, and indicate this hint, then clients can 293 send a request to www.example.com and then a request to 294 foo.example.org on the same TCP connection to that address. 296 If any of the sites grouped together for the purposes of pconn-ip 297 declare a max-conns hint, the max-conns value for that address is 298 considered to be the maximum of the declared max-conn hints present. 300 5.3. ip-balance 302 o Browser Hint Name: ip-balance 303 o Description: When present, this hint indicates a preferred policy 304 for clients to handle a DNS lookup that return multiple IPv4 305 addresses for the site. 306 o Value Type: string 307 o Contact: mnot@mnot.net 308 o Notes: Not to be used when there is evidence of a proxy. 310 Defined values include: 312 o round-robin - Use each IP address in succession, using the next 313 address each time a new connection is opened. 314 o random - Use a random IP address from the list for each new 315 connection. 316 o failover - Use the first IP address, falling back to the following 317 address upon failure, and so forth. 318 o fastest - Attempt to connect to all IP addresses, using the 319 fastest for this and subsequent connections. 321 5.4. connect-timeout 323 o Browser Hint Name: connect-timeout 324 o Description: When present, this hint indicates how long the site 325 wishes browsers to wait for a connection to be established, in 326 seconds, before considering that connection unresponsive. 328 o Value Type: integer 329 o Contact: mnot@mnot.net 330 o Notes: Not to be used when there is evidence of a proxy. 332 5.5. read-timeout 334 o Browser Hint Name: read-timeout 335 o Description: When present, this hint indicates how long the site 336 wishes browsers to wait before considering a connection 337 unresponsive, when data is outstanding (either a response or part 338 thereof), in seconds. 339 o Value Type: integer 340 o Contact: mnot@mnot.net 342 Note that requests on timed-out connections can be retried, subject 343 to the constraints of HTTP. 345 5.6. max-pipeline-depth 347 o Browser Hint Name: max-pipeline-depth 348 o Description: When present, this hint indicates the maximum number 349 of pipelined requests per connection that the site would like 350 clients to use. 351 o Value Type: number 352 o Contact: mnot@mnot.net 353 o Notes: Not to be used when there is evidence of a proxy. 355 5.7. small-hdrs 357 o Browser Hint Name: small-hdrs 358 o Description: When true, this hint indicates that clients can omit 359 the Accept and Accept-Charset request headers when communicating 360 with the resource, and that they can use a shortened version of 361 the User-Agent header. 362 o Value Type: prefixlist 363 o Contact: mnot@mnot.net 365 5.8. relative-referer 367 o Browser Hint Name: relative-referer 368 o Description: When true, this hint indicates that servers prefer a 369 relative URI in the Referer request header. 370 o Value Type: true | false 371 o Contact: mnot@mnot.net 373 5.9. chunk-req-bodies 375 o Browser Hint Name: chunk-req-bodies 376 o Description: When true, this hint indicates that the server can 377 successfully process a request with a chunk-encoded body; i.e., 378 that it should not return a 411 Length Required status. Note that 379 clients may still encounter a 411 response status, even in when 380 this hint is present (e.g., a proxy). When false, the server may 381 or may not require a Content-Length on requests with bodies. 382 o Value Type: true | false 383 o Contact: mnot@mnot.net 385 5.10. omit-cookies 387 o Browser Hint Name: omit-cookies 388 o Description: When true, this hint indicates that cookies [RFC6265] 389 can be omitted in requests. 390 o Value Type: prefixlist 391 o Contact: mnot@mnot.net 393 5.11. cookie-whitelist 395 o Browser Hint Name: cookie-whitelist 396 o Description: When present, indicates that the browser can omit any 397 cookie [RFC6265] whose cookie-name is not a member of the value 398 array. 399 o Value Type: array 400 o Contact: mnot@mnot.net 402 6. Security Considerations 404 TBD 406 7. IANA Considerations 408 7.1. The 'browser-hints' Well-Known URI 410 This document defines the "browser-hints" Well-Known URI [RFC5785]. 412 o URI suffix: browser-hints 413 o Change controller: mnot@mnot.net 414 o Specification document(s): [this document] 415 o Related information: 417 7.2. The BH HTTP Response Header Field 419 This document defines the "BH" HTTP header field, and registers it in 420 the Permanent Message Headers registry. 422 o Header field name: BH 423 o Applicable protocol: HTTP 424 o Status: Informational 425 o Author/Change controller: Mark Nottingham, mnot@mnot.net 426 o Specification document(s): [this document] 427 o Related information: 429 7.3. The HTTP Browser Hints Registry 431 This document establishes the HTTP Browser Hints Registry. 433 New hints are registered First Come First Served (see [RFC5226]), by 434 sending e-mail to (or using other mechanisms, 435 as established by IANA). 437 Registration requests MUST use the following template: 439 o Browser Hint Name: [name of hint] 440 o Description: [description of hint] 441 o Value Type: [JSON value type] 442 o Contact: [e-mail address(es)] 443 o Specification: [optional; reference or URI to more info] 444 o Notes: [optional] 446 New hints MUST be optional; they cannot place requirements upon 447 implementations. 449 Likewise, new hints MUST be relevant to browser use cases; other non- 450 browsing hints and metadata would make the hints response undesirably 451 large. However, note that non-browser clients MAY use them. 453 Finally, new hints MUST NOT make communication non-conformant with 454 HTTP itself; i.e., this is not a mechanism for changing the HTTP 455 protocol in incompatible ways. For example, if a hint indicates that 456 browsers can compress request headers using GZIP, intermediaries that 457 are interposed are likely to fail. 459 The initial contents of the registry are defined in Section 5. 461 8. References 462 8.1. Normative References 464 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 465 Requirement Levels", BCP 14, RFC 2119, March 1997. 467 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 468 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 469 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 471 [RFC4627] Crockford, D., "The application/json Media Type for 472 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 474 8.2. Informative References 476 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 477 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 478 May 2008. 480 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 481 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 483 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 484 Uniform Resource Identifiers (URIs)", RFC 5785, 485 April 2010. 487 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 488 April 2011. 490 Appendix A. Acknowledgements 492 Thanks to Mike Belshe, Artur Bergman, Jason Duell, Poul-Henning Kamp, 493 Anirban Kundu, Patrick McManus, Steve Souders, and Martin Thompson 494 for their suggestions and feedback. 496 The author takes all responsibility for errors and omissions. 498 Author's Address 500 Mark Nottingham 502 Email: mnot@mnot.net 503 URI: http://www.mnot.net/