doc: clarify QUIC async write backpressure

[johnfinnerty-nz]

Summary

Document strict async write behavior, ERR_INVALID_STATE, canWrite, and onblocked.

Validation

Documentation was checked against the current implementation; git diff --check passed.

Closes #63305

[nodejs-github-bot]

Review requested:

• @nodejs/quic

[github-actions]

Welcome to Node.js, and thank you for your first contribution!

Before review, please take a moment to read:

• the guide for first-time contributors
• the contribution and automation policies
• the pull request guide
• the AI use policy
• the Code of Conduct

Please make sure every commit is signed off. For a first pull request, GitHub Actions require collaborator approval and Jenkins CI must be started by a collaborator or triager, so an initial wait is normal.

Caution

AgentScan found account activity patterns that may be consistent with automation. This is a heuristic, not proof that this pull request was opened by an agent or violates policy. AI-assisted contributions are permitted, but automated tooling must not open pull requests without advance approval, and contributors must personally understand, test, verify, and take responsibility for every submitted change. See the AgentScan analysis, AI use policy, and automation policy for additional context.

[jasnell]

@johnfinnerty-nz ... While the change here looks fine and is acceptable, if you make future additional contributions, please do ensure that the PR description is not just AI generated. We need to know that the contribution comes from a person, not an AI agent.

[johnfinnerty-nz]

Cheers James. I did use Codex, including to polish my description, as grammar isn’t my strong suit. I reviewed the code before submitting. The change clarifies that asynchronous QUIC writes reject with ERR_INVALID_STATE when the buffer is full, rather than waiting for capacity. I’ll make sure future descriptions explain the reasoning in my own words. Thanks again for the review and feedback.

[nodejs-github-bot]

Commit Queue failed

This pull request has multiple commits, but no landing policy was selected.

Add commit-queue-squash PRs the Commit Queue should land as one squashed commit. to land it as one commit, or commit-queue-rebase PRs the Commit Queue should land as multiple self-contained commits. to land the commits separately.

The pull request was removed from the Commit Queue and labeled commit-queue-failed PRs whose Commit Queue landing failed and need manual intervention before retrying. . After resolving the failure, remove that label and add commit-queue PRs queued for automated landing through the Commit Queue. to retry.

Full Commit Queue output

- Loading data for nodejs/node/pull/65947
✔  Done loading data for nodejs/node/pull/65947
----------------------------------- PR info ------------------------------------
Title      doc: clarify QUIC async write backpressure (#65947)
   ⚠  Could not retrieve the email or name of the PR author's from user's GitHub profile!
Branch     johnfinnerty-nz:jftc/issue-63305-quic-docs -> nodejs:main
Labels     doc, quic, commit-queue, agentscan:automated-account
Commits    2
 - doc: clarify QUIC async write backpressure
 - doc: correct QUIC writer drain guidance
Committers 1
 - John Finnerty <297514060+johnfinnerty-nz@users.noreply.github.com>
PR-URL: https://github.com/nodejs/node/pull/65947
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Xuguang Mei <meixuguang@gmail.com>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/65947
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Xuguang Mei <meixuguang@gmail.com>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Wed, 09 Sep 2026 20:56:08 GMT
   ✔  Approvals: 2
   ✔  - James M Snell (@jasnell) (TSC): https://github.com/nodejs/node/pull/65947#pullrequestreview-5168118612
   ✔  - Xuguang Mei (@meixg): https://github.com/nodejs/node/pull/65947#pullrequestreview-5161942015
   ✔  Last GitHub CI successful
   ℹ  Green GitHub CI is sufficient
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 65947
From https://github.com/nodejs/node
 * branch                  refs/pull/65947/merge -> FETCH_HEAD
✔  Fetched commits as c081d10d7e43..f80e18bb12d4
--------------------------------------------------------------------------------
Auto-merging doc/api/quic.md
[main 65fdedf11c] doc: clarify QUIC async write backpressure
 Author: John Finnerty <297514060+johnfinnerty-nz@users.noreply.github.com>
 Date: Thu Sep 10 08:46:10 2026 +1200
 1 file changed, 15 insertions(+), 6 deletions(-)
Auto-merging doc/api/quic.md
[main bd25988cf0] doc: correct QUIC writer drain guidance
 Author: John Finnerty <297514060+johnfinnerty-nz@users.noreply.github.com>
 Date: Thu Sep 10 18:48:49 2026 +1200
 1 file changed, 26 insertions(+), 11 deletions(-)
   ✔  Patches applied
There are 2 commits in the PR. Attempting autorebase.
(node:425) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true can lead to security vulnerabilities, as the arguments are not escaped, only concatenated.
(Use `node --trace-deprecation ...` to show where the warning was created)
Rebasing (2/4)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
doc: clarify QUIC async write backpressure

Signed-off-by: John Finnerty <297514060+johnfinnerty-nz@users.noreply.github.com>
PR-URL: https://github.com/nodejs/node/pull/65947
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Xuguang Mei <meixuguang@gmail.com>
--------------------------------------------------------------------------------
[detached HEAD ff260256dc] doc: clarify QUIC async write backpressure
 Author: John Finnerty <297514060+johnfinnerty-nz@users.noreply.github.com>
 Date: Thu Sep 10 08:46:10 2026 +1200
 1 file changed, 15 insertions(+), 6 deletions(-)
Rebasing (3/4)
Rebasing (4/4)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
doc: correct QUIC writer drain guidance

Distinguish writer capacity from transport blocking and stop retrying when no drain wait is available.

Assisted-by: Codex
Signed-off-by: John Finnerty <297514060+johnfinnerty-nz@users.noreply.github.com>
PR-URL: https://github.com/nodejs/node/pull/65947
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Xuguang Mei <meixuguang@gmail.com>
--------------------------------------------------------------------------------
[detached HEAD 301b0528aa] doc: correct QUIC writer drain guidance
 Author: John Finnerty <297514060+johnfinnerty-nz@users.noreply.github.com>
 Date: Thu Sep 10 18:48:49 2026 +1200
 1 file changed, 26 insertions(+), 11 deletions(-)
Successfully rebased and updated refs/heads/main.
--------------------------------------------------------------------------------
   ℹ  Add `commit-queue-squash` label to land the PR as one commit, or `commit-queue-rebase` to land as separate commits.

View workflow run

[nodejs-github-bot]

Landed in fa10566