Add client hint docs: Downlink, ECT, RTT

files/en-us/glossary/client_hints/index.html

@@ -8,17 +8,18 @@
  - Reference
  - Web Performance
 ---
-<p><strong>Client Hints</strong> are a set of <a href="/en-US/docs/Web/HTTP/Headers">HTTP request header</a> fields that a server can proactively 
- request from a client in order to get its device and agent specific preferences. The set of "hint" headers are listed here: <a href="/en-US/docs/Web/HTTP/Headers#client_hints">HTTP Headers > Client hints</a>.</p>
+<p><strong>Client Hints</strong> are a set of <a href="/en-US/docs/Web/HTTP/Headers">HTTP request header</a> fields that a server can proactively request from a client in order to get information about the device, network, user and agent specific preferences. The server can then determine which resources to send based on the client information.</p>
 
-<p>A server must announce that it supports client hints, using the {{HTTPHeader("Accept-CH")}} header to specify the hints that it is interested in recieving.
- When a client that supports client hints receives the <code>Accept-CH</code> header it appends client hint headers that match the advertised field-values to subsequent requests.</p>
+<p>The set of "hint" headers are listed in the topic <a href="/en-US/docs/Web/HTTP/Headers#client_hints">HTTP Headers</a> and <a href="#hint_types">summarised below</a>.</p>
+
+<h2 id="Overview">Overview</h2>
 
-<p>For example, following <code>Accept-CH</code> in a response below, the client could append {{HTTPHeader("Width")}}, {{HTTPHeader("Viewport-Width")}}, and {{HTTPHeader("Downlink")}} headers to all subsequent requests.</p>
+<p>A server must announce that it supports client hints, using the {{HTTPHeader("Accept-CH")}} header to specify the hints that it is interested in recieving.
+ When a client that supports client hints receives the <code>Accept-CH</code> header it can append client hint headers that match the advertised field-values to subsequent requests.</p>
 
-<pre>Accept-CH: Width, Viewport-Width, Downlink</pre>
+<p>For example, following <code>Accept-CH</code> in a response below, the client could append {{HTTPHeader("Width")}} and {{HTTPHeader("Downlink")}} headers to all subsequent requests.</p>
 
-<p>The server can then determine which resources to send based on the client information.</p>
+<pre class="brush: http">Accept-CH: Width, Downlink</pre>
 
 <div class="notecard note">
  <h4>Note</h4>
@@ -27,14 +28,25 @@ <h4>Note</h4>
 </div>
 
 
+<h2 id="Caching_and_client_hints">Caching and Client Hints</h2>
+
+<p>Client hints that determine which resources are sent in responses should "generally" also be included in the affected response's {{HTTPHeader("Vary")}} header. This ensures that a different resource is cached for every different value of the hint header.</p>
+
+<pre class="brush: http">Vary: Accept, Width, ECT</pre>
+
+<p>You may prefer to omit specifying {{HTTPHeader("Vary")}} or use sme other strategy for client hint headers where the value changes a lot, as this effectively makes the resource uncachable (a new cache entry is created for every different value). This applies in particular to network client hints like {{HTTPHeader("Downlink")}} and {{HTTPHeader("RTT")}}. For more information see <a href="/en-US/docs/Web/HTTP/Caching#varying_responses">HTTP Caching > Varying responses</a>.</p>
+
+<h2 id="hint_types">Hint types</h2>
+
+<h3 id="device_client_hints">Device client hints</h3>
+
+<p>Device client hints allow a server to choose what information is sent based on the device characteristics including available memory and screen properties. Headers include: {{HTTPHeader("Device-Memory")}}, {{HTTPHeader("DPR")}}, {{HTTPHeader("Width")}}, {{HTTPHeader("Viewport-Width")}}</p>
 
-<h2 id="Varying_Client_Hints">Varying Client Hints</h2>
 
-<p>To convey to caches that different <a href="/en-US/docs/Web/HTTP/Headers#client_hints">Client Hints</a> may affect the response, the {{HTTPHeader("Vary")}} HTTP header must be used.</p>
+<h3 id="network_client_hints">Network client hints</h3>
 
