http.OutgoingMessage headers API

[ChALkeR]

Atm, http.OutgoingMessage has the following headers-related methods:

• .setHeader(name, value),
• .getHeader(name, value),
• .removeHeader(name).

There probably should be methods to:

• Check if headers were already sent (like ._headerSent).
• Clear all headers (if they were not already sent). — Doable with removeHeader and getHeaderNames/getHeaders since http: add new functions to OutgoingMessage #10805.
• List all headers that were set, with values. — Landed in http: add new functions to OutgoingMessage #10805, thanks, @mscdex!

All methods that modify headers should error if the headers were already sent.

Reasoning: https://gist.github.com/ChALkeR/26573ff704f987fd5304

[Fishrock123]

You may want to have a look at #772, which was originall a getAllHeaders(), but later changed focus to a getCurrentHeaders().

I didn't go through with it however, and doing it right requires re-writing far more bits of http than I was able to do.

[ChALkeR]

@Fishrock123 What's the reason for making the already sent headers ungettable?

[Fishrock123]

@ChALkeR I'm not sure, is that the current impl? I would say it maybe shouldn't? Honestly though, no clue.

[ChALkeR]

Ah, I misread #772, sorry.

Edit: No, I didn't.

Reads out all headers that are already been queued but not yet sent to the client. This can only be called before headers get implicitly flushed.

[ChALkeR]

Ok, so there are no objections to adding such API methods at this moment, as I understand it.
Correct?

[benjamingr]

@ChALkeR in general, I think it would be interesting to explore that option. I think it'd be better if you suggested a concrete API we can discuss.

[chrisdickinson]

Remove a single header (if headers were not already sent).

Isn't that covered by removeHeader?

Re: holding on to sent headers – I believe we avoid it on the grounds of not holding onto "informational" data that the user could grab earlier.

re: the reasoning: I'm not sure a list of _headers usage makes a good case for adding new APIs. What's the end goal of adding these APIs, given that we are unlikely to change _headers in the future? Would it be easier to document _headers?

[benjamingr]

@chrisdickinson the reasoning behind putting this behind an official API is that _headers can't and doesn't warn/error if the headers were already sent which makes it a very poor API susceptible to lots of unexpected behavior.

It might be possible to change _headers to __headers and expose a _headers getter in order to keep the current API but make it safer but that might possibly break some peoples' code.

I think the point of @ChALkeR is that this is functionality people need and expect to have on OutgoingMessage and they resort to _headers because there is no standard way to do this.

[ChALkeR]

@chrisdickinson Thanks. removeHeader is indeed already there, it was a bit late in my local time when I was writing this. Edited.

Documenting _headers would cause more havoc because it is not a fine API. A proper API for headers should check if the headers were already sent and error if the user tries to modify them after that. Or else it would be a debugging hell.

I understand that _headers are not going anywhere in the foreseeable future, but that doesn't mean that we should tell users to use that instead of implementing a proper api.

[jonathanong]

any node contributors have an opinion on an API? i don't mind submitting a PR if there's somewhat of a consensus

[ChALkeR]

/cc @nodejs/ctc

[Fishrock123]

Headers API will be a bit tricky, and probably require somewhat of a re-write of headers handling.
This is mostly because:

• You'll want to get the headers before they are sent to modify them in some way.
• You'll need access to headers that only get set when the headers are going to be sent, which is why people currently intercept writeHead().
• That duplicates a lot of already extremely messy and tedious headers logic.

[Fishrock123]

So, what you're really dealing with is: Current, Sent, and Total ("all") (including on-write) headers. The API probably needs to cover that. :/

[Fishrock123]

@ofrobots This is (one of?) the issue(s) for headers handlng refactoring.

[ChALkeR]

@mscdex the only remaining usecase here is «Check if headers were already sent (like ._headerSent)». Is that doable through the public API now?

[dougwilson]

Though there is a slight difference in the meaning, I wonder if the existing res.headersSent getter fits the use cases people are using res._headerSent for?

[ChALkeR]

@dougwilson Hm. It probably doesn't make sense to include two of those. I should check then why ._headerSent is used, since .headersSent is present for quite a long time. Perhaps those usages could be replaced with .headersSent (and this issue could be closed then), or perhaps there is a difference and then we should discuss what to do next.

[Trott]

This should stay open, yes?

[ChALkeR]

@Trott, yes, there are some things that I should check on this one before closing. Thanks for reminding me, though! :-)

[evanlucas]

@ChALkeR did you ever get around to this? Is the plan to consolidate _headerSent and headersSent?

[jasnell]

Should this remain open?

[jasnell]

Closing due to lack of follow up