Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Client hints updates #4907

Merged
merged 8 commits into from
Jun 1, 2021
Merged

Client hints updates #4907

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
c54fa6f
Client hints, general updates
hamishwillee May 11, 2021
2b9b979
Assorted minor changes, mostly to frontmatter
hamishwillee May 21, 2021
744e59b
Early-data is not a client hint header
hamishwillee May 21, 2021
233056d
Minor fixes
hamishwillee May 21, 2021
cfe9752
Merge branch 'main' into http_accept-ch
hamishwillee May 28, 2021
0deed1b
Update files/en-us/glossary/client_hints/index.html
hamishwillee Jun 1, 2021
40c1639
Update files/en-us/glossary/client_hints/index.html
hamishwillee Jun 1, 2021
d33e26b
Merge branch 'main' into http_accept-ch
hamishwillee Jun 1, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions files/en-us/glossary/client_hints/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand All @@ -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>
11 changes: 6 additions & 5 deletions files/en-us/glossary/forbidden_header_name/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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>
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Elchi3 How does one find out if something is a forbidden header name? Specifically, I checked the Fetch spec, and it matches the list here except it does not mention Feature-Policy. So how would I find out that Feature Policy is forbidden (I searched on forbidden in the permission-policy spec too and the term does not appear).

The main reason I ask is that the client hints all have "?" in the table for forbidden, so would help me to understand how you confirm their status.

Further, w.r.t. this doc, should I also add Permission-Policy?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually it's Permissions-Policy with an 's'.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought the list from the Fetch spec is exhaustive and new forbidden headers would start with Sec- but maybe that is a misunderstanding from my side.

I previously only confirmed these by looking at the Fetch spec...

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @Elchi3. The fetch spec being exhaustive seems a reasonable assumption. Just wasn't one I wanted to make. Happy to go with that now.

I wont add Permissions-Policy because I now know that this will be done "all in one go" later on.

<li><code>Host</code></li>
<li><code>Keep-Alive</code></li>
<li><code>Origin</code></li>
Expand All @@ -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">
Expand Down
15 changes: 10 additions & 5 deletions files/en-us/web/http/headers/accept-ch-lifetime/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note, this is non-standard. Last time I had both that and a deprecated header Chris suggested the deprecated header along covers that you should not use it.


<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
Expand All @@ -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>

Expand Down
34 changes: 24 additions & 10 deletions files/en-us/web/http/headers/accept-ch/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand All @@ -21,15 +21,15 @@
</tr>
<tr>
<th scope="row">{{Glossary("Forbidden header name")}}</th>
<td>?</td>
<td>no</td>
Elchi3 marked this conversation as resolved.
Show resolved Hide resolved
</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>
Expand All @@ -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>

Expand All @@ -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>
Elchi3 marked this conversation as resolved.
Show resolved Hide resolved
<li>{{HTTPHeader("Vary")}}</li>
</ul>
3 changes: 3 additions & 0 deletions files/en-us/web/http/headers/device-memory/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
5 changes: 4 additions & 1 deletion files/en-us/web/http/headers/dpr/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,21 @@
title: DPR
slug: Web/HTTP/Headers/DPR
tags:
- DPR
- Client hints
- HTTP
- HTTP Header
- Request header
- Deprecated
- Non-standard
- Exerimental
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deprecated, non-standard, experimental? What is going on here?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Elchi3 This is a reflection of the BCD.
image

Previously experimental was omitted - so all I did was add the tag as well (this updates the sidebar with the icon).

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>
Expand Down
7 changes: 5 additions & 2 deletions files/en-us/web/http/headers/early-data/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 0 additions & 1 deletion files/en-us/web/http/headers/feature-policy/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
tags:
- Authorization
- Experimental
- Feature Policy
- Feature-Policy
- HTTP
- Permissions
Expand Down
10 changes: 6 additions & 4 deletions files/en-us/web/http/headers/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No longer experimental?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Elchi3 Still experimental but also deprecated.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For all of these I matched the docs to BCD. Note that arguably for page headers you only need one of these - the deprecated. But since I can't find a clear policy on that I haven't removed the other headers. I have been trying to discuss/get agreement on that in the context of auto-generation of headers from BCD.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for matching BCD, let's go with this then.

<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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down
12 changes: 6 additions & 6 deletions files/en-us/web/http/headers/save-data/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down