Subject: Re: Working Group Last Call: Structured Headers for HTTP

From: Tommy Pauly <[email-masked]>
Date: Fri, 21 Feb 2020 13:40:51 -0800

Hi all,

Thanks for the good input during this WGLC! The authors will be producing an updated version of the draft to incorporate the feedback received during the last call, as is tracked on GitHub. We should expect that new version in the upcoming weeks, and then I’d like to see the document progress after that.

Best,
Tommy

> On Jan 29, 2020, at 9:11 AM, Tommy Pauly <[email-masked]> wrote:
> 
> Hi all,
> 
> The Structured Headers draft was updated yesterday, and Mark (as author) let me know that the authors believe this is ready for last call. The issues list is down to zero, so it's a good time for the working group to take a careful read-through the document, and get it progressed!
> 
> This email starts a working group last call, which will end on Friday, February 21. Please review the document and reply to the list with your comments (or file an issue), and state whether you think this document is ready for publication.
> 
> The current version of the document can be found here: https://tools.ietf.org/html/draft-ietf-httpbis-header-structure-15 <https://tools.ietf.org/html/draft-ietf-httpbis-header-structure-15>
> 
> Best,
> Tommy

---

From: Julian Reschke <[email-masked]>
Date: Sat, 22 Feb 2020 19:06:45 +0100

On 29.01.2020 18:11, Tommy Pauly wrote:
> ...

Below is my (slightly late feedback).

I was going to ask that the spec to be aligned with the recent
terminology clarification we did in the core specs (and which are not
yet published).

In fact, this is already addressed in the editor's draft, see current
diffs at
<https://greenbytes.de/tech/webdav/draft-ietf-httpbis-header-structure-latest-from-previous.diff.html>.
In encourage all participants to review these changes...

That said, the title probably should also change from "Structured
Headers for HTTP" to something like "Structured Field Values for HTTP
Headers and Trailers".

I did not really review the algorithms; this essentially requires
writing code. I'm not really happy with the statement that in case of
conflicts, the algorithms have higher precedence than the ABNF.

Other than that; I found one major issue:

In 3.3.4:

   sh-token = ( ALPHA / "\*" ) *( tchar / ":" / "/" )

This should be

   sh-token = ( ALPHA / "*" ) *( tchar / ":" / "/" )

...right?

Minor issues:

In Section 1:

At the end of the section (top level), there should be a paragraph break
between the two sentences (so that each Section 2, 3, and 4 are treated
consistently)

In Section 1.1:

"In doing so, uses the VCHAR, SP, DIGIT, ALPHA and DQUOTE rules from
[RFC5234]. It also includes the tchar rule from [RFC7230]."

...should say..: "In doing so, *it* uses..."

In Section 2:

"Specify the type of the header field itself; either Dictionary (Section
3.2), List (Section 3.1), or Item (Section 3.3)."

Maybe sort by section number (swap Dictionary and List)?

Further down below it talks about the letter "Q" and the letter 'q'.
Please make the quoting consistent.

In the example spec text:

> "fooUrl" contains a URI-reference (Section 4.1 of
> [RFC3986], Section 4.1). If its value is not a valid URI-reference,
> that URL MUST be ignored. If its value is a relative reference
> (Section 4.2 of [RFC3986]), it MUST be resolved (Section 5 of
> [RFC3986]) before being used.

1. remove ", Section 4.1"

2. use of "URL" comes as as surprise here, maybe just say "field value"

In Section 3.1.1:

"In HTTP headers, inner lists..." - I was going to say that this seems
to be unnecessary verbose (here and in other places), but this has
already been fixed in the latest editor's draft.

In Section 3.1.2:

ABNF:

parameter     = ";" *SP param-name [ "=" param-value ]

Prose:

"...parameters are separated from their item or inner-list and each
other by semicolons."

So there's an unfortunate mismatch between the ABNF production
"parameter" (which already includes the ";") and the use of "parameter"
in the prose. Maybe worth addressing in the ABNF.

In Section 3.2:

> Members whose value is Boolean true MUST omit that value when serialised, unless it has parameters. For example, here both “b” and “c” are true, but “c”’s value is serialised because it has parameters:
>
> Example-DictHeader: a=?0, b, c=?1; foo=bar

I guess this is needed in order to avoid ambiguities, but this outcome
is really a bit strange. Is there a summary of how we got to that
special case somewhere (github issue?)

In Section 3.3:

