quic: Implement callback for http/3 settings/application options

doc/api/quic.md

@@ -755,6 +755,8 @@ added: REPLACEME
 The current application-level options for this session. These include settings
 that are specific to the negotiated application protocol (e.g. HTTP/3) and may
 be negotiated separately from the transport parameters. Read only.
+You can use the callback [`session.onapplication`][] to be informed, when settings
+from the remote arrive.
 
 ### `session.close([options])`
 
@@ -887,6 +889,16 @@ added: v23.8.0
 The endpoint that created this session. Returns `null` if the session
 has been destroyed. Read only.
 
+### `session.onapplication`
+
+<!-- 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 +3212,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
@@ -3258,6 +3270,19 @@ added: v23.8.0
   datagram was never sent on the wire (dropped due to queue overflow,
   send attempt limit exceeded, or frame size rejection).
 
+### Callback: `OnApplicationCallback`
+
+<!-- YAML
+added: v23.8.0
+-->
+
+* `this` {quic.QuicSession}
+* `applicationoption` {quic.QuicSession}
+
+The callback function that is invoked when application options change.
+E.g. for http/3 settings are included in applications options and
+may arrive after the connection is established.
+
 ### Callback: `OnPathValidationCallback`
 
 <!-- YAML
@@ -3732,6 +3757,17 @@ 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 +4135,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 `ApplicationOptions` are changed, e.g. HTTP/3 settings.
+ * @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.onapplication;
   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, 'onapplication');
+      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/state.js

@@ -349,6 +349,7 @@ class QuicSessionState {
   static #LISTENER_SESSION_TICKET = 1 << 3;
   static #LISTENER_NEW_TOKEN = 1 << 4;
   static #LISTENER_ORIGIN = 1 << 5;
+  static #LISTENER_APPLICATION = 1 << 6;
 
   #getListenerFlag(flag) {
     const handle = this.#handle;
@@ -367,6 +368,14 @@ class QuicSessionState {
       val ? (current | flag) : (current & ~flag), kIsLittleEndian);
   }
 
+  /** @type {boolean} */
+  get hasApplicationListener() {
+    return this.#getListenerFlag(QuicSessionState.#LISTENER_APPLICATION);
+  }
+  set hasApplicationListener(val) {
+    this.#setListenerFlag(QuicSessionState.#LISTENER_APPLICATION, val);
+  }
+
   /** @type {boolean} */
   get hasPathValidationListener() {
     return this.#getListenerFlag(QuicSessionState.#LISTENER_PATH_VALIDATION);

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

@@ -72,6 +72,7 @@ enum class SessionListenerFlags : uint32_t {
   SESSION_TICKET = 1 << 3,
   NEW_TOKEN = 1 << 4,
   ORIGIN = 1 << 5,
+  APPLICATION = 1 << 6
 };
 
 inline SessionListenerFlags operator|(SessionListenerFlags a,
@@ -3601,6 +3602,33 @@ void Session::EmitSessionTicket(Store&& ticket) {
   }
 }
 
+void Session::EmitApplication() {
+  if (is_destroyed()) return;
+  if (!env()->can_call_into_js()) return;
+
+  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;
+  }
+
+  if (!HasListenerFlag(impl_->state()->listener_flags,
+                       SessionListenerFlags::APPLICATION)) [[likely]] {
+    return;
+  }
+
+  CallbackScope<Session> cb_scope(this);
+
+  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,