-<p id="Example_varying_response">Example varying response:</p>
+<p>Network client hints allow a server to choose what information is sent based on the user choice and network bandwidth and latency. Headers include: {{HTTPHeader("Save-Data")}}, {{HTTPHeader("Downlink")}}, {{HTTPHeader("ECT")}}, {{HTTPHeader("RTT")}}</p>
 
-<p><code>Vary: Accept, Width, Viewport-Width, Downlink</code></p>
 
 <h2 id="See_also">See also</h2>
 

files/en-us/glossary/effective_connection_type/index.html

@@ -65,4 +65,5 @@ <h2 id="See_also">See also</h2>
  <li><a href="/en-US/docs/Web/API/Network_Information_API">Network Information API</a></li>
  <li>{{domxref('NetworkInformation')}}</li>
  <li>{{domxref('NetworkInformation.effectiveType')}}</li>
+ <li>{{HTTPHeader("ECT")}}</li>
 </ul>

files/en-us/web/api/networkinformation/downlink/index.html

@@ -42,3 +42,11 @@ <h2 id="Specifications">Specifications</h2>
 <h2 id="Browser_compatibility">Browser compatibility</h2>
 
 <p>{{Compat}}</p>
+
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+ <li>{{HTTPHeader("Downlink")}}</li>
+</ul>
+

files/en-us/web/api/networkinformation/effectivetype/index.html

@@ -37,6 +37,8 @@ <h2 id="Browser_compatibility">Browser compatibility</h2>
 <h2 id="See_also">See also</h2>
 
 <ul>
- <li><a href="/en-US/docs/Glossary/Effective_connection_type">Effective Connection
-  Type</a></li>
+ <li><a href="/en-US/docs/Glossary/Effective_connection_type">Effective Connection Type</a></li>
+ <li>{{HTTPHeader("ECT")}}</li>
 </ul>
+
+

files/en-us/web/api/networkinformation/rtt/index.html

@@ -38,3 +38,9 @@ <h2 id="Specifications">Specifications</h2>
 <h2 id="Browser_compatibility">Browser compatibility</h2>
 
 <p>{{Compat}}</p>
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+ <li>{{HTTPHeader("RTT")}}</li>
+</ul>

files/en-us/web/api/networkinformation/savedata/index.html

@@ -34,3 +34,9 @@ <h2 id="Specifications">Specifications</h2>
 <h2 id="Browser_compatibility">Browser compatibility</h2>
 
 <p>{{Compat}}</p>
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+ <li>{{HTTPHeader("Save-Data")}}</li>
+</ul>

files/en-us/web/http/headers/accept-ch-lifetime/index.html

@@ -13,24 +13,30 @@
 browser-compat: http.headers.Accept-CH-Lifetime
 ---
 <div>{{HTTPSidebar}}{{securecontext_header}}{{Deprecated_header}}</div>
+<div class="notecard warning">
+ <p><strong>Warning:</strong> The header was removed from the specification in <a href="https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-client-hints-08">draft 8</a>.</p>
+</div>
 
 <p>The <code><strong>Accept-CH-Lifetime</strong></code> header is set by the server to
- specify the persistence of {{HTTPHeader("Accept-CH")}} header value that specifies for
- which <a href="/en-US/docs/Glossary/Client_hints">Client Hints</a> headers client should
+ specify the persistence of the <a href="/en-US/docs/Glossary/Client_hints">client hint headers</a> it specified using {{HTTPHeader("Accept-CH")}}, that the client should
  include in subsequent requests.</p>
 
 <table class="properties">
  <tbody>
- <tr>
- <th scope="row">Header type</th>
- <td>{{Glossary("Response header")}}</td>
- </tr>
- <tr>
- <th scope="row">{{Glossary("Forbidden header name")}}</th>
- <td>?</td>
- </tr>
+ <tr>
+ <th scope="row">Header type</th>
+ <td>{{Glossary("Response header")}}</td>
+ </tr>
+ <tr>
+ <th scope="row">{{Glossary("Forbidden header name")}}</th>
+ <td>no</td>
+ </tr>
+ <tr>
+ <th scope="row">{{Glossary("CORS-safelisted response header")}}</th>
+ <td>no</td>
+ </tr>
  </tbody>
-</table>
+ </table>
 
 <div class="notecard note">
  <p><strong>Note:</strong> Client Hints are accessible only on secure origins (via TLS).