> An item is can be a integer (Section 3.3.1), decimal (Section 3.3.2), string (Section 3.3.3), token (Section 3.3.4), byte sequence (Section 3.3.5), or Boolean (Section 3.3.6).

Please be consistent in upper/lowercasing...

In Section 3.3.2:

> Decimals are numbers with an integer and a fractional component. The Integer component has at most 12 digits; the fractional component has at most three digits.

Same here.

In Section 4.1:

Item 2 and 3 should be swapped (to reflect the order of the definitions
in the spec).

Item 5 seems to be unreachable by definition.

In Section 4.1.3:

Section references in the list should be wrapped in "(" and ")"

In Section 5:

s/draft/specification/ or "document"

Appendix A:

Acknowledgements should be in a unnumbered appendix at the end.

That said, is mentioning exactly one WG member the right thing here?

Appendix C:

> A generic implementation of this specification should expose the top-level parse (Section 4.2) and serialize (Section 4.1) functions

Maybe swap the two parts (Sections mentioned in reverse order really
trip me up)

Best regards, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 24 Feb 2020 10:55:18 +1100

Hi Julian,

Thanks for the feedback; responses below.

> On 23 Feb 2020, at 5:06 am, Julian Reschke <[email-masked]> wrote:
> 

I'm not against that, although it's quite wordy. Anyone else have thoughts?

>  sh-token = ( ALPHA / "*" ) *( tchar / ":" / "/" )

Yes; the glories of markdown escaping rules. Fixed.

> between the two sentences (so that each Section 2, 3, and 4 are treated

Added.

> ...should say..: "In doing so, *it* uses..."

Added.

> Maybe sort by section number (swap Dictionary and List)?

Done.

> Please make the quoting consistent.

I've done that, and also changed the latter letter to avoid confusion that they are related.

> 1. remove ", Section 4.1"

Done.

> 2. use of "URL" comes as as surprise here, maybe just say "field value"

The intent is to ignore the individual URL, not the entire field value.

> already been fixed in the latest editor's draft.

Ack.

> in the prose. Maybe worth addressing in the ABNF.

Please take a look at
  https://github.com/httpwg/http-extensions/commit/b4b8f4a73

> special case somewhere (github issue?)

https://github.com/httpwg/http-extensions/issues/992

> Please be consistent in upper/lowercasing...

Boolean refers to a person's name; lowercasing it would be equivalent to saying that your review is reschkean, not Reschkean. Or are you suggesting we uppercase all of them (which might be reasonable, given the next comment)?

>> Decimals are numbers with an integer and a fractional component. The Integer component has at most 12 digits; the fractional component has at most three digits.

Uppercase is used to refer to the SH-type; lowercase is referring to mathematical concepts.

> Item 2 and 3 should be swapped (to reflect the order of the definitions

OK, done.

> Item 5 seems to be unreachable by definition.

If for some reasons serialise is handed a value that doesn't match one of the above (or can't be identified as such), it needs to fail.

> Section references in the list should be wrapped in "(" and ")"

Done (one case)

> s/draft/specification/ or "document"

Done.

> That said, is mentioning exactly one WG member the right thing here?

Good point. I've added a number of folks who contributed according to Github; if others feel that they were involved to a significant degree, please ping me (privately if you wish).

I've continued to single Matthew out because his contribution was considerably greater than anyone else's.

> Maybe swap the two parts (Sections mentioned in reverse order really

Swapped.

Thanks again,

--
Mark Nottingham   https://www.mnot.net/

---

From: Julian Reschke <[email-masked]>
Date: Mon, 24 Feb 2020 10:23:46 +0100

> I'm not against that, although it's quite wordy. Anyone else have thoughts?

Or just "Structured Field Values for HTTP".

> The intent is to ignore the individual URL, not the entire field value.

Ack. But the mix of "URI-reference" and "URL" is just confusing.

> ... >> In Section 3.1.2:

LGTM, thanks.

> https://github.com/httpwg/http-extensions/issues/992

Hm, that refers to existing field values, which the spec says are out of
scope.

That said, I *do* agree that the value-less variant is nice for flags;
my question is why we ended up with special-casing this in parameters,
and also why we don't allow serialising with "true" value outside
parameters.

> Boolean refers to a person's name; lowercasing it would be equivalent to saying that your review is reschkean, not Reschkean. Or are you suggesting we uppercase all of them (which might be reasonab…

In that case I'd suggest uppercasing for consistency.

> Uppercase is used to refer to the SH-type; lowercase is referring to mathematical concepts.

"Integer component" vs "fractional component".

Best regards and thanks for the changes so far,

Julian

---

From: Jeffrey Yasskin <[email-masked]>
Date: Mon, 24 Feb 2020 11:08:23 -0800

> Or just "Structured Field Values for HTTP".

For what it's worth, I think this title would make it hard to find for
people who aren't experts in HTTP. We think of these things as headers, so
that ought to be in the title and the common name. "Structured HTTP Header
and Trailer Field Values"? I do think the original title is defensible:

*
https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#header.fields
says
that "header fields" are colloquially known as just "headers", so no need
for the "field".

* Very few people use trailers, and those who do are used to looking for
"header" documentation, so no need to mention them in the title.

* The boundary between the field name and value was already structured
before this I-D, so by adding structure to the values, this document
achieves structured fields.

Jeffrey

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 25 Feb 2020 11:34:10 +1100

> On 24 Feb 2020, at 8:23 pm, Julian Reschke <[email-masked]> wrote:

> Or just "Structured Field Values for HTTP".

That's better, and I think I can live with it -- as long as we establish that "Structured Headers" is an alias for it (and still use that in-spec, as it's in a number of places). Make sense?

> Ack. But the mix of "URI-reference" and "URL" is just confusing.

Fixed in https://github.com/httpwg/http-extensions/commit/86968ad5

> Hm, that refers to existing field values, which the spec says are out of

Yes - but future specs may build upon that capability.

> and also why we don't allow serialising with "true" value outside

The bug has the history; basically there are a number of already-defined headers that have value-less parameters that previously failed parsing as SH. *If* we want to try to back-port them in the future, accommodating that seems important.

> In that case I'd suggest uppercasing for consistency.

This ended up being more intrusive; once I looked at the whole spec with this in mind, a number of changes were necessary. Please review:
  https://github.com/httpwg/http-extensions/commit/4a18a87802d778

> "Integer component" vs "fractional component".

Fixed.

Thanks again,

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 25 Feb 2020 16:05:06 +1100

> On 25 Feb 2020, at 11:34 am, Mark Nottingham <[email-masked]> wrote:
> 
>> 

Also - experience with Cache-Status and Proxy-Status shows that it's really nice to have the value-less true. 

>> and also why we don't allow serialising with "true" value outside

I'm not sure what you mean here...

---

From: Julian Reschke <[email-masked]>
Date: Tue, 25 Feb 2020 07:08:53 +0100

> That's better, and I think I can live with it -- as long as we establish that "Structured Headers" is an alias for it (and still use that in-spec, as it's in a number of places). Make sense?

