HTTP headers: deprecating "(Want-)?Digest", adding "(Want-)?(Content-|Repr-)Digest" #26885

jfrech · 2023-05-21T21:03:20Z

Legacy description based off of draft 7.

github-actions · 2023-05-21T23:01:03Z

Preview URLs

External URLs (3)

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

https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-digest-headers-08 (1 time) (Note! This may be a new URL 👀)

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

https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-digest-headers-07 (1 time) (Note! This may be a new URL 👀)
https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-digest-headers-08 (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-05-30 00:35:42)

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

hamishwillee · 2023-05-21T23:16:57Z

Thanks very much. This is great but we'll want to do more. From the current spec:

Introduced Repr-Digest and Want-Repr-Digest, and deprecated Digest and Want-Digest. Use of Structured Fields. 1993, 1919

So we want to deprecate Want-Digest and add Repr-Digest and Want-Repr-Digest. Do you want to take a shot at that?

Note that there are a couple of macros we use to indicate deprecation - I added one above for the header, but in lists of headers and whatever you can use {{Deprecated_Inline}}.

If `Repr-Digest is a representation header we'll want to add it here too: https://developer.mozilla.org/en-US/docs/Glossary/Representation_header

@teoli2003 The deprecated macro should really be able to include the information in @jfrech warning block. Can we modify the macro to allow specification of what the deprecation cause/replacement is?

jfrech · 2023-05-29T17:10:49Z

@hamishwillee In e. g. Sec-CH-UA-Full-Version, deprecation replacement is indicated by a Note. I only used a Warning since e. g. Accept-CH-Lifetime notes a draft removal as a Warning.
So a more specific way to note prior feature existence and/or recommended newer alternatives may indeed be nice to have.

jfrech · 2023-05-29T18:16:39Z

@hamishwillee May I double-check my interpretation of the spec with you?

I read it to claim the Repr- to be the Selected Representation, fully dependent on Content Negotiation which takes Content-Type into account. Does this mean Content-Digest is of no use whatsoever if the "actual message content" (cf. https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-digest-headers-12#section-2) is not selectable as a representation (e. g. MDN's source files only being selectable as HTML)?

jfrech · 2023-05-29T20:44:43Z

@hamishwillee Should we remove "Content-Location" from the glossary? After all, it does not describe the representation sent by the associated HTTP message.

files/en-us/glossary/representation_header/index.md

hamishwillee · 2023-05-30T00:06:38Z

g. Sec-CH-UA-Full-Version, deprecation replacement is indicated by a Note. I only used a Warning since e. g. Accept-CH-Lifetime notes a draft removal as a Warning.

Yes, it would be great to be able to include deprecation replacement info in the macro itself, allowing just one note to be used to indicate deprecation. Let's see if we can get traction here: mdn/yari#8969.

I'm going to change to a note. This is purely my taste - there is no real rule as far as I know.

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

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

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

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

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

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

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

hamishwillee · 2023-06-16T02:07:38Z

@jfrech Other than the linter nits I think I've taken this as far as I want to. @teoli2003 should be around soon, and hopefully will take this to the end. He's far more experience than me on this!

teoli2003

A few extra points, but overall this looks good and close to be ready

teoli2003 · 2023-07-17T05:50:41Z

files/en-us/glossary/representation_header/index.md


-Representation headers may be present in both HTTP request and response messages.
-If sent as a response to a `HEAD` request, they describe the body content that _would_ be selected if the resource was actually requested.
+Whilst representations are different forms of resources, representations can themselves also be transmitted in different forms: an HTTP message frames (cf. e.&hairsp;g. HTTP/1.1's {{HTTPHeader("Transfer-Encoding")}}) a particular stream of octets (cf. e.&hairsp;g. {{HTTPHeader("Content-Range")}}) derived from the _selected representation_.


Suggested change

Whilst representations are different forms of resources, representations can themselves also be transmitted in different forms: an HTTP message frames (cf. e.&hairsp;g. HTTP/1.1's {{HTTPHeader("Transfer-Encoding")}}) a particular stream of octets (cf. e.&hairsp;g. {{HTTPHeader("Content-Range")}}) derived from the _selected representation_.

While representations are different forms of resources, representations can themselves also be transmitted in various forms: an HTTP message frames (cf., e.g., HTTP/1.1's {{HTTPHeader("Transfer-Encoding")}}), a particular stream of octets (cf., e.g., {{HTTPHeader("Content-Range")}}) derived from the _selected representation_.

teoli2003 · 2023-07-17T05:51:15Z

files/en-us/glossary/representation_header/index.md


 ## See also

 - [RFC 9110, section 3.2: Representations](https://httpwg.org/specs/rfc9110.html#representations)
 - [List of all HTTP headers](/en-US/docs/Web/HTTP/Headers)
 - {{Glossary("Payload header")}}
 - {{glossary("Entity header")}}
- {{HTTPHeader("Digest")}}/ {{HTTPHeader("Want-Digest")}}
+- {{HTTPHeader("Repr-Digest")}}, {{HTTPHeader("Want-Repr-Digest")}}
+- pertaining to particular forms of the selected representation: {{HTTPHeader("Content-Digest")}}, {{HTTPHeader("Want-Content-Digest")}}


Suggested change

- pertaining to particular forms of the selected representation: {{HTTPHeader("Content-Digest")}}, {{HTTPHeader("Want-Content-Digest")}}

- {{HTTPHeader("Content-Digest")}}, {{HTTPHeader("Want-Content-Digest")}}

teoli2003 · 2023-07-17T05:52:20Z

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

+As such, `Content-Digest` is dependent on among other things {{HTTPHeader("Content-Encoding")}} and {{HTTPHeader("Content-Range")}}, but not dependent on, for example, HTTP/1.1's {{HTTPHeader("Transfer-Encoding")}}.
+`Content-Digest` may coincide with {{HTTPHeader("Repr-Digest")}} if a representation was sent in a single message.
+
+"content" in this setting refers to a particular octet representation of the [selected representation](https://www.rfc-editor.org/rfc/rfc9110#section-6.4) of the target resource.


Suggested change

"content" in this setting refers to a particular octet representation of the [selected representation](https://www.rfc-editor.org/rfc/rfc9110#section-6.4) of the target resource.

In this setting, _content_ refers to a particular octet representation of the [selected representation](https://www.rfc-editor.org/rfc/rfc9110#section-6.4) of the target resource.

teoli2003 · 2023-07-17T05:53:36Z

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

+
+{{HTTPSidebar}}{{SeeCompatTable}}
+
+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.&hairsp;g. {{HTTPHeader("Content-Encoding")}} or {{HTTPHeader("Content-Range")}}, which do affect the {{HTTPHeader("Content-Digest")}}. Note furthermore that [Content Negotiation](/en-US/docs/Web/HTTP/Content_negotiation) can result in different selected representation with respectively different representation digests.


Suggested change

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.&hairsp;g. {{HTTPHeader("Content-Encoding")}} or {{HTTPHeader("Content-Range")}}, which do affect the {{HTTPHeader("Content-Digest")}}. Note furthermore that [Content Negotiation](/en-US/docs/Web/HTTP/Content_negotiation) can result in different selected representation with respectively different representation digests.

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.

teoli2003 · 2023-07-17T05:55:02Z

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

+`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).
+
+> **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).


