Subject: What we call "headers"

From: Mark Nottingham <[email-masked]>
Date: Tue, 17 Mar 2020 17:38:47 +1100

A little while back we made some changes in http-core regarding terminology and headers. This seems to have caused some confusion and comment, so I thought I'd summarise where I think we're at (Julian and Roy might want to chime in if they feel differently or want to add nuance). 

Note that this is _not_ a call to bikeshed the chosen terms*.

The corresponding spec text is at <https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#header.fields>, although of course we're still working on it.

## Field Components

A _field line_ is a field name/value pair that maps directly to the HTTP/1 serialisation of a field. Notably, it only includes the value between the `:` and the `\n` -- subsequent values have not been folded in. This is typically used by the syntactic specifications (h1, h2, h3), and in other limited cases (e.g., Cookies).

A _field section_ is a set of field lines before or after a message body (let's ignore "midders" for now).

A _field name_ is the field's name. Hopefully, this is pretty straightforward.

A _field value_ is the field's *whole* value -- after potential combination of multiple field lines. We chose this meaning because it's by far the most common; it's rare that specs need to refer to a syntactic HTTP/1 or HTTP/2 field line value. 

When we need to refer to the individual parts of a field line, we can call them the _field line name_ and _field line value_. Again, this is pretty rare, and usually in the "infrastructure" specs. I know this isn't a "pretty" name, but it's necessary to distinguish between the different meanings in some circumstances.

A _field_ is a field name/field value pair -- notably, including the result of combining multiple instances of the header field in the section. This is typically used in a fairly abstract way.

Colloquially, when we want to refer to a specific field section, we can call it _headers_ or _trailers_, as appropriate. Likewise _header_ and _trailer_ are understood to be _header field_ and _trailer field_ when expanded (note that this means it's *not* a field line).

## Field Contexts

Historically, we've used "header" and "headers" pretty loosely; sometimes things can be trailers, but this name doesn't recognise that. So, when the semantics document talks about these things, it uses "field" or "fields" -- unless something is defined very specifically as allowed (or required) to be in headers or trailers.

That's because we've made separate changes to make the delineation between headers and trailers stronger; trailers can no longer be "folded" into headers automatically.

So, if you define something that doesn't explicitly allow itself to be sent in the trailer section, it's perfectly OK to call it a "header field." You can also just call it a "field" if you like, but that may confuse some readers as to whether you intended to allow it to be sent as a trailer field.

Cheers,

*  The timeless phrase "welcome to my killfile" comes to mind.

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

---

From: "Roy T. Fielding" <[email-masked]>
Date: Tue, 17 Mar 2020 16:37:20 -0700

> On Mar 16, 2020, at 11:38 PM, Mark Nottingham <[email-masked]> wrote:
> 

It might be easier to see the changes vs 7231 in this diff

   https://httpwg.org/http-core/diffs/diff_semantics_frfc_to_07.html#part-9 <https://httpwg.org/http-core/diffs/diff_semantics_frfc_to_07.html#part-9>

One thing I noticed was that section 4 now says there are two separate areas
where fields can occur. I would prefer to define it as a possibly empty header
section and zero or more trailer sections (depending on the version or transfer
coding). I think it is better to provide for the general case instead of assuming
that chunked is the only example.  This is related to

  https://github.com/httpwg/http-core/issues/313

....Roy

---

From: Willy Tarreau <[email-masked]>
Date: Wed, 18 Mar 2020 05:15:36 +0100

Hi Roy,

On Tue, Mar 17, 2020 at 04:37:20PM -0700, Roy T. Fielding wrote:
> section and zero or more trailer sections

I like this approach a lot. It's just like when people tell me they've
seen "the double CRLF which delimits the body", I say "no, you've seen
the empty field that marks the end of the header section".

And software made to process header fields and calling them "headers"
are not really designed to apply the same processing to trailers, so
even in such software it would be easier to consider that there is
processing of header and trailer fields rather than saying that these
fields are "headers". This way it will be easier to add explicit support
of trailers or mid-stream fields later in such software than trying to
adapt them to process everything as headers.

Willy

---

From: "Poul-Henning Kamp" <[email-masked]>
Date: Thu, 19 Mar 2020 16:44:35 +0000

--------
In message <[email-masked]>, Mark Nottingham wri
tes:

>A little while back we made some changes in http-core regarding 
>terminology and headers. This seems to have caused some confusion and
>comment, so I thought I'd summarise where I think we're at (Julian and
>Roy might want to chime in if they feel differently or want to add
>nuance).

I appreciate that you are trying to disambiguate the confusion brought
about by headers being put in trailers.

However, given that we have talked about trailers for 20+ years
now, yet they have never gained any serious traction, the simplest
and most efficient way to end the confusion is to do away with
trailers, so that headers only live in headers, as originally
intended.

The problems trailers were invented to work around, are barely
relevant these days, and almost universally handled with JS on the
client.

We are not running out of headers, so trailers do not enjoy a
"insurance for the future" status like IPv6 did during its
twenty years of crossing of the desert.

KISS: Trailers must die.

-- 
Poul-Henning Kamp       | UNIX since Zilog Zeus 3.20
[email-masked]         | TCP/IP since RFC 956
FreeBSD committer       | BSD since 4.3-tahoe    
Never attribute to malice what can adequately be explained by incompetence.

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 20 Mar 2020 08:55:56 +1100

> On 20 Mar 2020, at 3:44 am, Poul-Henning Kamp <[email-masked]> wrote:
> 
> --------

Thanks, but most of the focus here is disambiguating the various meanings of "headers", regardless of trailers.

> twenty years of crossing of the desert.

That's been discussed quite a bit before, and given that trailers are starting to be both used and reasonably well-supported, it's probably not the time to start that discussion again. The good news is that any implementation can just drop them on the floor if it doesn't want to deal with them; the most they're required to do is to maintain message framing.

Cheers,