quic: do not destroy incoming streams that have a consumer

An incoming stream was destroyed unless the session had an onstream
callback, even when session-level stream callbacks (onheaders et al)
were registered and the negotiated application (HTTP/3) would drive
the stream through them. Users had to register stub onstream handlers
just to keep their streams alive.
Destroy an incoming stream only when the session has no consumer for
it at all: no onstream callback, and no session-level stream callbacks
runnable on the negotiated application (checked via the existing
headersSupported session state, computed when the application is
selected from ALPN). Sessions with no consumers keep the current
destroy-and-warn behavior so unconsumed streams cannot accumulate and
hold flow control credit.
On HTTP/3 sessions only bidirectional request streams reach this path;
control and QPACK streams are consumed internally by nghttp3 and are
never exposed to JavaScript.
Fixes: #64192
Signed-off-by: Naman Trivedi <trivenay@amazon.com>
PR-URL: #65335Fixes: #64192
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

Author: trivenay

doc/api/quic.md

@@ -305,7 +305,11 @@ unidirectional (data flows in only one direction). The `quic` module provides
 separate APIs for creating each kind:
 [`session.createBidirectionalStream()`][] and
 [`session.createUnidirectionalStream()`][]. Streams initiated by a remote
-peer are delivered via the [`session.onstream`][] callback.
+peer are delivered via the [`session.onstream`][] callback. When the
+negotiated application protocol supports the stream-level callbacks (e.g.
+HTTP/3) and an `onheaders` callback is configured, incoming streams can
+instead be consumed entirely through it and registering `onstream` is
+optional.
 
 There are two ways to write data to a stream:
 
@@ -409,7 +413,9 @@ A typical client session progresses through these stages:
 
 On the server side, call [`quic.listen()`][] with a callback. The callback
 fires for each incoming session after the TLS handshake begins. Incoming
-streams arrive via the [`session.onstream`][] callback.
+streams arrive via the [`session.onstream`][] callback, or, for HTTP/3
+sessions with an `onheaders` callback configured, directly through that
+callback (see the [minimal HTTP/3 server][] example).
 
 [`session.destroy()`][] is available for immediate teardown — all open streams
 are destroyed and the session is closed without waiting for them to finish.
@@ -1108,6 +1114,15 @@ added: v23.8.0
 
 The callback to invoke when a new stream is initiated by a remote peer. Read/write.
 
+If no `onstream` callback is set and the stream has no other consumer, an
+incoming stream is destroyed on arrival and a warning is emitted. An
+`onheaders` callback counts as a consumer when the negotiated application
+protocol supports it (e.g. HTTP/3), because it is invoked for every incoming
+request stream. Other stream-level callbacks (`ontrailers`, `oninfo`,
+`onwanttrailers`) do not, since they are conditional or outbound-only and
+would leave the stream unobservable. An HTTP/3 server that handles requests
+entirely through `onheaders` does not need to set `onstream`.
+
 ### `session.ondatagram`
 
 <!-- YAML
