fix(algorithms): better explain structured header serialization #1
Conversation
There was a problem hiding this comment.
Agreed keeping it as a separate algorithm does help with organization and it's also a good spot for an example. However, it feels a bit odd that the algorithm is referred only once. Maybe it'd be nice to give it a more specialized name such as setting content-digest header. Wdyt?
Also it might be helpful to define the algorithm as:
To set as structured header given a string headerName , string algorithm, string digestValue. See, for example,
https://html.spec.whatwg.org/multipage/popover.html#show-popover
I'd also suggest referring directly to rfc8941 spec serialization part instead of just the definitions. Something like: let headerValue be the result of serizalizing a dictionary structure (https://www.rfc-editor.org/rfc/rfc8941#name-serializing-a-dictionary) of a single key sha-512 and an item of byte sequence type (https://www.rfc-editor.org/rfc/rfc8941#name-serializing-a-byte-sequence).
It's actually referred twice, that's why generic name. First for |
|
Tried to make it clearer in 17a1238.
|
section/algorithms.html
Outdated
| <ol> | ||
| <li>Let |headerValue:structured field dictionary| be a <a data-cite="RFC9651#dictionary">structured field dictionary</a> with a single key |key| with corresponding value |value|.</li> | ||
| <li>Let |header| be a [=tuple=] of |headerName| and |headerValue|.</li> | ||
| <li>[=header list/Set a structured field value=] |header| to the [=request/header list=] of the |request|. The |headerValue| must be <a data-cite="RFC9651#name-serializing-a-dictionary">serialized</a> as described in [[RFC9651]].</li> |
There was a problem hiding this comment.
RFC9651 reference should probably go into note section, because [=header list/Set a structured field value=] specifies that for a structure field value, right?
section/algorithms.html
Outdated
| @@ -374,9 +374,9 @@ <h4>Generate HTTP Signature</h4> | |||
| <li> | |||
| Let <var>components</var> be an array of strings identifying which content (headers, etc.) to include in the signature. | |||
| <ol> | |||
| <li>Let `components` default value be `<<"@method", "@target-uri">>`.</li> | |||
| <li>Let |components| default value be `<<"@method", "@target-uri">>`.</li> | |||
There was a problem hiding this comment.
initial value?
Also <<"item">> feels like a form of serialization of an array of strings, would be better to move that into item 6-8. Btw, it'd be nice to restructure those into a form of let canonicalData be ...
|
(I'm avoiding rewriting everything in this PR, keeping it focused to header serialization) |
No description provided.