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>
PR-URL: #63558
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Tim Perry <pimterry@gmail.com>
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

Author: martenrichter

doc/api/quic.md

@@ -934,6 +934,8 @@ added: v26.3.0
 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])`
 
@@ -1066,6 +1068,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
@@ -3525,11 +3537,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
@@ -3583,6 +3595,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
@@ -4057,6 +4082,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
@@ -4440,6 +4476,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

@@ -204,6 +204,7 @@ const {
   kPrivateConstructor,
   kReset,
   kSendHeaders,
+  kSessionApplication,
   kSessionTicket,
   kTrailers,
   kVersionNegotiation,
@@ -252,6 +253,7 @@ const {
   onSessionReceiveDatagramStatusChannel,
   onSessionPathValidationChannel,
   onSessionNewTokenChannel,
+  onSessionApplicationChannel,
   onSessionTicketChannel,
   onSessionVersionNegotiationChannel,
   onSessionOriginChannel,
@@ -453,6 +455,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.
@@ -583,6 +586,13 @@ const endpointRegistry = new SafeSet();
  * @returns {void}
  */
 
+/**
+ * @callback OnApplicationCallback
+ * @this {QuicSession}
+ * @param {ApplicationOptions} applicationoptions
+ * @returns {void}
+ */
+
 /**
  * @callback OnSessionTicketCallback
  * @this {QuicSession}
@@ -660,6 +670,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}
@@ -817,6 +835,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
@@ -1271,6 +1299,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,
@@ -2964,6 +2993,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);
@@ -3551,6 +3599,7 @@ class QuicSession {
     inner.ondatagramstatus = undefined;
     inner.onpathvalidation = undefined;
     inner.onsessionticket = undefined;
+    inner.onapplication = undefined;
     inner.onkeylog = undefined;
     inner.onversionnegotiation = undefined;
     inner.onhandshake = undefined;
@@ -3779,6 +3828,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
@@ -4356,6 +4422,7 @@ class QuicEndpoint {
       ongoaway,
       onkeylog,
       onqlog,
+      onapplication,
       // Stream-level callbacks applied to each incoming stream.
       onheaders,
       ontrailers,
@@ -4381,6 +4448,7 @@ class QuicEndpoint {
       ongoaway,
       onkeylog,
       onqlog,
+      onapplication,
       onheaders,
       ontrailers,
       oninfo,
@@ -5113,6 +5181,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,
@@ -5234,6 +5304,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

@@ -55,6 +55,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');
@@ -90,6 +91,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

@@ -1015,6 +1015,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,
@@ -3669,6 +3670,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

@@ -615,6 +615,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,