chore(http): Refresh headers r-s

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

@@ -7,7 +7,13 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc9530
 
 {{HTTPSidebar}}
 
-The **`Repr-Digest`** response or request header provides a {{Glossary("digest")}} of the [selected representation](https://www.rfc-editor.org/rfc/rfc9110#section-6.4) of the target resource. It is invariant under e.g., {{HTTPHeader("Content-Encoding")}} or {{HTTPHeader("Content-Range")}}, which do affect the {{HTTPHeader("Content-Digest")}}. Furthermore, [Content Negotiation](/en-US/docs/Web/HTTP/Content_negotiation) can result in different selected representations with different representation digests.
+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 _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.
 
 <table class="properties">
   <tbody>
@@ -17,104 +23,129 @@ The **`Repr-Digest`** response or request header provides a {{Glossary("digest")
     </tr>
     <tr>
       <th scope="row">{{Glossary("Forbidden header name")}}</th>
-      <td>no</td>
+      <td>No</td>
     </tr>
   </tbody>
 </table>
 
 ## Syntax
 
-`Repr-Digest` describes an [RFC8941 dictionary](https://www.rfc-editor.org/rfc/rfc8941#section-3.2) with its keys being names of digest algorithms and its values being the digest in bytes (or an integer digest for legacy digest algorithms).
+```http
+Repr-Digest: <digest-algorithm>=<digest-value>
 
-> [!NOTE]
-> 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).
+// Multiple digest algorithms
+Repr-Digest: <digest-algorithm>=<digest-value>,<digest-algorithm>=<digest-value>
+```
 
 ## Directives
 
-### Digest algorithms
+- `<digest-algorithm>`
+  - : The algorithm used to create a digest of the representation.
+    Only two registered digest algorithms are considered secure: `sha-512` and `sha-256`.
+    The insecure (legacy) registered digest algorithms are: `md5`, `sha` (SHA-1), `unixsum`, `unixcksum`, `adler` (ADLER32) and `crc32c`.
+- `<digest-value>`
+  - : The digest in bytes of the representation using the `<digest-algorithm>`.
+    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).
 
-Only two digest algorithms are currently registered and not considered insecure: `sha-512` and `sha-256`.
-
-The registered insecure digest algorithms are: `md5`, `sha` (SHA-1), `unixsum`, `unixcksum`, `adler` (ADLER32) and `crc32c`.
-
-Usage of digest algorithms which are considered insecure is discouraged as collisions can realistically be forced, rendering the digest's usefulness weak. Unless when working with legacy systems (which is unlikely since most will expect the legacy {{HTTPHeader("Digest")}} header and not understand this specification), consider not emitting a `Repr-Digest` instead of emitting one using an insecure digest algorithm.
+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.
 
 ## Examples
 
 ### HTTP response where `Repr-Digest` and `Content-Digest` coincide
 
-An HTTP server may send content octets equivalent to the selected representation's octets:
+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:
 
 ```http
-...
+…
 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
-...
+…
+
+[message body]
 ```
 
 ### HTTP responses where `Repr-Digest` and `Content-Digest` diverge
 
-A static file server may however choose to compress an HTML page, resulting in differing {{HTTPHeader("Content-Digest")}} and `Repr-Digest` header values:
+A server may compress the content for sending.
+In this case {{HTTPHeader("Content-Digest")}} will depend on the {{HTTPHeader("Content-Encoding")}}, and will therefore have a different value to the `Repr-Digest` header in a response:
 
 ```http
-...
+…
 Repr-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=:, sha-512=:U59TCCaZPA9Qio3CzHJVAgDnIAut53t5Sgkj2Gv4BvDd0b+OX9QpIdgWkzdXLmBsmvBrf3t5PBt+UrVK6k5dkw==:
 Content-Digest: sha-256=:293wcr5IoFAsDCzdoDXR1Qppgf2yxOPO1bvQ3nZQtuI=:, unixsum=54809
-...
+…
 Content-Type: text/html; charset=utf-8
 Content-Encoding: br
-...
+…
 
-...
+[message body]
 ```
 
+In another response, the server uses a different compression method, resulting in a new `Content-Digest`, but the same `Repr-Digest` digests:
+
 ```http
-...
+…
 Repr-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=:, sha-512=:U59TCCaZPA9Qio3CzHJVAgDnIAut53t5Sgkj2Gv4BvDd0b+OX9QpIdgWkzdXLmBsmvBrf3t5PBt+UrVK6k5dkw==:
 Content-Digest: sha-256=:rv9Jivc4TmcacLUshzN3OdX7Hz+ORnQRaiTaIKZQ0zk=:
-...
+…
 Content-Type: text/html; charset=utf-8
-Content-Encoding: deflate, deflate, deflate
-...
+Content-Encoding: zstd
+…
 
-...
+[message body]
 ```
 
 ### Successful HTTP request-response employing `Want-Repr-Digest`, `Repr-Digest`, and `Content-Digest`
 
+The following {{HTTPMethod("PUT")}} request includes a `Want-Repr-Digest` header, indicating that the server should include a `Repr-Digest` header with a `sha-256` digest if the operation is successful:
+
 ```http
 PUT /api/transact HTTP/1.1
 Want-Repr-Digest: sha-256=8
 Content-Type: text/json
-...
+…
+
+[message body]
 ```
 
+The server responds with a successful {{HTTPStatus("201", "201 Created")}} response, including `Repr-Digest` and `Content-Digest` headers with sha-256 digests of the representation and content, respectively:
+
 ```http
 HTTP/1.1 201 Created
 Repr-Digest: sha-256=:W8oN3H3CmE/CBpV6ZPNozV2AIDzzQpWL7CCOXyDyDzI=:
 Content-Encoding: br
 Content-Digest: sha-256=:2IBI7hQn83oTCgB3Z/6apOl91WGoctRfRj/F9gkvVo8=:
-...
+…
+
+[message body]
 ```
 
 ### Unsuccessful HTTP request-response employing `Repr-Digest`
 
+In the following message, a client requests a resource with a specific sha-256 digest:
+
 ```http
 GET /api/last-transaction HTTP/1.1
 Accept: text/json
 Repr-Digest: sha-256=:2IBI7hQn83oTCgB3Z/6apOl91WGoctRfRj/F9gkvVo8=:
-...
+…
 ```
 
+A {{HTTPStatus("406", "406 Not Acceptable")}} is returned by the server to indicate the operation failed given a specific digest for the resource.
+A `Repr-Digest` header is included with the SHA-256 digest value that would result in a successful response if the client repeated the request with that value:
+
 ```http
 HTTP/1.1 406 Not Acceptable
 Repr-Digest: sha-256=:W8oN3H3CmE/CBpV6ZPNozV2AIDzzQpWL7CCOXyDyDzI=:
-...
+…
 ```
 
 ## Specifications

files/en-us/web/http/headers/retry-after/index.md

@@ -7,17 +7,12 @@ browser-compat: http.headers.Retry-After
 
 {{HTTPSidebar}}
 
-The **`Retry-After`** response HTTP header indicates how long
-the user agent should wait before making a follow-up request. There are three main cases
-this header is used:
-
-- When sent with a {{HTTPStatus(503)}} (Service Unavailable) response, this indicates
-  how long the service is expected to be unavailable.
-- When sent with a {{HTTPStatus(429)}} (Too Many Requests) response, this indicates
-  how long to wait before making a new request.
-- When sent with a redirect response, such as {{HTTPStatus(301)}} (Moved Permanently),
-  this indicates the minimum time that the user agent is asked to wait before issuing
-  the redirected request.
+The HTTP **`Retry-After`** {{Glossary("response header")}} indicates how long the user agent should wait before making a follow-up request.
+There are three main cases this header is used:
+
+- In a {{HTTPStatus("503", "503 Service Unavailable")}} response, this indicates how long the service is expected to be unavailable.
+- In a {{HTTPStatus("429", "429 Too Many Requests")}} response, this indicates how long to wait before making a new request.
+- In a redirect response, such as {{HTTPStatus("301", "301 Moved Permanently")}}, this indicates the minimum time that the user agent is asked to wait before issuing the redirected request.
 
 <table class="properties">
   <tbody>
@@ -27,7 +22,7 @@ this header is used:
     </tr>
     <tr>
       <th scope="row">{{Glossary("Forbidden header name")}}</th>
-      <td>no</td>
+      <td>No</td>
     </tr>
   </tbody>
 </table>
@@ -41,10 +36,10 @@ Retry-After: <delay-seconds>
 
 ## Directives
 
-- \<http-date>
+- `<http-date>`
   - : A date after which to retry. See the {{HTTPHeader("Date")}} header for more details
     on the HTTP date format.
-- \<delay-seconds>
+- `<delay-seconds>`
   - : A non-negative decimal integer indicating the seconds to delay after the response is
     received.
 
@@ -54,8 +49,7 @@ Retry-After: <delay-seconds>
 
 Support for the `Retry-After` header on both clients and servers is still
 inconsistent. However, some crawlers and spiders, like the Googlebot, honor the
-`Retry-After` header. It is useful to send it along with a
-{{HTTPStatus(503)}} (Service Unavailable) response, so that search engines will keep
+`Retry-After` header. It is useful to send it along with a `503` response, so that search engines will keep
 indexing your site when the downtime is over.
 
 ```http
@@ -73,6 +67,6 @@ Retry-After: 120
 
 ## See also
 
-- [Google Webmaster blog: How to deal with planned site downtime](https://webmasters.googleblog.com/2011/01/how-to-deal-with-planned-site-downtime.html)
-- {{HTTPStatus(503)}} (Service Unavailable)
-- {{HTTPStatus(301)}} (Moved Permanently)
+- {{HTTPStatus("503", "503 Service Unavailable")}}
+- {{HTTPStatus("301", "301 Moved Permanently")}}
+- [How to deal with planned site downtime](https://developers.google.com/search/blog/2011/01/how-to-deal-with-planned-site-downtime) on developers.google.com (2011)

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

@@ -9,7 +9,15 @@ browser-compat: http.headers.RTT
 
 {{HTTPSidebar}} {{SeeCompatTable}}
 
-The **`RTT`** [Client hint](/en-US/docs/Web/HTTP/Client_hints) request header field provides the approximate round trip time on the application layer, in milliseconds. The RTT hint, unlike transport layer RTT, includes server processing time.
+The HTTP **`RTT`** {{Glossary("request header")}} is a [network client hint](/en-US/docs/Web/HTTP/Client_hints#network_client_hints) which provides the approximate round trip time on the application layer, in milliseconds.
+The RTT hint includes server processing time, unlike transport layer RTT.
+
+The RTT value is rounded to the nearest 25 milliseconds to prevent [fingerprinting](/en-US/docs/Glossary/Fingerprinting), although there are many other mechanisms an attacker might use to obtain similar round-trip information.
+
+The hint allows a server to choose what information is sent based on the network responsiveness/latency. For example, it might choose to send fewer resources.
+
+> [!NOTE]
+> The {{HTTPHeader("Vary")}} header is used in responses to indicate that a different resource is sent for every different value of the header (see [HTTP Caching Vary](/en-US/docs/Web/HTTP/Caching#vary)). Even if `RTT` 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 uncacheable.
 
 <table class="properties">
   <tbody>
@@ -22,18 +30,11 @@ The **`RTT`** [Client hint](/en-US/docs/Web/HTTP/Client_hints) request header fi
     </tr>
     <tr>
       <th scope="row">{{Glossary("Forbidden header name")}}</th>
-      <td>no</td>
+      <td>No</td>
     </tr>
   </tbody>
 </table>
 
-The RTT value is rounded to the nearest 25 milliseconds to prevent [fingerprinting](/en-US/docs/Glossary/Fingerprinting). There are many other mechanisms an attacker might use to obtain similar round-trip information.
-
-The hint allows a server to choose what information is sent based on the network responsiveness/latency. For example, it might choose to send fewer resources.
-
-> [!NOTE]
-> The {{HTTPHeader("Vary")}} header is used in responses to indicate that a different resource is sent for every different value of the header (see [HTTP Caching Vary](/en-US/docs/Web/HTTP/Caching#vary)). Even if `RTT` 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 uncacheable.
-
 ## Syntax
 
 ```http
@@ -42,11 +43,13 @@ RTT: <number>
 
 ## Directives
 
-- \<number>
+- `<number>`
   - : The approximate round trip time in milliseconds, rounded to the nearest 25 milliseconds.
 
 ## Examples
 
+### Using RTT client hints
+
 A server first needs to opt in to receive the `RTT` header by sending the {{HTTPHeader("Accept-CH")}} response header containing `RTT`.
 
 ```http
@@ -69,13 +72,8 @@ RTT: 125
 
 ## See also
 
-- [Improving user privacy and developer experience with User-Agent Client Hints](https://developer.chrome.com/docs/privacy-security/user-agent-client-hints) (developer.chrome.com)
-- Network client hints
-
-  - {{HTTPHeader("Downlink")}}
-  - {{HTTPHeader("ECT")}}
-  - {{HTTPHeader("Save-Data")}}
-
+- {{HTTPHeader("Downlink")}}, {{HTTPHeader("ECT")}}, {{HTTPHeader("Save-Data")}} network client hints
 - {{HTTPHeader("Accept-CH")}}
-- [HTTP Caching > Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}}
+- [HTTP Caching: Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}}
 - {{domxref("NetworkInformation.effectiveType")}}
+- [Improving user privacy and developer experience with User-Agent Client Hints](https://developer.chrome.com/docs/privacy-security/user-agent-client-hints) (developer.chrome.com)