Skip to content

Commit 404dc3a

Browse files
igrigorikannevk
igrigorik
authored and
annevk
committed
Support HTTP Client Hints
This makes the following changes to the Fetch Standard: * DPR, Save-Data, Viewport-Width are sent on navigation requests * Subresource requests are subject to the set client hints policy * Client Hints headers are treated as (CORS) simple headers: each Client Hints header has a BNF grammar that must be validated by the user agent. Fixes #52 and fixes httpwg/http-extensions#141.
1 parent 667ca32 commit 404dc3a

File tree

2 files changed

+203
-19
lines changed

2 files changed

+203
-19
lines changed

‎Overview.html

Lines changed: 106 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
<p><a class="logo" href="https://whatwg.org/"><img alt="WHATWG" height="100" src="https://resources.whatwg.org/logo-fetch.svg" width="100"></a>
99
<h1 id="cors">Fetch</h1>
10-
<h2 class="no-num no-toc" id="living-standard-—-last-updated-5-april-2016">Living Standard — Last Updated 5 April 2016</h2>
10+
<h2 class="no-num no-toc" id="living-standard-—-last-updated-10-april-2016">Living Standard — Last Updated 10 April 2016</h2>
1111

1212
<dl>
1313
<dt>Participate:
@@ -60,9 +60,10 @@ <h2 class="no-num no-toc" id="table-of-contents">Table of Contents</h2>
6060
<li><a href="#should-response-to-request-be-blocked-due-to-mime-type?"><span class="secno">3.6 </span>Should
6161
<var>response</var> to <var>request</var> be blocked due to its MIME type?</a></li>
6262
<li><a href="#referrer-policies"><span class="secno">3.7 </span>Referrer policies</a></li>
63-
<li><a href="#streams"><span class="secno">3.8 </span>Streams</a>
63+
<li><a href="#client-hints-list"><span class="secno">3.8 </span>Client hints list</a></li>
64+
<li><a href="#streams"><span class="secno">3.9 </span>Streams</a>
6465
<ol>
65-
<li><a href="#readablestream"><span class="secno">3.8.1 </span>ReadableStream</a></ol></ol></li>
66+
<li><a href="#readablestream"><span class="secno">3.9.1 </span>ReadableStream</a></ol></ol></li>
6667
<li><a href="#http-extensions"><span class="secno">4 </span>HTTP extensions</a>
6768
<ol>
6869
<li><a href="#origin-header"><span class="secno">4.1 </span>`<code title="">Origin</code>` header</a></li>
@@ -393,17 +394,35 @@ <h4 id="terminology-headers"><span class="secno">3.1.2 </span>Headers</h4>
393394
<hr>
394395

395396
<p>A <dfn id="simple-header">simple header</dfn> is a <a href="#concept-header" title="concept-header">header</a> whose
396-
<a href="#concept-header-name" title="concept-header-name">name</a> is `<code title="">Accept</code>`,
397-
`<code title="">Accept-Language</code>`, or `<code title="">Content-Language</code>`, or whose
398-
<a href="#concept-header-name" title="concept-header-name">name</a> is `<code title="">Content-Type</code>` and
399-
<a href="#concept-header-value" title="concept-header-value">value</a>, <a href="#concept-header-parse" title="concept-header-parse">once parsed</a>,
400-
has a MIME type (ignoring parameters) that is
401-
`<code title="">application/x-www-form-urlencoded</code>`, `<code title="">multipart/form-data</code>`, or
402-
`<code title="">text/plain</code>`.
397+
<a href="#concept-header-name" title="concept-header-name">name</a> is one of
398+
399+
<ul class="brief">
400+
<li>`<code title="">Accept</code>`
401+
<li>`<code title="">Accept-Language</code>`
402+
<li>`<code title="">Content-Language</code>`
403+
<li>`<code title="">Content-Type</code>` and whose <a href="#concept-header-value" title="concept-header-value">value</a>,
404+
<a href="#concept-header-parse" title="concept-header-parse">once parsed</a>, has a MIME type (ignoring parameters)
405+
that is `<code title="">application/x-www-form-urlencoded</code>`,
406+
`<code title="">multipart/form-data</code>`, or `<code title="">text/plain</code>`
407+
</ul>
408+
403409
<!-- XXX * needs better xref
404410
* ignoring parameters has been the standard for a long time now
405411
* interesting test: "Content-Type: text/plain;" -->
406412