files/en-us/web/http/headers/accept-ch/index.html

@@ -2,9 +2,11 @@
 title: Accept-CH
 slug: Web/HTTP/Headers/Accept-CH
 tags:
+ - Accept-CH
  - Client hints
  - HTTP
  - HTTP Header
+ - Response header
 browser-compat: http.headers.Accept-CH
 ---
 <div>{{HTTPSidebar}}{{securecontext_header}}{{SeeCompatTable}}</div>
@@ -23,6 +25,10 @@
  <th scope="row">{{Glossary("Forbidden header name")}}</th>
  <td>no</td>
  </tr>
+ <tr>
+ <th scope="row">{{Glossary("CORS-safelisted response header")}}</th>
+ <td>no</td>
+ </tr>
  </tbody>
 </table>
 
@@ -34,12 +40,12 @@
 
 <h2 id="Syntax">Syntax</h2>
 
-<pre class="brush: html">Accept-CH: &lt;list of client hints&gt;
+<pre class="brush: http">Accept-CH: &lt;list of client hints&gt;
 </pre>
 
 <h2 id="Examples">Examples</h2>
 
-<pre>Accept-CH: Viewport-Width, Width
+<pre class="brush: http">Accept-CH: Viewport-Width, Width
 Vary: Viewport-Width, Width
 </pre>
 
@@ -51,20 +57,7 @@ <h2 id="Examples">Examples</h2>
 
 <h2 id="Specifications">Specifications</h2>
 
-<table class="standard-table">
- <thead>
- <tr>
- <th scope="col">Specification</th>
- <th scope="col">Title</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>{{RFC("8942", "Accept-CH")}}</td>
- <td>HTTP Client Hints</td>
- </tr>
- </tbody>
-</table>
+{{Specifications}}
 
 <h2 id="Browser_compatibility">Browser compatibility</h2>
 

files/en-us/web/http/headers/downlink/index.html

@@ -0,0 +1,76 @@
+---
+title: Downlink
+slug: Web/HTTP/Headers/Downlink
+tags:
+ - Downlink
+ - Client hints
+ - HTTP
+ - HTTP Header
+ - Request header
+ - Client hints
+ - Experimental
+browser-compat: http.headers.downlink
+---
+<div>{{HTTPSidebar}} {{SeeCompatTable}}</div>
+
+<p>The <strong><code>Downlink</code></strong> {{Glossary("Client hints","network client hint")}} request header field provides the approximate bandwidth of the client's connection to the server, in Mbps.</p>
+
+<table class="properties">
+ <tbody>
+ <tr>
+ <th scope="row">Header type</th>
+ <td>{{Glossary("Request header")}}, {{Glossary("Client hints","Client hint")}}</td>
+ </tr>
+ <tr>
+ <th scope="row">{{Glossary("Forbidden header name")}}</th>
+ <td>no</td>
+ </tr>
+ </tbody>
+ </table>
+
+<p>The Downlink value is rounded to the nearest 25 kilobits per second to prevent fingerprinting; There are many other mechanisms an attacker might use to obtain similar information.</p>
+
+<p>The hint allows a server to choose what information is sent based on the network bandwidth. For example, a server might choose to send smaller versions of images and other resources on low bandwidth networks.</p>
+
+<div class="notecard note">
+ <p><strong>Note:</strong> The {{HTTPHeader("Vary")}} header is used in responses to indicate that a different resource is sent for every different value of the header (see <a href="/en-US/docs/Web/HTTP/Caching#varying_responses">HTTP Caching > Varying responses</a>). Even if {{HTTPHeader("Downlink")}} is used to configure what resources are sent, consider omitting it in the {{HTTPHeader("Vary")}} header — it is likely to change often, which effectively makes the resource uncachable.</p>
+</div>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="brush: http">Downlink: &lt;number&gt;</pre>
+
+<h2 id="Examples">Examples</h2>
+
+<p>Server first needs to opt in to receive the <code>Downlink</code> header by sending the response headers {{HTTPHeader("Accept-CH")}} containing <code>Downlink</code>.</p>
+
+<pre class="brush: http">Accept-CH: Downlink</pre>
+
+<p>Then on subsequent requests the client might send <code>Downlink</code> header back:</p>
+
+<pre class="brush: http">Downlink: 1.7</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<p>{{Specifications}}</p>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<p>{{Compat}}</p>
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+ <li><a href="https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/client-hints">Adapting to Users with Client Hints</a> (developer.google.com)</li>
+ <li>Network client hints
+ <ul>
+ <li>{{HTTPHeader("Downlink")}}</li>
+ <li>{{HTTPHeader("RTT")}}</li>
+ <li>{{HTTPHeader("ECT")}}</li>
+ <li>{{HTTPHeader("Save-Data")}}</li>
+ </ul>
+ </li>
+ <li>{{HTTPHeader("Accept-CH")}}</li>
+ <li><a href="/en-US/docs/Web/HTTP/Caching#varying_responses">HTTP Caching > Varying responses</a> and {{HTTPHeader("Vary")}}</li>
+ <li>{{domxref("NetworkInformation.effectiveType")}}</li>
+</ul>

