chore(http): Refresh headers ~[s->x] #36862

bsmth · 2024-11-19T13:49:20Z

Description

This PR refreshes a few HTTP headers pages.

common changes:

Add missing properties tables
Capitalize Yes/No in properties table & move verbose notes/caveats under table
Normalize The HTTP **`Header-Name`** (request|response) header in first sentence
Add status text to HTTPStatus macros, e.g. {{HTTPStatus("406", "406 Not Acceptable")}}
Improve Syntax section where possible
Remove improper use of quotes in and around code
Avoid escaping angle brackets in directive names in favor of backticks:

- \<directive>
+ `<directive>`

Motivation

Keeping content up-to-date, fixing formatting, unifying writing conventions

files/en-us/web/http/headers/service-worker-navigation-preload/index.md

files/en-us/web/http/headers/sourcemap/index.md

github-actions · 2024-11-19T14:56:36Z

Preview URLs (41 pages)

External URLs (40)

URL: /en-US/docs/Glossary/Source_map
Title: Source map

https://firefox-source-docs.mozilla.org/devtools-user/debugger/how_to/use_a_source_map/index.html (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Viewport-Width
Title: Viewport-Width

https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-client-hints-07 (1 time) (Note! This may be a new URL 👀)
https://wicg.github.io/responsive-image-client-hints/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/WWW-Authenticate
Title: WWW-Authenticate

https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/X-Forwarded-For
Title: X-Forwarded-For

https://en.wikipedia.org/wiki/Private_network (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Proxy-Authenticate
Title: Proxy-Authenticate

https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Set-Login
Title: Set-Login

Preventing silent timing attacks w3c-fedid/FedCM#447 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Origin-Agent-Cluster
Title: Origin-Agent-Cluster

https://tc39.es/ecma262/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/X-XSS-Protection
Title: X-XSS-Protection

https://blogs.windows.com/windows-insider/2018/07/25/announcing-windows-10-insider-preview-build-17723-and-build-18204/ (1 time) (Note! This may be a new URL 👀)
https://bugzil.la/528661 (1 time) (Note! This may be a new URL 👀)
https://chromestatus.com/feature/5021976655560704 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Want-Repr-Digest
Title: Want-Repr-Digest

https://developer.ebay.com/develop/guides/digital-signatures-for-apis (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Proxy-Authorization
Title: Proxy-Authorization

https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/SourceMap
Title: SourceMap

https://web.dev/articles/source-maps (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Vary
Title: Vary

https://www.fastly.com/blog/best-practices-using-vary-header (1 time) (Note! This may be a new URL 👀)
https://www.smashingmagazine.com/2017/11/understanding-vary-header/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/TE
Title: TE

https://en.wikipedia.org/wiki/LZ77_and_LZ78 (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/LZW (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/Zlib (1 time) (Note! This may be a new URL 👀)
https://httpwg.org/specs/rfc9113.html (1 time) (Note! This may be a new URL 👀)
https://httpwg.org/specs/rfc9114.html (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/X-Content-Type-Options
Title: X-Content-Type-Options

https://fetch.spec.whatwg.org/ (2 times) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Width
Title: Width