413+
<p>or whose <a href="#concept-header-name" title="concept-header-name">name</a> is one of
414+
415+
<ul class="brief">
416+
<li>`<code title=""><a href="http://httpwg.org/http-extensions/client-hints.html#dpr">DPR</a></code>`
417+
<li>`<code title=""><a href="http://httpwg.org/http-extensions/client-hints.html#downlink">Downlink</a></code>`
418+
<li>`<code title=""><a href="http://httpwg.org/http-extensions/client-hints.html#save-data">Save-Data</a></code>`
419+
<li>`<code title=""><a href="http://httpwg.org/http-extensions/client-hints.html#viewport-width">Viewport-Width</a></code>`
420+
<li>`<code title=""><a href="http://httpwg.org/http-extensions/client-hints.html#width">Width</a></code>`
421+
</ul>
422+
423+
<p>and whose <a href="#concept-header-value" title="concept-header-value">value</a>,
424+
<a href="#concept-header-parse" title="concept-header-parse">once parsed</a>, is not a failure.
425+
407426
<p>A <dfn id="forbidden-header-name">forbidden header name</dfn> is a <a href="#concept-header" title="concept-header">header</a>
408427
<a href="#concept-header-name" title="concept-header-name">name</a> that is one of
409428

@@ -873,6 +892,15 @@ <h4 id="requests"><span class="secno">3.1.5 </span>Requests</h4>
873892
an <a class="external" data-anolis-spec="html" href="https://html.spec.whatwg.org/multipage/webappapis.html#environment-settings-object">environment settings object</a>.
874893
<a href="#refsREFERRER">[REFERRER]</a>
875894

895+
<p>A <a href="#concept-request" title="concept-request">request</a> has an associated
896+
<dfn id="concept-request-client-hints-list" title="concept-request-client-hints-list">client hints list</dfn>, which is a
897+
<a href="#concept-client-hints-list" title="concept-client-hints-list">client-hints list</a>. Unless stated otherwise, it is
898+
the empty list.
899+
900+
<p class="note no-backref">This will be used to override a client hints list associated with
901+
an <a class="external" data-anolis-spec="html" href="https://html.spec.whatwg.org/multipage/webappapis.html#environment-settings-object">environment settings object</a>.
902+
<a href="#refsCLIENT-HINTS">[CLIENT-HINTS]</a>
903+
876904
<p>A <a href="#concept-request" title="concept-request">request</a> has an associated
877905
<dfn id="synchronous-flag">synchronous flag</dfn>. Unless stated otherwise it is unset.
878906

@@ -1456,11 +1484,24 @@ <h3 id="referrer-policies"><span class="secno">3.7 </span>Referrer policies</h3>
14561484
<a href="#refsREFERRER">[REFERRER]</a>
14571485

14581486

1459-
<h3 id="streams"><span class="secno">3.8 </span>Streams</h3>
1487+
<h3 id="client-hints-list"><span class="secno">3.8 </span>Client hints list</h3>
1488+
1489+
<p class="note">This section will be integrated into HTTP Client Hints.
1490+
<a href="#refsCLIENT-HINTS">[CLIENT-HINTS]</a>
1491+
<!-- XXX -->
1492+
1493+
<p>A <dfn id="concept-client-hints-list" title="concept-client-hints-list">client hints list</dfn> is a list of
1494+
<a href="http://httpwg.org/http-extensions/client-hints.html#accept-ch">Client hint tokens</a>,
1495+
each of which is one of `<code title="">dpr</code>`,
1496+
`<code title="">save-data</code>`, `<code title="">viewport-width</code>`, or
1497+
`<code title="">width</code>`.
1498+
1499+
1500+
<h3 id="streams"><span class="secno">3.9 </span>Streams</h3>
14601501

14611502
<p class="note no-backref">This section might be integrated into other standards, such as IDL.
14621503

1463-
<h4 id="readablestream"><span class="secno">3.8.1 </span>ReadableStream</h4>
1504+
<h4 id="readablestream"><span class="secno">3.9.1 </span>ReadableStream</h4>
14641505