files/en-us/web/http/headers/ect/index.html

@@ -0,0 +1,77 @@
+---
+title: ECT
+slug: Web/HTTP/Headers/ECT
+tags:
+ - ect
+ - Client hints
+ - HTTP
+ - HTTP Header
+ - Request header
+ - Client hints
+ - Experimental
+browser-compat: http.headers.ect
+---
+<div>{{HTTPSidebar}} {{SeeCompatTable}}</div>
+
+<p>The <strong><code>ECT</code></strong> {{Glossary("Client hints","network client hint")}} request header field indicates the {{Glossary("effective connection type")}}: <code>slow-2g</code>, <code>2g</code>, <code>3g</code>, <code>4g</code>.</p>
+
+<table class="properties">
+ <tbody>
+ <tr>
+ <th scope="row">Header type</th>
+ <td>{{Glossary("Request header")}}, {{Glossary("Client hints","Client hint")}}</td>
+ </tr>
+ <tr>
+ <th scope="row">{{Glossary("Forbidden header name")}}</th>
+ <td>no</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <p>The value represents the "network profile" that best matches the connection's latency and bandwidth, rather than the actual mechanisms used for transferring the data. For example, <code>2g</code> might be used to represent a slow wifi connection with high latency and low bandwidth, while <code>4g</code> might be used to represent a fast fibre-based broadband network.</p>
+
+<p>The hint allows a server to choose what information is sent based on the broad characteristics of the network. For example, a server might choose to send smaller versions of images and other resources on less capable connections. The value might also be used as a starting point for determining what information is sent, which is further refined using information in {{HTTPHeader("RTT")}} and {{HTTPHeader("Downlink")}} hints.</p>
+
+<div class="notecard note">
+ <p><strong>Note:</strong> A server that specifies {{HTTPHeader("ECT")}} in {{HTTPHeader("Accept-CH")}} may also specify it in {{HTTPHeader("Vary")}} to indicate that responses should be cached for different ECT values.</p>
+</div>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="brush: http">ect: &lt;value&gt;</pre>
+
+<h2 id="Examples">Examples</h2>
+
+<p>Server first needs to opt in to receive the <code>Downlink</code> header by sending the response headers {{HTTPHeader("Accept-CH")}} containing <code>Downlink</code>.</p>
+
+<pre class="brush: http">Accept-CH: ECT</pre>
+
+<p>Then on subsequent requests the client might send <code>Downlink</code> header back:</p>
+
+<pre class="brush: http">ECT: 2g</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<p>{{Specifications}}</p>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<p>{{Compat}}</p>
+
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+ <li><a href="https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/client-hints">Adapting to Users with Client Hints</a> (developer.google.com)</li>
+ <li>Network client hints
+ <ul>
+ <li>{{HTTPHeader("Downlink")}}</li>
+ <li>{{HTTPHeader("RTT")}}</li>
+ <li>{{HTTPHeader("ECT")}}</li>
+ <li>{{HTTPHeader("Save-Data")}}</li>
+ </ul>
+ </li>
+ <li>{{HTTPHeader("Accept-CH")}}</li>
+ <li><a href="/en-US/docs/Web/HTTP/Caching#varying_responses">HTTP Caching > Varying responses</a> and {{HTTPHeader("Vary")}}</li>
+ <li>{{domxref("NetworkInformation.effectiveType")}}</li>
+</ul>