WFM.

> Fixed in https://github.com/httpwg/http-extensions/commit/86968ad5

Thanks.

> The bug has the history; basically there are a number of already-defined headers that have value-less parameters that previously failed parsing as SH. *If* we want to try to back-port them in the f…

I understand that. What trips me up is that we we have to different
cases: one in which the shorter notation MUST be used, one in which it
MUST NOT be used. Am I the only one who thinks that this is sub-optimal?

In a perfect world, the serialization should not depend on the context
it appears in. I understand that this is a trade-off, but it would be
good to see more context about how we got there, and whether
alternatives were discussed.

>    https://github.com/httpwg/http-extensions/commit/4a18a87802d778

Looks good to me.

Best regards, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 25 Feb 2020 17:13:49 +1100

> On 25 Feb 2020, at 5:08 pm, Julian Reschke <[email-masked]> wrote:
> 

If you're referring to the case of a Boolean as a Dictionary value (and it would be good if you confirmed that this is what you had in mind; if you're talking about Booleans wherever they might appear, I don't know how that would work), it was considered, but IIRC it would have required a substantially more complicated parsing algorithm, because of cases like this:

Example-Field: ;param=on-default-boolean

Parameter values are comparatively simpler, because they can't have any further substructure.

Cheers,

---

From: Julian Reschke <[email-masked]>
Date: Tue, 25 Feb 2020 09:06:45 +0100

> If you're referring to the case of a Boolean as a Dictionary value (and it would be good if you confirmed that this is what you had in mind; if you're talking about Booleans wherever they might app…

Yes.

> Parameter values are comparatively simpler, because they can't have any further substructure.

I don't quite get the example. In the spec I see:

If this would be instead:

   Example-DictHeader: a=?0, b, c; foo=bar

...what would break?

Best regards, Julian

PS: I'm tempted to propose "!a" instead of "a=?0" :-)