I wonder if we should have a glossary entry for RFC8941 dictionary: I don't like to send readers to the spec (that are difficult to understand) to grasp the syntax.

teoli2003 · 2023-07-17T05:55:33Z

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

+...
+```
+
+### Example: HTTP responses where {{HTTPHeader("Repr-Digest")}} and {{HTTPHeader("Content-Digest")}} diverge


Suggested change

### Example: HTTP responses where {{HTTPHeader("Repr-Digest")}} and {{HTTPHeader("Content-Digest")}} diverge

### HTTP responses where {{HTTPHeader("Repr-Digest")}} and {{HTTPHeader("Content-Digest")}} diverge

teoli2003 · 2023-07-17T05:55:44Z

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

+...
+```
+
+### Example: Successful HTTP request-response employing {{HTTHeader("Want-Repr-Digest")}}, {{HTTHeader("Repr-Digest")}}, {{HTTHeader("Content-Digest")}}


Suggested change

### Example: Successful HTTP request-response employing {{HTTHeader("Want-Repr-Digest")}}, {{HTTHeader("Repr-Digest")}}, {{HTTHeader("Content-Digest")}}

### Successful HTTP request-response employing {{HTTHeader("Want-Repr-Digest")}}, {{HTTHeader("Repr-Digest")}}, {{HTTHeader("Content-Digest")}}

