doc: fix misleading sentence in http.md

[lpinca]

Calling response.end(data) is not 100% equivalent to calling
response.write(data) followed by response.end().

Fixes: #26005

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[nodejs-github-bot]

@lpinca build started: https://ci.nodejs.org/blue/organizations/jenkins/node-test-pull-request-lite-pipeline/detail/node-test-pull-request-lite-pipeline/2778/pipeline

[vsemozhetbyt]

Nit:

Suggested change

	`chunked`, otherwise the `Transfer-Encoding` header is replaced by the
	`'chunked'`, otherwise the `Transfer-Encoding` header is replaced by the

[Trott]

Optional suggestion: Change the comma to a period and make the Otherwise clause its own sentence.

[richardlau]

Commit message has misspelled sentence.

[sam-github]

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!

[lpinca]

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?

[sam-github]

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.

[lpinca]

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]

nit: I think a commit message of doc: describe when chunked mode is used would be more descriptive of the specific change being made.

[lpinca]

Folks that approved this, PTAL, I've updated as per @sam-github suggestion.

Abstain

[BridgeAR]

I would rather have a detailed information but I won't block this either.

[lpinca]

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.

[BridgeAR]

What should be done here?

@jasnell PTAL

[BridgeAR]

Landed in 1706a2d 🎉