From 47e84e4e75f2d4a92abc97a64c1d3d001188a3ff Mon Sep 17 00:00:00 2001
From: Naman Trivedi <trivenay@amazon.com>
Date: Sat, 12 Sep 2026 13:47:33 +0000
Subject: [PATCH] quic: add stream.cancel() sending H3_REQUEST_CANCELLED

When an endpoint deliberately abandons a request or response, RFC 9114
section 4.1.1 says the stream should be aborted with the error code
H3_REQUEST_CANCELLED. There is currently no way to express this: the
reset primitives default to the no-error code and destroy(error) uses
the internal error code.

Add stream.cancel([reason]), which abruptly terminates both directions
of the stream using the cancellation code defined by the negotiated
application protocol (H3_REQUEST_CANCELLED for HTTP/3; the no-error
code for other applications). The code value is plumbed from the
application layer through the session state, following the same
pattern as the request-rejected code.

Refs: https://github.com/nodejs/node/issues/65509
Signed-off-by: Naman Trivedi <trivenay@amazon.com>
---
 doc/api/quic.md                           |  19 ++++
 lib/internal/quic/quic.js                 |  17 ++++
 lib/internal/quic/state.js                |   9 ++
 src/quic/application.cc                   |   5 ++
 src/quic/application.h                    |   7 ++
 src/quic/http3.cc                         |   4 +
 src/quic/session.cc                       |   2 +
 test/parallel/test-quic-stream-cancel.mjs | 102 ++++++++++++++++++++++
 8 files changed, 165 insertions(+)
 create mode 100644 test/parallel/test-quic-stream-cancel.mjs

diff --git a/doc/api/quic.md b/doc/api/quic.md
index 19995000b20e..577d1e8348b6 100644
--- a/doc/api/quic.md
+++ b/doc/api/quic.md
@@ -1948,6 +1948,24 @@ an `ERR_QUIC_APPLICATION_ERROR` or `ERR_QUIC_TRANSPORT_ERROR` when the
 stream is closed due to a QUIC error (e.g., stream reset by the peer,
 CONNECTION\_CLOSE with a non-zero error code).
 
+### `stream.cancel([reason])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `reason` {string} Optional human-readable reason.
+
+Cancels the stream: abruptly terminates both directions, signaling to the
+peer that the request or response was deliberately abandoned. `STOP_SENDING`
+is sent for a still-open readable side and `RESET_STREAM` for a still-open
+writable side. When the negotiated application protocol defines a
+cancellation code ([RFC 9114 section 4.1.1][] defines `H3_REQUEST_CANCELLED`
+for HTTP/3) the frames carry it; other application protocols use their
+"no error" code.
+
+The call does nothing if the stream is already destroyed.
+
 ### `stream.destroy([error[, options]])`
 
 <!-- YAML
@@ -4761,6 +4779,7 @@ throughput issues caused by flow control.
 [RFC 9001]: https://www.rfc-editor.org/rfc/rfc9001
 [RFC 9002]: https://www.rfc-editor.org/rfc/rfc9002
 [RFC 9114]: https://www.rfc-editor.org/rfc/rfc9114
+[RFC 9114 section 4.1.1]: https://www.rfc-editor.org/rfc/rfc9114.html#section-4.1.1
 [RFC 9204]: https://www.rfc-editor.org/rfc/rfc9204
 [RFC 9218]: https://www.rfc-editor.org/rfc/rfc9218
 [RFC 9220]: https://www.rfc-editor.org/rfc/rfc9220
