From fad35447c4da4a1b588a1707a774a4e5fbbb3e20 Mon Sep 17 00:00:00 2001
From: Tim Perry <pimterry@gmail.com>
Date: Thu, 9 Apr 2026 16:53:00 +0200
Subject: [PATCH] quic: add QuicEndpoint.listening & QuicStream.destroy() and
 tests

Starting to explore and cover the existing implementation, this covers
the basic endpoint & stream lifecycle and the exposed properties.
Added endpoint.listening to match net.Server and round out endpoint
properties, and stream.destroy() which is already called by
quicSession.destroy() and documented, but didn't actually exist.

Signed-off-by: Tim Perry <pimterry@gmail.com>
---
 doc/api/quic.md                               |  6 ++
 lib/internal/quic/quic.js                     | 20 ++++
 .../test-quic-session-stream-lifecycle.mjs    | 98 +++++++++++++++++++
 3 files changed, 124 insertions(+)
 create mode 100644 test/parallel/test-quic-session-stream-lifecycle.mjs

diff --git a/doc/api/quic.md b/doc/api/quic.md
index 45aa2409fd1cc9..c5c197991cf923 100644
--- a/doc/api/quic.md
+++ b/doc/api/quic.md
@@ -204,6 +204,12 @@ added: v23.8.0
 
 True if `endpoint.destroy()` has been called. Read only.
 
+### `endpoint.listening`
+
+* Type: {boolean}
+
+True if the endpoint is actively listening for incoming connections. Read only.
+
 ### `endpoint.setSNIContexts(entries[, options])`
 
 <!-- YAML
diff --git a/lib/internal/quic/quic.js b/lib/internal/quic/quic.js
index fa0cfcf278538e..a24ba4d39c6e69 100644
--- a/lib/internal/quic/quic.js
+++ b/lib/internal/quic/quic.js
@@ -808,6 +808,20 @@ class QuicStream {
     return this.#pendingClose.promise;
   }
 
+  /**
+   * Immediately destroys the stream. Any queued data is discarded. If an
+   * error is given, the closed promise will be rejected with that error.
+   * If no error is given, the closed promise will be resolved.
+   * @param {any} error
+   */
+  destroy(error) {
+    QuicStream.#assertIsQuicStream(this);
+    if (this.destroyed) return;
+    const handle = this.#handle;
+    this[kFinishClose](error);
+    handle.destroy();
+  }
+
   /**
    * Sets the outbound data source for the stream. This can only be called
    * once and must be called before any data will be sent. The body can be
@@ -1930,6 +1944,12 @@ class QuicEndpoint {
     return this.#isPendingClose;
   }
 
+  /** @type {boolean} */
+  get listening() {
+    QuicEndpoint.#assertIsQuicEndpoint(this);
+    return this.#listening;
+  }
+
   /** @type {boolean} */
   get destroyed() {
     QuicEndpoint.#assertIsQuicEndpoint(this);
diff --git a/test/parallel/test-quic-session-stream-lifecycle.mjs b/test/parallel/test-quic-session-stream-lifecycle.mjs
new file mode 100644
index 00000000000000..dcd9fa9987eae6
--- /dev/null
+++ b/test/parallel/test-quic-session-stream-lifecycle.mjs
@@ -0,0 +1,98 @@
+// Flags: --experimental-quic --no-warnings
+
+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');
+}
+
+// Import after the hasQuic check
+const quic = await import('node:quic');
+const { createPrivateKey } = await import('node:crypto');
+
+const keys = createPrivateKey(fixtures.readKey('agent1-key.pem'));
+const certs = fixtures.readKey('agent1-cert.pem');
+
+const serverDone = Promise.withResolvers();
+const clientDone = Promise.withResolvers();
+
+// Create a server endpoint
+const serverEndpoint = await quic.listen(mustCall((serverSession) => {
+  serverSession.opened.then((info) => {
+    assert.ok(serverSession.endpoint !== null);
+    assert.strictEqual(serverSession.destroyed, false);
+
+    const stats = serverSession.stats;
+    assert.strictEqual(stats.isConnected, true);
+    assert.ok(stats.handshakeCompletedAt > 0n);
+    assert.ok(stats.handshakeConfirmedAt > 0n);
+    assert.strictEqual(stats.closingAt, 0n);
+
+    serverDone.resolve();
+    serverSession.close();
+  }).then(mustCall());
+}), { sni: { '*': { keys, certs } } });
+
+assert.strictEqual(serverEndpoint.busy, false);
+assert.strictEqual(serverEndpoint.closing, false);
+assert.strictEqual(serverEndpoint.destroyed, false);
+assert.strictEqual(serverEndpoint.listening, true);
+
+assert.ok(serverEndpoint.address !== undefined);
+assert.strictEqual(serverEndpoint.address.family, 'ipv4');
+assert.strictEqual(serverEndpoint.address.address, '127.0.0.1');
+assert.ok(typeof serverEndpoint.address.port === 'number');
+assert.ok(serverEndpoint.address.port > 0);
+
+const epStats = serverEndpoint.stats;
+assert.strictEqual(epStats.isConnected, true);
+assert.ok(epStats.createdAt > 0n);
+
+// Connect with a client
+const clientSession = await quic.connect(serverEndpoint.address);
+
+assert.strictEqual(clientSession.destroyed, false);
+assert.ok(clientSession.endpoint !== null);
+assert.strictEqual(clientSession.stats.isConnected, true);
+
+clientSession.opened.then((clientInfo) => {
+  assert.strictEqual(clientInfo.servername, 'localhost');
+  assert.strictEqual(clientInfo.protocol, 'h3');
+  assert.strictEqual(clientInfo.cipherVersion, 'TLSv1.3');
+  assert.ok(clientInfo.local !== undefined);
+  assert.ok(clientInfo.remote !== undefined);
+
+  const cStats = clientSession.stats;
+  assert.strictEqual(cStats.isConnected, true);
+  assert.ok(cStats.handshakeCompletedAt > 0n);
+  assert.ok(cStats.bytesSent > 0n, 'Expected bytesSent > 0 after handshake');
+
+  clientDone.resolve();
+}).then(mustCall());
+
+await Promise.all([serverDone.promise, clientDone.promise]);
+
+// Open a bidirectional stream.
+const stream = await clientSession.createBidirectionalStream();
+
+assert.strictEqual(stream.destroyed, false);
+assert.strictEqual(stream.direction, 'bidi');
+assert.strictEqual(stream.session, clientSession);
+assert.ok(stream.id !== null, 'Non-pending stream should have an id');
+assert.strictEqual(typeof stream.id, 'bigint');
+assert.strictEqual(stream.pending, false);
+assert.strictEqual(stream.stats.isConnected, true);
+assert.ok(stream.readable instanceof ReadableStream);
+
+// Destroying the session should destroy it and the stream, and clear its properties.
+clientSession.destroy();
+assert.strictEqual(clientSession.destroyed, true);
+assert.strictEqual(clientSession.endpoint, null);
+assert.strictEqual(clientSession.stats.isConnected, false);
+
+assert.strictEqual(stream.destroyed, true);
+assert.strictEqual(stream.session, null);
+assert.strictEqual(stream.id, null);
+assert.strictEqual(stream.direction, null);