diff --git a/doc/api/quic.md b/doc/api/quic.md index 7a52e4f72c1f..d40827f57e32 100644 --- a/doc/api/quic.md +++ b/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. @@ -1110,6 +1116,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`