quic: impl. cb for http/3 settings/app. options

Implements a callback that is invoked once http/3
settings are received.
Background, http/3 settings usually arrive a bit
later than connection establishment, and e.g. for
webtransport these settings are used to indicate
support. So e.g. the examples for quiche from
 google, wait for the settings to arrive.
 (This is different to http/2).
The implemented callback mechanism allows to wait
for the settings to arrive until connection
attempts are made. As settings are stored in the
generic applications option object, the callback's
 name refers to the application rather than the
 settings. Whether this is a good choice is
 debatable.

Fixes: #63553
Signed-off-by: Marten Richter <marten.richter@freenet.de>

Author: martenrichter

doc/api/quic.md

@@ -887,6 +887,16 @@ added: v23.8.0
 The endpoint that created this session. Returns `null` if the session
 has been destroyed. Read only.
 
+### `session.onappliation`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {quic.OnApplicationCallback}
+
+The callback to invoke when new application options, e.g. HTTP/3 settings arrived.
+
 ### `session.onerror`
 
 <!-- YAML
@@ -3200,11 +3210,11 @@ with that error:
 
 * Stream callbacks (`onblocked`, `onreset`, `onheaders`, `ontrailers`,
   `oninfo`, `onwanttrailers`): the stream is destroyed.
-* Session callbacks (`onstream`, `ondatagram`, `ondatagramstatus`,
-  `onpathvalidation`, `onsessionticket`, `onnewtoken`,
-  `onversionnegotiation`, `onorigin`, `ongoaway`, `onhandshake`,
-  `onkeylog`, `onqlog`): the session is destroyed along with all of its
-  streams.
+* Session callbacks (`onapplication`, `onstream`, `ondatagram`,
+  `ondatagramstatus`, `onpathvalidation`, `onsessionticket`,
+  `onnewtoken`, `onversionnegotiation`, `onorigin`, `ongoaway`, 
+  `onhandshake`, `onkeylog`, `onqlog`): the session is destroyed along
+  with all of its streams.
 
 Before destruction, the optional [`session.onerror`][] or
 [`stream.onerror`][] callback is invoked (if set), giving the application a
@@ -3732,6 +3742,18 @@ added: v23.8.0
 
 Published when an endpoint's busy state changes.
 
+### Channel: `quic.session.application`
+
+<!-- YAML
+added: v23.8.0
+-->
+
+* `applicationoptions` {quic.ApplicationOptions} Current application options.
+* `session` {quic.QuicSession}
+
+Published when a locally-initiated stream is opened.
+
+
 ### Channel: `quic.session.created.client`
 
 <!-- YAML
@@ -4099,6 +4121,7 @@ throughput issues caused by flow control.
 [`session.createUnidirectionalStream()`]: #sessioncreateunidirectionalstreamoptions
 [`session.destroy()`]: #sessiondestroyerror-options
 [`session.maxPendingDatagrams`]: #sessionmaxpendingdatagrams
+[`session.onapplication`]: #sessiononapplication
 [`session.ondatagram`]: #sessionondatagram
 [`session.ondatagramstatus`]: #sessionondatagramstatus
 [`session.onearlyrejected`]: #sessiononearlyrejected

lib/internal/quic/diagnostics.js

@@ -14,6 +14,7 @@ const onEndpointErrorChannel = dc.channel('quic.endpoint.error');
 const onEndpointBusyChangeChannel = dc.channel('quic.endpoint.busy.change');
 const onEndpointClientSessionChannel = dc.channel('quic.session.created.client');
 const onEndpointServerSessionChannel = dc.channel('quic.session.created.server');
+const onSessionApplicationChannel = dc.channel('quic.session.application');
 const onSessionOpenStreamChannel = dc.channel('quic.session.open.stream');
 const onSessionReceivedStreamChannel = dc.channel('quic.session.received.stream');
 const onSessionSendDatagramChannel = dc.channel('quic.session.send.datagram');
