Client hints updates (#4907)

* Client hints, general updates * Assorted minor changes, mostly to frontmatter * Early-data is not a client hint header * Minor fixes * Update files/en-us/glossary/client_hints/index.html Co-authored-by: Florian Scholz <[email protected]> * Update files/en-us/glossary/client_hints/index.html Co-authored-by: Florian Scholz <[email protected]> Co-authored-by: Florian Scholz <[email protected]>
mdn · Jun 1, 2021 · 7a06a72 · 7a06a72
1 parent eca14db
commit 7a06a72
Show file tree

Hide file tree

Showing 10 changed files with 80 additions and 42 deletions.
diff --git a/files/en-us/glossary/client_hints/index.html b/files/en-us/glossary/client_hints/index.html
@@ -8,23 +8,29 @@
   - Reference
   - Web Performance
 ---
-<p><span class="seoSummary"><strong>Client Hints</strong> are a set of <a href="/en-US/docs/Web/HTTP/Headers">HTTP request header</a> fields for proactive content negotiation allowing clients to indicate a list of device and agent specific preferences.</span></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 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>Use of client hints isn't automatic: rather, servers must announce that they support client hints. Servers announce support for Client Hints using the <code><a href="https://datatracker.ietf.org/doc/html/draft-grigorik-http-client-hints-03#section-2.2.1">Accept-CH</a></code> (accept client hints) header or an equivalent HTML meta element with the <code><a href="/en-US/docs/Web/HTML/Element/meta#attributes">http-equiv</a></code> attribute.</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><code>Accept-CH: Width, Viewport-Width, Downlink</code></p>
+<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>and / or</p>
+<pre>Accept-CH: Width, Viewport-Width, Downlink</pre>
 
-<p><code>&lt;meta http-equiv="Accept-CH" content="Width, Viewport-Width, Downlink</code><code>"&gt;</code></p>
+<p>The server can then determine which resources to send based on the client information.</p>
+
+<div class="notecard note">
+  <h4>Note</h4>
+  <p>Client hints can also be specified in HTML using the {{HTMLElement("meta")}} element with the <code><a href="/en-US/docs/Web/HTML/Element/meta#attr-http-equiv">http-equiv</a></code> attribute.</p>
+  <pre>&lt;meta http-equiv="Accept-CH" content="Width, Viewport-Width, Downlink"&gt;</pre>
+</div>
 
-<p>When a client receives the <code>Accept-CH</code> header, if supported, it appends Client Hint headers that match the advertised field-values. For example, based on Accept-CH example above, the client could append Width, Viewport-Width, and Downlink headers to all subsequent requests. In the second example, the server gives the browser the hints by setting the Accept-CH meta tag.</p>
 
-<p>Basically, with the Client Hints header, the developer or application can tell the browser to advertise information about itself to the server, such as the device pixel ratio, the viewport width, and the display width. The client can then give the server information about the client's environment, and the server can determine which resources to send based on that information.</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 <code><a href="/en-US/docs/Web/HTTP/Headers/Vary">Vary</a></code> HTTP header must be used.</p>
+<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>
 
 <p id="Example_varying_response">Example varying response:</p>
 
@@ -35,4 +41,6 @@ <h2 id="See_also">See also</h2>
 <ul>
  <li><a href="/en-US/docs/Web/HTTP/Headers#client_hints">Client Hints headers</a></li>
  <li><a href="/en-US/docs/Web/HTTP/Headers/Vary"><code>Vary</code> HTTP Header</a></li>
+ <li><a href="https://wicg.github.io/client-hints-infrastructure/">Client Hints Infrastructure</a></li>
+
 </ul>
diff --git a/files/en-us/glossary/forbidden_header_name/index.html b/files/en-us/glossary/forbidden_header_name/index.html
@@ -8,13 +8,13 @@
   - Headers
   - forbidden
 ---
-<p>A <dfn>forbidden header name</dfn> is the name of any <a href="/en-US/docs/Web/HTTP/Headers">HTTP header</a> that cannot be modified programmatically; specifically, an HTTP <strong>request</strong> header name (in contrast with a {{Glossary("Forbidden response header name")}}).</p>
+<p>A <strong>forbidden header name</strong> is the name of any <a href="/en-US/docs/Web/HTTP/Headers">HTTP header</a> that cannot be modified programmatically; specifically, an HTTP <strong>request</strong> header name (in contrast with a {{Glossary("Forbidden response header name")}}).</p>
 
 <p>Modifying such headers is forbidden because the user agent retains full control over them. Names starting with `<code>Sec-</code>` are reserved for creating new headers safe from {{glossary("API","APIs")}} using <a href="/en-US/docs/Web/API/Fetch_API">Fetch</a> that grant developers control over headers, such as {{domxref("XMLHttpRequest")}}.</p>
 
 <p>Forbidden header names start with <code>Proxy-</code> or <code>Sec-</code>, or are one of the following names:</p>
 
-<ul class="brief">
+<ul>
  <li><code>Accept-Charset</code></li>
  <li><code>Accept-Encoding</code></li>
  <li><code>Access-Control-Request-Headers</code></li>
@@ -26,7 +26,7 @@
  <li><code>Date</code></li>
  <li><code>DNT</code></li>
  <li><code>Expect</code></li>
- <li><code>Feature-Policy</code></li>
+ <li><code>Feature-Policy</code></li> 
  <li><code>Host</code></li>
  <li><code>Keep-Alive</code></li>
  <li><code>Origin</code></li>
@@ -40,8 +40,9 @@
  <li><code>Via</code></li>
 </ul>
 
-<div class="note">
-<p><strong>Note</strong>: The <code>User-Agent</code> header is no longer forbidden, <a href="https://fetch.spec.whatwg.org/#terminology-headers">as per spec</a> — see forbidden header name list (this was implemented in Firefox 43) — it can now be set in a Fetch <a href="/en-US/docs/Web/API/Headers">Headers</a> object, or via XHR <a href="/en-US/docs/Web/API/XMLHttpRequest#setrequestheader%28%29">setRequestHeader()</a>.  However, Chrome will silently drop the header from Fetch requests (see <a href="https://bugs.chromium.org/p/chromium/issues/detail?id=571722">Chromium bug 571722</a>).</p>
+<div class="notecard note">
+  <h4>Note</h4>
+  <p>The <code>User-Agent</code> header is no longer forbidden, <a href="https://fetch.spec.whatwg.org/#terminology-headers">as per spec</a> — see forbidden header name list (this was implemented in Firefox 43) — it can now be set in a Fetch <a href="/en-US/docs/Web/API/Headers">Headers</a> object, or via XHR <a href="/en-US/docs/Web/API/XMLHttpRequest#setrequestheader%28%29">setRequestHeader()</a>.  However, Chrome will silently drop the header from Fetch requests (see <a href="https://bugs.chromium.org/p/chromium/issues/detail?id=571722">Chromium bug 571722</a>).</p>
 </div>
 
 <section id="Quick_links">

diff --git a/files/en-us/web/http/headers/accept-ch-lifetime/index.html b/files/en-us/web/http/headers/accept-ch-lifetime/index.html
@@ -2,12 +2,17 @@
 title: Accept-CH-Lifetime
 slug: Web/HTTP/Headers/Accept-CH-Lifetime
 tags:
-- Client hints
-- HTTP
-- header
+  - Accept-CH-Lifetime
+  - Client hints
+  - HTTP
+  - HTTP Header
+  - Response header
+  - Deprecated
+  - Non-standard
+  - Experimental
 browser-compat: http.headers.Accept-CH-Lifetime
 ---
-<div>{{HTTPSidebar}}{{securecontext_header}}{{Deprecated_header}}{{Non-standard_header}}</div>
+<div>{{HTTPSidebar}}{{securecontext_header}}{{Deprecated_header}}</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
@@ -29,7 +34,7 @@
 
 <div class="notecard note">
   <p><strong>Note:</strong> Client Hints are accessible only on secure origins (via TLS).
-    Accept-CH and Accept-CH-Lifetime headers should be persisted for all secure requests
+    {{HTTPHeader("Accept-CH")}} and {{HTTPHeader("Accept-CH-Lifetime")}} headers should be persisted for all secure requests
     to ensure Client Hints are sent reliably.</p>
 </div>
 

diff --git a/files/en-us/web/http/headers/accept-ch/index.html b/files/en-us/web/http/headers/accept-ch/index.html
@@ -9,8 +9,8 @@
 ---
 <div>{{HTTPSidebar}}{{securecontext_header}}{{SeeCompatTable}}</div>
 
-<p>The <code><strong>Accept-CH</strong></code> header is set by the server to specify
-  which <a href="/en-US/docs/Glossary/Client_hints">Client Hints</a> headers a client
+<p>The <code><strong>Accept-CH</strong></code> header may be set by a server to specify
+  which <a href="/en-US/docs/Glossary/Client_hints">client hints</a> headers a client
   should include in subsequent requests.</p>
 
 <table class="properties">
@@ -21,15 +21,15 @@
     </tr>
     <tr>
       <th scope="row">{{Glossary("Forbidden header name")}}</th>
-      <td>?</td>
+      <td>no</td>
     </tr>
   </tbody>
 </table>
 
 <div class="notecard note">
-  <p><strong>Note:</strong> Client Hints are accessible only on secure origins (via TLS).
-    Accept-CH and Accept-CH-Lifetime headers should be persisted for all secure requests
-    to ensure Client Hints are sent reliably.</p>
+  <p><strong>Note:</strong> Client hints are accessible only on secure origins (via TLS).
+    <code>Accept-CH</code> (and <code>Accept-CH-Lifetime</code>) headers should be persisted for all secure requests
+    to ensure client hints are sent reliably.</p>
 </div>
 
 <h2 id="Syntax">Syntax</h2>
@@ -39,9 +39,7 @@ <h2 id="Syntax">Syntax</h2>
 
 <h2 id="Examples">Examples</h2>
 
-<pre>Accept-CH: Viewport-Width
-Accept-CH: Width
-Accept-CH-Lifetime: 86400
+<pre>Accept-CH: Viewport-Width, Width
 Vary: Viewport-Width, Width
 </pre>
 
@@ -51,13 +49,29 @@ <h2 id="Examples">Examples</h2>
     based on the accepted client hints.</p>
 </div>
 
+<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>
+
 <h2 id="Browser_compatibility">Browser compatibility</h2>
 
 <p>{{Compat}}</p>
 
 <h2 id="See_also">See also</h2>
 
 <ul>
-  <li>{{HTTPHeader("Accept-CH-Lifetime")}}</li>
   <li>{{HTTPHeader("Vary")}}</li>
 </ul>
diff --git a/files/en-us/web/http/headers/device-memory/index.html b/files/en-us/web/http/headers/device-memory/index.html
@@ -2,10 +2,13 @@
 title: Device-Memory
 slug: Web/HTTP/Headers/Device-Memory
 tags:
+  - Device-Memory
   - Client hints
   - Device Memory API
   - HTTP
   - HTTP Header
+  - Request header
+  - Experimental
 browser-compat: http.headers.Device-Memory
 ---
 <div>{{HTTPSidebar}}{{securecontext_header}}{{SeeCompatTable}}</div>

diff --git a/files/en-us/web/http/headers/dpr/index.html b/files/en-us/web/http/headers/dpr/index.html
@@ -2,18 +2,21 @@
 title: DPR
 slug: Web/HTTP/Headers/DPR
 tags:
+  - DPR
   - Client hints
   - HTTP
   - HTTP Header
+  - Request header
   - Deprecated
   - Non-standard
+  - Exerimental
 browser-compat: http.headers.DPR
 ---
 <div>{{deprecated_header}}{{Non-standard_header}}</div>
 
 <div>{{HTTPSidebar}}{{securecontext_header}}{{SeeCompatTable}}</div>
 
-<p>The <strong><code>DPR</code></strong> header is a <a href="/en-US/docs/Glossary/Client_hints">Client Hints</a> header which represents the client device pixel ratio ({{Glossary("DPR")}}), which is the number of physical device pixels corresponding to every CSS pixel.</p>
+<p>The <strong><code>DPR</code></strong> header is a <a href="/en-US/docs/Glossary/Client_hints">Client Hints</a> header which represents the client device pixel ratio, which is the number of physical device pixels corresponding to every CSS pixel.</p>
 
 <table class="properties">
  <tbody>

diff --git a/files/en-us/web/http/headers/early-data/index.html b/files/en-us/web/http/headers/early-data/index.html
@@ -2,10 +2,13 @@
 title: Early-Data
 slug: Web/HTTP/Headers/Early-Data
 tags:
+  - Early-Data
   - Client hints
   - HTTP
-  - header
-  - request
+  - HTTP Header
+  - Request header
+  - Reference
+  - Experimental
 browser-compat: http.headers.Early-Data
 ---
 <div>{{SeeCompatTable}}{{HTTPSidebar}}</div>

diff --git a/files/en-us/web/http/headers/feature-policy/index.html b/files/en-us/web/http/headers/feature-policy/index.html
@@ -4,7 +4,6 @@
 tags:
   - Authorization
   - Experimental
-  - Feature Policy
   - Feature-Policy
   - HTTP
   - Permissions

diff --git a/files/en-us/web/http/headers/index.html b/files/en-us/web/http/headers/index.html
@@ -81,12 +81,12 @@ <h2 id="Client_hints">Client hints</h2>
 <dl>
  <dt>{{HTTPHeader("Accept-CH")}} {{experimental_inline}}</dt>
  <dd>Servers can advertise support for Client Hints using the <code>Accept-CH</code> header field or an equivalent HTML <code>&lt;meta&gt;</code> element with <code>http-equiv</code> attribute (<a href="https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-http-equiv"><cite>[HTML]</cite></a>).</dd>
- <dt>{{HTTPHeader("Accept-CH-Lifetime")}} {{experimental_inline}}</dt>
+ <dt>{{HTTPHeader("Accept-CH-Lifetime")}} {{experimental_inline}} {{deprecated_inline}}</dt>
  <dd>Servers can ask the client to remember the set of Client Hints that the server supports for a specified period of time, to enable delivery of Client Hints on subsequent requests to the server’s origin (<a href="https://datatracker.ietf.org/doc/html/rfc6454"><cite>[RFC6454]</cite></a>).</dd>
- <dt>{{HTTPHeader("Early-Data")}} {{experimental_inline}}</dt>
- <dd>Indicates that the request has been conveyed in early data.</dd>
  <dt>{{HTTPHeader("Device-Memory")}} {{experimental_inline}}</dt>
  <dd>Technically a part of Device Memory API, this header represents an approximate amount of RAM client has.</dd>
+ <dt>{{HTTPHeader("DPR")}} {{deprecated_inline}}</dt>
+ <dd>Client device pixel ratio (DPR), which is the number of physical device pixels corresponding to every CSS pixel.</dd>
  <dt>{{HTTPHeader("Save-Data")}} {{experimental_inline}}</dt>
  <dd>A boolean that indicates the user agent's preference for reduced data usage.</dd>
  <dt>{{HTTPHeader("Viewport-Width")}} {{experimental_inline}}</dt>
@@ -321,7 +321,7 @@ <h2 id="Security">Security</h2>
 
 <h3 id="HTTP_Public_Key_Pinning_GlossaryHPKP">HTTP Public Key Pinning (HPKP)</h3>
 
-<p>{{Glossary("HPKP", "HTTP Public Key Pinning (HPKP)")}} has been deprecated and removed in favor of Certificate Transparency and {{HTTPHeader("Expect-CT")}}.</p>
+<p>{{Glossary("HPKP", "HTTP Public Key Pinning")}} has been deprecated and removed in favor of Certificate Transparency and {{HTTPHeader("Expect-CT")}}.</p>
 
 <dl>
  <dt>{{HTTPHeader("Public-Key-Pins")}}</dt>
@@ -395,6 +395,8 @@ <h2 id="Other">Other</h2>
  <dd>Used to list alternate ways to reach this service.</dd>
  <dt>{{HTTPHeader("Date")}}</dt>
  <dd>Contains the date and time at which the message was originated.</dd>
+ <dt>{{HTTPHeader("Early-Data")}} {{experimental_inline}}</dt>
+ <dd>Indicates that the request has been conveyed in TLS early data.</dd>
  <dt>{{HTTPHeader("Large-Allocation")}}</dt>
  <dd>Tells the browser that the page being loaded is going to want to perform a large allocation.</dd>
  <dt>{{HTTPHeader("Link")}}</dt>

diff --git a/files/en-us/web/http/headers/save-data/index.html b/files/en-us/web/http/headers/save-data/index.html
@@ -2,12 +2,12 @@
 title: Save-Data
 slug: Web/HTTP/Headers/Save-Data
 tags:
-- HTTP
-- HTTP Header
-- Reference
-- Request header
-- Save-Data
-- header
+  - Save-Data
+  - Client hints
+  - HTTP
+  - HTTP Header
+  - Reference
+  - Request header
 browser-compat: http.headers.Save-Data
 ---
 <p>{{HTTPSidebar}}</p>