Skip to content

doc: document quic stopSending() and resetStream() - #64888

Open
theSnackOverflow wants to merge 2 commits into
nodejs:mainfrom
theSnackOverflow:quic-doc-stopsending-resetstream
Open

doc: document quic stopSending() and resetStream()#64888
theSnackOverflow wants to merge 2 commits into
nodejs:mainfrom
theSnackOverflow:quic-doc-stopsending-resetstream

Conversation

@theSnackOverflow

@theSnackOverflow theSnackOverflow commented Aug 1, 2026

Copy link
Copy Markdown

Fixes: #63680

QuicStream.prototype.stopSending() and QuicStream.prototype.resetStream()
are part of the public surface but were missing from the QuicStream reference.

The wording follows the JSDoc already on the implementation:

node/lib/internal/quic/quic.js

Lines 2411 to 2435 in 8a1ca0f

/**
* Tells the peer to stop sending data for this stream. The optional error
* code will be sent to the peer as part of the request. If the stream is
* already destroyed, this is a no-op. No acknowledgement of this action
* will be provided.
* @param {number|bigint} code
*/
stopSending(code = 0n) {
assertIsQuicStream(this);
if (this.destroyed) return;
this.#handle.stopSending(BigInt(code));
}
/**
* Tells the peer that this end will not send any more data on this stream.
* The optional error code will be sent to the peer as part of the
* request. If the stream is already destroyed, this is a no-op. No
* acknowledgement of this action will be provided.
* @param {number|bigint} code
*/
resetStream(code = 0n) {
assertIsQuicStream(this);
if (this.destroyed) return;
this.#handle.resetStream(BigInt(code));
}

I also added both to the Aborting a stream section, which listed only
writer.fail() and stream.destroy(). The distinction seemed worth calling
out: those two derive the wire code from an error (falling back to the
protocol's "internal error" code), while stopSending() and resetStream()
send the given code as-is.

added: is set to v23.8.0, matching the rest of the file β€” both methods were
introduced in 062ae6f, the same commit that created doc/api/quic.md, and
were simply omitted from it. Happy to change this if a different version is
more accurate.

Verification

doc/api/quic.md is in skip_apidoc_files (Makefile), so it is not part of the
HTML/JSON doc build and make doc-only does not exercise it. Validation was
therefore limited to:

  • node tools/lint-md/lint-md.mjs doc/api/quic.md β€” clean
  • python3 tools/test.py doctool β€” 3/3 passing
  • Anchors follow the file's existing convention (stream.setPriority([options])
    β†’ #streamsetpriorityoptions)

Note

This supersedes #63681, which covered the same issue but was closed without
landing.

Update

Added a second commit covering behaviour the first one missed:

  • resetStream() discards any data still queued for sending, and is a no-op
    once the stream has already been reset.
  • Neither method sends a frame on the unidirectional stream that lacks the side
    it aborts β€” stopSending() on a locally-initiated one, resetStream() on a
    remote-initiated one. Both fail silently there.

Verified against Stream::DoStreamReset and Stream::SendStopSending in
src/quic/streams.cc. The directionality wording follows stream.destroy(),
which already frames the readable side as existing on bidirectional and
remote-initiated unidirectional streams.

I left the valid range of code undocumented on purpose: the binding reads it
with Uint64Value() and discards the lossless flag, so out-of-range values are
silently truncated rather than rejected. Documenting a 62-bit limit would state
a contract the implementation does not currently enforce. Happy to open that
separately if it's worth tracking.

`QuicStream` exposes `stopSending()` and `resetStream()`, but neither
appeared in the QuicStream API reference. Both matter when half-closing
a stream, which protocols such as WebTransport rely on.

Document the two methods and list them in the "Aborting a stream"
summary, which previously covered only `writer.fail()` and
`stream.destroy()`. Unlike those, both send the given code as-is rather
than deriving a wire code from an error.

Fixes: nodejs#63680
Signed-off-by: Ji Hoon Kang <ivory.ma9ic@gmail.com>
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/quic

@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to the documentations. quic Issues and PRs related to the QUIC implementation / HTTP/3. labels Aug 1, 2026
The reference added earlier in this pull request described only the
bidirectional happy path. Three behaviours were missing:

* `resetStream()` discards any data still queued for sending. A reset
  stream is never acknowledged, so that queue can no longer drain.
* `resetStream()` is a no-op once the stream has already been reset.
* Neither method sends a frame on the unidirectional stream that lacks
  the side it aborts β€” `stopSending()` on a locally-initiated one,
  `resetStream()` on a remote-initiated one. Both fail silently there.

The wording for stream directionality follows `stream.destroy()`, which
already states that the readable side exists on bidirectional and
remote-initiated unidirectional streams.

Refs: nodejs#63680
Signed-off-by: Ji Hoon Kang <ivory.ma9ic@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Issues and PRs related to the documentations. quic Issues and PRs related to the QUIC implementation / HTTP/3.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

quic: QuicStream missing docu for stopSending, and resetStream

2 participants