idnits 2.17.00 (12 Aug 2021) /tmp/idnits53479/draft-nottingham-http-browser-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 : ---------------------------------------------------------------------------- -- 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 (June 20, 2012) is 3621 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 June 20, 2012 4 Intended status: Informational 5 Expires: December 22, 2012 7 HTTP Browser Hints 8 draft-nottingham-http-browser-hints-03 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 Status of this Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on December 22, 2012. 42 Copyright Notice 44 Copyright (c) 2012 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3. A file format for Browser Hints . . . . . . . . . . . . . . . 3 62 3.1. The 'prefixlist' Value Type . . . . . . . . . . . . . . . 4 63 4. Discovering Browser Hints for a Web site . . . . . . . . . . . 4 64 5. Pre-defined Browser Hints . . . . . . . . . . . . . . . . . . 5 65 5.1. max-conns . . . . . . . . . . . . . . . . . . . . . . . . 5 66 5.2. pconn-ip . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 5.3. ip-balance . . . . . . . . . . . . . . . . . . . . . . . . 6 68 5.4. connect-timeout . . . . . . . . . . . . . . . . . . . . . 6 69 5.5. read-timeout . . . . . . . . . . . . . . . . . . . . . . . 6 70 5.6. max-pipeline-depth . . . . . . . . . . . . . . . . . . . . 7 71 5.7. small-hdrs . . . . . . . . . . . . . . . . . . . . . . . . 7 72 5.8. relative-referer . . . . . . . . . . . . . . . . . . . . . 7 73 5.9. chunk-req-bodies . . . . . . . . . . . . . . . . . . . . . 7 74 5.10. omit-cookies . . . . . . . . . . . . . . . . . . . . . . . 8 75 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 76 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 77 7.1. The 'browser-hints' Well-Known URI . . . . . . . . . . . . 8 78 7.2. The HTTP Browser Hints Registry . . . . . . . . . . . . . 8 79 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 80 8.1. Normative References . . . . . . . . . . . . . . . . . . . 9 81 8.2. Informative References . . . . . . . . . . . . . . . . . . 9 82 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 85 1. Introduction 87 HTTP [RFC2616] clients -- especially browsers -- typically use 88 hardcoded values or heuristics to determine how many TCP connections 89 to use to a server, based on common-case server behaviours and 90 limitations. 92 Likewise, they often send voluminous request headers (e.g., in User- 93 Agent and Allow) because they fear that changing those headers' 94 values will break some sites that depend upon specific values. 96 These are just two examples of common, conservative behaviour by 97 browsers that is good for interoperability, but potentially bad for 98 performance in certain circumstances. 100 This memo proposes a mechanism whereby a HTTP server can advertise 101 hints for browsers (and other clients), so that communication with 102 them can be optimised. 104 It does so by defining a file format for such Browser Hints 105 Section 3, and defining how clients can discover it for a given Web 106 site Section 4. Finally, an extensible vocabulary of hints is 107 defined Section 5. 109 Feedback for this draft should take place on the 110 apps-discuss@ietf.org mailing list 111 . 113 2. Requirements 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 3. A file format for Browser Hints 121 Browser hints are indicating using a JSON [RFC4627] formatted file, 122 containing a single object whose member's names are browser hints, as 123 defined by the registry Section 7.2. 125 For example; 127 { 128 "max-conns": 5, 129 "small-hdrs": true 130 } 132 By their nature, all browser hints are optional; i.e., browsers are 133 free to ignore them. 135 3.1. The 'prefixlist' Value Type 137 Each browser hint is defined to have a JSON-derived value type; e.g., 138 'string' or 'array'. This section defines a special value type, 139 'prefixlist' that is an array containing one or more arrays, each 140 containing a path prefix followed by either 'true' or 'false' to 141 indicate whether the hint applies to that path. 143 Prefixlists are evaluated in order, with the first case-sensitive, 144 character-by-character prefix match for a given URI's path 145 determining whether the hint applies. 147 For example, given the following hint document: 149 { 150 "omit-cookies": [ 151 ["/images/users/", false], 152 ["/images/", true] 153 ] 154 } 156 We can tell that "omit-cookies" applies to resources under the 157 "/images/" path (such as "/images/123.jpg"), except for those under 158 "/images/users/" (such as "/images/users/bob.jpg"). 160 If a value specified to be a prefixlist is either 'true' or 'false' 161 that indicates that the hint applies to the whole site, or does not 162 apply to the whole site, respectively. 164 For example, 166 { 167 "omit-cookies": true 168 } 170 Indicates that the "omit-cookies" hint applies to the entire site. 172 Prefixlists can only be used when the browser hint's registration 173 nominates their use. 175 4. Discovering Browser Hints for a Web site 177 The hints relevant to a given site can be determined by fetching the 178 URI path "/.well-known/browser-hints" for that site. 180 Typically, clients (especially browsers) will not block other 181 requests to a site while fetching the browser hints (because they're 182 optional); instead, it will usually be done concurrently with other 183 requests, or on idle connections for future use. 185 In this specification, "site" is scoped by the URI scheme and 186 authority. As such, all of the following are considered to be 187 different sites, and therefore have different browser hints: 189 o http://foo.com/ 190 o https://foo.com/ 191 o http://foo.com:8000/ 192 o http://www.foo.com/ 194 Clients SHOULD follow HTTP 3xx redirects when retrieving hints. 196 A successful response is valid for its associated site for as long as 197 it can be cached in HTTP. 199 If the response has a 200 status code but no explicit freshness 200 (e.g., a Cache-Control: max-age or Expires: header), clients SHOULD 201 cache the response heuristically for a generous fixed period (e.g., 202 14 days). 204 If the response has a 404 status code but no explicit freshness, 205 clients SHOULD cache the response heuristically for a generous fixed 206 period (e.g., 14 days). 208 5. Pre-defined Browser Hints 210 5.1. max-conns 212 o Browser Hint Name: max-conns 213 o Description: When present, this hint indicates the maximum number 214 of concurrent persistent connections that the site would like 215 clients to use. 216 o Value Type: number 217 o Contact: mnot@mnot.net 219 5.2. pconn-ip 221 o Browser Hint Name: pconn-ip 222 o Description: When true, this hint indicates that the site allows 223 clients to reuse persistent connections keyed by IP address, 224 rather than by hostname. Note that all sites that are sharing the 225 connection MUST declare this hint for it to be used, and if a 226 transport-layer certificate is in use (e.g., for TLS [RFC5246]), 227 it MUST be valid for all sites. 228 o Value Type: true | false 229 o Contact: mnot@mnot.net 230 o Specification: [this document] 232 In other words, if both www.example.com and foo.example.org resolve 233 to the address 192.0.2.5, and indicate this hint, then clients can 234 send a request to www.example.com and then a request to 235 foo.example.org on the same TCP connection to that address. 237 If any of the sites grouped together for the purposes of pconn-ip 238 declare a max-conns hint, the max-conns value for that address is 239 considered to be the maximum of the declared max-conn hints present. 241 5.3. ip-balance 243 o Browser Hint Name: ip-balance 244 o Description: When present, this hint indicates a preferred policy 245 for clients to handle a DNS lookup that return multiple IPv4 246 addresses for the site. 247 o Value Type: string 248 o Contact: mnot@mnot.net 250 Defined values include: 252 o round-robin - Use each IP address in succession, using the next 253 address each time a new connection is opened. 254 o random - Use a random IP address from the list for each new 255 connection. 256 o failover - Use the first IP address, falling back to the following 257 address upon failure, and so forth. 258 o fastest - Attempt to connect to all IP addresses, using the 259 fastest for this and subsequent connections. 261 5.4. connect-timeout 263 o Browser Hint Name: connect-timeout 264 o Description: When present, this hint indicates how long the site 265 wishes browsers to wait for a connection to be established, in 266 seconds, before considering that connection unresponsive. 267 o Value Type: integer 268 o Contact: mnot@mnot.net 270 5.5. read-timeout 272 o Browser Hint Name: read-timeout 273 o Description: When present, this hint indicates how long the site 274 wishes browsers to wait before considering a connection 275 unresponsive, when data is outstanding (either a response or part 276 thereof), in seconds. 277 o Value Type: integer 278 o Contact: mnot@mnot.net 280 Note that requests on timed-out connections can be retried, subjects 281 to the constraints of HTTP. 283 5.6. max-pipeline-depth 285 o Browser Hint Name: max-pipeline-depth 286 o Description: When present, this hint indicates the maximum number 287 of pipelined requests per connection that the site would like 288 clients to use. 289 o Value Type: number 290 o Contact: mnot@mnot.net 292 5.7. small-hdrs 294 o Browser Hint Name: small-hdrs 295 o Description: When true, this hint indicates that clients can omit 296 the Accept and Accept-Charset request headers when communicating 297 with the resource, and that they can use a shortened version of 298 the User-Agent header. 299 o Value Type: prefixlist 300 o Contact: mnot@mnot.net 302 5.8. relative-referer 304 o Browser Hint Name: relative-referer 305 o Description: When true, this hint indicates that servers prefer a 306 relative URI in the Referer request header. 307 o Value Type: true | false 308 o Contact: mnot@mnot.net 310 5.9. chunk-req-bodies 312 o Browser Hint Name: chunk-req-bodies 313 o Description: When true, this hint indicates that the server can 314 successfully process a request with a chunk-encoded body; i.e., 315 that it should not return a 411 Length Required status. Note that 316 clients may still require a 411 response status, even in when this 317 hint is present. When false, the server may or may not require a 318 Content-Length on requests with bodies. 320 o Value Type: true | false 321 o Contact: mnot@mnot.net 323 5.10. omit-cookies 325 o Browser Hint Name: omit-cookies 326 o Description: When true, this hint indicates that cookies [RFC6265] 327 can be omitted in requests. 328 o Value Type: prefixlist 329 o Contact: mnot@mnot.net 331 6. Security Considerations 333 TBD 335 7. IANA Considerations 337 7.1. The 'browser-hints' Well-Known URI 339 This document defines the "browser-hints" Well-Known URI [RFC5785]. 341 o URI suffix: browser-hints 342 o Change controller: mnot@mnot.net 343 o Specification document(s): [this document] 344 o Related information: 346 7.2. The HTTP Browser Hints Registry 348 This document establishes the HTTP Browser Hints Registry. 350 New hints are registered First Come First Served (see [RFC5226]), by 351 sending e-mail to (or using other mechanisms, 352 as established by IANA). 354 Registration requests MUST use the following template: 356 o Browser Hint Name: [name of hint] 357 o Description: [description of hint] 358 o Value Type: [JSON value type] 359 o Contact: [e-mail address(es)] 360 o Specification: [optional; reference or URI to more info] 362 New hints MUST be optional; they cannot place requirements upon 363 implementations. 365 Likewise, new hints MUST be relevant to browser use cases; other non- 366 browsing hints and metadata would make the hints response undesirably 367 large. However, note that non-browser clients MAY use them. 369 Finally, new hints MUST NOT make communication non-conformant with 370 HTTP itself; i.e., this is not a mechanism for changing the HTTP 371 protocol in incompatible ways. For example, if a hint indicates that 372 browsers can compress request headers using GZIP, intermediaries that 373 are interposed are likely to fail. 375 The initial contents of the registry are defined in Section 5. 377 8. References 379 8.1. Normative References 381 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 382 Requirement Levels", BCP 14, RFC 2119, March 1997. 384 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 385 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 386 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 388 [RFC4627] Crockford, D., "The application/json Media Type for 389 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 391 8.2. Informative References 393 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 394 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 395 May 2008. 397 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 398 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 400 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 401 Uniform Resource Identifiers (URIs)", RFC 5785, 402 April 2010. 404 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 405 April 2011. 407 Appendix A. Acknowledgements 409 Thanks to Mike Belshe, Artur Bergman, Poul-Henning Kamp, Anirban 410 Kundu, Patrick McManus, Steve Souders, and Martin Thompson for their 411 suggestions and feedback. 413 The author takes all responsibility for errors and omissions. 415 Author's Address 417 Mark Nottingham 419 Email: mnot@mnot.net 420 URI: http://www.mnot.net/