@@ -48,6 +49,7 @@ module.exports = {
   onEndpointBusyChangeChannel,
   onEndpointClientSessionChannel,
   onEndpointServerSessionChannel,
+  onSessionApplicationChannel,
   onSessionOpenStreamChannel,
   onSessionReceivedStreamChannel,
   onSessionSendDatagramChannel,

lib/internal/quic/quic.js

@@ -199,6 +199,7 @@ const {
   kPrivateConstructor,
   kReset,
   kSendHeaders,
+  kSessionApplication,
   kSessionTicket,
   kTrailers,
   kVersionNegotiation,
@@ -247,6 +248,7 @@ const {
   onSessionReceiveDatagramStatusChannel,
   onSessionPathValidationChannel,
   onSessionNewTokenChannel,
+  onSessionApplicationChannel,
   onSessionTicketChannel,
   onSessionVersionNegotiationChannel,
   onSessionOriginChannel,
@@ -436,6 +438,7 @@ const endpointRegistry = new SafeSet();
  * @property {OnGoawayCallback} [ongoaway] GOAWAY frame callback.
  * @property {OnKeylogCallback} [onkeylog] TLS key-log callback.
  * @property {OnQlogCallback} [onqlog] qlog data callback.
+ * @property {OnApplicationCallback} [onapplication] application options callback.
  * @property {OnHeadersCallback} [onheaders] Default per-stream initial-headers callback.
  * @property {OnTrailersCallback} [ontrailers] Default per-stream trailing-headers callback.
  * @property {OnInfoCallback} [oninfo] Default per-stream informational-headers callback.
@@ -566,6 +569,13 @@ const endpointRegistry = new SafeSet();
  * @returns {void}
  */
 
+/**
+ * @callback OnApplicationCallback
+ * @this {QuicSession}
+ * @param {ApplicationOptions} applicationoptions
+ * @returns {void}
+ */
+
 /**
  * @callback OnSessionTicketCallback
  * @this {QuicSession}
@@ -643,6 +653,14 @@ const endpointRegistry = new SafeSet();
  * @returns {void}
  */
 
+/**
+ * Called when initial request or response headers are received.
+ * @callback OnApplicationCallback
+ * @this {QuicSession}
+ * @param {ApplicationOptions} applicationoptions ApplicationOptions object
+ * @returns {void}
+ */
+
 /**
  * @callback OnBlockedCallback
  * @this {QuicStream}
@@ -798,6 +816,16 @@ setCallbacks({
                                   preferredAddress);
   },
 
+  /**
+   * Called when the session's application object is updated
+   * E.g. http/3 session arrived.
+   * @param {ApplicationOptions} applicationoptions An application object
+   */
+  onSessionApplication(applicationoptions) {
+    debug('session application callback', this[kOwner]);
+    this[kOwner][kSessionApplication](applicationoptions);
+  },
+
   /**
    * Called when the session generates a new TLS session ticket
    * @param {object} ticket An opaque session ticket
@@ -1208,6 +1236,7 @@ function applyCallbacks(session, cbs) {
   if (cbs.ongoaway) session.ongoaway = cbs.ongoaway;
   if (cbs.onkeylog) session.onkeylog = cbs.onkeylog;
   if (cbs.onqlog) session.onqlog = cbs.onqlog;
+  if (cbs.onapplication) session.onapplication = cbs.application;
   if (cbs.onheaders || cbs.ontrailers || cbs.oninfo || cbs.onwanttrailers) {
     session[kStreamCallbacks] = {
       __proto__: null,
@@ -2896,6 +2925,25 @@ class QuicSession {
     }
   }
 
+  /** @type {Function|undefined} */
+  get onapplication() {
+    assertIsQuicSession(this);
+    return this.#inner.onapplication;
+  }
+
+  set onapplication(fn) {
+    assertIsQuicSession(this);
+    const inner = this.#inner;
+    if (fn === undefined) {
+      inner.onapplication = undefined;
+      inner.state.hasApplicationListener = false;
+    } else {
+      validateFunction(fn, 'onsessionticket');
+      inner.onapplication = FunctionPrototypeBind(fn, this);
+      inner.state.hasApplicationListener = true;
+    }
+  }
+
   /** @type {Function|undefined} */
   get onversionnegotiation() {
     assertIsQuicSession(this);
@@ -3483,6 +3531,7 @@ class QuicSession {
     inner.ondatagramstatus = undefined;
     inner.onpathvalidation = undefined;
     inner.onsessionticket = undefined;
+    inner.onapplication = undefined;
     inner.onkeylog = undefined;
     inner.onversionnegotiation = undefined;
     inner.onhandshake = undefined;
@@ -3704,6 +3753,23 @@ class QuicSession {
     safeCallbackInvoke(inner.onsessionticket, this, ticket);
   }
 
+  /**
+   * @param {ApplicationOptions} applicationoptions
+   */
+  [kSessionApplication](applicationoptions) {
+    if (this.destroyed) return;
+    if (onSessionApplicationChannel.hasSubscribers) {
+      onSessionApplicationChannel.publish({
+        __proto__: null,
+        applicationoptions,
+        session: this,
+      });
+    }
+    const inner = this.#inner;
+    if (typeof inner.onapplication === 'function')
+      safeCallbackInvoke(inner.onapplication, this, applicationoptions);
+  }
+
   /**
    * @param {Buffer} token
    * @param {SocketAddress} address
@@ -4222,6 +4288,7 @@ class QuicEndpoint {
       ongoaway,
       onkeylog,
       onqlog,
+      onapplication,
       // Stream-level callbacks applied to each incoming stream.
       onheaders,
       ontrailers,
@@ -4247,6 +4314,7 @@ class QuicEndpoint {
       ongoaway,
       onkeylog,
       onqlog,
+      onapplication,
       onheaders,
       ontrailers,
       oninfo,
@@ -4955,6 +5023,8 @@ function processSessionOptions(options, config = kEmptyObject) {
     ongoaway,
     onkeylog,
     onqlog,
+    onapplication,
+    // Application level options changed, e.g. HTTP/3 settings related
     // Stream-level callbacks.
     onheaders,
     ontrailers,
@@ -5060,6 +5130,7 @@ function processSessionOptions(options, config = kEmptyObject) {
     ongoaway,
     onkeylog,
     onqlog,
+    onapplication,
     onheaders,
     ontrailers,
     oninfo,

lib/internal/quic/symbols.js

@@ -54,6 +54,7 @@ const kRemoveSession = Symbol('kRemoveSession');
 const kRemoveStream = Symbol('kRemoveStream');
 const kReset = Symbol('kReset');
 const kSendHeaders = Symbol('kSendHeaders');
+const kSessionApplication = Symbol('kSessionApplication');
 const kSessionTicket = Symbol('kSessionTicket');
 const kTrailers = Symbol('kTrailers');
 const kVersionNegotiation = Symbol('kVersionNegotiation');
@@ -88,6 +89,7 @@ module.exports = {
   kRemoveStream,
   kReset,
   kSendHeaders,
+  kSessionApplication,
   kSessionTicket,
   kTrailers,
   kVersionNegotiation,

src/quic/bindingdata.h

@@ -41,6 +41,7 @@ class SessionManager;
 #define QUIC_JS_CALLBACKS(V)                                                   \
   V(endpoint_close, EndpointClose)                                             \
   V(session_close, SessionClose)                                               \
+  V(session_application, SessionApplication)                                   \
   V(session_early_data_rejected, SessionEarlyDataRejected)                     \
   V(session_goaway, SessionGoaway)                                             \
   V(session_datagram, SessionDatagram)                                         \

src/quic/http3.cc

@@ -1012,6 +1012,8 @@ class Http3ApplicationImpl final : public Session::Application {
     Debug(&session(),
           "HTTP/3 application received updated settings: %s",
           options_);
+    // The settings are part of the application
+    session().EmitApplication();
   }
 
   bool started_ = false;

src/quic/session.cc

@@ -3601,6 +3601,27 @@ void Session::EmitSessionTicket(Store&& ticket) {
   }
 }
 
+void Session::EmitApplication() {
+  if (is_destroyed()) return;
+  if (!env()->can_call_into_js()) return;
+
+  CallbackScope<Session> cb_scope(this);
+
+  if (!has_application()) {
+    // The application has not yet been selected (ALPN negotiation is not
+    // yet complete on the server) or the session has been destroyed. In
+    // either case, the application options are not available.
+    // Should not happen, but we bail out
+    return;
+  }
+  Local<Value> argv;
+  auto& options = application().options();
+  if (options.ToObject(env()).ToLocal(&argv)) {
+    MakeCallback(
+        BindingData::Get(env()).session_application_callback(), 1, &argv);
+  }
+}
+
 void Session::DestroyAllStreams(const QuicError& error) {
   DCHECK(!is_destroyed());
   // Copy the streams map since streams remove themselves during

src/quic/session.h

@@ -602,6 +602,7 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
   void EmitVersionNegotiation(const ngtcp2_pkt_hd& hd,
                               const uint32_t* sv,
                               size_t nsv);
+  void EmitApplication();
   void DatagramStatus(datagram_id datagramId, DatagramStatus status);
   void DatagramReceived(const uint8_t* data,
                         size_t datalen,

test/parallel/test-quic-h3-settings.mjs

@@ -166,6 +166,10 @@ const decoder = new TextDecoder();
     servername: 'localhost',
     application: { enableConnectProtocol: true, enableDatagrams: true },
   });
+  clientSession.onapplication = mustCall((appopt) => {
+    strictEqual(appopt.enableConnectProtocol, true);
+    strictEqual(appopt.enableDatagrams, true);
+  });
   await clientSession.opened;
 
   const stream = await clientSession.createBidirectionalStream({