14651506
<p>A <dfn id="concept-readablestream" title="concept-ReadableStream">ReadableStream</dfn> object represents a
14661507
<a class="external" data-anolis-spec="streams" href="https://streams.spec.whatwg.org/#rs-class" title="readablestream">stream of data</a>. In this section, we
@@ -1957,10 +1998,60 @@ <h2 id="fetching"><span class="secno">5 </span>Fetching</h2>
19571998
for HTTP/2, and equivalent information used to prioritize dispatch and processing of
19581999
HTTP/1 fetches.
19592000

2001+
2002+
<li>
2003+
<p>If <var>request</var> is a <a href="#navigation-request">navigation request</a>, a user agent should, for each
2004+
<a href="#concept-header" title="concept-header">header</a> <a href="#concept-header-name" title="concept-header-name">name</a>
2005+
(<var>hint-name</var>) in the first column of the following table, if <var>hint-name</var>
2006+
is not in <var>request</var>'s <a href="#concept-request-header-list" title="concept-request-header-list">header list</a>,
2007+
<a href="#concept-header-list-append" title="concept-header-list-append">append</a>
2008+
<var>hint-name</var>/<var>hint-value</var> given in the same row on the second column, to
2009+
<var>request</var>'s <a href="#concept-request-header-list" title="concept-request-header-list">header list</a>.
2010+
2011+
<table>
2012+
<tr>
2013+
<th><span title="hint-name">hint-name</span>
2014+
<th><span title="hint-value">hint-value</span>
2015+
<tr>
2016+
<td>`<code title="http-dpr">dpr</code>`
2017+
<td>a suitable <a href="http://httpwg.org/http-extensions/client-hints.html#dpr">dpr value</a>
2018+
<tr>
2019+
<td>`<code title="http-save-data">save-data</code>`
2020+
<td>a suitable <a href="http://httpwg.org/http-extensions/client-hints.html#save-data">save-data value</a>
2021+
<tr>
2022+
<td>`<code title="http-viewport-width">viewport-width</code>`
2023+
<td>a suitable <a href="http://httpwg.org/http-extensions/client-hints.html#viewport-width">viewport-width value</a>
2024+
</table>
2025+
19602026
<li>
19612027
<p>If <var>request</var> is a <a href="#subresource-request">subresource request</a>, run these substeps:
19622028

19632029
<ol>
2030+
<li>
2031+
<p>If the <var>request</var>'s <span title="concept-client-hint-list">client hints list</span> is
2032+
not empty, then run these substeps for each <var>hint-name</var> in the list:
2033+
2034+
<ol>
2035+
<li>
2036+
<p>Set <var>value</var> to the first matching statement, if any, switching on
2037+
<var>hint-name</var>:
2038+
2039+
<dl class="switch">
2040+
<dt>"<code title="">dpr</code>"
2041+
<dd>a suitable <a href="http://httpwg.org/http-extensions/client-hints.html#dpr">dpr value</a>
2042+
<dt>"<code title="">save-data</code>"
2043+
<dd>a suitable <a href="http://httpwg.org/http-extensions/client-hints.html#save-data">save-data value</a>
2044+
<dt>"<code title="">viewport-width</code>"
2045+
<dd>a suitable <a href="http://httpwg.org/http-extensions/client-hints.html#viewport-width">viewport-width value</a>
2046+
<dt>"<code title="">width</code>"
2047+
<dd>a suitable <a href="http://httpwg.org/http-extensions/client-hints.html#width">width value</a>
2048+
</dl>
2049+
2050+
<li><p><a href="#concept-header-list-append" title="concept-header-list-append">Append</a>
2051+
<var>hint-name</var>/<var>value</var> to <var>request</var>'s
2052+
<a href="#concept-request-header-list" title="concept-request-header-list">header list</a>.
2053+
</ol>
2054+
19642055
<li><p>Let <var>record</var> be a new
19652056
<a href="#concept-fetch-record" title="concept-fetch-record">fetch record</a> consisting of
19662057
<var>request</var> and this instance of the
@@ -5074,6 +5165,9 @@ <h2 class="no-num" id="references">References</h2>
50745165
<div id="anolis-references"><dl><dt id="refsABNF">[ABNF]
50755166
<dd><cite><a href="http://tools.ietf.org/html/rfc5234">Augmented BNF for Syntax Specifications: ABNF</a></cite>, D. Crocker and P. Overell. IETF.
50765167

