quic: use 'kApplication' not ALPN to explicitly connect QUIC to H3

Author: pimterry

lib/internal/quic/http3.js

@@ -14,6 +14,7 @@ const {
   listen: quicListen,
   QuicSession,
   QuicStream,
+  kApplication,
 } = require('internal/quic/quic');
 
 const {
@@ -224,6 +225,7 @@ async function connect(address, options = kEmptyObject) {
   const session = await quicConnect(address, {
     ...options,
     alpn: kHttp3Alpn,
+    [kApplication]: 'http3',
   });
   return new Http3Session(session);
 }
@@ -240,7 +242,7 @@ async function listen(onsession, options = kEmptyObject) {
   validateObject(options, 'options');
   return quicListen((session) => {
     onsession(new Http3Session(session));
-  }, { ...options, alpn: kHttp3Alpn });
+  }, { ...options, alpn: kHttp3Alpn, [kApplication]: 'http3' });
 }
 
 module.exports = {

lib/internal/quic/quic.js

@@ -4974,35 +4974,35 @@ function processTlsOptions(tls, forServer) {
   validateBoolean(tlsTrace, 'options.tlsTrace');
 
   // Encode the ALPN option to wire format (length-prefixed protocol names).
-  // Server: array of protocol names. Client: single protocol name.
-  // If not specified, the C++ default (h3) is used.
-  let encodedAlpn;
-  if (alpn !== undefined) {
-    const protocols = forServer ?
-      (ArrayIsArray(alpn) ? alpn : [alpn]) :
-      [alpn];
-    if (!forServer) {
-      validateString(alpn, 'options.alpn');
-    }
-    let totalLen = 0;
-    for (let i = 0; i < protocols.length; i++) {
-      validateString(protocols[i], `options.alpn[${i}]`);
-      if (protocols[i].length === 0 || protocols[i].length > 255) {
-        throw new ERR_INVALID_ARG_VALUE(`options.alpn[${i}]`, protocols[i],
-                                        'must be between 1 and 255 characters');
-      }
-      totalLen += 1 + protocols[i].length;
-    }
-    // Build wire format: [len1][name1][len2][name2]...
-    const buf = Buffer.allocUnsafe(totalLen);
-    let offset = 0;
-    for (let i = 0; i < protocols.length; i++) {
-      buf[offset++] = protocols[i].length;
-      buf.write(protocols[i], offset, 'ascii');
-      offset += protocols[i].length;
-    }
-    encodedAlpn = buf.toString('latin1');
-  }
+  if (alpn === undefined) {
+    throw new ERR_INVALID_ARG_VALUE(
+      'options.alpn', alpn,
+      'is required');
+  }
+  const protocols = forServer ?
+    (ArrayIsArray(alpn) ? alpn : [alpn]) :
+    [alpn];
+  if (!forServer) {
+    validateString(alpn, 'options.alpn');
+  }
+  let totalLen = 0;
+  for (let i = 0; i < protocols.length; i++) {
+    validateString(protocols[i], `options.alpn[${i}]`);
+    if (protocols[i].length === 0 || protocols[i].length > 255) {
+      throw new ERR_INVALID_ARG_VALUE(`options.alpn[${i}]`, protocols[i],
+                                      'must be between 1 and 255 characters');
+    }
+    totalLen += 1 + protocols[i].length;
+  }
+  // Build wire format: [len1][name1][len2][name2]...
+  const buf = Buffer.allocUnsafe(totalLen);
+  let offset = 0;
+  for (let i = 0; i < protocols.length; i++) {
+    buf[offset++] = protocols[i].length;
+    buf.write(protocols[i], offset, 'ascii');
+    offset += protocols[i].length;
+  }
+  const encodedAlpn = buf.toString('latin1');
 
   if (ca !== undefined) {
     const caInputs = ArrayIsArray(ca) ? ca : [ca];
@@ -5195,6 +5195,7 @@ function processSessionOptions(options, config = kEmptyObject) {
     // HTTP/3 application-specific options. Nested under `application`
     // to separate protocol-specific settings from transport-level ones.
     application = kEmptyObject,
+
     // Session callbacks that can be set at construction time to avoid
     // race conditions with events that fire during or immediately
     // after the handshake.
@@ -5226,6 +5227,10 @@ function processSessionOptions(options, config = kEmptyObject) {
     targetAddress,
   } = config;
 
+  const applicationName = options[kApplication];
+  assert(applicationName === undefined || typeof applicationName === 'string',
+         'options[kApplication] must be a registered application name');
+
   if (token !== undefined) {
     if (!isArrayBufferView(token)) {
       throw new ERR_INVALID_ARG_TYPE('options.token',
@@ -5329,6 +5334,7 @@ function processSessionOptions(options, config = kEmptyObject) {
     maxDatagramSendAttempts,
     streamIdleTimeout,
     application,
+    applicationName,
     onerror,
     onstream,
     ondatagram,
@@ -5465,6 +5471,8 @@ module.exports = {
   CC_ALGO_BBR,
   DEFAULT_CIPHERS,
   DEFAULT_GROUPS,
+  // Internal only for http3+quic integration
+  kApplication,
   // These are exported only for internal testing purposes.
   getQuicStreamState,
   getQuicSessionState,

src/quic/application.cc

@@ -10,6 +10,9 @@
 #include <node_sockaddr-inl.h>
 #include <uv.h>
 #include <v8.h>
+#include <mutex>
+#include <string>
+#include <vector>
 #include "application.h"
 #include "defs.h"
 #include "endpoint.h"
@@ -165,6 +168,39 @@ MaybeLocal<Object> Session::Application_Options::ToObject(
 
 // ============================================================================
 
+namespace {
+struct ApplicationFactoryEntry {
+  std::string name;
+  ApplicationFactory factory;
+};
+// Process-wide registry. Registered once per process at binding
+// initialization (registration is idempotent for repeated binding inits,
+// e.g. workers); intentionally leaked, process lifetime.
+std::mutex application_factories_mutex;
+std::vector<ApplicationFactoryEntry>* application_factories = nullptr;
+}  // namespace
+
+void RegisterApplicationFactory(std::string_view name,
+                                ApplicationFactory factory) {
+  std::lock_guard<std::mutex> lock(application_factories_mutex);
+  if (application_factories == nullptr) {
+    application_factories = new std::vector<ApplicationFactoryEntry>();
+  }
+  for (const auto& entry : *application_factories) {
+    if (entry.factory == factory) return;
+  }
+  application_factories->push_back({std::string(name), factory});
+}
+
+ApplicationFactory FindApplicationFactory(std::string_view name) {
+  std::lock_guard<std::mutex> lock(application_factories_mutex);
+  if (application_factories == nullptr) return nullptr;
+  for (const auto& entry : *application_factories) {
+    if (entry.name == name) return entry.factory;
+  }
+  return nullptr;
+}
+
 Session::Application::Application(Session* session, const Options& options)
     : session_(session) {}
 

src/quic/application.h

@@ -3,6 +3,7 @@
 #if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
 
 #include <optional>
+#include <string_view>
 #include <variant>
 #include <vector>
 
@@ -266,6 +267,17 @@ class Session::Application : public MemoryRetainer {
 std::unique_ptr<Session::Application> CreateDefaultApplication(
     Session* session, const Session::Application_Options& options);
 
+// A factory for protocol-specific Session::Application implementations.
+// Protocols register themselves under a name at binding initialization
+// (e.g. "http3"); a session installs one only when its options request
+// that name explicitly.
+using ApplicationFactory = std::unique_ptr<Session::Application> (*)(
+    Session* session, const Session::Application_Options& options);
+void RegisterApplicationFactory(std::string_view name,
+                                ApplicationFactory factory);
+// Returns the factory registered under name, or nullptr.
+ApplicationFactory FindApplicationFactory(std::string_view name);
+
 }  // namespace node::quic
 
 #endif  // defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS

src/quic/bindingdata.cc

@@ -7,6 +7,7 @@
 #include <nghttp3/nghttp3.h>
 #include <ngtcp2/ngtcp2.h>
 #include <node.h>
+#include "http3.h"
 #include <node_errors.h>
 #include <node_external_reference.h>
 #include <node_mem-inl.h>
@@ -303,6 +304,7 @@ BindingData::BindingData(Realm* realm, Local<Object> object)
   MakeWeak();
   // Unref so the check handle doesn't keep the event loop alive on its own.
   flush_check_.Unref();
+  RegisterHttp3Application();
 }
 
 SessionManager& BindingData::session_manager() {

src/quic/bindingdata.h

@@ -88,6 +88,7 @@ class SessionManager;
   V(disable_stateless_reset, "disableStatelessReset")                          \
   V(draining_period_multiplier, "drainingPeriodMultiplier")                    \
   V(enable_connect_protocol, "enableConnectProtocol")                          \
+  V(applicationName, "applicationName")                                        \
   V(enable_early_data, "enableEarlyData")                                      \
   V(enable_datagrams, "enableDatagrams")                                       \
   V(enable_tls_trace, "tlsTrace")                                              \

src/quic/http3.cc

@@ -1426,6 +1426,10 @@ std::unique_ptr<Session::Application> CreateHttp3Application(
   return std::make_unique<Http3ApplicationImpl>(session, options);
 }
 
+void RegisterHttp3Application() {
+  RegisterApplicationFactory("http3", CreateHttp3Application);
+}
+
 }  // namespace quic
 }  // namespace node
 #endif  // OPENSSL_NO_QUIC

src/quic/http3.h

@@ -15,6 +15,8 @@ namespace node::quic {
 std::unique_ptr<Session::Application> CreateHttp3Application(
     Session* session, const Session::Application_Options& options);
 
+void RegisterHttp3Application();
+
 // Parse HTTP/3 specific session ticket app data. Called from
 // Application::ParseTicketData() when the type byte is HTTP3.
 // The data includes the type byte prefix.

src/quic/session.cc

@@ -23,7 +23,6 @@
 #include "data.h"
 #include "defs.h"
 #include "endpoint.h"
-#include "http3.h"
 #include "ncrypto.h"
 #include "packet.h"
 #include "preferredaddress.h"
@@ -249,8 +248,6 @@ SessionStatsArena& GetSessionStatsArena(BindingData& binding) {
 
 // ============================================================================
 
-class Http3Application;
-
 namespace {
 constexpr std::string to_string(PreferredAddress::Policy policy) {
   switch (policy) {
@@ -617,6 +614,7 @@ Maybe<Session::Options> Session::Options::From(Environment* env,
 
   if (!SET(version) || !SET(min_version) || !SET(preferred_address_strategy) ||
       !SET(transport_params) || !SET(tls_options) || !SET(qlog) ||
+      !SET(applicationName) ||
       !SET(handshake_timeout) || !SET(initial_rtt) ||
       !SET(keep_alive_timeout) || !SET(max_stream_window) || !SET(max_window) ||
       !SET(max_payload_size) || !SET(unacknowledged_packet_threshold) ||
@@ -2279,8 +2277,7 @@ Session::Session(Endpoint* endpoint,
   // known upfront from the options. For servers, application_ stays
   // null until OnSelectAlpn fires during the TLS handshake.
   if (config.side == Side::CLIENT) {
-    auto app =
-        SelectApplicationFromAlpn(DecodeAlpn(config.options.tls_options.alpn));
+    auto app = SelectApplication();
     if (app) SetApplication(std::move(app));
   }
 
@@ -2632,12 +2629,12 @@ std::string_view Session::DecodeAlpn(std::string_view wire) {
   return {};
 }
 
-std::unique_ptr<Session::Application> Session::SelectApplicationFromAlpn(
-    std::string_view alpn) {
-  // h3 and h3-XX variants use Http3ApplicationImpl.
-  // Everything else uses DefaultApplication.
-  if (alpn == "h3" || (alpn.size() > 3 && alpn.substr(0, 3) == "h3-")) {
-    return CreateHttp3Application(this, config().options.application_options);
+std::unique_ptr<Session::Application> Session::SelectApplication() {
+  const auto& name = config().options.applicationName;
+  if (!name.empty()) {
+    auto factory = FindApplicationFactory(name);
+    CHECK_NOT_NULL(factory);
+    return factory(this, config().options.application_options);
   }
   return CreateDefaultApplication(this, config().options.application_options);
 }

src/quic/session.h

@@ -126,10 +126,10 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
   // Decode the first ALPN protocol name from wire format (length-prefixed).
   static std::string_view DecodeAlpn(std::string_view wire);
 
-  // Select the Application implementation based on the negotiated ALPN.
-  // h3 (and h3-XX variants) map to Http3ApplicationImpl; all others map
-  // to DefaultApplication. Sets the application_type state field.
-  std::unique_ptr<Application> SelectApplicationFromAlpn(std::string_view alpn);
+  // Select the Application implementation: the factory registered under
+  // options.applicationName when set (see application.h), otherwise the default
+  // raw-stream application.
+  std::unique_ptr<Application> SelectApplication();
 
   // Install the Application on the session. Called at construction for
   // clients (ALPN known upfront) or from OnSelectAlpn for servers
@@ -174,6 +174,8 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
     // ALPN selects Http3ApplicationImpl).
     Application_Options application_options = Application_Options::kDefault;
 
+    std::string applicationName;
+
     // When true, QLog output will be enabled for the session.
     bool qlog = false;