teoli2003 · 2023-07-17T05:55:53Z

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

+...
+```
+
+### Example: Unsuccessful HTTP request-response employing {{HTTHeader("Repr-Digest")}}


Suggested change

### Example: Unsuccessful HTTP request-response employing {{HTTHeader("Repr-Digest")}}

### Unsuccessful HTTP request-response employing {{HTTHeader("Repr-Digest")}}

teoli2003 · 2023-07-17T05:56:17Z

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

+
+`Want-Content-Digest` describes an [RFC8941 dictionary](https://www.rfc-editor.org/rfc/rfc8941#section-3.2) with its keys being hashing algorithms and its values being the integers `0` (meaning "not acceptable") or `1` to `9` (conveying ascending, relative, weighted preference).
+
+> **Note:** In contrast to earlier drafts of the specifications, the weighting is *not* declared via [q-values](/en-US/docs/Glossary/Quality_values).


Suggested change

> **Note:** In contrast to earlier drafts of the specifications, the weighting is *not* declared via [q-values](/en-US/docs/Glossary/Quality_values).

> **Note:** In contrast to earlier drafts of the specifications, the weighting is _not_ declared via [q-values](/en-US/docs/Glossary/Quality_values).

teoli2003 · 2023-07-17T05:56:44Z

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

+
+`Want-Repr-Digest` describes an [RFC8941 dictionary](https://www.rfc-editor.org/rfc/rfc8941#section-3.2) with its keys being hashing algorithms and its values being the integers `0` (meaning "not acceptable") or `1` to `9` (conveying ascending, relative, weighted preference).
+
+> **Note:** In contrast to earlier drafts of the specifications, the weighting is *not* declared via [q-values](/en-US/docs/Glossary/Quality_values).


Suggested change

> **Note:** In contrast to earlier drafts of the specifications, the weighting is *not* declared via [q-values](/en-US/docs/Glossary/Quality_values).

> **Note:** In contrast to earlier drafts of the specifications, the weighting is _not_ declared via [q-values](/en-US/docs/Glossary/Quality_values).

bsmth · 2024-01-09T11:23:09Z

Hi @jfrech - thanks a lot for the submission. There are some review comments outstanding above, would you like to come back to this one? @teoli2003 has indicated that "this looks good and close to be ready", so it would be great to have your work land eventually.

jfrech requested a review from a team as a code owner May 21, 2023 21:03

jfrech requested review from teoli2003 and removed request for a team May 21, 2023 21:03

github-actions bot added the Content:HTTP HTTP docs label May 21, 2023

hamishwillee reviewed May 21, 2023

View reviewed changes

files/en-us/web/http/headers/digest/index.md Outdated Show resolved Hide resolved

jfrech changed the title ~~HTTP header "Digest": set status to "deprecated", fixed legacy description~~ HTTP headers: deprecating "(Want-)?Digest", adding "(Want-)?(Content-|Repr-)Digest" May 29, 2023

jfrech requested a review from a team as a code owner May 29, 2023 20:43

github-actions bot added the Content:Glossary Glossary entries label May 29, 2023

hamishwillee reviewed May 29, 2023

View reviewed changes

files/en-us/glossary/representation_header/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed May 29, 2023

View reviewed changes

files/en-us/glossary/representation_header/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed May 29, 2023

View reviewed changes

files/en-us/glossary/representation_header/index.md Show resolved Hide resolved

hamishwillee reviewed May 29, 2023

View reviewed changes

files/en-us/glossary/representation_header/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed May 29, 2023

View reviewed changes

files/en-us/glossary/representation_header/index.md Outdated Show resolved Hide resolved