5168+
<dt id="refsCLIENT-HINTS">[CLIENT-HINTS]
5169+
<dd><cite><a href="https://tools.ietf.org/html/draft-ietf-httpbis-client-hints">HTTP Client Hints</a></cite>, Ilya Grigorik. IETF.
5170+
50775171
<dt id="refsCOOKIES">[COOKIES]
50785172
<dd><cite><a href="https://tools.ietf.org/html/rfc6265">HTTP State Management Mechanism</a></cite>, Adam Barth. IETF.
50795173

‎Overview.src.html

Lines changed: 97 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -324,17 +324,35 @@ <h4 id=terminology-headers>Headers</h4>
324324
<hr>
325325

326326
<p>A <dfn>simple header</dfn> is a <span title=concept-header>header</span> whose
327-
<span title=concept-header-name>name</span> is `<code title>Accept</code>`,
328-
`<code title>Accept-Language</code>`, or `<code title>Content-Language</code>`, or whose
329-
<span title=concept-header-name>name</span> is `<code title>Content-Type</code>` and
330-
<span title=concept-header-value>value</span>, <span title=concept-header-parse>once parsed</span>,
331-
has a MIME type (ignoring parameters) that is
332-
`<code title>application/x-www-form-urlencoded</code>`, `<code title>multipart/form-data</code>`, or
333-
`<code title>text/plain</code>`.
327+
<span title=concept-header-name>name</span> is one of
328+
329+
<ul class=brief>
330+
<li>`<code title>Accept</code>`
331+
<li>`<code title>Accept-Language</code>`
332+
<li>`<code title>Content-Language</code>`
333+
<li>`<code title>Content-Type</code>` and whose <span title=concept-header-value>value</span>,
334+
<span title=concept-header-parse>once parsed</span>, has a MIME type (ignoring parameters)
335+
that is `<code title>application/x-www-form-urlencoded</code>`,
336+
`<code title>multipart/form-data</code>`, or `<code title>text/plain</code>`
337+
</ul>
338+
334339
<!-- XXX * needs better xref
335340
* ignoring parameters has been the standard for a long time now
336341
* interesting test: "Content-Type: text/plain;" -->
337342

343+
<p>or whose <span title=concept-header-name>name</span> is one of
344+
345+
<ul class=brief>
346+
<li>`<code title><a href=http://httpwg.org/http-extensions/client-hints.html#dpr>DPR</a></code>`
347+
<li>`<code title><a href=http://httpwg.org/http-extensions/client-hints.html#downlink>Downlink</a></code>`
348+
<li>`<code title><a href=http://httpwg.org/http-extensions/client-hints.html#save-data>Save-Data</a></code>`
349+
<li>`<code title><a href=http://httpwg.org/http-extensions/client-hints.html#viewport-width>Viewport-Width</a></code>`
350+
<li>`<code title><a href=http://httpwg.org/http-extensions/client-hints.html#width>Width</a></code>`
351+
</ul>
352+
353+
<p>and whose <span title=concept-header-value>value</span>,
354+
<span title=concept-header-parse>once parsed</span>, is not a failure.
355+
338356
<p>A <dfn>forbidden header name</dfn> is a <span title=concept-header>header</span>
339357
<span title=concept-header-name>name</span> that is one of
340358

@@ -804,6 +822,15 @@ <h4>Requests</h4>
804822
an <span data-anolis-spec=html>environment settings object</span>.
805823
<span data-anolis-ref>REFERRER</span>
806824

825+
<p>A <span title=concept-request>request</span> has an associated
826+
<dfn title=concept-request-client-hints-list>client hints list</dfn>, which is a
827+
<span title=concept-client-hints-list>client-hints list</span>. Unless stated otherwise, it is
828+
the empty list.
829+
830+
<p class="note no-backref">This will be used to override a client hints list associated with
831+
an <span data-anolis-spec=html>environment settings object</span>.
832+
<span data-anolis-ref>CLIENT-HINTS</span>
833+
807834
<p>A <span title=concept-request>request</span> has an associated
808835
<dfn>synchronous flag</dfn>. Unless stated otherwise it is unset.
809836

@@ -1387,6 +1414,19 @@ <h3>Referrer policies</h3>
13871414
<span data-anolis-ref>REFERRER</span>
13881415

