docs: clarify writableNeedDrain behavior and usage in streams

[oussamaBGZ]

This PR updates the documentation for the writableNeedDrain property in the streams module to clarify its behavior and guide developers on how to handle backpressure effectively.

Problem
Inconsistent handling of backpressure can lead to issues like incomplete data transfer.

For example:

1. Correct Backpressure Handling: The following code correctly handles backpressure by using the return value of writable.write(chunk) and listens for the 'drain' event to resume the readable stream:

2. Incorrect Backpressure Handling: The following code checks writableNeedDrain directly, which leads to incomplete copying (only 80% of the file is copied) because writableNeedDrain isn't updated immediately after each write():

[lpinca]

The problem in your example seems to be that the chunk of data is not written when writable.writableNeedDrain is true, so it is simply discarded.

Approved too quickly without enough thought

[oussamaBGZ]

The problem in your example seems to be that the chunk of data is not written when writable.writableNeedDrain is true, so it is simply discarded.

when its discarded the read stream is paused so technically we should not lost any data.
the example doesn't skip chunks intentionally, the problem lies in the timing of when writable.writableNeedDrain is updated.

[lpinca]

when its discarded the read stream is paused so technically we should not lost any data

No, you get the chunk, the chunk it not written (else branch in your example), and then the stream is paused. The chunk is lost forever. You should at least write it before pausing the stream.

[oussamaBGZ]

e chunk it not wri

Ahh ok thanks a lot, i added writable.write(chunk) before the pause func, the outpout file size was exactly the same. It was a bit tricky to notice hahaha maybe we could add a section in the docs to talk about situations like these

[Ethan-Arrowood]

Hello, I'm doing some backlog hygiene on all PRs related to networking and streaming modules. There hasn't been any activity here for quite a while so I'm going to mark it stalled. It will auto-close in ~30 days. This is not a rejection; if you've like to pick it back up, rebase onto latest main and give me a ping.

Thank you!

[github-actions]

This issue/PR was marked as stalled, it will be automatically closed in 30 days. If it should remain open, please leave a comment explaining why it should remain open.