From e996e9a338a7a213fd54d5119d951b02543dc249 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 18 Nov 2024 17:37:30 +0100 Subject: [PATCH] chore(http): Changes following reviewer feedback --- .../web/http/headers/repr-digest/index.md | 18 +++++++++--------- .../en-us/web/http/headers/save-data/index.md | 10 ++++------ .../index.md | 2 +- .../sec-ch-ua-full-version-list/index.md | 6 +++--- .../en-us/web/http/headers/sec-ch-ua/index.md | 4 ++-- 5 files changed, 19 insertions(+), 21 deletions(-) diff --git a/files/en-us/web/http/headers/repr-digest/index.md b/files/en-us/web/http/headers/repr-digest/index.md index 3f290ba56462c08..e71299d244c113c 100644 --- a/files/en-us/web/http/headers/repr-digest/index.md +++ b/files/en-us/web/http/headers/repr-digest/index.md @@ -7,10 +7,13 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc9530 {{HTTPSidebar}} -The HTTP **`Repr-Digest`** {{Glossary("Request header", "request")}} and {{Glossary("Response header", "response header")}} provides a {{Glossary("digest")}} of the [selected representation](https://www.rfc-editor.org/rfc/rfc9110#section-6.4) of the target resource. +The HTTP **`Repr-Digest`** {{Glossary("Request header", "request")}} and {{Glossary("Response header", "response header")}} provides a {{Glossary("digest")}} of the selected representation of the target resource. -The representation digest applies to the whole resource rather than the encoding or chunking of the messages that are used to send it. This differs from {HTTPHeader("Content-Digest")}} which applies to the content of a particular message, and is therefore is affected by the {{HTTPHeader("Content-Encoding")}} and {{HTTPHeader("Content-Range")}} of each message. -Furthermore, [Content Negotiation](/en-US/docs/Web/HTTP/Content_negotiation) can result in different selected representations which results in different representation digests. +The _selected representation_ is the specific format of a resource chosen through [content negotiation](/en-US/docs/Web/HTTP/Content_negotiation). +Details about this representation can be determined from the response's {{Glossary("Representation header", "representation headers")}}, such as {{HTTPHeader("Content-Language")}}, {{HTTPHeader("Content-Type")}}, and {{HTTPHeader("Content-Encoding")}}. + +The representation digest applies to the whole resource rather than the encoding or chunking of the messages that are used to send it. +This differs from {{HTTPHeader("Content-Digest")}} which applies to the content of a particular message, and is therefore is affected by the {{HTTPHeader("Content-Encoding")}} and {{HTTPHeader("Content-Range")}} of each message. @@ -42,11 +45,9 @@ Repr-Digest: =,= The insecure (legacy) registered digest algorithms are: `md5`, `sha` (SHA-1), `unixsum`, `unixcksum`, `adler` (ADLER32) and `crc32c`. - `` - : The digest in bytes of the representation using the ``. - The choice of digest algorithm also determines the encoding to use: `sha-512` and `sha-256` use base64 encoding, while some legacy digest algorithms such as `unixsum` use a decimal integer. + The choice of digest algorithm also determines the encoding to use: `sha-512` and `sha-256` use {{Glossary("base64")}} encoding, while some legacy digest algorithms such as `unixsum` use a decimal integer. In contrast to earlier drafts of the specification, the standard-base64-encoded digest bytes are wrapped in colons (`:`, ASCII 0x3A) as part of the [dictionary syntax](https://www.rfc-editor.org/rfc/rfc8941#name-byte-sequences). -### Usage notes - Usage of insecure digest algorithms is discouraged as collisions can realistically be forced, rendering the digest's usefulness weak. Unless working with legacy systems (which is unlikely since most will expect the legacy {{HTTPHeader("Digest")}} header and not understand this specification), consider omitting a `Repr-Digest` instead of including one with an insecure digest algorithm. @@ -56,7 +57,6 @@ Unless working with legacy systems (which is unlikely since most will expect the An HTTP server may send the whole representation unencoded in a single message. In this case, `Repr-Digest` and `Content-Digest` have equal values for the same digest algorithms: -In this case, `Repr-Digest` and `Content-Digest` have equal values for the same digest algorithms: ```http … @@ -64,7 +64,7 @@ Repr-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=: Content-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=: … Content-Type: text/yaml -Content-Encoding: identity +Content-Encoding: br Content-Length: 38054 Content-Range: 0-38053/38054 … @@ -97,7 +97,7 @@ Repr-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=:, sha-512=:U5 Content-Digest: sha-256=:rv9Jivc4TmcacLUshzN3OdX7Hz+ORnQRaiTaIKZQ0zk=: … Content-Type: text/html; charset=utf-8 -Content-Encoding: deflate, deflate, deflate +Content-Encoding: zstd … [message body] diff --git a/files/en-us/web/http/headers/save-data/index.md b/files/en-us/web/http/headers/save-data/index.md index bca0da1cf54fe23..76f8757dde360f3 100644 --- a/files/en-us/web/http/headers/save-data/index.md +++ b/files/en-us/web/http/headers/save-data/index.md @@ -15,6 +15,9 @@ This could be for reasons such as high transfer costs, slow connection speeds, e `Save-Data` is a [low entropy hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints), and hence may be sent by the client even if not requested by the server using an {{HTTPHeader("Accept-CH")}} response header. Further, it should be used to reduce data sent to the client irrespective of the values of other client hints that indicate network capability, like {{HTTPHeader("Downlink")}} and {{HTTPHeader("RTT")}}. +A value of `On` indicates explicit user opt-in into a reduced data usage mode on the client. +When communicated to origins, this allows them to deliver alternative content to reduce the data downloaded such as smaller image and video resources, different markup and styling, disabled polling and automatic updates, and so on. + > [!NOTE] > Disabling HTTP/2 Server Push ({{RFC("7540", "Server Push", "8.2")}}) may reduce data downloads. > Note that this feature is no longer supported by default in most major browser engines. @@ -53,11 +56,6 @@ Save-Data: - : A value indicating whether the client wants to opt in to reduced data usage mode. `on` indicates yes, while `off` (the default) indicates no. -### Description - -A value of `On` indicates explicit user opt-in into a reduced data usage mode on the client. -When communicated to origins, this allows them to deliver alternative content to reduce the data downloaded such as smaller image and video resources, different markup and styling, disabled polling and automatic updates, and so on. - ## Examples ### Using `Save-Data: on` @@ -115,7 +113,7 @@ Content-Type: image/jpeg ## See also -- CSS @media feature [`prefers-reduced-data`](/en-US/docs/Web/CSS/@media/prefers-reduced-data) {{experimental_inline}} +- CSS `@media` feature [`prefers-reduced-data`](/en-US/docs/Web/CSS/@media/prefers-reduced-data) {{experimental_inline}} - {{HTTPHeader("Vary")}} header which indicates that the content served varies depending on the value of `Save-Data` (see [HTTP Caching: Vary](/en-US/docs/Web/HTTP/Caching#vary)) - {{domxref("NetworkInformation.saveData")}} - [Help Your Users `Save-Data`](https://css-tricks.com/help-users-save-data/) on css-tricks.com diff --git a/files/en-us/web/http/headers/sec-ch-prefers-reduced-transparency/index.md b/files/en-us/web/http/headers/sec-ch-prefers-reduced-transparency/index.md index e3e6b4963a09bdf..485065b1e5fe1e9 100644 --- a/files/en-us/web/http/headers/sec-ch-prefers-reduced-transparency/index.md +++ b/files/en-us/web/http/headers/sec-ch-prefers-reduced-transparency/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Sec-CH-Prefers-Reduced-Transparency {{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}} -The HTTP **`Sec-CH-Prefers-Reduced-Transparency`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user_preference_media_features_client_hints) which indicates the user agent's preference for reduced transparency. +The HTTP **`Sec-CH-Prefers-Reduced-Transparency`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user_preference_media_features_client_hints) that indicates the user agent's preference for reduced transparency. If a server signals to a client via the {{httpheader("Accept-CH")}} header that it accepts `Sec-CH-Prefers-Reduced-Transparency`, the client can then respond with this header to indicate the user's preference for reduced transparency. The server can send the client appropriately adapted content — for example, CSS or images — to reduce the transparency of the content. diff --git a/files/en-us/web/http/headers/sec-ch-ua-full-version-list/index.md b/files/en-us/web/http/headers/sec-ch-ua-full-version-list/index.md index dfa8e1f0d2493e0..7980e1a2598c134 100644 --- a/files/en-us/web/http/headers/sec-ch-ua-full-version-list/index.md +++ b/files/en-us/web/http/headers/sec-ch-ua-full-version-list/index.md @@ -52,13 +52,13 @@ Sec-CH-UA-Full-Version-List: "";v="", ... - `` - : A full version number, such as 98.0.4750.0. -#### Description +## Description A brand is a commercial name for the user agent like: Chromium, Opera, Google Chrome, Microsoft Edge, Firefox, and Safari. A user agent might have several associated brands. -For example, Opera, Chrome, and Edge are all based on Chromium, and will provide both brands in the **`Sec-CH-UA-Full-Version-List`** header. +For example, Opera, Chrome, and Edge are all based on Chromium, and will provide both brands in the `Sec-CH-UA-Full-Version-List` header. -The header therefore allows the server to customize its response based on both shared brands and on particular customizations in their specific respective builds. +The header allows the server to customize its response based on both shared brands and on particular customizations in their specific respective builds. ## Examples diff --git a/files/en-us/web/http/headers/sec-ch-ua/index.md b/files/en-us/web/http/headers/sec-ch-ua/index.md index 4517d398aad1194..024647e687f5c8a 100644 --- a/files/en-us/web/http/headers/sec-ch-ua/index.md +++ b/files/en-us/web/http/headers/sec-ch-ua/index.md @@ -45,7 +45,7 @@ A comma separated list of brands in the user agent brand list, and their associa The syntax for a single entry has the following format: ```http -Sec-CH-UA: "";v="", ... +Sec-CH-UA: "";v="", … ``` ### Directives @@ -55,7 +55,7 @@ Sec-CH-UA: "";v="", ... - `` - : The "marketing" version number associated with distinguishable web-exposed features. -#### Description +## Description A brand is a commercial name for the user agent like: Chromium, Opera, Google Chrome, Microsoft Edge, Firefox, and Safari. A user agent might have several associated brands.