quic: StopSending callback

[martenrichter]

The docs for QuicStream's onreset callback says:

The callback to invoke when the peer aborts a direction of the stream by sending a RESET_STREAM frame (the peer abandons their writable side, so no further data will arrive on our readable side) or a STOP_SENDING frame (the peer asks us to stop writing on our writable side).

1.) How can the receiver determine, if it is a RESET_STREAM frame or a STOP_SENDING frame. This is actually a big difference. So do we need a separate onstopsending ? Or is it possible to have a property to determine this?
Or may be one sees it in the iterable?
2.) It does not look as if it is invoked for a STOP_SENDING frame, see:

node/src/quic/streams.cc

Line 1787 in 30a7e28

void Stream::ReceiveStopSending(QuicError error) {

it is just interacting with the stream.

@jasnell I may discover, that this is actually not a problem if one iterates the stream, what I am not sure yet,

[martenrichter]

No, it is a problem for StopSending. But only if you need low level stream operations.

[syedahmedx3]

Great questions — these touch on a real gap in the current docs.

Q1 — How do you tell a RESET_STREAM from a STOP_SENDING in onreset?

These two frames are fundamentally different things:

Frame	Who sends it	What it means to you
RESET_STREAM	The remote peer	"I'm aborting my send side — stop expecting data from me on this stream"
STOP_SENDING	The remote peer	"Stop sending to me — I don't want any more data from you on this stream"

So from your perspective as the receiver:

• A RESET_STREAM affects your readable side — incoming data is being aborted.
• A STOP_SENDING affects your writable side — the peer is asking you to stop writing.

The current onreset callback doesn't surface which frame triggered it, which is exactly the ambiguity you're pointing at. The error object passed to onreset carries an application-level error code (set by the sender), but there's no built-in flag today that says "this came from a STOP_SENDING vs a RESET_STREAM."

The practical workaround right now:

You can infer the frame type from which side of the stream is affected. If onreset fires and stream.readable is no longer usable, it was triggered by a RESET_STREAM. If it fires and you're still trying to write but suddenly can't, it was a STOP_SENDING.

A cleaner solution would be to expose a type property on the error argument (e.g. error.type === 'reset' vs error.type === 'stop_sending'). This would be worth a feature request / docs clarification.

Q2 — Why doesn't ReceiveStopSending seem to invoke onreset?

You're right to call this out — looking at node/src/quic/streams.cc line 1787, Stream::ReceiveStopSending directly interacts with the stream internals rather than routing through the same JS-visible onreset path.

This appears to be intentional in the current implementation: when a STOP_SENDING frame arrives, ngtcp2 (the underlying QUIC library) triggers ReceiveStopSending at the C++ level, which internally signals the writable side of the stream to abort. The JS onreset callback is primarily wired to the read-side abort path (RESET_STREAM).

So your observation is correct: STOP_SENDING may not surface as an onreset at the JS level today. It may only be visible if you're consuming the stream as an async iterable and the write-side error propagates there.

This is likely an oversight or a TODO in the experimental QUIC implementation — worth flagging explicitly.

Suggested doc improvement

The current docs say:

The callback to invoke when the peer aborts a direction of the stream by sending a RESET_STREAM frame ... or a STOP_SENDING frame ...

This should clarify:

1. Which onreset argument (if any) lets you tell the two frames apart
2. Whether ReceiveStopSending is guaranteed to trigger onreset or only the stream's writable-side error
3. Whether there's a way to get the raw application error code from either frame

A small table like the one above in the docs would go a long way.

---

I may be wrong on some of the C++ internals — @jasnell or anyone closer to ngtcp2 would know better — but this is my read from the source. Happy to help draft a doc PR if the behavior gets confirmed.

[martenrichter]

@syedahmedx3
Your answer confuses webstreams (stream.readable is not a thing for QuicStream) with the new QuicStream api.