idnits 2.17.00 (12 Aug 2021) /tmp/idnits53049/draft-nottingham-http-browser-hints-02.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 31, 2011) is 4007 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 31, 2011 4 Intended status: Informational 5 Expires: December 2, 2011 7 HTTP Browser Hints 8 draft-nottingham-http-browser-hints-02 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 2, 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 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. max-pipeline-depth . . . . . . . . . . . . . . . . . . . . 6 68 5.4. small-hdrs . . . . . . . . . . . . . . . . . . . . . . . . 6 69 5.5. relative-referer . . . . . . . . . . . . . . . . . . . . . 6 70 5.6. chunk-req-bodies . . . . . . . . . . . . . . . . . . . . . 6 71 5.7. omit-cookies . . . . . . . . . . . . . . . . . . . . . . . 7 72 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 73 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 74 7.1. The 'browser-hints' Well-Known URI . . . . . . . . . . . . 7 75 7.2. The HTTP Browser Hints Registry . . . . . . . . . . . . . . 7 76 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 77 8.1. Normative References . . . . . . . . . . . . . . . . . . . 8 78 8.2. Informative References . . . . . . . . . . . . . . . . . . 8 79 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 8 80 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9 82 1. Introduction 84 HTTP [RFC2616] clients -- especially browsers -- typically use 85 hardcoded values or heuristics to determine how many TCP connections 86 to use to a server, based on common-case server behaviours and 87 limitations. 89 Likewise, they often send voluminous request headers (e.g., in User- 90 Agent and Allow) because they fear that changing those headers' 91 values will break some sites that depend upon specific values. 93 These are just two examples of common, conservative behaviour by 94 browsers that is good for interoperability, but potentially bad for 95 performance in certain circumstances. 97 This memo proposes a mechanism whereby a HTTP server can advertise 98 hints for browsers (and other clients), so that communication with 99 them can be optimised. 101 It does so by defining a file format for such Browser Hints 102 Section 3, and defining how clients can discover it for a given Web 103 site Section 4. Finally, an extensible vocabulary of hints is 104 defined Section 5. 106 Feedback for this draft should take place on the 107 apps-discuss@ietf.org mailing list 108 . 110 2. Requirements 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 114 document are to be interpreted as described in [RFC2119]. 116 3. A file format for Browser Hints 118 Browser hints are indicating using a JSON [RFC4627] formatted file, 119 containing a single object whose member's names are browser hints, as 120 defined by the registry Section 7.2. 122 For example; 124 { 125 "max-conns": 5, 126 "small-hdrs": true 127 } 129 By their nature, all browser hints are optional; i.e., browsers are 130 free to ignore them. 132 3.1. The 'prefixlist' Value Type 134 Each browser hint is defined to have a JSON-derived value type; e.g., 135 'string' or 'array'. This section defines a special value type, 136 'prefixlist' that is an array containing one or more arrays, each 137 containing a path prefix followed by either 'true' or 'false' to 138 indicate whether the hint applies to that path. 140 Prefixlists are evaluated in order, with the first case-sensitive, 141 character-by-character prefix match for a given URI's path 142 determining whether the hint applies. 144 For example, given the following hint document: 146 { 147 "omit-cookies": [ 148 ["/images/users/", false], 149 ["/images/", true] 150 ] 151 } 153 We can tell that "omit-cookies" applies to resources under the 154 "/images/" path (such as "/images/123.jpg"), except for those under 155 "/images/users/" (such as "/images/users/bob.jpg"). 157 If a value specified to be a prefixlist is either 'true' or 'false' 158 that indicates that the hint applies to the whole site, or does not 159 apply to the whole site, respectively. 161 For example, 163 { 164 "omit-cookies": true 165 } 167 Indicates that the "omit-cookies" hint applies to the entire site. 169 Prefixlists can only be used when the browser hint's registration 170 nominates their use. 172 4. Discovering Browser Hints for a Web site 174 The hints relevant to a given site can be determined by fetching the 175 URI path "/.well-known/browser-hints" for that site. 177 Typically, clients (especially browsers) will not block other 178 requests to a site while fetching the browser hints (because they're 179 optional); instead, it will usually be done concurrently with other 180 requests, or on idle connections for future use. 182 In this specification, "site" is scoped by the URI scheme and 183 authority. As such, all of the following are considered to be 184 different sites, and therefore have different browser hints: 186 o http://foo.com/ 187 o https://foo.com/ 188 o http://foo.com:8000/ 189 o http://www.foo.com/ 191 Clients SHOULD follow HTTP 3xx redirects when retrieving hints. 193 A successful response is valid for its associated site for as long as 194 it can be cached in HTTP. 196 If the response has a 200 status code but no explicit freshness 197 (e.g., a Cache-Control: max-age or Expires: header), clients SHOULD 198 cache the response heuristically for a generous fixed period (e.g., 199 14 days). 201 If the response has a 404 status code but no explicit freshness, 202 clients SHOULD cache the response heuristically for a generous fixed 203 period (e.g., 14 days). 205 5. Pre-defined Browser Hints 207 5.1. max-conns 209 o Browser Hint Name: max-conns 210 o Description: When present, this hint indicates the maximum number 211 of concurrent persistent connections that the site would like 212 clients to use. 213 o Value Type: number 214 o Contact: mnot@mnot.net 216 5.2. pconn-ip 218 o Browser Hint Name: pconn-ip 219 o Description: When true, this hint indicates that the site allows 220 clients to reuse persistent connections keyed by IP address, 221 rather than by hostname. Note that all sites that are sharing the 222 connection MUST declare this hint for it to be used, and if a 223 transport-layer certificate is in use (e.g., for TLS [RFC5246]), 224 it MUST be valid for all sites. 225 o Value Type: true | false 226 o Contact: mnot@mnot.net 227 o Specification: [this document] 229 In other words, if both www.example.com and foo.example.org resolve 230 to the address 192.0.2.5, and indicate this hint, then clients can 231 send a request to www.example.com and then a request to 232 foo.example.org on the same TCP connection to that address. 234 If any of the sites grouped together for the purposes of pconn-ip 235 declare a max-conns hint, the max-conns value for that address is 236 considered to be the maximum of the declared max-conn hints present. 238 5.3. max-pipeline-depth 240 o Browser Hint Name: max-pipeline-depth 241 o Description: When present, this hint indicates the maximum number 242 of pipelined requests per connection that the site would like 243 clients to use. 244 o Value Type: number 245 o Contact: mnot@mnot.net 247 5.4. small-hdrs 249 o Browser Hint Name: small-hdrs 250 o Description: When true, this hint indicates that clients can omit 251 the Accept and Accept-Charset request headers when communicating 252 with the resource, and that they can use a shortened version of 253 the User-Agent header. 254 o Value Type: prefixlist 255 o Contact: mnot@mnot.net 257 5.5. relative-referer 259 o Browser Hint Name: relative-referer 260 o Description: When true, this hint indicates that servers prefer a 261 relative URI in the Referer request header. 262 o Value Type: true | false 263 o Contact: mnot@mnot.net 265 5.6. chunk-req-bodies 267 o Browser Hint Name: chunk-req-bodies 268 o Description: When true, this hint indicates that the server can 269 successfully process a request with a chunk-encoded body; i.e., 270 that it should not return a 411 Length Required status. Note that 271 clients may still require a 411 response status, even in when this 272 hint is present. When false, the server may or may not require a 273 Content-Length on requests with bodies. 274 o Value Type: true | false 275 o Contact: mnot@mnot.net 277 5.7. omit-cookies 279 o Browser Hint Name: omit-cookies 280 o Description: When true, this hint indicates that cookies [RFC6265] 281 can be omitted in requests. 282 o Value Type: prefixlist 283 o Contact: mnot@mnot.net 285 6. Security Considerations 287 TBD 289 7. IANA Considerations 291 7.1. The 'browser-hints' Well-Known URI 293 This document defines the "browser-hints" Well-Known URI [RFC5785]. 295 o URI suffix: browser-hints 296 o Change controller: mnot@mnot.net 297 o Specification document(s): [this document] 298 o Related information: 300 7.2. The HTTP Browser Hints Registry 302 This document establishes the HTTP Browser Hints Registry. 304 New hints are registered First Come First Served (see [RFC5226]), by 305 sending e-mail to (or using other mechanisms, 306 as established by IANA). 308 Registration requests MUST use the following template: 310 o Browser Hint Name: [name of hint] 311 o Description: [description of hint] 312 o Value Type: [JSON value type] 313 o Contact: [e-mail address(es)] 314 o Specification: [optional; reference or URI to more info] 316 New hints MUST be optional; they cannot place requirements upon 317 implementations. 319 Likewise, new hints MUST be relevant to browser use cases; other non- 320 browsing hints and metadata would make the hints response undesirably 321 large. However, note that non-browser clients MAY use them. 323 Finally, new hints MUST NOT make communication non-conformant with 324 HTTP itself; i.e., this is not a mechanism for changing the HTTP 325 protocol in incompatible ways. For example, if a hint indicates that 326 browsers can compress request headers using GZIP, intermediaries that 327 are interposed are likely to fail. 329 The initial contents of the registry are defined in Section 5. 331 8. References 333 8.1. Normative References 335 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 336 Requirement Levels", BCP 14, RFC 2119, March 1997. 338 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 339 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 340 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 342 [RFC4627] Crockford, D., "The application/json Media Type for 343 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 345 8.2. Informative References 347 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 348 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 349 May 2008. 351 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 352 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 354 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 355 Uniform Resource Identifiers (URIs)", RFC 5785, 356 April 2010. 358 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 359 April 2011. 361 Appendix A. Acknowledgements 363 Thanks to Mike Belshe, Poul-Henning Kamp, Anirban Kundu, Patrick 364 McManus, Steve Souders, and Martin Thompson for their suggestions and 365 feedback. 367 The author takes all responsibility for errors and omissions. 369 Author's Address 371 Mark Nottingham 373 Email: mnot@mnot.net 374 URI: http://www.mnot.net/