diff --git a/lib/internal/quic/quic.js b/lib/internal/quic/quic.js
index 33e419002495..6a4aeb85c0ca 100644
--- a/lib/internal/quic/quic.js
+++ b/lib/internal/quic/quic.js
@@ -2035,6 +2035,23 @@ class QuicStream {
    * @param {any} error
    * @param {QuicStreamDestroyOptions} [options]
    */
+  /**
+   * Cancels the stream: abruptly terminates both directions and signals
+   * to the peer that the request or response was deliberately abandoned.
+   * When the negotiated application protocol defines a cancellation code
+   * (HTTP/3: `H3_REQUEST_CANCELLED`, RFC 9114 section 4.1.1) it is sent
+   * on the RESET_STREAM / STOP_SENDING frames; other applications use
+   * their "no error" code.
+   * @param {string} [reason] Optional human-readable reason.
+   */
+  cancel(reason) {
+    assertIsQuicStream(this);
+    if (this.#inner.destroying || this.destroyed) return;
+    const code =
+      getQuicSessionState(this.#inner.session).requestCancelledCode;
+    this.destroy(undefined, { code, reason });
+  }
+
   destroy(error, options = kEmptyObject) {
     assertIsQuicStream(this);
     const inner = this.#inner;
diff --git a/lib/internal/quic/state.js b/lib/internal/quic/state.js
index 21db0f0e3d59..6731238e520f 100644
--- a/lib/internal/quic/state.js
+++ b/lib/internal/quic/state.js
@@ -78,6 +78,7 @@ const {
   IDX_STATE_SESSION_NO_ERROR_CODE,
   IDX_STATE_SESSION_INTERNAL_ERROR_CODE,
   IDX_STATE_SESSION_REQUEST_REJECTED_CODE,
+  IDX_STATE_SESSION_REQUEST_CANCELLED_CODE,
   IDX_STATE_SESSION_MAX_DATAGRAM_SIZE,
   IDX_STATE_SESSION_LAST_DATAGRAM_ID,
   IDX_STATE_SESSION_MAX_PENDING_DATAGRAMS,
@@ -125,6 +126,7 @@ assert(IDX_STATE_SESSION_APPLICATION_TYPE !== undefined);
 assert(IDX_STATE_SESSION_NO_ERROR_CODE !== undefined);
 assert(IDX_STATE_SESSION_INTERNAL_ERROR_CODE !== undefined);
 assert(IDX_STATE_SESSION_REQUEST_REJECTED_CODE !== undefined);
+assert(IDX_STATE_SESSION_REQUEST_CANCELLED_CODE !== undefined);
 assert(IDX_STATE_SESSION_MAX_DATAGRAM_SIZE !== undefined);
 assert(IDX_STATE_SESSION_LAST_DATAGRAM_ID !== undefined);
 assert(IDX_STATE_ENDPOINT_BOUND !== undefined);
@@ -557,6 +559,13 @@ class QuicSessionState {
       handle, this.#offset + IDX_STATE_SESSION_REQUEST_REJECTED_CODE, kIsLittleEndian);
   }
 
+  get requestCancelledCode() {
+    const handle = this.#handle;
+    if (handle === undefined) return undefined;
+    return DataViewPrototypeGetBigUint64(
+      handle, this.#offset + IDX_STATE_SESSION_REQUEST_CANCELLED_CODE, kIsLittleEndian);
+  }
+
   /** @type {number} */
   get maxDatagramSize() {
     const handle = this.#handle;
diff --git a/src/quic/application.cc b/src/quic/application.cc
index 1e78b7931ce1..8d278323691f 100644
--- a/src/quic/application.cc
+++ b/src/quic/application.cc
@@ -262,6 +262,11 @@ class DefaultApplication final : public Session::Application {
     return GetNoErrorCode();
   }
 
+  // Raw QUIC has no "request cancelled" semantic; reuse the no-error code.
+  error_code GetRequestCancelledCode() const override {
+    return GetNoErrorCode();
+  }
+
   void EarlyDataRejected() override {
     // Destroy all open streams — ngtcp2 has already discarded their
     // internal state when it rejected the early data. Use the
diff --git a/src/quic/application.h b/src/quic/application.h
index 0ae4ab53ab7e..f11f990f9b04 100644
--- a/src/quic/application.h
+++ b/src/quic/application.h
@@ -78,6 +78,13 @@ class Session::Application : public MemoryRetainer {
   // "no error" code.
   virtual error_code GetRequestRejectedCode() const = 0;
 
+  // The "request cancelled" code is sent on RESET_STREAM / STOP_SENDING
+  // when an endpoint deliberately abandons a request or response (e.g.
+  // stream.cancel()). For HTTP/3 this is NGHTTP3_H3_REQUEST_CANCELLED
+  // (0x10c); other applications have no such semantic and reuse the
+  // "no error" code.
+  virtual error_code GetRequestCancelledCode() const = 0;
+
   // Called after Session::Receive processes a packet, outside all callback
   // scopes. Applications can use this to handle deferred operations that
   // require calling into JS (e.g., HTTP/3 GOAWAY processing).
diff --git a/src/quic/http3.cc b/src/quic/http3.cc
index 43ead1b8164e..8f47048d268e 100644
--- a/src/quic/http3.cc
+++ b/src/quic/http3.cc
@@ -199,6 +199,10 @@ class Http3ApplicationImpl final : public Session::Application {
     return NGHTTP3_H3_REQUEST_REJECTED;
   }
 
+  error_code GetRequestCancelledCode() const override {
+    return NGHTTP3_H3_REQUEST_CANCELLED;
+  }
+
   void EarlyDataRejected() override {
     // When 0-RTT is rejected, destroy the nghttp3 connection and all
     // open streams — ngtcp2 has discarded their internal state.
diff --git a/src/quic/session.cc b/src/quic/session.cc
index 1c159d763521..22a4ac01a22b 100644
--- a/src/quic/session.cc
+++ b/src/quic/session.cc
@@ -143,6 +143,7 @@ uint64_t MaxDatagramPayload(uint64_t max_frame_size) {
   V(NO_ERROR_CODE, no_error_code, error_code)                                  \
   V(INTERNAL_ERROR_CODE, internal_error_code, error_code)                      \
   V(REQUEST_REJECTED_CODE, request_rejected_code, error_code)                  \
+  V(REQUEST_CANCELLED_CODE, request_cancelled_code, error_code)                \
   V(MAX_DATAGRAM_SIZE, max_datagram_size, uint16_t)                            \
   V(LAST_DATAGRAM_ID, last_datagram_id, datagram_id)                           \
   V(MAX_PENDING_DATAGRAMS, max_pending_datagrams, uint16_t)
@@ -2656,6 +2657,7 @@ void Session::SetApplication(std::unique_ptr<Application> app) {
   impl_->state()->no_error_code = app->GetNoErrorCode();
   impl_->state()->internal_error_code = app->GetInternalErrorCode();
   impl_->state()->request_rejected_code = app->GetRequestRejectedCode();
+  impl_->state()->request_cancelled_code = app->GetRequestCancelledCode();
   impl_->application_ = std::move(app);
 }
 
diff --git a/test/parallel/test-quic-stream-cancel.mjs b/test/parallel/test-quic-stream-cancel.mjs
new file mode 100644
index 000000000000..b6bb8fe934e7
--- /dev/null
+++ b/test/parallel/test-quic-stream-cancel.mjs
@@ -0,0 +1,102 @@
+// Flags: --experimental-quic --no-warnings
+
+// stream.cancel() abruptly terminates both directions of a stream. On a
+// session whose application protocol defines a cancellation code (HTTP/3),
+// the RESET_STREAM / STOP_SENDING frames carry H3_REQUEST_CANCELLED
+// (RFC 9114 section 4.1.1); other applications use their "no error" code.
+// Refs: https://github.com/nodejs/node/issues/65509
+
+import { hasQuic, skip, mustCall } from '../common/index.mjs';
+import assert from 'node:assert';
+import * as fixtures from '../common/fixtures.mjs';
+
+if (!hasQuic) {
+  skip('QUIC is not enabled');
+}
+
+const { listen, connect } = await import('node:quic');
+const { createPrivateKey } = await import('node:crypto');
+
+const key = createPrivateKey(fixtures.readKey('agent1-key.pem'));
+const cert = fixtures.readKey('agent1-cert.pem');
+
+// RFC 9114 H3_REQUEST_CANCELLED.
+const H3_REQUEST_CANCELLED = 0x10cn;
+
+// --- An h3 server abandoning a request signals H3_REQUEST_CANCELLED ---
+{
+  const clientSawReset = Promise.withResolvers();
+  const serverEndpoint = await listen(mustCall((serverSession) => {
+    serverSession.onerror = () => {};
+  }), {
+    sni: { '*': { keys: [key], certs: [cert] } },
+    onheaders: mustCall(function() {
+      // The server abandons the request without responding.
+      this.cancel();
+      assert.strictEqual(this.destroyed, true);
+      // Cancelling again is a no-op.
+      this.cancel();
+    }),
+  });
+
+  const clientSession = await connect(serverEndpoint.address, {
+    servername: 'localhost',
+    verifyPeer: 'manual',
+  });
+  await clientSession.opened;
+
+  const stream = await clientSession.createBidirectionalStream({
+    headers: {
+      ':method': 'GET',
+      ':path': '/test',
+      ':scheme': 'https',
+      ':authority': 'localhost',
+    },
+  });
+  stream.onerror = () => {};
+  stream.onreset = mustCall((err) => {
+    assert.strictEqual(err.code, 'ERR_QUIC_APPLICATION_ERROR');
+    assert.strictEqual(err.errorCode, H3_REQUEST_CANCELLED);
+    clientSawReset.resolve();
+  });
+
+  await clientSawReset.promise;
+  await clientSession.close();
+  await serverEndpoint.close();
+}
+
+// --- On a non-h3 application, cancel() uses the "no error" code (0) ---
+{
+  const clientSawReset = Promise.withResolvers();
+  const serverEndpoint = await listen(mustCall((serverSession) => {
+    serverSession.onerror = () => {};
+    serverSession.onstream = mustCall((stream) => {
+      stream.cancel();
+    });
+  }), {
+    sni: { '*': { keys: [key], certs: [cert] } },
+    alpn: ['test-proto'],
+  });
+
+  const clientSession = await connect(serverEndpoint.address, {
+    servername: 'localhost',
+    alpn: 'test-proto',
+    verifyPeer: 'manual',
+  });
+  await clientSession.opened;
+
+  const stream = await clientSession.createBidirectionalStream({
+    body: 'data',
+  });
+  stream.onerror = () => {};
+  stream.onreset = mustCall((err) => {
+    // A reset carrying the "no error" code is surfaced without an error
+    // object: the peer terminated the stream cleanly.
+    assert.strictEqual(err, undefined);
+    clientSawReset.resolve();
+  });
+
+  await clientSawReset.promise;
+  await clientSession.close();
+  await serverEndpoint.close();
+}