13891416

1417+
<h3>Client hints list</h3>
1418+
1419+
<p class="note">This section will be integrated into HTTP Client Hints.
1420+
<span data-anolis-ref>CLIENT-HINTS</span>
1421+
<!-- XXX -->
1422+
1423+
<p>A <dfn title=concept-client-hints-list>client hints list</dfn> is a list of
1424+
<a href=http://httpwg.org/http-extensions/client-hints.html#accept-ch>Client hint tokens</a>,
1425+
each of which is one of `<code title>dpr</code>`,
1426+
`<code title>save-data</code>`, `<code title>viewport-width</code>`, or
1427+
`<code title>width</code>`.
1428+
1429+
13901430
<h3>Streams</h3>
13911431

13921432
<p class="note no-backref">This section might be integrated into other standards, such as IDL.
@@ -1888,10 +1928,60 @@ <h2>Fetching</h2>
18881928
for HTTP/2, and equivalent information used to prioritize dispatch and processing of
18891929
HTTP/1 fetches.
18901930

1931+
1932+
<li>
1933+
<p>If <var>request</var> is a <span>navigation request</span>, a user agent should, for each
1934+
<span title=concept-header>header</span> <span title=concept-header-name>name</span>
1935+
(<var>hint-name</var>) in the first column of the following table, if <var>hint-name</var>
1936+
is not in <var>request</var>'s <span title=concept-request-header-list>header list</span>,
1937+
<span title=concept-header-list-append>append</span>
1938+
<var>hint-name</var>/<var>hint-value</var> given in the same row on the second column, to
1939+
<var>request</var>'s <span title=concept-request-header-list>header list</span>.
1940+
1941+
<table>
1942+
<tr>
1943+
<th><span title=hint-name>hint-name</span>
1944+
<th><span title=hint-value>hint-value</span>
1945+
<tr>
1946+
<td>`<code title=http-dpr>dpr</a></code>`
1947+
<td>a suitable <a href=http://httpwg.org/http-extensions/client-hints.html#dpr>dpr value</a>
1948+
<tr>
1949+
<td>`<code title=http-save-data>save-data</code>`
1950+
<td>a suitable <a href=http://httpwg.org/http-extensions/client-hints.html#save-data>save-data value</a>
1951+
<tr>
1952+
<td>`<code title=http-viewport-width>viewport-width</code>`
1953+
<td>a suitable <a href=http://httpwg.org/http-extensions/client-hints.html#viewport-width>viewport-width value</a>
1954+
</table>
1955+
18911956
<li>
18921957
<p>If <var>request</var> is a <span>subresource request</span>, run these substeps:
18931958

18941959
<ol>
1960+
<li>
1961+
<p>If the <var>request</var>'s <span title=concept-client-hint-list>client hints list</span> is
1962+
not empty, then run these substeps for each <var>hint-name</var> in the list:
1963+
1964+
<ol>
1965+
<li>
1966+
<p>Set <var>value</var> to the first matching statement, if any, switching on
1967+
<var>hint-name</var>:
1968+
1969+
<dl class=switch>
1970+
<dt>"<code title>dpr</code>"
1971+
<dd>a suitable <a href=http://httpwg.org/http-extensions/client-hints.html#dpr>dpr value</a>
1972+
<dt>"<code title>save-data</code>"
1973+
<dd>a suitable <a href=http://httpwg.org/http-extensions/client-hints.html#save-data>save-data value</a>
1974+
<dt>"<code title>viewport-width</code>"
1975+
<dd>a suitable <a href=http://httpwg.org/http-extensions/client-hints.html#viewport-width>viewport-width value</a>
1976+
<dt>"<code title>width</code>"
1977+
<dd>a suitable <a href=http://httpwg.org/http-extensions/client-hints.html#width>width value</a></code>
1978+
</dl>
1979+
1980+
<li><p><span title=concept-header-list-append>Append</span>
1981+
<var>hint-name</var>/<var>value</var> to <var>request</var>'s
1982+
<span title=concept-request-header-list>header list</span>.
1983+
</ol>
1984+
18951985
<li><p>Let <var>record</var> be a new
18961986
<span title=concept-fetch-record>fetch record</span> consisting of
18971987
<var>request</var> and this instance of the

0 commit comments

Comments
 (0)