doc: clarify QUIC stream state wording

[EduardF1]

Summary

• describe createBidirectionalStream() without a body as half-open instead of half-closed
• make the same clarification for createUnidirectionalStream()
• note explicitly that omitting body does not send a FIN immediately

Fixes #63655

Validation

• node tools/lint-md/lint-md.mjs doc/api/quic.md

[nodejs-github-bot]

Review requested:

• @nodejs/quic

[EduardF1]

Friendly ping — just checking in on this documentation clarification. Happy to make any changes if needed!

[Qard]

Note that half-open and half-closed generally have different meanings in networking. Half-open is a failure case, implying one side has crashed or broken somehow. Half-closed implies one side was explicitly/intentionally closed, but the other remains open for listening, this exact scenario.

[EduardF1]

Hi @Qard, thank you for the feedback on the terminology. You make a great point regarding 'half-open' implying a failure state in networking contexts vs 'half-closed' implying intentional closure of one stream direction. I will update the documentation to explicitly use 'half-closed' instead to avoid any ambiguity.

[EduardF1]

Thanks @Qard. I've aligned the wording on "half-closed" throughout, since that matches the intentional one-direction-closed semantics here (writable side open, readable side not yet closed), rather than "half-open" which would imply a failure/crash on one peer.

The current head already reflects this at all four spots in doc/api/quic.md:

• the body-omitted note for opening a stream (writable side open, no body queued, no immediate FIN)
• the bidirectional-stream open note (writable side open, no FIN sent)

So there's no separate term left to change. Let me know if you'd prefer I also spell out "readable side open until the peer sends data / writable side open until end()" inline for extra clarity.

[Qard]

It does not appear to have been updated, and also looks like it needs a rebase.

[EduardF1]

Thanks for the patience @Qard, and sorry for the earlier confusion — you were right on both counts. The branch had not actually been updated and was stale.

I've now force-pushed a rebased, corrected version:

• Rebased onto the current main (the branch is now a single commit on top of HEAD).
• Aligned the wording on "half-closed" in all four spots in doc/api/quic.md, per your terminology note. To avoid the "half-open implies a peer failure" ambiguity, the docs now consistently describe the no-body case as half-closed and explicitly note that the writable side stays open and no FIN is sent immediately (so the stream can still be written via stream.setBody() or the writer):
  • createBidirectionalStream() option note + prose
  • createUnidirectionalStream() option note + prose (these previously said "closed"/"closed immediately", which was misleading since a body can still be set afterwards)

Validation: node tools/lint-md/lint-md.mjs doc/api/quic.md passes with no warnings.

Let me know if you'd prefer different phrasing for the unidirectional case (a unidirectional send stream only has the one writable direction, so I kept the same "half-closed (writable side open, no FIN sent)" wording for consistency — happy to adjust if you'd rather it read simply "writable side open, no FIN sent").

[EduardF1]

Thanks @Qard — I rebased the branch onto current main and confirmed the QUIC docs now use "half-closed" for this intentional writable-side-open/no-immediate-FIN state. The updated head is bdf316b.

[Qard]

It's a bit inconsistent with the "outgoing stream" part. The "outgoing" stream is one of the two halves the "half-closed" terminology is referring to, so saying the outgoing stream itself is half-closed feels a bit semantically wrong.