Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: explain HTTP writeHead()'s fast path behavior #21289

Closed
wants to merge 1 commit into from
Closed

doc: explain HTTP writeHead()'s fast path behavior #21289

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions doc/api/http.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1277,6 +1277,13 @@ const server = http.createServer((req, res) => {
});
```

If [`response.writeHead()`][] method is called and this method has not been
called, it will directly write the supplied header values onto the network
channel without caching internally, and the [`response.getHeader()`][] on the
header will not yield the expected result. If progressive population of headers
is desired with potential future retrieval and modification, use
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is modification still possible after writeHead? Sounds to me like only retrieval is possible. Ditto below.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@TimothyGu - yes, that is right: headers written through writeHead are not modifiable, and attempt to do so results in error Cannot set headers after they are sent to the client. Hence the suggestion to use setHeader() API for such cases. If the text is not conveying that let me know where and how can I fix it, thanks.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, you wrote

If progressive population of headers is desired with potential future retrieval and modification, use …

It seemed to me that the bolded bit should perhaps be removed.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry, missed this update. Sorry, I am missing your point:
#cat 10354.js

const h = require('http')
h.createServer((q, r) => {
  r.setHeader('foo', 'bar')
  r.setHeader('foo', 'new')
  r.end()
}).listen(12000, () => {
  const c = h.get('http://localhost:12000', (m) => {
    console.log(m.headers)
  })
})

#node 10354.js

{ foo: 'new',
  date: 'Thu, 21 Jun 2018 14:42:33 GMT',
  connection: 'close',
  'content-length': '0' }

setHeader() is indeed used for modification, and hence the text. Can you please clarify your point?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Never mind, I see what this is trying to say now.

[`response.setHeader()`][] instead of [`response.writeHead()`][].

### response.setTimeout(msecs[, callback])
<!-- YAML
added: v0.9.12
Expand Down Expand Up @@ -1444,6 +1451,13 @@ When headers have been set with [`response.setHeader()`][], they will be merged
with any headers passed to [`response.writeHead()`][], with the headers passed
to [`response.writeHead()`][] given precedence.

If this method is called and [`response.setHeader()`][] has not been called,
it will directly write the supplied header values onto the network channel
without caching internally, and the [`response.getHeader()`][] on the header
will not yield the expected result. If progressive population of headers is
desired with potential future retrieval and modification, use
[`response.setHeader()`][] instead.

```js
// returns content-type = text/plain
const server = http.createServer((req, res) => {
Expand Down