idnits 2.17.00 (12 Aug 2021) /tmp/idnits54001/draft-nottingham-http-browser-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 : ---------------------------------------------------------------------------- -- 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 (May 27, 2011) is 4011 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 May 27, 2011 4 Intended status: Informational 5 Expires: November 28, 2011 7 HTTP Browser Hints 8 draft-nottingham-http-browser-hints-01 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 November 28, 2011. 42 Copyright Notice 44 Copyright (c) 2011 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 4. Discovering Browser Hints for a Web site . . . . . . . . . . . 4 63 5. Pre-defined Browser Hints . . . . . . . . . . . . . . . . . . . 4 64 5.1. max-conns . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 5.2. pconn-ip . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 5.3. max-pipeline-depth . . . . . . . . . . . . . . . . . . . . 5 67 5.4. small-hdrs . . . . . . . . . . . . . . . . . . . . . . . . 5 68 5.5. no-referer . . . . . . . . . . . . . . . . . . . . . . . . 5 69 5.6. send-ref . . . . . . . . . . . . . . . . . . . . . . . . . 6 70 5.7. chunk-req-bodies . . . . . . . . . . . . . . . . . . . . . 6 71 5.8. omit-cookies . . . . . . . . . . . . . . . . . . . . . . . 6 72 6. The Ref HTTP Request Header . . . . . . . . . . . . . . . . . . 6 73 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 74 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 75 8.1. The 'browser-hints' Well-Known URI . . . . . . . . . . . . 7 76 8.2. The HTTP Browser Hints Registry . . . . . . . . . . . . . . 7 77 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 78 9.1. Normative References . . . . . . . . . . . . . . . . . . . 7 79 9.2. Informative References . . . . . . . . . . . . . . . . . . 8 80 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 8 81 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 83 1. Introduction 85 HTTP [RFC2616] clients -- especially browsers -- typically use 86 hardcoded values or heuristics to determine how many TCP connections 87 to use to a server, based on common-case server behaviours and 88 limitations. 90 Likewise, they often send voluminous request headers (e.g., in User- 91 Agent and Allow) because they fear that changing those headers' 92 values will break some sites that depend upon specific values. 94 These are just two examples of common, conservative behaviour by 95 browsers that is good for interoperability, but potentially bad for 96 performance in certain circumstances. 98 This memo proposes a mechanism whereby a HTTP server can advertise 99 hints for browsers (and other clients), so that communication with 100 them can be optimised. 102 It does so by defining a file format for such Browser Hints 103 Section 3, and defining how clients can discover it for a given Web 104 site Section 4. Finally, an extensible vocabulary of hints is 105 defined Section 5. 107 Feedback for this draft should take place on the 108 apps-discuss@ietf.org mailing list 109 . 111 2. Requirements 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 115 document are to be interpreted as described in [RFC2119]. 117 3. A file format for Browser Hints 119 Browser hints are indicating using a JSON [RFC4627] formatted file, 120 containing a single object whose member's names are browser hints, as 121 defined by the registry Section 8.2. 123 For example; 125 { 126 "max-conns": 5, 127 "small-hdrs": true 128 } 130 By their nature, all browser hints are optional; i.e., browsers are 131 free to ignore them. 133 4. Discovering Browser Hints for a Web site 135 The hints relevant to a given site can be determined by fetching the 136 URI path "/.well-known/browser-hints" for that site. 138 Typically, clients (especially browsers) will not block other 139 requests to a site while fetching the browser hints (because they're 140 optional); instead, it will usually be done concurrently with other 141 requests, or on idle connections for future use. 143 In this specification, "site" is scoped by the URI scheme and 144 authority. As such, all of the following are considered to be 145 different sites, and therefore have different browser hints: 147 o http://foo.com/ 148 o https://foo.com/ 149 o http://foo.com:8000/ 150 o http://www.foo.com/ 152 Clients SHOULD follow HTTP 3xx redirects when retrieving hints. 154 A successful response is valid for its associated site for as long as 155 it can be cached in HTTP. 157 If the response has a 200 status code but no explicit freshness 158 (e.g., a Cache-Control: max-age or Expires: header), browsers SHOULD 159 cache the response heuristically for a generous fixed period (e.g., 160 30 days). 162 5. Pre-defined Browser Hints 164 5.1. max-conns 166 o Browser Hint Name: max-conns 167 o Description: When present, this hint indicates the maximum number 168 of concurrent persistent connections that the site would like 169 clients to use. 170 o Value Type: number 171 o Contact: mnot@mnot.net 173 5.2. pconn-ip 175 o Browser Hint Name: pconn-ip 176 o Description: When true, this hint indicates that the site allows 177 clients to reuse persistent connections keyed by IP address, 178 rather than by hostname. Note that all sites that are sharing the 179 connection MUST declare this hint for it to be used, and if a 180 transport-layer certificate is in use (e.g., for TLS [RFC5246]), 181 it MUST be valid for all sites. 182 o Value Type: true | false 183 o Contact: mnot@mnot.net 184 o Specification: [this document] 186 In other words, if both www.example.com and foo.example.org resolve 187 to the address 192.0.2.5, and indicate this hint, then clients can 188 send a request to www.example.com and then a request to 189 foo.example.org on the same TCP connection to that address. 191 If any of the sites grouped together for the purposes of pconn-ip 192 declare a max-conns hint, the max-conns value for that address is 193 considered to be the maximum of the declared max-conn hints present. 195 5.3. max-pipeline-depth 197 o Browser Hint Name: max-pipeline-depth 198 o Description: When present, this hint indicates the maximum number 199 of pipelined requests per connection that the site would like 200 clients to use. 201 o Value Type: number 202 o Contact: mnot@mnot.net 204 5.4. small-hdrs 206 o Browser Hint Name: small-hdrs 207 o Description: When true, this hint indicates that clients can omit 208 the Accept and Accept-Charset request headers when communicating 209 with the site, and that they can use a shortened version of the 210 User-Agent header. 211 o Value Type: true | false 212 o Contact: mnot@mnot.net 214 5.5. no-referer 216 o Browser Hint Name: no-referer 217 o Description: When true, this hint indicates that clients can omit 218 the Referer HTTP request header when sending requests to the site. 220 o Value Type: true | false 221 o Contact: mnot@mnot.net 223 5.6. send-ref 225 o Browser Hint Name: send-ref 226 o Description: When true, this hint indicates that clients can omit 227 the Referer HTTP request header when sending requests to the site, 228 if they instead send a Ref HTTP request header (see Section 6). 229 o Value Type: true | false 230 o Contact: mnot@mnot.net 232 5.7. chunk-req-bodies 234 o Browser Hint Name: chunk-req-bodies 235 o Description: When true, this hint indicates that the server can 236 successfully process a request with a chunk-encoded body; i.e., 237 that it should not return a 411 Length Required status. Note that 238 clients may still require a 411 response status, even in when this 239 hint is present. When false, the server may or may not require a 240 Content-Length on requests with bodies. 241 o Value Type: true | false 242 o Contact: mnot@mnot.net 244 5.8. omit-cookies 246 o Browser Hint Name: omit-cookies 247 o Description: This hint contains a list of cookie [RFC6265] cookie- 248 names which can be omitted in requests sent to this site. 249 o Value Type: Array of strings 250 o Contact: mnot@mnot.net 252 6. The Ref HTTP Request Header 254 TBD: relative URI referer header 256 7. Security Considerations 258 TBD 260 8. IANA Considerations 261 8.1. The 'browser-hints' Well-Known URI 263 This document defines the "browser-hints" Well-Known URI [RFC5785]. 265 o URI suffix: browser-hints 266 o Change controller: mnot@mnot.net 267 o Specification document(s): [this document] 268 o Related information: 270 8.2. The HTTP Browser Hints Registry 272 This document establishes the HTTP Browser Hints Registry. 274 New hints are registered First Come First Served (see [RFC5226]), by 275 sending e-mail to (or using other mechanisms, 276 as established by IANA). 278 Registration requests MUST use the following template: 280 o Browser Hint Name: [name of hint] 281 o Description: [description of hint] 282 o Value Type: [JSON value type] 283 o Contact: [e-mail address(es)] 284 o Specification: [optional; reference or URI to more info] 286 New hints MUST be optional; they cannot place requirements upon 287 implementations. 289 Likewise, new hints MUST be relevant to browser use cases; other non- 290 browsing hints and metadata would make the hints response undesirably 291 large. However, note that non-browser clients MAY use them. 293 Finally, new hints MUST NOT make communication non-conformant with 294 HTTP itself; i.e., this is not a mechanism for changing the HTTP 295 protocol in incompatible ways. For example, if a hint indicates that 296 browsers can compress request headers using GZIP, intermediaries that 297 are interposed are likely to fail. 299 The initial contents of the registry are defined in Section 5. 301 9. References 303 9.1. Normative References 305 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 306 Requirement Levels", BCP 14, RFC 2119, March 1997. 308 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 309 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 310 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 312 [RFC4627] Crockford, D., "The application/json Media Type for 313 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 315 9.2. Informative References 317 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 318 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 319 May 2008. 321 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 322 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 324 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 325 Uniform Resource Identifiers (URIs)", RFC 5785, 326 April 2010. 328 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 329 April 2011. 331 Appendix A. Acknowledgements 333 Thanks to Mike Belshe, Poul-Henning Kamp, Anirban Kundu, Patrick 334 McManus, and Steve Souders for their suggestions and feedback. 336 The author takes all responsibility for errors and omissions. 338 Author's Address 340 Mark Nottingham 342 Email: mnot@mnot.net 343 URI: http://www.mnot.net/