doc: fix misleading sentence in http.md #26465
Conversation
nodejs-github-bot
added
doc
BridgeAR
added
the
author ready
doc/api/http.md
Outdated
| [`response.write(data, encoding)`][] followed by `response.end(callback)`. There | ||
| is, however, a difference in the headers that are sent by default. If | ||
| [`response.write()`][] is used, the `Transfer-Encoding` header is set to | ||
| `chunked`, otherwise the `Transfer-Encoding` header is replaced by the |
There was a problem hiding this comment.
Nit:
| `chunked`, otherwise the `Transfer-Encoding` header is replaced by the | |
| `'chunked'`, otherwise the `Transfer-Encoding` header is replaced by the |
There was a problem hiding this comment.
Optional suggestion: Change the comma to a period and make the Otherwise clause its own sentence.
|
Commit message has misspelled |
doc/api/http.md
Outdated
| is, however, a difference in the headers that are sent by default. If | ||
| [`response.write()`][] is used, the `Transfer-Encoding` header is set to | ||
| `'chunked'`. Otherwise the `Transfer-Encoding` header is replaced by the | ||
| `Content-Length` header. |
There was a problem hiding this comment.
I think this leaves one case undescribed: response.write(data); response.end(data)
Also, while accurate, so an improvement, I think its too low level, it doesn't give any idea why its done this way. And if you knew why, then you wouldn't need the docs.
I'd suggest that the .write() docs be modified to say that because .write() can be called multiple times, the size of the entire response (or request, I suspect these docs apply to both req and response) cannot be known when .write() is called, so HTTP will use chunked transfer encoding, and there will not be a content-size header.
In .end(), I'd say that if .write() has not previously been called, the total size is known (zero, or the size of the data arg), so node.js doesn't have to (and won't) use chunked transfer encoding, and it will write a content-length header. In other cases, since chunked transfer has already begun, any data provided to .end() will be transferred as a chunk.
^--- I think this is accurate, and describes why this is, and makes this seem less like a weird gotcha, and more like a feature: that if you have one large chunk that can be written in a single call to .end(), you can cause the content-size to be set and chunked mode not to be used. I'm not sure if it applies equally to the writing of requests, and the writing of responponses... but it should!
There was a problem hiding this comment.
I only wanted to address the misleading sentence quoted in #26005 and not describe chunk mode. This is also not 100% accurate as the user could explicitly specify Content-Length disabling the default chunked mode. Perhaps it's simpler to just remove that sentence?
There was a problem hiding this comment.
It would be nice to have the info about how explicitly setting the header changes things. Basically, that Node.js has good support for chunked mode (unlike a number of crappy HTTP APIs I've come across), is a wonderful feature, its a shame we don't document it better.
Your comment above makes me wonder if your proposed text is accurate/complete, doesn't it suffer the same problem?
For now, yes, I think rather than dumping in the detail you proposed, if you aren't up to a really comprehensive treatment, just changing "the same as" to "similar in effect to", or similar weasel words, might make the docs "not wrong", even though it still leaves streaming vs non-streaming mode undoced.
There was a problem hiding this comment.
Your comment above makes me wonder if your proposed text is accurate/complete, doesn't it suffer the same problem?
Yes, I've added "the headers that are sent by default" to address that but I guess it's not clear.
I will change this tomorrow and use "similar" removing all the chunked mode info.
FWIW the request counterparts are slightly better documented.
sam-github
changed the title
|
nit: I think a commit message of |
Calling `response.end(data)` is not 100% equivalent to calling `response.write(data)` followed by `response.end()`. Fixes: nodejs#26005
|
Folks that approved this, PTAL, I've updated as per @sam-github suggestion. |
|
I would rather have a detailed information but I won't block this either. |
|
It makes sense but I don't have the energy to update the docs as suggested in #26465 (comment) explaining how and when chunked mode is used, how to disable it, etc. especially due to all the nit picking that will come from that. If that is preferred I would prefer it to be done by a native speaker. |
|
What should be done here? @jasnell PTAL |
Calling `response.end(data)` is not 100% equivalent to calling `response.write(data)` followed by `response.end()`. PR-URL: nodejs#26465 Fixes: nodejs#26005 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Sam Roberts <[email protected]>
|
Landed in 1706a2d 🎉 |
Calling `response.end(data)` is not 100% equivalent to calling `response.write(data)` followed by `response.end()`. PR-URL: #26465 Fixes: #26005 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Sam Roberts <[email protected]>
Calling `response.end(data)` is not 100% equivalent to calling `response.write(data)` followed by `response.end()`. PR-URL: nodejs#26465 Fixes: nodejs#26005 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Sam Roberts <[email protected]>
Calling `response.end(data)` is not 100% equivalent to calling `response.write(data)` followed by `response.end()`. PR-URL: #26465 Fixes: #26005 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Sam Roberts <[email protected]>
Calling `response.end(data)` is not 100% equivalent to calling `response.write(data)` followed by `response.end()`. PR-URL: #26465 Fixes: #26005 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Sam Roberts <[email protected]>
Calling
response.end(data)is not 100% equivalent to callingresponse.write(data)followed byresponse.end().Fixes: #26005
Checklist
make -j4 test(UNIX), orvcbuild test(Windows) passes