]>

mnot@mnot.net http://www.mnot.net/

Over time, Web browsers have adapted how they use HTTP based upon common server configurations and behaviours. While this is necessary in the common case, it can be detrimental for performance and interoperability. This document establishes a mechanism whereby origin servers can make available hints for browsers about their preferences and capabilities, without imposing overhead on their interactions or requiring support for them. This is intended to allow browsers to safely optimise connections to servers.

HTTP clients -- especially browsers -- typically use hardcoded values or heuristics to determine how many TCP connections to use to a server, based on common-case server behaviours and limitations. Likewise, they often send voluminous request headers (e.g., in User-Agent and Allow) because they fear that changing those headers' values will break some sites that depend upon specific values. These are just two examples of common, conservative behaviour by browsers that is good for interoperability, but potentially bad for performance in certain circumstances. This memo proposes a mechanism whereby a HTTP server can advertise hints for browsers (and other clients), so that communication with them can be optimised. It does so by defining a file format for such Browser Hints , and defining how clients can discover it for a given Web site . Finally, an extensible vocabulary of hints is defined . Feedback for this draft should take place on the apps-discuss@ietf.org mailing list .

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

Browser hints are indicating using a JSON formatted file, containing a single object whose member's names are browser hints, as defined by the registry . For example;

{ "max-conns": 5, "small-hdrs": true }

By their nature, all browser hints are optional; i.e., browsers are free to ignore them.

The hints relevant to a given site can be determined by fetching the URI path "/.well-known/browser-hints" for that site. Typically, clients (especially browsers) will not block other requests to a site while fetching the browser hints (because they're optional); instead, it will usually be done concurrently with other requests, or on idle connections for future use. In this specification, "site" is scoped by the URI scheme and authority. As such, all of the following are considered to be different sites, and therefore have different browser hints: http://foo.com/ https://foo.com/ http://foo.com:8000/ http://www.foo.com/ Clients SHOULD follow HTTP 3xx redirects when retrieving hints. A successful response is valid for its associated site for as long as it can be cached in HTTP. If the response has a 200 status code but no explicit freshness (e.g., a Cache-Control: max-age or Expires: header), browsers SHOULD cache the response heuristically for a generous fixed period (e.g., 30 days).

Browser Hint Name: max-conns Description: When present, this hint indicates the maximum number of concurrent persistent connections that the site would like clients to use. Value Type: number Contact: mnot@mnot.net

Browser Hint Name: pconn-ip Description: When true, this hint indicates that the site allows clients to reuse persistent connections keyed by IP address, rather than by hostname. Note that all sites that are sharing the connection MUST declare this hint for it to be used, and if a transport-layer certificate is in use (e.g., for TLS ), it MUST be valid for all sites. Value Type: true | false Contact: mnot@mnot.net Specification: [this document] In other words, if both www.example.com and foo.example.org resolve to the address 192.0.2.5, and indicate this hint, then clients can send a request to www.example.com and then a request to foo.example.org on the same TCP connection to that address. If any of the sites grouped together for the purposes of pconn-ip declare a max-conns hint, the max-conns value for that address is considered to be the maximum of the declared max-conn hints present.

Browser Hint Name: max-pipeline-depth Description: When present, this hint indicates the maximum number of pipelined requests per connection that the site would like clients to use. Value Type: number Contact: mnot@mnot.net

Browser Hint Name: small-hdrs Description: When true, this hint indicates that clients can omit the Accept and Accept-Charset request headers when communicating with the site, and that they can use a shortened version of the User-Agent header. Value Type: true | false Contact: mnot@mnot.net

Browser Hint Name: no-referer Description: When true, this hint indicates that clients can omit the Referer HTTP request header when sending requests to the site. Value Type: true | false Contact: mnot@mnot.net

Browser Hint Name: send-ref Description: When true, this hint indicates that clients can omit the Referer HTTP request header when sending requests to the site, if they instead send a Ref HTTP request header (see ). Value Type: true | false Contact: mnot@mnot.net

TBD: relative URI referer header

TBD

This document defines the "browser-hints" Well-Known URI . URI suffix: browser-hints Change controller: mnot@mnot.net Specification document(s): [this document] Related information:

This document establishes the HTTP Browser Hints Registry. New hints are registered First Come First Served (see ), by sending e-mail to (or using other mechanisms, as established by IANA). Registration requests MUST use the following template: Browser Hint Name: [name of hint] Description: [description of hint] Value Type: [JSON value type] Contact: [e-mail address(es)] Specification: [optional; reference or URI to more info] New hints MUST be optional; they cannot place requirements upon implementations. Likewise, new hints MUST be relevant to browser use cases; other non-browsing hints and metadata would make the hints response undesirably large. However, note that non-browser clients MAY use them. Finally, new hints MUST NOT make communication non-conformant with HTTP itself; i.e., this is not a mechanism for changing the HTTP protocol in incompatible ways. For example, if a hint indicates that browsers can compress request headers using GZIP, intermediaries that are interposed are likely to fail. The initial contents of the registry are defined in .

&rfc2119; &rfc2616; &rfc4627; &rfc5226; &rfc5246; &rfc5785;

Thanks to Mike Belshe, Anirban Kundu, Patrick McManus, and Steve Souders for their suggestions and feedback. The author takes all responsibility for errors and omissions.