@@ -3998,7 +4013,9 @@ import { listen } from 'node:quic';
 constencoder=newTextEncoder();
 
 constendpoint=awaitlisten((session) => {
-// The session.onstream callback fires for each new client-initiated stream.
+// The session.onstream callback fires for each new client-initiated
+// stream. It is optional here: with `onheaders` configured below,
+// request streams are consumed through that callback.
 }, {
  sni: { '*': { keys: [defaultKey], certs: [defaultCert] } },
 // ALPN defaults to 'h3'.
@@ -4632,5 +4649,6 @@ throughput issues caused by flow control.
 [`stream.writer`]: #streamwriter
 [`writer.fail()`]: #streamwriter
 [`writer.fail(reason)`]: #streamwriter
+[minimal HTTP/3 server]: #minimal-http3-server
 [qlog]: https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/
 [qvis]: https://qvis.quictools.info/

lib/internal/quic/quic.js

@@ -4129,6 +4129,24 @@ class QuicSession {
 this.#inner.verifyPeer=value;
 }
 
+/**
+ * True if an incoming stream has a consumer registered on this session:
+ * either an onstream callback, or - when the negotiated application
+ * supports headers (e.g. HTTP/3) - session-level stream callbacks that
+ * the application layer will invoke (onheaders et al).
+ * @returns {boolean}
+ */
+ #hasStreamConsumer(){
+if(typeofthis.#inner.onstream==='function')returntrue;
+// Only onheaders is guaranteed to fire for every incoming stream when
+// the negotiated application supports stream callbacks (e.g. HTTP/3).
+// Other stream callbacks are conditional (ontrailers, oninfo) or
+// outbound-only (onwanttrailers) and do not expose the stream, so they
+// do not count as a consumer.
+if(typeofthis[kStreamCallbacks]?.onheaders!=='function')returnfalse;
+returngetQuicSessionState(this).streamCallbacksSupported===1;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4141,10 +4159,13 @@ class QuicSession {
 // Set the default byte budget for received streams.
 stream.budget=kDefaultBudget;
 
-// A new stream was received. If we don't have an onstream callback, then
-// there's nothing we can do about it. Destroy the stream in this case.
-if(typeofinner.onstream!=='function'){
-process.emitWarning('A new stream was received but no onstream callback was provided');
+// A new stream was received. If the session has no consumer for it -
+// neither an onstream callback nor, on a session whose application
+// supports headers (e.g. HTTP/3), any session-level stream callbacks -
+// there's nothing that could ever read it. Destroy the stream in this
+// case rather than letting it hold flow control credit.
+if(!this.#hasStreamConsumer()){
+process.emitWarning('A new stream was received but no stream consumer callback was provided');
 stream.destroy();
 return;
 }
@@ -4175,7 +4196,14 @@ class QuicSession {
 });
 }
 
-safeCallbackInvoke(inner.onstream,this,stream);
+// Deliver the stream to the onstream consumer if one is registered.
+// Reaching this point without one means #hasStreamConsumer accepted
+// the stream on behalf of the application layer: the session-level
+// stream callbacks were applied above and the application (e.g.
+// HTTP/3) drives the stream, so there is nothing to invoke here.
+if(typeofinner.onstream==='function'){
+safeCallbackInvoke(inner.onstream,this,stream);
+}
 }
 
 [kRemoveStream](stream){

lib/internal/quic/state.js

@@ -72,6 +72,7 @@ const {
 IDX_STATE_SESSION_STREAM_OPEN_ALLOWED,
 IDX_STATE_SESSION_PRIORITY_SUPPORTED,
 IDX_STATE_SESSION_HEADERS_SUPPORTED,
+IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED,
 IDX_STATE_SESSION_WRAPPED,
 IDX_STATE_SESSION_APPLICATION_TYPE,
 IDX_STATE_SESSION_NO_ERROR_CODE,
@@ -119,6 +120,7 @@ assert(IDX_STATE_SESSION_HANDSHAKE_CONFIRMED !== undefined);
 assert(IDX_STATE_SESSION_STREAM_OPEN_ALLOWED!==undefined);
 assert(IDX_STATE_SESSION_PRIORITY_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_HEADERS_SUPPORTED!==undefined);
+assert(IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_WRAPPED!==undefined);
 assert(IDX_STATE_SESSION_APPLICATION_TYPE!==undefined);
 assert(IDX_STATE_SESSION_NO_ERROR_CODE!==undefined);
@@ -493,6 +495,19 @@ class QuicSessionState {
 returnDataViewPrototypeGetUint8(handle,this.#offset +IDX_STATE_SESSION_HEADERS_SUPPORTED);
 }
 
+/**
+ * Whether the negotiated application dispatches the session-level
+ * stream callbacks (onheaders et al) for incoming streams.
+ * Returns 0 (unknown), 1 (supported), or 2 (not supported).
+ * @type {number}
+ */
+getstreamCallbacksSupported(){
+consthandle=this.#handle;
+if(handle===undefined)returnundefined;
+returnDataViewPrototypeGetUint8(
+handle,this.#offset +IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED);
+}
+
 /** @type {boolean} */
 getisWrapped(){
 consthandle=this.#handle;

src/quic/application.h

@@ -210,6 +210,11 @@ class Session::Application : public MemoryRetainer {
 // do not support headers should return false (the default).
 virtualboolSupportsHeaders() const { returnfalse; }
 
+// True if this application dispatches the session-level stream
+// callbacks (onheaders et al) for incoming streams when they are
+// registered on the session.
+virtualboolSupportsStreamCallbacks() const { returnfalse; }
+
 // Initiates application-level graceful shutdown signaling (e.g.,
 // HTTP/3 GOAWAY). Called when Session::Close(GRACEFUL) is invoked.
 virtualvoidBeginShutdown() {}

src/quic/defs.h

@@ -328,6 +328,12 @@ enum class HeadersSupportState : uint8_t {
 UNSUPPORTED,
 };
 
+enumclassStreamCallbacksSupportState : uint8_t {
+UNKNOWN,
+SUPPORTED,
+UNSUPPORTED,
+};
+
 enumclassPathValidationResult : uint8_t {
 SUCCESS = NGTCP2_PATH_VALIDATION_RESULT_SUCCESS,
 FAILURE = NGTCP2_PATH_VALIDATION_RESULT_FAILURE,

src/quic/http3.cc

@@ -202,6 +202,8 @@ class Http3ApplicationImpl final : public Session::Application {
 
 boolSupportsHeaders() constoverride { returntrue; }
 
+boolSupportsStreamCallbacks() constoverride { returntrue; }
+
 boolis_started() constoverride { return started_; }
 
 boolStart() override {

src/quic/session.cc

@@ -136,6 +136,7 @@ uint64_t MaxDatagramPayload(uint64_t max_frame_size) {
 V(STREAM_OPEN_ALLOWED, stream_open_allowed, uint8_t) \
 V(PRIORITY_SUPPORTED, priority_supported, uint8_t) \
 V(HEADERS_SUPPORTED, headers_supported, uint8_t) \
+V(STREAM_CALLBACKS_SUPPORTED, stream_callbacks_supported, uint8_t) \
 V(WRAPPED, wrapped, uint8_t) \
 V(APPLICATION_TYPE, application_type, uint8_t) \
 V(NO_ERROR_CODE, no_error_code, error_code) \
@@ -2649,6 +2650,10 @@ void Session::SetApplication(std::unique_ptr<Application> app) {
  impl_->state()->headers_supported = static_cast<uint8_t>(
  app->SupportsHeaders() ? HeadersSupportState::SUPPORTED
  : HeadersSupportState::UNSUPPORTED);
+ impl_->state()->stream_callbacks_supported =
+static_cast<uint8_t>(app->SupportsStreamCallbacks()
+ ? StreamCallbacksSupportState::SUPPORTED
+ : StreamCallbacksSupportState::UNSUPPORTED);
 // Surface the application's "no error" and "internal error" codes via
 // session state so that JS-side code (e.g. the stream writer's fail()
 // path) can resolve the right wire code for the negotiated ALPN

doc/api/quic.md

@@ -305,7 +305,11 @@ unidirectional (data flows in only one direction). The `quic` module provides
 separate APIs for creating each kind:
 [`session.createBidirectionalStream()`][] and
 [`session.createUnidirectionalStream()`][]. Streams initiated by a remote
-peer are delivered via the [`session.onstream`][] callback.
+peer are delivered via the [`session.onstream`][] callback. When the
+negotiated application protocol supports the stream-level callbacks (e.g.
+HTTP/3) and an `onheaders` callback is configured, incoming streams can
+instead be consumed entirely through it and registering `onstream` is
+optional.
 
 There are two ways to write data to a stream:
 
@@ -409,7 +413,9 @@ A typical client session progresses through these stages:
 
 On the server side, call [`quic.listen()`][] with a callback. The callback
 fires for each incoming session after the TLS handshake begins. Incoming
-streams arrive via the [`session.onstream`][] callback.
+streams arrive via the [`session.onstream`][] callback, or, for HTTP/3
+sessions with an `onheaders` callback configured, directly through that
+callback (see the [minimal HTTP/3 server][] example).
 
 [`session.destroy()`][] is available for immediate teardown — all open streams
 are destroyed and the session is closed without waiting for them to finish.
@@ -1108,6 +1114,15 @@ added: v23.8.0
 
 The callback to invoke when a new stream is initiated by a remote peer. Read/write.
 
+If no `onstream` callback is set and the stream has no other consumer, an
+incoming stream is destroyed on arrival and a warning is emitted. An
+`onheaders` callback counts as a consumer when the negotiated application
+protocol supports it (e.g. HTTP/3), because it is invoked for every incoming
+request stream. Other stream-level callbacks (`ontrailers`, `oninfo`,
+`onwanttrailers`) do not, since they are conditional or outbound-only and
+would leave the stream unobservable. An HTTP/3 server that handles requests
+entirely through `onheaders` does not need to set `onstream`.
+
 ### `session.ondatagram`
 
 <!-- YAML
@@ -3998,7 +4013,9 @@ import { listen } from 'node:quic';
 constencoder=newTextEncoder();
 
 constendpoint=awaitlisten((session) => {
-// The session.onstream callback fires for each new client-initiated stream.
+// The session.onstream callback fires for each new client-initiated
+// stream. It is optional here: with `onheaders` configured below,
+// request streams are consumed through that callback.
 }, {
  sni: { '*': { keys: [defaultKey], certs: [defaultCert] } },
 // ALPN defaults to 'h3'.
@@ -4632,5 +4649,6 @@ throughput issues caused by flow control.
 [`stream.writer`]: #streamwriter
 [`writer.fail()`]: #streamwriter
 [`writer.fail(reason)`]: #streamwriter
+[minimal HTTP/3 server]: #minimal-http3-server
 [qlog]: https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/
 [qvis]: https://qvis.quictools.info/

lib/internal/quic/quic.js

@@ -4129,6 +4129,24 @@ class QuicSession {
 this.#inner.verifyPeer=value;
 }
 
+/**
+ * True if an incoming stream has a consumer registered on this session:
+ * either an onstream callback, or - when the negotiated application
+ * supports headers (e.g. HTTP/3) - session-level stream callbacks that
+ * the application layer will invoke (onheaders et al).
+ * @returns {boolean}
+ */
+ #hasStreamConsumer(){
+if(typeofthis.#inner.onstream==='function')returntrue;
+// Only onheaders is guaranteed to fire for every incoming stream when
+// the negotiated application supports stream callbacks (e.g. HTTP/3).
+// Other stream callbacks are conditional (ontrailers, oninfo) or
+// outbound-only (onwanttrailers) and do not expose the stream, so they
+// do not count as a consumer.
+if(typeofthis[kStreamCallbacks]?.onheaders!=='function')returnfalse;
+returngetQuicSessionState(this).streamCallbacksSupported===1;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4141,10 +4159,13 @@ class QuicSession {
 // Set the default byte budget for received streams.
 stream.budget=kDefaultBudget;
 
-// A new stream was received. If we don't have an onstream callback, then
-// there's nothing we can do about it. Destroy the stream in this case.
-if(typeofinner.onstream!=='function'){
-process.emitWarning('A new stream was received but no onstream callback was provided');
+// A new stream was received. If the session has no consumer for it -
+// neither an onstream callback nor, on a session whose application
+// supports headers (e.g. HTTP/3), any session-level stream callbacks -
+// there's nothing that could ever read it. Destroy the stream in this
+// case rather than letting it hold flow control credit.
+if(!this.#hasStreamConsumer()){
+process.emitWarning('A new stream was received but no stream consumer callback was provided');
 stream.destroy();
 return;
 }
@@ -4175,7 +4196,14 @@ class QuicSession {
 });
 }
 
-safeCallbackInvoke(inner.onstream,this,stream);
+// Deliver the stream to the onstream consumer if one is registered.
+// Reaching this point without one means #hasStreamConsumer accepted
+// the stream on behalf of the application layer: the session-level
+// stream callbacks were applied above and the application (e.g.
+// HTTP/3) drives the stream, so there is nothing to invoke here.
+if(typeofinner.onstream==='function'){
+safeCallbackInvoke(inner.onstream,this,stream);
+}
 }
 
 [kRemoveStream](stream){

lib/internal/quic/state.js

@@ -72,6 +72,7 @@ const {
 IDX_STATE_SESSION_STREAM_OPEN_ALLOWED,
 IDX_STATE_SESSION_PRIORITY_SUPPORTED,
 IDX_STATE_SESSION_HEADERS_SUPPORTED,
+IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED,
 IDX_STATE_SESSION_WRAPPED,
 IDX_STATE_SESSION_APPLICATION_TYPE,
 IDX_STATE_SESSION_NO_ERROR_CODE,
@@ -119,6 +120,7 @@ assert(IDX_STATE_SESSION_HANDSHAKE_CONFIRMED !== undefined);
 assert(IDX_STATE_SESSION_STREAM_OPEN_ALLOWED!==undefined);
 assert(IDX_STATE_SESSION_PRIORITY_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_HEADERS_SUPPORTED!==undefined);
+assert(IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_WRAPPED!==undefined);
 assert(IDX_STATE_SESSION_APPLICATION_TYPE!==undefined);
 assert(IDX_STATE_SESSION_NO_ERROR_CODE!==undefined);
@@ -493,6 +495,19 @@ class QuicSessionState {
 returnDataViewPrototypeGetUint8(handle,this.#offset +IDX_STATE_SESSION_HEADERS_SUPPORTED);
 }
 
+/**
+ * Whether the negotiated application dispatches the session-level
+ * stream callbacks (onheaders et al) for incoming streams.
+ * Returns 0 (unknown), 1 (supported), or 2 (not supported).
+ * @type {number}
+ */
+getstreamCallbacksSupported(){
+consthandle=this.#handle;
+if(handle===undefined)returnundefined;
+returnDataViewPrototypeGetUint8(
+handle,this.#offset +IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED);
+}
+
 /** @type {boolean} */
 getisWrapped(){
 consthandle=this.#handle;

src/quic/application.h

@@ -210,6 +210,11 @@ class Session::Application : public MemoryRetainer {
 // do not support headers should return false (the default).
 virtualboolSupportsHeaders() const { returnfalse; }
 
+// True if this application dispatches the session-level stream
+// callbacks (onheaders et al) for incoming streams when they are
+// registered on the session.
+virtualboolSupportsStreamCallbacks() const { returnfalse; }
+
 // Initiates application-level graceful shutdown signaling (e.g.,
 // HTTP/3 GOAWAY). Called when Session::Close(GRACEFUL) is invoked.
 virtualvoidBeginShutdown() {}

src/quic/defs.h

@@ -328,6 +328,12 @@ enum class HeadersSupportState : uint8_t {
 UNSUPPORTED,
 };
 
+enumclassStreamCallbacksSupportState : uint8_t {
+UNKNOWN,
+SUPPORTED,
+UNSUPPORTED,
+};
+
 enumclassPathValidationResult : uint8_t {
 SUCCESS = NGTCP2_PATH_VALIDATION_RESULT_SUCCESS,
 FAILURE = NGTCP2_PATH_VALIDATION_RESULT_FAILURE,

src/quic/http3.cc

@@ -202,6 +202,8 @@ class Http3ApplicationImpl final : public Session::Application {
 
 boolSupportsHeaders() constoverride { returntrue; }
 
+boolSupportsStreamCallbacks() constoverride { returntrue; }
+
 boolis_started() constoverride { return started_; }
 
 boolStart() override {

src/quic/session.cc

@@ -136,6 +136,7 @@ uint64_t MaxDatagramPayload(uint64_t max_frame_size) {
 V(STREAM_OPEN_ALLOWED, stream_open_allowed, uint8_t) \
 V(PRIORITY_SUPPORTED, priority_supported, uint8_t) \
 V(HEADERS_SUPPORTED, headers_supported, uint8_t) \
+V(STREAM_CALLBACKS_SUPPORTED, stream_callbacks_supported, uint8_t) \
 V(WRAPPED, wrapped, uint8_t) \
 V(APPLICATION_TYPE, application_type, uint8_t) \
 V(NO_ERROR_CODE, no_error_code, error_code) \
@@ -2649,6 +2650,10 @@ void Session::SetApplication(std::unique_ptr<Application> app) {
  impl_->state()->headers_supported = static_cast<uint8_t>(
  app->SupportsHeaders() ? HeadersSupportState::SUPPORTED
  : HeadersSupportState::UNSUPPORTED);
+ impl_->state()->stream_callbacks_supported =
+static_cast<uint8_t>(app->SupportsStreamCallbacks()
+ ? StreamCallbacksSupportState::SUPPORTED
+ : StreamCallbacksSupportState::UNSUPPORTED);
 // Surface the application's "no error" and "internal error" codes via
 // session state so that JS-side code (e.g. the stream writer's fail()
 // path) can resolve the right wire code for the negotiated ALPN

doc/api/quic.md

@@ -305,7 +305,11 @@ unidirectional (data flows in only one direction). The `quic` module provides
 separate APIs for creating each kind:
 [`session.createBidirectionalStream()`][] and
 [`session.createUnidirectionalStream()`][]. Streams initiated by a remote
-peer are delivered via the [`session.onstream`][] callback.
+peer are delivered via the [`session.onstream`][] callback. When the
+negotiated application protocol supports the stream-level callbacks (e.g.
+HTTP/3) and an `onheaders` callback is configured, incoming streams can
+instead be consumed entirely through it and registering `onstream` is
+optional.
 
 There are two ways to write data to a stream:
 
@@ -409,7 +413,9 @@ A typical client session progresses through these stages:
 
 On the server side, call [`quic.listen()`][] with a callback. The callback
 fires for each incoming session after the TLS handshake begins. Incoming
-streams arrive via the [`session.onstream`][] callback.
+streams arrive via the [`session.onstream`][] callback, or, for HTTP/3
+sessions with an `onheaders` callback configured, directly through that
+callback (see the [minimal HTTP/3 server][] example).
 
 [`session.destroy()`][] is available for immediate teardown — all open streams
 are destroyed and the session is closed without waiting for them to finish.
@@ -1108,6 +1114,15 @@ added: v23.8.0
 
 The callback to invoke when a new stream is initiated by a remote peer. Read/write.
 
+If no `onstream` callback is set and the stream has no other consumer, an
+incoming stream is destroyed on arrival and a warning is emitted. An
+`onheaders` callback counts as a consumer when the negotiated application
+protocol supports it (e.g. HTTP/3), because it is invoked for every incoming
+request stream. Other stream-level callbacks (`ontrailers`, `oninfo`,
+`onwanttrailers`) do not, since they are conditional or outbound-only and
+would leave the stream unobservable. An HTTP/3 server that handles requests
+entirely through `onheaders` does not need to set `onstream`.
+
 ### `session.ondatagram`
 
 <!-- YAML
@@ -3998,7 +4013,9 @@ import { listen } from 'node:quic';
 constencoder=newTextEncoder();
 
 constendpoint=awaitlisten((session) => {
-// The session.onstream callback fires for each new client-initiated stream.
+// The session.onstream callback fires for each new client-initiated
+// stream. It is optional here: with `onheaders` configured below,
+// request streams are consumed through that callback.
 }, {
  sni: { '*': { keys: [defaultKey], certs: [defaultCert] } },
 // ALPN defaults to 'h3'.
@@ -4632,5 +4649,6 @@ throughput issues caused by flow control.
 [`stream.writer`]: #streamwriter
 [`writer.fail()`]: #streamwriter
 [`writer.fail(reason)`]: #streamwriter
+[minimal HTTP/3 server]: #minimal-http3-server
 [qlog]: https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/
 [qvis]: https://qvis.quictools.info/

lib/internal/quic/quic.js

@@ -4129,6 +4129,24 @@ class QuicSession {
 this.#inner.verifyPeer=value;
 }
 
+/**
+ * True if an incoming stream has a consumer registered on this session:
+ * either an onstream callback, or - when the negotiated application
+ * supports headers (e.g. HTTP/3) - session-level stream callbacks that
+ * the application layer will invoke (onheaders et al).
+ * @returns {boolean}
+ */
+ #hasStreamConsumer(){
+if(typeofthis.#inner.onstream==='function')returntrue;
+// Only onheaders is guaranteed to fire for every incoming stream when
+// the negotiated application supports stream callbacks (e.g. HTTP/3).
+// Other stream callbacks are conditional (ontrailers, oninfo) or
+// outbound-only (onwanttrailers) and do not expose the stream, so they
+// do not count as a consumer.
+if(typeofthis[kStreamCallbacks]?.onheaders!=='function')returnfalse;
+returngetQuicSessionState(this).streamCallbacksSupported===1;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4141,10 +4159,13 @@ class QuicSession {
 // Set the default byte budget for received streams.
 stream.budget=kDefaultBudget;
 
-// A new stream was received. If we don't have an onstream callback, then
-// there's nothing we can do about it. Destroy the stream in this case.
-if(typeofinner.onstream!=='function'){
-process.emitWarning('A new stream was received but no onstream callback was provided');
+// A new stream was received. If the session has no consumer for it -
+// neither an onstream callback nor, on a session whose application
+// supports headers (e.g. HTTP/3), any session-level stream callbacks -
+// there's nothing that could ever read it. Destroy the stream in this
+// case rather than letting it hold flow control credit.
+if(!this.#hasStreamConsumer()){
+process.emitWarning('A new stream was received but no stream consumer callback was provided');
 stream.destroy();
 return;
 }
@@ -4175,7 +4196,14 @@ class QuicSession {
 });
 }
 
-safeCallbackInvoke(inner.onstream,this,stream);
+// Deliver the stream to the onstream consumer if one is registered.
+// Reaching this point without one means #hasStreamConsumer accepted
+// the stream on behalf of the application layer: the session-level
+// stream callbacks were applied above and the application (e.g.
+// HTTP/3) drives the stream, so there is nothing to invoke here.
+if(typeofinner.onstream==='function'){
+safeCallbackInvoke(inner.onstream,this,stream);
+}
 }
 
 [kRemoveStream](stream){

lib/internal/quic/state.js

@@ -72,6 +72,7 @@ const {
 IDX_STATE_SESSION_STREAM_OPEN_ALLOWED,
 IDX_STATE_SESSION_PRIORITY_SUPPORTED,
 IDX_STATE_SESSION_HEADERS_SUPPORTED,
+IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED,
 IDX_STATE_SESSION_WRAPPED,
 IDX_STATE_SESSION_APPLICATION_TYPE,
 IDX_STATE_SESSION_NO_ERROR_CODE,
@@ -119,6 +120,7 @@ assert(IDX_STATE_SESSION_HANDSHAKE_CONFIRMED !== undefined);
 assert(IDX_STATE_SESSION_STREAM_OPEN_ALLOWED!==undefined);
 assert(IDX_STATE_SESSION_PRIORITY_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_HEADERS_SUPPORTED!==undefined);
+assert(IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_WRAPPED!==undefined);
 assert(IDX_STATE_SESSION_APPLICATION_TYPE!==undefined);
 assert(IDX_STATE_SESSION_NO_ERROR_CODE!==undefined);
@@ -493,6 +495,19 @@ class QuicSessionState {
 returnDataViewPrototypeGetUint8(handle,this.#offset +IDX_STATE_SESSION_HEADERS_SUPPORTED);
 }
 
+/**
+ * Whether the negotiated application dispatches the session-level
+ * stream callbacks (onheaders et al) for incoming streams.
+ * Returns 0 (unknown), 1 (supported), or 2 (not supported).
+ * @type {number}
+ */
+getstreamCallbacksSupported(){
+consthandle=this.#handle;
+if(handle===undefined)returnundefined;
+returnDataViewPrototypeGetUint8(
+handle,this.#offset +IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED);
+}
+
 /** @type {boolean} */
 getisWrapped(){
 consthandle=this.#handle;

src/quic/application.h

@@ -210,6 +210,11 @@ class Session::Application : public MemoryRetainer {
 // do not support headers should return false (the default).
 virtualboolSupportsHeaders() const { returnfalse; }
 
+// True if this application dispatches the session-level stream
+// callbacks (onheaders et al) for incoming streams when they are
+// registered on the session.
+virtualboolSupportsStreamCallbacks() const { returnfalse; }
+
 // Initiates application-level graceful shutdown signaling (e.g.,
 // HTTP/3 GOAWAY). Called when Session::Close(GRACEFUL) is invoked.
 virtualvoidBeginShutdown() {}

src/quic/defs.h

@@ -328,6 +328,12 @@ enum class HeadersSupportState : uint8_t {
 UNSUPPORTED,
 };
 
+enumclassStreamCallbacksSupportState : uint8_t {
+UNKNOWN,
+SUPPORTED,
+UNSUPPORTED,
+};
+
 enumclassPathValidationResult : uint8_t {
 SUCCESS = NGTCP2_PATH_VALIDATION_RESULT_SUCCESS,
 FAILURE = NGTCP2_PATH_VALIDATION_RESULT_FAILURE,

src/quic/http3.cc

@@ -202,6 +202,8 @@ class Http3ApplicationImpl final : public Session::Application {
 
 boolSupportsHeaders() constoverride { returntrue; }
 
+boolSupportsStreamCallbacks() constoverride { returntrue; }
+
 boolis_started() constoverride { return started_; }
 
 boolStart() override {

src/quic/session.cc

@@ -136,6 +136,7 @@ uint64_t MaxDatagramPayload(uint64_t max_frame_size) {
 V(STREAM_OPEN_ALLOWED, stream_open_allowed, uint8_t) \
 V(PRIORITY_SUPPORTED, priority_supported, uint8_t) \
 V(HEADERS_SUPPORTED, headers_supported, uint8_t) \
+V(STREAM_CALLBACKS_SUPPORTED, stream_callbacks_supported, uint8_t) \
 V(WRAPPED, wrapped, uint8_t) \
 V(APPLICATION_TYPE, application_type, uint8_t) \
 V(NO_ERROR_CODE, no_error_code, error_code) \
@@ -2649,6 +2650,10 @@ void Session::SetApplication(std::unique_ptr<Application> app) {
  impl_->state()->headers_supported = static_cast<uint8_t>(
  app->SupportsHeaders() ? HeadersSupportState::SUPPORTED
  : HeadersSupportState::UNSUPPORTED);
+ impl_->state()->stream_callbacks_supported =
+static_cast<uint8_t>(app->SupportsStreamCallbacks()
+ ? StreamCallbacksSupportState::SUPPORTED
+ : StreamCallbacksSupportState::UNSUPPORTED);
 // Surface the application's "no error" and "internal error" codes via
 // session state so that JS-side code (e.g. the stream writer's fail()
 // path) can resolve the right wire code for the negotiated ALPN

doc/api/quic.md

@@ -305,7 +305,11 @@ unidirectional (data flows in only one direction). The `quic` module provides
 separate APIs for creating each kind:
 [`session.createBidirectionalStream()`][] and
 [`session.createUnidirectionalStream()`][]. Streams initiated by a remote
-peer are delivered via the [`session.onstream`][] callback.
+peer are delivered via the [`session.onstream`][] callback. When the
+negotiated application protocol supports the stream-level callbacks (e.g.
+HTTP/3) and an `onheaders` callback is configured, incoming streams can
+instead be consumed entirely through it and registering `onstream` is
+optional.
 
 There are two ways to write data to a stream:
 
@@ -409,7 +413,9 @@ A typical client session progresses through these stages:
 
 On the server side, call [`quic.listen()`][] with a callback. The callback
 fires for each incoming session after the TLS handshake begins. Incoming
-streams arrive via the [`session.onstream`][] callback.
+streams arrive via the [`session.onstream`][] callback, or, for HTTP/3
+sessions with an `onheaders` callback configured, directly through that
+callback (see the [minimal HTTP/3 server][] example).
 
 [`session.destroy()`][] is available for immediate teardown — all open streams
 are destroyed and the session is closed without waiting for them to finish.
@@ -1108,6 +1114,15 @@ added: v23.8.0
 
 The callback to invoke when a new stream is initiated by a remote peer. Read/write.
 
+If no `onstream` callback is set and the stream has no other consumer, an
+incoming stream is destroyed on arrival and a warning is emitted. An
+`onheaders` callback counts as a consumer when the negotiated application
+protocol supports it (e.g. HTTP/3), because it is invoked for every incoming
+request stream. Other stream-level callbacks (`ontrailers`, `oninfo`,
+`onwanttrailers`) do not, since they are conditional or outbound-only and
+would leave the stream unobservable. An HTTP/3 server that handles requests
+entirely through `onheaders` does not need to set `onstream`.
+
 ### `session.ondatagram`
 
 <!-- YAML
@@ -3998,7 +4013,9 @@ import { listen } from 'node:quic';
 constencoder=newTextEncoder();
 
 constendpoint=awaitlisten((session) => {
-// The session.onstream callback fires for each new client-initiated stream.
+// The session.onstream callback fires for each new client-initiated
+// stream. It is optional here: with `onheaders` configured below,
+// request streams are consumed through that callback.
 }, {
  sni: { '*': { keys: [defaultKey], certs: [defaultCert] } },
 // ALPN defaults to 'h3'.
@@ -4632,5 +4649,6 @@ throughput issues caused by flow control.
 [`stream.writer`]: #streamwriter
 [`writer.fail()`]: #streamwriter
 [`writer.fail(reason)`]: #streamwriter
+[minimal HTTP/3 server]: #minimal-http3-server
 [qlog]: https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/
 [qvis]: https://qvis.quictools.info/

lib/internal/quic/quic.js

@@ -4129,6 +4129,24 @@ class QuicSession {
 this.#inner.verifyPeer=value;
 }
 
+/**
+ * True if an incoming stream has a consumer registered on this session:
+ * either an onstream callback, or - when the negotiated application
+ * supports headers (e.g. HTTP/3) - session-level stream callbacks that
+ * the application layer will invoke (onheaders et al).
+ * @returns {boolean}
+ */
+ #hasStreamConsumer(){
+if(typeofthis.#inner.onstream==='function')returntrue;
+// Only onheaders is guaranteed to fire for every incoming stream when
+// the negotiated application supports stream callbacks (e.g. HTTP/3).
+// Other stream callbacks are conditional (ontrailers, oninfo) or
+// outbound-only (onwanttrailers) and do not expose the stream, so they
+// do not count as a consumer.
+if(typeofthis[kStreamCallbacks]?.onheaders!=='function')returnfalse;
+returngetQuicSessionState(this).streamCallbacksSupported===1;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4141,10 +4159,13 @@ class QuicSession {
 // Set the default byte budget for received streams.
 stream.budget=kDefaultBudget;
 
-// A new stream was received. If we don't have an onstream callback, then
-// there's nothing we can do about it. Destroy the stream in this case.
-if(typeofinner.onstream!=='function'){
-process.emitWarning('A new stream was received but no onstream callback was provided');
+// A new stream was received. If the session has no consumer for it -
+// neither an onstream callback nor, on a session whose application
+// supports headers (e.g. HTTP/3), any session-level stream callbacks -
+// there's nothing that could ever read it. Destroy the stream in this
+// case rather than letting it hold flow control credit.
+if(!this.#hasStreamConsumer()){
+process.emitWarning('A new stream was received but no stream consumer callback was provided');
 stream.destroy();
 return;
 }
@@ -4175,7 +4196,14 @@ class QuicSession {
 });
 }
 
-safeCallbackInvoke(inner.onstream,this,stream);
+// Deliver the stream to the onstream consumer if one is registered.
+// Reaching this point without one means #hasStreamConsumer accepted
+// the stream on behalf of the application layer: the session-level
+// stream callbacks were applied above and the application (e.g.
+// HTTP/3) drives the stream, so there is nothing to invoke here.
+if(typeofinner.onstream==='function'){
+safeCallbackInvoke(inner.onstream,this,stream);
+}
 }
 
 [kRemoveStream](stream){

lib/internal/quic/state.js

@@ -72,6 +72,7 @@ const {
 IDX_STATE_SESSION_STREAM_OPEN_ALLOWED,
 IDX_STATE_SESSION_PRIORITY_SUPPORTED,
 IDX_STATE_SESSION_HEADERS_SUPPORTED,
+IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED,
 IDX_STATE_SESSION_WRAPPED,
 IDX_STATE_SESSION_APPLICATION_TYPE,
 IDX_STATE_SESSION_NO_ERROR_CODE,
@@ -119,6 +120,7 @@ assert(IDX_STATE_SESSION_HANDSHAKE_CONFIRMED !== undefined);
 assert(IDX_STATE_SESSION_STREAM_OPEN_ALLOWED!==undefined);
 assert(IDX_STATE_SESSION_PRIORITY_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_HEADERS_SUPPORTED!==undefined);
+assert(IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_WRAPPED!==undefined);
 assert(IDX_STATE_SESSION_APPLICATION_TYPE!==undefined);
 assert(IDX_STATE_SESSION_NO_ERROR_CODE!==undefined);
@@ -493,6 +495,19 @@ class QuicSessionState {
 returnDataViewPrototypeGetUint8(handle,this.#offset +IDX_STATE_SESSION_HEADERS_SUPPORTED);
 }
 
+/**
+ * Whether the negotiated application dispatches the session-level
+ * stream callbacks (onheaders et al) for incoming streams.
+ * Returns 0 (unknown), 1 (supported), or 2 (not supported).
+ * @type {number}
+ */
+getstreamCallbacksSupported(){
+consthandle=this.#handle;
+if(handle===undefined)returnundefined;
+returnDataViewPrototypeGetUint8(
+handle,this.#offset +IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED);
+}
+
 /** @type {boolean} */
 getisWrapped(){
 consthandle=this.#handle;

src/quic/application.h

@@ -210,6 +210,11 @@ class Session::Application : public MemoryRetainer {
 // do not support headers should return false (the default).
 virtualboolSupportsHeaders() const { returnfalse; }
 
+// True if this application dispatches the session-level stream
+// callbacks (onheaders et al) for incoming streams when they are
+// registered on the session.
+virtualboolSupportsStreamCallbacks() const { returnfalse; }
+
 // Initiates application-level graceful shutdown signaling (e.g.,
 // HTTP/3 GOAWAY). Called when Session::Close(GRACEFUL) is invoked.
 virtualvoidBeginShutdown() {}

src/quic/defs.h

@@ -328,6 +328,12 @@ enum class HeadersSupportState : uint8_t {
 UNSUPPORTED,
 };
 
+enumclassStreamCallbacksSupportState : uint8_t {
+UNKNOWN,
+SUPPORTED,
+UNSUPPORTED,
+};
+
 enumclassPathValidationResult : uint8_t {
 SUCCESS = NGTCP2_PATH_VALIDATION_RESULT_SUCCESS,
 FAILURE = NGTCP2_PATH_VALIDATION_RESULT_FAILURE,

src/quic/http3.cc

@@ -202,6 +202,8 @@ class Http3ApplicationImpl final : public Session::Application {
 
 boolSupportsHeaders() constoverride { returntrue; }
 
+boolSupportsStreamCallbacks() constoverride { returntrue; }
+
 boolis_started() constoverride { return started_; }
 
 boolStart() override {

src/quic/session.cc

@@ -136,6 +136,7 @@ uint64_t MaxDatagramPayload(uint64_t max_frame_size) {
 V(STREAM_OPEN_ALLOWED, stream_open_allowed, uint8_t) \
 V(PRIORITY_SUPPORTED, priority_supported, uint8_t) \
 V(HEADERS_SUPPORTED, headers_supported, uint8_t) \
+V(STREAM_CALLBACKS_SUPPORTED, stream_callbacks_supported, uint8_t) \
 V(WRAPPED, wrapped, uint8_t) \
 V(APPLICATION_TYPE, application_type, uint8_t) \
 V(NO_ERROR_CODE, no_error_code, error_code) \
@@ -2649,6 +2650,10 @@ void Session::SetApplication(std::unique_ptr<Application> app) {
  impl_->state()->headers_supported = static_cast<uint8_t>(
  app->SupportsHeaders() ? HeadersSupportState::SUPPORTED
  : HeadersSupportState::UNSUPPORTED);
+ impl_->state()->stream_callbacks_supported =
+static_cast<uint8_t>(app->SupportsStreamCallbacks()
+ ? StreamCallbacksSupportState::SUPPORTED
+ : StreamCallbacksSupportState::UNSUPPORTED);
 // Surface the application's "no error" and "internal error" codes via
 // session state so that JS-side code (e.g. the stream writer's fail()
 // path) can resolve the right wire code for the negotiated ALPN

doc/api/quic.md

@@ -305,7 +305,11 @@ unidirectional (data flows in only one direction). The `quic` module provides
 separate APIs for creating each kind:
 [`session.createBidirectionalStream()`][] and
 [`session.createUnidirectionalStream()`][]. Streams initiated by a remote
-peer are delivered via the [`session.onstream`][] callback.
+peer are delivered via the [`session.onstream`][] callback. When the
+negotiated application protocol supports the stream-level callbacks (e.g.
+HTTP/3) and an `onheaders` callback is configured, incoming streams can
+instead be consumed entirely through it and registering `onstream` is
+optional.
 
 There are two ways to write data to a stream:
 
@@ -409,7 +413,9 @@ A typical client session progresses through these stages:
 
 On the server side, call [`quic.listen()`][] with a callback. The callback
 fires for each incoming session after the TLS handshake begins. Incoming
-streams arrive via the [`session.onstream`][] callback.
+streams arrive via the [`session.onstream`][] callback, or, for HTTP/3
+sessions with an `onheaders` callback configured, directly through that
+callback (see the [minimal HTTP/3 server][] example).
 
 [`session.destroy()`][] is available for immediate teardown — all open streams
 are destroyed and the session is closed without waiting for them to finish.
@@ -1108,6 +1114,15 @@ added: v23.8.0
 
 The callback to invoke when a new stream is initiated by a remote peer. Read/write.
 
+If no `onstream` callback is set and the stream has no other consumer, an
+incoming stream is destroyed on arrival and a warning is emitted. An
+`onheaders` callback counts as a consumer when the negotiated application
+protocol supports it (e.g. HTTP/3), because it is invoked for every incoming
+request stream. Other stream-level callbacks (`ontrailers`, `oninfo`,
+`onwanttrailers`) do not, since they are conditional or outbound-only and
+would leave the stream unobservable. An HTTP/3 server that handles requests
+entirely through `onheaders` does not need to set `onstream`.
+
 ### `session.ondatagram`
 
 <!-- YAML
@@ -3998,7 +4013,9 @@ import { listen } from 'node:quic';
 constencoder=newTextEncoder();
 
 constendpoint=awaitlisten((session) => {
-// The session.onstream callback fires for each new client-initiated stream.
+// The session.onstream callback fires for each new client-initiated
+// stream. It is optional here: with `onheaders` configured below,
+// request streams are consumed through that callback.
 }, {
  sni: { '*': { keys: [defaultKey], certs: [defaultCert] } },
 // ALPN defaults to 'h3'.
@@ -4632,5 +4649,6 @@ throughput issues caused by flow control.
 [`stream.writer`]: #streamwriter
 [`writer.fail()`]: #streamwriter
 [`writer.fail(reason)`]: #streamwriter
+[minimal HTTP/3 server]: #minimal-http3-server
 [qlog]: https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/
 [qvis]: https://qvis.quictools.info/

lib/internal/quic/quic.js

@@ -4129,6 +4129,24 @@ class QuicSession {
 this.#inner.verifyPeer=value;
 }
 
+/**
+ * True if an incoming stream has a consumer registered on this session:
+ * either an onstream callback, or - when the negotiated application
+ * supports headers (e.g. HTTP/3) - session-level stream callbacks that
+ * the application layer will invoke (onheaders et al).
+ * @returns {boolean}
+ */
+ #hasStreamConsumer(){
+if(typeofthis.#inner.onstream==='function')returntrue;
+// Only onheaders is guaranteed to fire for every incoming stream when
+// the negotiated application supports stream callbacks (e.g. HTTP/3).
+// Other stream callbacks are conditional (ontrailers, oninfo) or
+// outbound-only (onwanttrailers) and do not expose the stream, so they
+// do not count as a consumer.
+if(typeofthis[kStreamCallbacks]?.onheaders!=='function')returnfalse;
+returngetQuicSessionState(this).streamCallbacksSupported===1;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4141,10 +4159,13 @@ class QuicSession {
 // Set the default byte budget for received streams.
 stream.budget=kDefaultBudget;
 
-// A new stream was received. If we don't have an onstream callback, then
-// there's nothing we can do about it. Destroy the stream in this case.
-if(typeofinner.onstream!=='function'){
-process.emitWarning('A new stream was received but no onstream callback was provided');
+// A new stream was received. If the session has no consumer for it -
+// neither an onstream callback nor, on a session whose application
+// supports headers (e.g. HTTP/3), any session-level stream callbacks -
+// there's nothing that could ever read it. Destroy the stream in this
+// case rather than letting it hold flow control credit.
+if(!this.#hasStreamConsumer()){
+process.emitWarning('A new stream was received but no stream consumer callback was provided');
 stream.destroy();
 return;
 }
@@ -4175,7 +4196,14 @@ class QuicSession {
 });
 }
 
-safeCallbackInvoke(inner.onstream,this,stream);
+// Deliver the stream to the onstream consumer if one is registered.
+// Reaching this point without one means #hasStreamConsumer accepted
+// the stream on behalf of the application layer: the session-level
+// stream callbacks were applied above and the application (e.g.
+// HTTP/3) drives the stream, so there is nothing to invoke here.
+if(typeofinner.onstream==='function'){
+safeCallbackInvoke(inner.onstream,this,stream);
+}
 }
 
 [kRemoveStream](stream){

lib/internal/quic/state.js

@@ -72,6 +72,7 @@ const {
 IDX_STATE_SESSION_STREAM_OPEN_ALLOWED,
 IDX_STATE_SESSION_PRIORITY_SUPPORTED,
 IDX_STATE_SESSION_HEADERS_SUPPORTED,
+IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED,
 IDX_STATE_SESSION_WRAPPED,
 IDX_STATE_SESSION_APPLICATION_TYPE,
 IDX_STATE_SESSION_NO_ERROR_CODE,
@@ -119,6 +120,7 @@ assert(IDX_STATE_SESSION_HANDSHAKE_CONFIRMED !== undefined);
 assert(IDX_STATE_SESSION_STREAM_OPEN_ALLOWED!==undefined);
 assert(IDX_STATE_SESSION_PRIORITY_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_HEADERS_SUPPORTED!==undefined);
+assert(IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_WRAPPED!==undefined);
 assert(IDX_STATE_SESSION_APPLICATION_TYPE!==undefined);
 assert(IDX_STATE_SESSION_NO_ERROR_CODE!==undefined);
@@ -493,6 +495,19 @@ class QuicSessionState {
 returnDataViewPrototypeGetUint8(handle,this.#offset +IDX_STATE_SESSION_HEADERS_SUPPORTED);
 }
 
+/**
+ * Whether the negotiated application dispatches the session-level
+ * stream callbacks (onheaders et al) for incoming streams.
+ * Returns 0 (unknown), 1 (supported), or 2 (not supported).
+ * @type {number}
+ */
+getstreamCallbacksSupported(){
+consthandle=this.#handle;
+if(handle===undefined)returnundefined;
+returnDataViewPrototypeGetUint8(
+handle,this.#offset +IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED);
+}
+
 /** @type {boolean} */
 getisWrapped(){
 consthandle=this.#handle;

src/quic/application.h

@@ -210,6 +210,11 @@ class Session::Application : public MemoryRetainer {
 // do not support headers should return false (the default).
 virtualboolSupportsHeaders() const { returnfalse; }
 
+// True if this application dispatches the session-level stream
+// callbacks (onheaders et al) for incoming streams when they are
+// registered on the session.
+virtualboolSupportsStreamCallbacks() const { returnfalse; }
+
 // Initiates application-level graceful shutdown signaling (e.g.,
 // HTTP/3 GOAWAY). Called when Session::Close(GRACEFUL) is invoked.
 virtualvoidBeginShutdown() {}

src/quic/defs.h

@@ -328,6 +328,12 @@ enum class HeadersSupportState : uint8_t {
 UNSUPPORTED,
 };
 
+enumclassStreamCallbacksSupportState : uint8_t {
+UNKNOWN,
+SUPPORTED,
+UNSUPPORTED,
+};
+
 enumclassPathValidationResult : uint8_t {
 SUCCESS = NGTCP2_PATH_VALIDATION_RESULT_SUCCESS,
 FAILURE = NGTCP2_PATH_VALIDATION_RESULT_FAILURE,

src/quic/http3.cc

@@ -202,6 +202,8 @@ class Http3ApplicationImpl final : public Session::Application {
 
 boolSupportsHeaders() constoverride { returntrue; }
 
+boolSupportsStreamCallbacks() constoverride { returntrue; }
+
 boolis_started() constoverride { return started_; }
 
 boolStart() override {

src/quic/session.cc

@@ -136,6 +136,7 @@ uint64_t MaxDatagramPayload(uint64_t max_frame_size) {
 V(STREAM_OPEN_ALLOWED, stream_open_allowed, uint8_t) \
 V(PRIORITY_SUPPORTED, priority_supported, uint8_t) \
 V(HEADERS_SUPPORTED, headers_supported, uint8_t) \
+V(STREAM_CALLBACKS_SUPPORTED, stream_callbacks_supported, uint8_t) \
 V(WRAPPED, wrapped, uint8_t) \
 V(APPLICATION_TYPE, application_type, uint8_t) \
 V(NO_ERROR_CODE, no_error_code, error_code) \
@@ -2649,6 +2650,10 @@ void Session::SetApplication(std::unique_ptr<Application> app) {
  impl_->state()->headers_supported = static_cast<uint8_t>(
  app->SupportsHeaders() ? HeadersSupportState::SUPPORTED
  : HeadersSupportState::UNSUPPORTED);
+ impl_->state()->stream_callbacks_supported =
+static_cast<uint8_t>(app->SupportsStreamCallbacks()
+ ? StreamCallbacksSupportState::SUPPORTED
+ : StreamCallbacksSupportState::UNSUPPORTED);
 // Surface the application's "no error" and "internal error" codes via
 // session state so that JS-side code (e.g. the stream writer's fail()
 // path) can resolve the right wire code for the negotiated ALPN

doc/api/quic.md

@@ -305,7 +305,11 @@ unidirectional (data flows in only one direction). The `quic` module provides
 separate APIs for creating each kind:
 [`session.createBidirectionalStream()`][] and
 [`session.createUnidirectionalStream()`][]. Streams initiated by a remote
-peer are delivered via the [`session.onstream`][] callback.
+peer are delivered via the [`session.onstream`][] callback. When the
+negotiated application protocol supports the stream-level callbacks (e.g.
+HTTP/3) and an `onheaders` callback is configured, incoming streams can
+instead be consumed entirely through it and registering `onstream` is
+optional.
 
 There are two ways to write data to a stream:
 
@@ -409,7 +413,9 @@ A typical client session progresses through these stages:
 
 On the server side, call [`quic.listen()`][] with a callback. The callback
 fires for each incoming session after the TLS handshake begins. Incoming
-streams arrive via the [`session.onstream`][] callback.
+streams arrive via the [`session.onstream`][] callback, or, for HTTP/3
+sessions with an `onheaders` callback configured, directly through that
+callback (see the [minimal HTTP/3 server][] example).
 
 [`session.destroy()`][] is available for immediate teardown — all open streams
 are destroyed and the session is closed without waiting for them to finish.
@@ -1108,6 +1114,15 @@ added: v23.8.0
 
 The callback to invoke when a new stream is initiated by a remote peer. Read/write.
 
+If no `onstream` callback is set and the stream has no other consumer, an
+incoming stream is destroyed on arrival and a warning is emitted. An
+`onheaders` callback counts as a consumer when the negotiated application
+protocol supports it (e.g. HTTP/3), because it is invoked for every incoming
+request stream. Other stream-level callbacks (`ontrailers`, `oninfo`,
+`onwanttrailers`) do not, since they are conditional or outbound-only and
+would leave the stream unobservable. An HTTP/3 server that handles requests
+entirely through `onheaders` does not need to set `onstream`.
+
 ### `session.ondatagram`
 
 <!-- YAML
@@ -3998,7 +4013,9 @@ import { listen } from 'node:quic';
 constencoder=newTextEncoder();
 
 constendpoint=awaitlisten((session) => {
-// The session.onstream callback fires for each new client-initiated stream.
+// The session.onstream callback fires for each new client-initiated
+// stream. It is optional here: with `onheaders` configured below,
+// request streams are consumed through that callback.
 }, {
  sni: { '*': { keys: [defaultKey], certs: [defaultCert] } },
 // ALPN defaults to 'h3'.
@@ -4632,5 +4649,6 @@ throughput issues caused by flow control.
 [`stream.writer`]: #streamwriter
 [`writer.fail()`]: #streamwriter
 [`writer.fail(reason)`]: #streamwriter
+[minimal HTTP/3 server]: #minimal-http3-server
 [qlog]: https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/
 [qvis]: https://qvis.quictools.info/

lib/internal/quic/quic.js

@@ -4129,6 +4129,24 @@ class QuicSession {
 this.#inner.verifyPeer=value;
 }
 
+/**
+ * True if an incoming stream has a consumer registered on this session:
+ * either an onstream callback, or - when the negotiated application
+ * supports headers (e.g. HTTP/3) - session-level stream callbacks that
+ * the application layer will invoke (onheaders et al).
+ * @returns {boolean}
+ */
+ #hasStreamConsumer(){
+if(typeofthis.#inner.onstream==='function')returntrue;
+// Only onheaders is guaranteed to fire for every incoming stream when
+// the negotiated application supports stream callbacks (e.g. HTTP/3).
+// Other stream callbacks are conditional (ontrailers, oninfo) or
+// outbound-only (onwanttrailers) and do not expose the stream, so they
+// do not count as a consumer.
+if(typeofthis[kStreamCallbacks]?.onheaders!=='function')returnfalse;
+returngetQuicSessionState(this).streamCallbacksSupported===1;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4141,10 +4159,13 @@ class QuicSession {
 // Set the default byte budget for received streams.
 stream.budget=kDefaultBudget;
 
-// A new stream was received. If we don't have an onstream callback, then
-// there's nothing we can do about it. Destroy the stream in this case.
-if(typeofinner.onstream!=='function'){
-process.emitWarning('A new stream was received but no onstream callback was provided');
+// A new stream was received. If the session has no consumer for it -
+// neither an onstream callback nor, on a session whose application
+// supports headers (e.g. HTTP/3), any session-level stream callbacks -
+// there's nothing that could ever read it. Destroy the stream in this
+// case rather than letting it hold flow control credit.
+if(!this.#hasStreamConsumer()){
+process.emitWarning('A new stream was received but no stream consumer callback was provided');
 stream.destroy();
 return;
 }
@@ -4175,7 +4196,14 @@ class QuicSession {
 });
 }
 
-safeCallbackInvoke(inner.onstream,this,stream);
+// Deliver the stream to the onstream consumer if one is registered.
+// Reaching this point without one means #hasStreamConsumer accepted
+// the stream on behalf of the application layer: the session-level
+// stream callbacks were applied above and the application (e.g.
+// HTTP/3) drives the stream, so there is nothing to invoke here.
+if(typeofinner.onstream==='function'){
+safeCallbackInvoke(inner.onstream,this,stream);
+}
 }
 
 [kRemoveStream](stream){

lib/internal/quic/state.js

@@ -72,6 +72,7 @@ const {
 IDX_STATE_SESSION_STREAM_OPEN_ALLOWED,
 IDX_STATE_SESSION_PRIORITY_SUPPORTED,
 IDX_STATE_SESSION_HEADERS_SUPPORTED,
+IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED,
 IDX_STATE_SESSION_WRAPPED,
 IDX_STATE_SESSION_APPLICATION_TYPE,
 IDX_STATE_SESSION_NO_ERROR_CODE,
@@ -119,6 +120,7 @@ assert(IDX_STATE_SESSION_HANDSHAKE_CONFIRMED !== undefined);
 assert(IDX_STATE_SESSION_STREAM_OPEN_ALLOWED!==undefined);
 assert(IDX_STATE_SESSION_PRIORITY_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_HEADERS_SUPPORTED!==undefined);
+assert(IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_WRAPPED!==undefined);
 assert(IDX_STATE_SESSION_APPLICATION_TYPE!==undefined);
 assert(IDX_STATE_SESSION_NO_ERROR_CODE!==undefined);
@@ -493,6 +495,19 @@ class QuicSessionState {
 returnDataViewPrototypeGetUint8(handle,this.#offset +IDX_STATE_SESSION_HEADERS_SUPPORTED);
 }
 
+/**
+ * Whether the negotiated application dispatches the session-level
+ * stream callbacks (onheaders et al) for incoming streams.
+ * Returns 0 (unknown), 1 (supported), or 2 (not supported).
+ * @type {number}
+ */
+getstreamCallbacksSupported(){
+consthandle=this.#handle;
+if(handle===undefined)returnundefined;
+returnDataViewPrototypeGetUint8(
+handle,this.#offset +IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED);
+}
+
 /** @type {boolean} */
 getisWrapped(){
 consthandle=this.#handle;

src/quic/application.h

@@ -210,6 +210,11 @@ class Session::Application : public MemoryRetainer {
 // do not support headers should return false (the default).
 virtualboolSupportsHeaders() const { returnfalse; }
 
+// True if this application dispatches the session-level stream
+// callbacks (onheaders et al) for incoming streams when they are
+// registered on the session.
+virtualboolSupportsStreamCallbacks() const { returnfalse; }
+
 // Initiates application-level graceful shutdown signaling (e.g.,
 // HTTP/3 GOAWAY). Called when Session::Close(GRACEFUL) is invoked.
 virtualvoidBeginShutdown() {}

src/quic/defs.h

@@ -328,6 +328,12 @@ enum class HeadersSupportState : uint8_t {
 UNSUPPORTED,
 };
 
+enumclassStreamCallbacksSupportState : uint8_t {
+UNKNOWN,
+SUPPORTED,
+UNSUPPORTED,
+};
+
 enumclassPathValidationResult : uint8_t {
 SUCCESS = NGTCP2_PATH_VALIDATION_RESULT_SUCCESS,
 FAILURE = NGTCP2_PATH_VALIDATION_RESULT_FAILURE,

src/quic/http3.cc

@@ -202,6 +202,8 @@ class Http3ApplicationImpl final : public Session::Application {
 
 boolSupportsHeaders() constoverride { returntrue; }
 
+boolSupportsStreamCallbacks() constoverride { returntrue; }
+
 boolis_started() constoverride { return started_; }
 
 boolStart() override {

src/quic/session.cc

@@ -136,6 +136,7 @@ uint64_t MaxDatagramPayload(uint64_t max_frame_size) {
 V(STREAM_OPEN_ALLOWED, stream_open_allowed, uint8_t) \
 V(PRIORITY_SUPPORTED, priority_supported, uint8_t) \
 V(HEADERS_SUPPORTED, headers_supported, uint8_t) \
+V(STREAM_CALLBACKS_SUPPORTED, stream_callbacks_supported, uint8_t) \
 V(WRAPPED, wrapped, uint8_t) \
 V(APPLICATION_TYPE, application_type, uint8_t) \
 V(NO_ERROR_CODE, no_error_code, error_code) \
@@ -2649,6 +2650,10 @@ void Session::SetApplication(std::unique_ptr<Application> app) {
  impl_->state()->headers_supported = static_cast<uint8_t>(
  app->SupportsHeaders() ? HeadersSupportState::SUPPORTED
  : HeadersSupportState::UNSUPPORTED);
+ impl_->state()->stream_callbacks_supported =
+static_cast<uint8_t>(app->SupportsStreamCallbacks()
+ ? StreamCallbacksSupportState::SUPPORTED
+ : StreamCallbacksSupportState::UNSUPPORTED);
 // Surface the application's "no error" and "internal error" codes via
 // session state so that JS-side code (e.g. the stream writer's fail()
 // path) can resolve the right wire code for the negotiated ALPN

doc/api/quic.md

@@ -305,7 +305,11 @@ unidirectional (data flows in only one direction). The `quic` module provides
 separate APIs for creating each kind:
 [`session.createBidirectionalStream()`][] and
 [`session.createUnidirectionalStream()`][]. Streams initiated by a remote
-peer are delivered via the [`session.onstream`][] callback.
+peer are delivered via the [`session.onstream`][] callback. When the
+negotiated application protocol supports the stream-level callbacks (e.g.
+HTTP/3) and an `onheaders` callback is configured, incoming streams can
+instead be consumed entirely through it and registering `onstream` is
+optional.
 
 There are two ways to write data to a stream:
 
@@ -409,7 +413,9 @@ A typical client session progresses through these stages:
 
 On the server side, call [`quic.listen()`][] with a callback. The callback
 fires for each incoming session after the TLS handshake begins. Incoming
-streams arrive via the [`session.onstream`][] callback.
+streams arrive via the [`session.onstream`][] callback, or, for HTTP/3
+sessions with an `onheaders` callback configured, directly through that
+callback (see the [minimal HTTP/3 server][] example).
 
 [`session.destroy()`][] is available for immediate teardown — all open streams
 are destroyed and the session is closed without waiting for them to finish.
@@ -1108,6 +1114,15 @@ added: v23.8.0
 
 The callback to invoke when a new stream is initiated by a remote peer. Read/write.
 
+If no `onstream` callback is set and the stream has no other consumer, an
+incoming stream is destroyed on arrival and a warning is emitted. An
+`onheaders` callback counts as a consumer when the negotiated application
+protocol supports it (e.g. HTTP/3), because it is invoked for every incoming
+request stream. Other stream-level callbacks (`ontrailers`, `oninfo`,
+`onwanttrailers`) do not, since they are conditional or outbound-only and
+would leave the stream unobservable. An HTTP/3 server that handles requests
+entirely through `onheaders` does not need to set `onstream`.
+
 ### `session.ondatagram`
 
 <!-- YAML
@@ -3998,7 +4013,9 @@ import { listen } from 'node:quic';
 constencoder=newTextEncoder();
 
 constendpoint=awaitlisten((session) => {
-// The session.onstream callback fires for each new client-initiated stream.
+// The session.onstream callback fires for each new client-initiated
+// stream. It is optional here: with `onheaders` configured below,
+// request streams are consumed through that callback.
 }, {
  sni: { '*': { keys: [defaultKey], certs: [defaultCert] } },
 // ALPN defaults to 'h3'.
@@ -4632,5 +4649,6 @@ throughput issues caused by flow control.
 [`stream.writer`]: #streamwriter
 [`writer.fail()`]: #streamwriter
 [`writer.fail(reason)`]: #streamwriter
+[minimal HTTP/3 server]: #minimal-http3-server
 [qlog]: https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/
 [qvis]: https://qvis.quictools.info/

lib/internal/quic/quic.js

@@ -4129,6 +4129,24 @@ class QuicSession {
 this.#inner.verifyPeer=value;
 }
 
+/**
+ * True if an incoming stream has a consumer registered on this session:
+ * either an onstream callback, or - when the negotiated application
+ * supports headers (e.g. HTTP/3) - session-level stream callbacks that
+ * the application layer will invoke (onheaders et al).
+ * @returns {boolean}
+ */
+ #hasStreamConsumer(){
+if(typeofthis.#inner.onstream==='function')returntrue;
+// Only onheaders is guaranteed to fire for every incoming stream when
+// the negotiated application supports stream callbacks (e.g. HTTP/3).
+// Other stream callbacks are conditional (ontrailers, oninfo) or
+// outbound-only (onwanttrailers) and do not expose the stream, so they
+// do not count as a consumer.
+if(typeofthis[kStreamCallbacks]?.onheaders!=='function')returnfalse;
+returngetQuicSessionState(this).streamCallbacksSupported===1;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4141,10 +4159,13 @@ class QuicSession {
 // Set the default byte budget for received streams.
 stream.budget=kDefaultBudget;
 
-// A new stream was received. If we don't have an onstream callback, then
-// there's nothing we can do about it. Destroy the stream in this case.
-if(typeofinner.onstream!=='function'){
-process.emitWarning('A new stream was received but no onstream callback was provided');
+// A new stream was received. If the session has no consumer for it -
+// neither an onstream callback nor, on a session whose application
+// supports headers (e.g. HTTP/3), any session-level stream callbacks -
+// there's nothing that could ever read it. Destroy the stream in this
+// case rather than letting it hold flow control credit.
+if(!this.#hasStreamConsumer()){
+process.emitWarning('A new stream was received but no stream consumer callback was provided');
 stream.destroy();
 return;
 }
@@ -4175,7 +4196,14 @@ class QuicSession {
 });
 }
 
-safeCallbackInvoke(inner.onstream,this,stream);
+// Deliver the stream to the onstream consumer if one is registered.
+// Reaching this point without one means #hasStreamConsumer accepted
+// the stream on behalf of the application layer: the session-level
+// stream callbacks were applied above and the application (e.g.
+// HTTP/3) drives the stream, so there is nothing to invoke here.
+if(typeofinner.onstream==='function'){
+safeCallbackInvoke(inner.onstream,this,stream);
+}
 }
 
 [kRemoveStream](stream){

lib/internal/quic/state.js

@@ -72,6 +72,7 @@ const {
 IDX_STATE_SESSION_STREAM_OPEN_ALLOWED,
 IDX_STATE_SESSION_PRIORITY_SUPPORTED,
 IDX_STATE_SESSION_HEADERS_SUPPORTED,
+IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED,
 IDX_STATE_SESSION_WRAPPED,
 IDX_STATE_SESSION_APPLICATION_TYPE,
 IDX_STATE_SESSION_NO_ERROR_CODE,
@@ -119,6 +120,7 @@ assert(IDX_STATE_SESSION_HANDSHAKE_CONFIRMED !== undefined);
 assert(IDX_STATE_SESSION_STREAM_OPEN_ALLOWED!==undefined);
 assert(IDX_STATE_SESSION_PRIORITY_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_HEADERS_SUPPORTED!==undefined);
+assert(IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_WRAPPED!==undefined);
 assert(IDX_STATE_SESSION_APPLICATION_TYPE!==undefined);
 assert(IDX_STATE_SESSION_NO_ERROR_CODE!==undefined);
@@ -493,6 +495,19 @@ class QuicSessionState {
 returnDataViewPrototypeGetUint8(handle,this.#offset +IDX_STATE_SESSION_HEADERS_SUPPORTED);
 }
 
+/**
+ * Whether the negotiated application dispatches the session-level
+ * stream callbacks (onheaders et al) for incoming streams.
+ * Returns 0 (unknown), 1 (supported), or 2 (not supported).
+ * @type {number}
+ */
+getstreamCallbacksSupported(){
+consthandle=this.#handle;
+if(handle===undefined)returnundefined;
+returnDataViewPrototypeGetUint8(
+handle,this.#offset +IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED);
+}
+
 /** @type {boolean} */
 getisWrapped(){
 consthandle=this.#handle;

src/quic/application.h

@@ -210,6 +210,11 @@ class Session::Application : public MemoryRetainer {
 // do not support headers should return false (the default).
 virtualboolSupportsHeaders() const { returnfalse; }
 
+// True if this application dispatches the session-level stream
+// callbacks (onheaders et al) for incoming streams when they are
+// registered on the session.
+virtualboolSupportsStreamCallbacks() const { returnfalse; }
+
 // Initiates application-level graceful shutdown signaling (e.g.,
 // HTTP/3 GOAWAY). Called when Session::Close(GRACEFUL) is invoked.
 virtualvoidBeginShutdown() {}

src/quic/defs.h

@@ -328,6 +328,12 @@ enum class HeadersSupportState : uint8_t {
 UNSUPPORTED,
 };
 
+enumclassStreamCallbacksSupportState : uint8_t {
+UNKNOWN,
+SUPPORTED,
+UNSUPPORTED,
+};
+
 enumclassPathValidationResult : uint8_t {
 SUCCESS = NGTCP2_PATH_VALIDATION_RESULT_SUCCESS,
 FAILURE = NGTCP2_PATH_VALIDATION_RESULT_FAILURE,

src/quic/http3.cc

@@ -202,6 +202,8 @@ class Http3ApplicationImpl final : public Session::Application {
 
 boolSupportsHeaders() constoverride { returntrue; }
 
+boolSupportsStreamCallbacks() constoverride { returntrue; }
+
 boolis_started() constoverride { return started_; }
 
 boolStart() override {

src/quic/session.cc

@@ -136,6 +136,7 @@ uint64_t MaxDatagramPayload(uint64_t max_frame_size) {
 V(STREAM_OPEN_ALLOWED, stream_open_allowed, uint8_t) \
 V(PRIORITY_SUPPORTED, priority_supported, uint8_t) \
 V(HEADERS_SUPPORTED, headers_supported, uint8_t) \
+V(STREAM_CALLBACKS_SUPPORTED, stream_callbacks_supported, uint8_t) \
 V(WRAPPED, wrapped, uint8_t) \
 V(APPLICATION_TYPE, application_type, uint8_t) \
 V(NO_ERROR_CODE, no_error_code, error_code) \
@@ -2649,6 +2650,10 @@ void Session::SetApplication(std::unique_ptr<Application> app) {
  impl_->state()->headers_supported = static_cast<uint8_t>(
  app->SupportsHeaders() ? HeadersSupportState::SUPPORTED
  : HeadersSupportState::UNSUPPORTED);
+ impl_->state()->stream_callbacks_supported =
+static_cast<uint8_t>(app->SupportsStreamCallbacks()
+ ? StreamCallbacksSupportState::SUPPORTED
+ : StreamCallbacksSupportState::UNSUPPORTED);
 // Surface the application's "no error" and "internal error" codes via
 // session state so that JS-side code (e.g. the stream writer's fail()
 // path) can resolve the right wire code for the negotiated ALPN

doc/api/quic.md

@@ -305,7 +305,11 @@ unidirectional (data flows in only one direction). The `quic` module provides
 separate APIs for creating each kind:
 [`session.createBidirectionalStream()`][] and
 [`session.createUnidirectionalStream()`][]. Streams initiated by a remote
-peer are delivered via the [`session.onstream`][] callback.
+peer are delivered via the [`session.onstream`][] callback. When the
+negotiated application protocol supports the stream-level callbacks (e.g.
+HTTP/3) and an `onheaders` callback is configured, incoming streams can
+instead be consumed entirely through it and registering `onstream` is
+optional.
 
 There are two ways to write data to a stream:
 
@@ -409,7 +413,9 @@ A typical client session progresses through these stages:
 
 On the server side, call [`quic.listen()`][] with a callback. The callback
 fires for each incoming session after the TLS handshake begins. Incoming
-streams arrive via the [`session.onstream`][] callback.
+streams arrive via the [`session.onstream`][] callback, or, for HTTP/3
+sessions with an `onheaders` callback configured, directly through that
+callback (see the [minimal HTTP/3 server][] example).
 
 [`session.destroy()`][] is available for immediate teardown — all open streams
 are destroyed and the session is closed without waiting for them to finish.
@@ -1108,6 +1114,15 @@ added: v23.8.0
 
 The callback to invoke when a new stream is initiated by a remote peer. Read/write.
 
+If no `onstream` callback is set and the stream has no other consumer, an
+incoming stream is destroyed on arrival and a warning is emitted. An
+`onheaders` callback counts as a consumer when the negotiated application
+protocol supports it (e.g. HTTP/3), because it is invoked for every incoming
+request stream. Other stream-level callbacks (`ontrailers`, `oninfo`,
+`onwanttrailers`) do not, since they are conditional or outbound-only and
+would leave the stream unobservable. An HTTP/3 server that handles requests
+entirely through `onheaders` does not need to set `onstream`.
+
 ### `session.ondatagram`
 
 <!-- YAML
@@ -3998,7 +4013,9 @@ import { listen } from 'node:quic';
 constencoder=newTextEncoder();
 
 constendpoint=awaitlisten((session) => {
-// The session.onstream callback fires for each new client-initiated stream.
+// The session.onstream callback fires for each new client-initiated
+// stream. It is optional here: with `onheaders` configured below,
+// request streams are consumed through that callback.
 }, {
  sni: { '*': { keys: [defaultKey], certs: [defaultCert] } },
 // ALPN defaults to 'h3'.
@@ -4632,5 +4649,6 @@ throughput issues caused by flow control.
 [`stream.writer`]: #streamwriter
 [`writer.fail()`]: #streamwriter
 [`writer.fail(reason)`]: #streamwriter
+[minimal HTTP/3 server]: #minimal-http3-server
 [qlog]: https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/
 [qvis]: https://qvis.quictools.info/

lib/internal/quic/quic.js

@@ -4129,6 +4129,24 @@ class QuicSession {
 this.#inner.verifyPeer=value;
 }
 
+/**
+ * True if an incoming stream has a consumer registered on this session:
+ * either an onstream callback, or - when the negotiated application
+ * supports headers (e.g. HTTP/3) - session-level stream callbacks that
+ * the application layer will invoke (onheaders et al).
+ * @returns {boolean}
+ */
+ #hasStreamConsumer(){
+if(typeofthis.#inner.onstream==='function')returntrue;
+// Only onheaders is guaranteed to fire for every incoming stream when
+// the negotiated application supports stream callbacks (e.g. HTTP/3).
+// Other stream callbacks are conditional (ontrailers, oninfo) or
+// outbound-only (onwanttrailers) and do not expose the stream, so they
+// do not count as a consumer.
+if(typeofthis[kStreamCallbacks]?.onheaders!=='function')returnfalse;
+returngetQuicSessionState(this).streamCallbacksSupported===1;
+}
+
 /**
  * @param {object} handle
  * @param {number} direction
@@ -4141,10 +4159,13 @@ class QuicSession {
 // Set the default byte budget for received streams.
 stream.budget=kDefaultBudget;
 
-// A new stream was received. If we don't have an onstream callback, then
-// there's nothing we can do about it. Destroy the stream in this case.
-if(typeofinner.onstream!=='function'){
-process.emitWarning('A new stream was received but no onstream callback was provided');
+// A new stream was received. If the session has no consumer for it -
+// neither an onstream callback nor, on a session whose application
+// supports headers (e.g. HTTP/3), any session-level stream callbacks -
+// there's nothing that could ever read it. Destroy the stream in this
+// case rather than letting it hold flow control credit.
+if(!this.#hasStreamConsumer()){
+process.emitWarning('A new stream was received but no stream consumer callback was provided');
 stream.destroy();
 return;
 }
@@ -4175,7 +4196,14 @@ class QuicSession {
 });
 }
 
-safeCallbackInvoke(inner.onstream,this,stream);
+// Deliver the stream to the onstream consumer if one is registered.
+// Reaching this point without one means #hasStreamConsumer accepted
+// the stream on behalf of the application layer: the session-level
+// stream callbacks were applied above and the application (e.g.
+// HTTP/3) drives the stream, so there is nothing to invoke here.
+if(typeofinner.onstream==='function'){
+safeCallbackInvoke(inner.onstream,this,stream);
+}
 }
 
 [kRemoveStream](stream){

lib/internal/quic/state.js

@@ -72,6 +72,7 @@ const {
 IDX_STATE_SESSION_STREAM_OPEN_ALLOWED,
 IDX_STATE_SESSION_PRIORITY_SUPPORTED,
 IDX_STATE_SESSION_HEADERS_SUPPORTED,
+IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED,
 IDX_STATE_SESSION_WRAPPED,
 IDX_STATE_SESSION_APPLICATION_TYPE,
 IDX_STATE_SESSION_NO_ERROR_CODE,
@@ -119,6 +120,7 @@ assert(IDX_STATE_SESSION_HANDSHAKE_CONFIRMED !== undefined);
 assert(IDX_STATE_SESSION_STREAM_OPEN_ALLOWED!==undefined);
 assert(IDX_STATE_SESSION_PRIORITY_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_HEADERS_SUPPORTED!==undefined);
+assert(IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED!==undefined);
 assert(IDX_STATE_SESSION_WRAPPED!==undefined);
 assert(IDX_STATE_SESSION_APPLICATION_TYPE!==undefined);
 assert(IDX_STATE_SESSION_NO_ERROR_CODE!==undefined);
@@ -493,6 +495,19 @@ class QuicSessionState {
 returnDataViewPrototypeGetUint8(handle,this.#offset +IDX_STATE_SESSION_HEADERS_SUPPORTED);
 }
 
+/**
+ * Whether the negotiated application dispatches the session-level
+ * stream callbacks (onheaders et al) for incoming streams.
+ * Returns 0 (unknown), 1 (supported), or 2 (not supported).
+ * @type {number}
+ */
+getstreamCallbacksSupported(){
+consthandle=this.#handle;
+if(handle===undefined)returnundefined;
+returnDataViewPrototypeGetUint8(
+handle,this.#offset +IDX_STATE_SESSION_STREAM_CALLBACKS_SUPPORTED);
+}
+
 /** @type {boolean} */
 getisWrapped(){
 consthandle=this.#handle;

src/quic/application.h

@@ -210,6 +210,11 @@ class Session::Application : public MemoryRetainer {
 // do not support headers should return false (the default).
 virtualboolSupportsHeaders() const { returnfalse; }
 
+// True if this application dispatches the session-level stream
+// callbacks (onheaders et al) for incoming streams when they are
+// registered on the session.
+virtualboolSupportsStreamCallbacks() const { returnfalse; }
+
 // Initiates application-level graceful shutdown signaling (e.g.,
 // HTTP/3 GOAWAY). Called when Session::Close(GRACEFUL) is invoked.
 virtualvoidBeginShutdown() {}

src/quic/defs.h

@@ -328,6 +328,12 @@ enum class HeadersSupportState : uint8_t {
 UNSUPPORTED,
 };
 
+enumclassStreamCallbacksSupportState : uint8_t {
+UNKNOWN,
+SUPPORTED,
+UNSUPPORTED,
+};
+
 enumclassPathValidationResult : uint8_t {
 SUCCESS = NGTCP2_PATH_VALIDATION_RESULT_SUCCESS,
 FAILURE = NGTCP2_PATH_VALIDATION_RESULT_FAILURE,

src/quic/http3.cc

@@ -202,6 +202,8 @@ class Http3ApplicationImpl final : public Session::Application {
 
 boolSupportsHeaders() constoverride { returntrue; }
 
+boolSupportsStreamCallbacks() constoverride { returntrue; }
+
 boolis_started() constoverride { return started_; }
 
 boolStart() override {

src/quic/session.cc

@@ -136,6 +136,7 @@ uint64_t MaxDatagramPayload(uint64_t max_frame_size) {
 V(STREAM_OPEN_ALLOWED, stream_open_allowed, uint8_t) \
 V(PRIORITY_SUPPORTED, priority_supported, uint8_t) \
 V(HEADERS_SUPPORTED, headers_supported, uint8_t) \
+V(STREAM_CALLBACKS_SUPPORTED, stream_callbacks_supported, uint8_t) \
 V(WRAPPED, wrapped, uint8_t) \
 V(APPLICATION_TYPE, application_type, uint8_t) \
 V(NO_ERROR_CODE, no_error_code, error_code) \
@@ -2649,6 +2650,10 @@ void Session::SetApplication(std::unique_ptr<Application> app) {
  impl_->state()->headers_supported = static_cast<uint8_t>(
  app->SupportsHeaders() ? HeadersSupportState::SUPPORTED
  : HeadersSupportState::UNSUPPORTED);
+ impl_->state()->stream_callbacks_supported =
+static_cast<uint8_t>(app->SupportsStreamCallbacks()
+ ? StreamCallbacksSupportState::SUPPORTED
+ : StreamCallbacksSupportState::UNSUPPORTED);
 // Surface the application's "no error" and "internal error" codes via
 // session state so that JS-side code (e.g. the stream writer's fail()
 // path) can resolve the right wire code for the negotiated ALPN