https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-client-hints-07 (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-security/user-agent-client-hints (1 time) (Note! This may be a new URL 👀)
https://wicg.github.io/responsive-image-client-hints/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Want-Content-Digest
Title: Want-Content-Digest

https://developer.ebay.com/develop/guides/digital-signatures-for-apis (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Set-Cookie
Title: Set-Cookie

https://fetch.spec.whatwg.org/ (2 times) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Tk
Title: Tk

https://en.wikipedia.org/wiki/Do_Not_Track (1 time) (Note! This may be a new URL 👀)
https://globalprivacycontrol.org/ (2 times) (Note! This may be a new URL 👀)
https://support.mozilla.org/en-US/kb/global-privacy-control?as=u&utm_source=inproduct (1 time) (Note! This may be a new URL 👀)
https://www.eff.org/deeplinks/2011/02/what-does-track-do-not-track-mean (1 time) (Note! This may be a new URL 👀)
https://www.eff.org/issues/do-not-track (1 time) (Note! This may be a new URL 👀)
https://www.w3.org/TR/tracking-dnt/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
Title: Strict-Transport-Security

https://blog.sidstamm.com/2010/08/http-strict-transport-security-has.html (1 time) (Note! This may be a new URL 👀)
https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Strict_Transport_Security_Cheat_Sheet.html (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security (1 time) (Note! This may be a new URL 👀)
https://hacks.mozilla.org/2010/08/firefox-4-http-strict-transport-security-force-https/ (1 time) (Note! This may be a new URL 👀)
https://hstspreload.org (1 time) (Note! This may be a new URL 👀)
https://hstspreload.org/ (2 times) (Note! This may be a new URL 👀)
https://www.chromium.org/hsts/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-12-01 22:52:16)

github-actions · 2024-11-25T09:02:18Z

This pull request has merge conflicts that must be resolved before it can be merged.

files/en-us/web/http/headers/server-timing/index.md

hamishwillee · 2024-12-02T00:32:49Z

files/en-us/web/http/headers/sourcemap/index.md

-The **`SourceMap`** [HTTP](/en-US/docs/Web/HTTP) response header links generated code to a [source map](https://firefox-source-docs.mozilla.org/devtools-user/debugger/how_to/use_a_source_map/index.html), enabling the browser to reconstruct the original source and present the reconstructed original in the debugger.
+The HTTP **`SourceMap`** {{Glossary("response header")}} links generated code to a {{Glossary("source map")}}, enabling the browser to reconstruct the original source and present the reconstructed original in the debugger.
+
+The HTTP `SourceMap` header has precedence over a source annotation (`sourceMappingURL=path-to-map.js.map`), and if both are present, the header URL is used to resolve the source map file.


Link to sourceMappingURL?

hamishwillee · 2024-12-02T00:36:57Z

files/en-us/web/http/headers/sourcemap/index.md

 ```

+Developer tools use the mappings between optimized code and the original source to improve readability, which can make debugging easier.


Suggested change

Developer tools use the mappings between optimized code and the original source to improve readability, which can make debugging easier.

Developer tools use the source map to reconstruct the original source from the optimized JavaScript returned in the response, allowing developers to debug the original code rather than the format that has been optimized for sending.

hamishwillee · 2024-12-02T00:51:48Z

files/en-us/web/http/headers/te/index.md

-the user agent is willing to accept. (you could informally call it
-`Accept-Transfer-Encoding`, which would be more intuitive).
+The HTTP **`TE`** {{Glossary("request header")}} specifies the transfer encodings the user agent is willing to accept.
+Some people informally consider "`Accept-Transfer-Encoding`" to be a more intuitive name for this header.


I'm sure they do, as do I. But it's odd to talk about a more intuitive name that doesn't exist.

Suggested change

Some people informally consider "`Accept-Transfer-Encoding`" to be a more intuitive name for this header.

hamishwillee · 2024-12-02T00:55:40Z

files/en-us/web/http/headers/te/index.md

-> [HTTP/2](https://httpwg.org/specs/rfc9113.html#ConnectionSpecific) and
-> [HTTP/3](https://httpwg.org/specs/rfc9114.html#header-formatting), the `TE`
-> header field is only accepted if the `trailers` value is set.
+Note that `chunked` is always acceptable for HTTP/1.1 recipients and you don't have to specify `chunked` using the `TE` header.


What is chunked? It isn't mentioned elsewhere in this doc. I would assume a kind of encoding but it is not listed

hamishwillee · 2024-12-02T01:01:29Z

files/en-us/web/http/headers/tk/index.md

@@ -82,9 +82,14 @@ Tk: N

 ## Specifications

-Part of the discontinued [Tracking Preference Expression (DNT)](https://www.w3.org/TR/tracking-dnt/#response-header-field) specification.
+The discontinued [Tracking Preference Expression (DNT)](https://www.w3.org/TR/tracking-dnt/#response-header-field) specification.


Why not do this using spec-url?

hamishwillee · 2024-12-02T01:04:26Z

files/en-us/web/http/headers/trailer/index.md

-dynamically generated while the message body is sent, such as a message integrity check,
-digital signature, or post-processing status.
+The HTTP **Trailer** {{glossary("request header", "request")}} and {{glossary("response header")}} allows the sender to include additional fields at the end of chunked messages in order to supply metadata that might be dynamically generated while the message body is sent.
+The content of a trailer field may be a message integrity check, digital signature, or post-processing status.


Or Server-Timing, and maybe other things - is this canonical or "for example"?

hamishwillee · 2024-12-02T01:07:58Z

files/en-us/web/http/headers/trailer/index.md


-In this example, the {{HTTPHeader("Expires")}} header is used at the end of the chunked
-message and serves as a trailing header.
+In this example response, the {{HTTPHeader("Expires")}} header is used at the end of the chunked message and serves as a trailing header:


Confusing.

Suggested change

In this example response, the {{HTTPHeader("Expires")}} header is used at the end of the chunked message and serves as a trailing header:

In this example response, the {{HTTPHeader("Expires")}} header is used as a trailing header:

hamishwillee · 2024-12-02T01:09:49Z

files/en-us/web/http/headers/transfer-encoding/index.md


 `Transfer-Encoding` is a [hop-by-hop header](/en-US/docs/Web/HTTP/Headers#hop-by-hop_headers), that is applied to a message between two nodes, not to a resource itself.
 Each segment of a multi-node connection can use different `Transfer-Encoding` values.
 If you want to compress data over the whole connection, use the end-to-end {{HTTPHeader("Content-Encoding")}} header instead.

 When present on a response to a {{HTTPMethod("HEAD")}} request that has no body, it indicates the value that would have applied to the corresponding {{HTTPMethod("GET")}} message.

+> [!WARNING]
+> HTTP/2 disallows all uses of the `Transfer-Encoding` header other than the HTTP/2 specific value `"trailers"`.
+> HTTP/2 and later provides other, more efficient, mechanisms for data streaming than chunked transfer.


Provide?

Suggested change

> HTTP/2 and later provides other, more efficient, mechanisms for data streaming than chunked transfer.

> HTTP/2 and later provide other, more efficient, mechanisms for data streaming than chunked transfer.

hamishwillee · 2024-12-02T01:15:49Z

files/en-us/web/http/headers/upgrade/index.md

+    - `<protocol_version>` {{optional_inline}}
+      - : An optional protocol version may be provided prefixed with a `/` forward slash.


Should this be indented?

hamishwillee · 2024-12-02T01:16:48Z

files/en-us/web/http/headers/upgrade/index.md


-The `Upgrade` header field may be used by clients to invite a server to switch to one (or more) of the listed protocols, in descending preference order.
+```http
+Upgrade: <protocol>[/<protocol_version>]


I can't remember if we normally show multiples here, rather than stating below that they are comma separated. But I think we do

hamishwillee · 2024-12-02T01:28:41Z

files/en-us/web/http/headers/want-content-digest/index.md

-> [!NOTE]
-> In contrast to earlier drafts of the specifications, the weighting is _not_ declared via [q-values](/en-US/docs/Glossary/Quality_values).
+```http
+Want-Content-Digest: <digest-algorithm>=<preference>


This implies you can set only one value, even though example below shows multiples, and you would not necessarily need preference if you could only set one.

hamishwillee · 2024-12-02T01:29:10Z

files/en-us/web/http/headers/want-content-digest/index.md


 ## Directives

-For permissible digest algorithms see {{HTTPHeader("Repr-Digest")}}.
+- `<digest-algorithm>`
+  - : The algorithm used to create a digest of the message content.


Should this be something like "the algorithm to be used to ..."

hamishwillee · 2024-12-02T01:29:58Z

files/en-us/web/http/headers/want-repr-digest/index.md

-> [!NOTE]
-> In contrast to earlier drafts of the specifications, the weighting is _not_ declared via [q-values](/en-US/docs/Glossary/Quality_values).
+```http
+Want-Repr-Digest: <digest-algorithm>=<preference>


Ditto to above - do we need to indicate multiple values are allowed here?

hamishwillee · 2024-12-02T01:30:45Z

files/en-us/web/http/headers/want-repr-digest/index.md


 ## Directives

-For permissible digest algorithms see {{HTTPHeader("Repr-Digest")}}.
+- `<digest-algorithm>`
+  - : The algorithm used to create a digest of the representation.


As above - the "requested algorithm" or something to state that this is wanted. Perhaps this is fine.

hamishwillee · 2024-12-02T01:36:27Z

files/en-us/web/http/headers/www-authenticate/index.md

-...
-WWW-Authenticate: challengeN
+```plain
+WWW-Authenticate = #challenge


Why #

Oh, I see - I think you're perhaps pulling this out of the spec to mean "some kind of challenge". Lets not do that.

hamishwillee · 2024-12-02T01:41:30Z

files/en-us/web/http/headers/www-authenticate/index.md

-WWW-Authenticate: <auth-scheme> realm=<realm> auth-param1=auth-param1-token, ..., auth-paramN=auth-paramN-token
-WWW-Authenticate: <auth-scheme> token68 auth-param1=auth-param1-token, ..., auth-paramN=auth-paramN-token
+```plain
+challenge = <auth-scheme> [ 1*SP ( <token68> / #<auth-param> ) ]


I don't understand this syntax. We don't use it anywhere else, and it is nowhere near as clear as what it replaces.

For example, what is 1*SP? What is #<auth-param>.

Web APIs and CSS spell out the options. I'm not sure that is possible here, but certainly this is not helpful without some more work.

hamishwillee · 2024-12-02T01:42:31Z

files/en-us/web/http/headers/www-authenticate/index.md

-    According to the specification, it can hold a base64, base64url, base32, or base16 (hex) encoding, with or without padding, but excluding whitespace.
+  - : A token that may be useful for some schemes.
+    The token allows the 66 unreserved URI characters plus a few others.
+    According to the specification, it can hold a {{glossary("base64")}}, base64url, base32, or base16 (hex) encoding, with or without padding, but excluding whitespace.


Do we need "According to the specification, " (see similar previous comment)

hamishwillee · 2024-12-02T01:44:04Z

files/en-us/web/http/headers/www-authenticate/index.md

+WWW-Authenticate: challenge1, …, challengeN
+```
+
+Multiple challenges can be sent in separate `WWW-Authenticate` headers in the same response:


I wonder if this should also be said up in the syntax section.

hamishwillee · 2024-12-02T01:46:33Z

files/en-us/web/http/headers/x-content-type-options/index.md

@@ -53,6 +42,15 @@ X-Content-Type-Options: nosniff
    `style` and the MIME type is not `text/css`,
    or of type `script` and the MIME type is not a [JavaScript MIME type](https://html.spec.whatwg.org/multipage/scripting.html#javascript-mime-type).

+## Description
+
+This header was introduced by Microsoft in IE 8 as a way for webmasters to block content sniffing that was happening and could transform non-executable MIME types into executable MIME types.


Feels like there should be a BCD entry for this and the information here should go into it.

hamishwillee · 2024-12-02T01:49:15Z