Skip to content

Commit 95fa855

Browse files
theSnackOverflowaduh95
authored andcommitted
doc: document quic stopSending() and resetStream()
`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: #63680 Signed-off-by: Ji Hoon Kang <ivory.ma9ic@gmail.com> PR-URL: #64888 Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent 52b2c73 commit 95fa855

1 file changed

Lines changed: 48 additions & 1 deletion

File tree

doc/api/quic.md

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1921,9 +1921,14 @@ True if `stream.destroy()` has been called.
19211921

19221922
### Aborting a stream
19231923

1924-
A QuicStream can be aborted in three ways, each producing different
1924+
A QuicStream can be aborted in several ways, each producing different
19251925
wire-frame side effects:
19261926

1927+
* [`stream.stopSending()`][] — Aborts only the readable side. Sends
1928+
`STOP_SENDING` to the peer. The writable side is unaffected.
1929+
* [`stream.resetStream()`][] — Aborts only the writable side. Sends
1930+
`RESET_STREAM` to the peer. Unlike [`writer.fail(reason)`][], the wire
1931+
code is given directly rather than derived from an error.
19271932
* [`writer.fail(reason)`][] — Aborts only the writable side. Sends
19281933
`RESET_STREAM` to the peer. The readable side is unaffected; any data
19291934
already buffered for read remains available.
@@ -1941,6 +1946,46 @@ the wire code for both `writer.fail()` and `stream.destroy()`. Otherwise
19411946
the implementation falls back to the negotiated application protocol's
19421947
"internal error" code (see [`QuicError`][]).
19431948

1949+
[`stream.stopSending()`][] and [`stream.resetStream()`][] do
1950+
not perform this derivation: they send `code` as given.
1951+
1952+
### `stream.resetStream([code])`
1953+
1954+
<!-- YAML
1955+
added: v23.8.0
1956+
-->
1957+
1958+
* `code` {number|bigint} The application error code to send to the peer.
1959+
**Default:** `0n`.
1960+
1961+
Tells the peer that this end will not send any more data on this stream,
1962+
sending a `RESET_STREAM` frame carrying `code`. The readable side is left
1963+
open, so data already sent by the peer remains available to read.
1964+
1965+
Any data still queued for sending is discarded. A reset stream is never
1966+
acknowledged by the peer, so the outbound queue can no longer drain.
1967+
1968+
No acknowledgement of this action is provided. The call does nothing if the
1969+
stream has been destroyed, if it has already been reset, or if it is a
1970+
remote-initiated unidirectional stream, which has no writable side to abort.
1971+
1972+
### `stream.stopSending([code])`
1973+
1974+
<!-- YAML
1975+
added: v23.8.0
1976+
-->
1977+
1978+
* `code` {number|bigint} The application error code to send to the peer.
1979+
**Default:** `0n`.
1980+
1981+
Asks the peer to stop sending data on this stream, sending a `STOP_SENDING`
1982+
frame carrying `code`. The writable side is left open, so this end can
1983+
still send data.
1984+
1985+
No acknowledgement of this action is provided. The call does nothing if the
1986+
stream has been destroyed, or if it is a locally-initiated unidirectional
1987+
stream, which has no readable side to abort.
1988+
19441989
### `stream.early`
19451990

19461991
<!-- YAML
@@ -4576,11 +4621,13 @@ throughput issues caused by flow control.
45764621
[`stream.onwanttrailers`]: #streamonwanttrailers
45774622
[`stream.pendingTrailers`]: #streampendingtrailers
45784623
[`stream.priority`]: #streampriority
4624+
[`stream.resetStream()`]: #streamresetstreamcode
45794625
[`stream.sendHeaders()`]: #streamsendheadersheaders-options
45804626
[`stream.sendInformationalHeaders()`]: #streamsendinformationalheadersheaders
45814627
[`stream.sendTrailers()`]: #streamsendtrailersheaders
45824628
[`stream.setBody()`]: #streamsetbodybody
45834629
[`stream.setPriority()`]: #streamsetpriorityoptions
4630+
[`stream.stopSending()`]: #streamstopsendingcode
45844631
[`stream.writer`]: #streamwriter
45854632
[`writer.fail()`]: #streamwriter
45864633
[`writer.fail(reason)`]: #streamwriter

0 commit comments

Comments
 (0)