feat(connect): add preferH2 connector option to offer h2 first in ALPN (#5327)

Author: Antamansid

docs/docs/api/Connector.md

@@ -13,6 +13,7 @@ Every Tls option, see [here](https://nodejs.org/api/tls.html#tls_tls_connect_opt
 Furthermore, the following options can be passed:
 
 * **socketPath** `string | null` (optional) - Default: `null` - An IPC endpoint, either Unix domain socket or Windows named pipe.
+* **preferH2** `boolean` (optional) - Default: `false` - Only effective together with `allowH2`. When `true`, ALPN is offered as `['h2', 'http/1.1']` (HTTP/2 first) instead of the default `['http/1.1', 'h2']`. Use this when the server selects the ALPN protocol by *client* preference (e.g. some load balancers) so that HTTP/2 is negotiated whenever the server supports it. If the server does not support HTTP/2, ALPN transparently falls back to `http/1.1`.
 * **maxCachedSessions** `number | null` (optional) - Default: `100` - Maximum number of TLS cached sessions. Use 0 to disable TLS session caching. Default: `100`.
 * **timeout** `number | null` (optional) -  In milliseconds. Default `10e3`.
 * **servername** `string | null` (optional)

lib/core/connect.js

@@ -59,7 +59,7 @@ const SessionCache = class WeakSessionCache {
   }
 }
 
-function buildConnector ({ allowH2, useH2c, maxCachedSessions, socketPath, timeout, session: customSession, ...opts }) {
+function buildConnector ({ allowH2, preferH2, useH2c, maxCachedSessions, socketPath, timeout, session: customSession, ...opts }) {
   if (maxCachedSessions != null && (!Number.isInteger(maxCachedSessions) || maxCachedSessions < 0)) {
     throw new InvalidArgumentError('maxCachedSessions must be a positive integer or zero')
   }
@@ -89,7 +89,7 @@ function buildConnector ({ allowH2, useH2c, maxCachedSessions, socketPath, timeo
         servername,
         session,
         localAddress,
-        ALPNProtocols: allowH2 ? ['http/1.1', 'h2'] : ['http/1.1'],
+        ALPNProtocols: allowH2 ? (preferH2 ? ['h2', 'http/1.1'] : ['http/1.1', 'h2']) : ['http/1.1'],
         socket: httpSocket, // upgrade socket connection
         port,
         host: hostname

test/connect-h2-alpn-order.js

@@ -0,0 +1,64 @@
+'use strict'
+
+const { tspl } = require('@matteo.collina/tspl')
+const { test, after, mock } = require('node:test')
+const { createSecureServer } = require('node:http2')
+const { once } = require('node:events')
+const { readFileSync } = require('node:fs')
+const { join } = require('node:path')
+const tls = require('node:tls')
+
+const { Client } = require('..')
+
+const key = readFileSync(join(__dirname, 'fixtures', 'key.pem'), 'utf8')
+const cert = readFileSync(join(__dirname, 'fixtures', 'cert.pem'), 'utf8')
+const ca = readFileSync(join(__dirname, 'fixtures', 'ca.pem'), 'utf8')
+
+function createServer () {
+  const server = createSecureServer({ key, cert, allowHTTP1: true }, (req, res) => {
+    res.writeHead(200)
+    res.end()
+  })
+  after(() => server.close())
+  return server
+}
+
+test('preferH2 offers ALPN as [h2, http/1.1] (h2 first)', async (t) => {
+  t = tspl(t, { plan: 2 })
+
+  const mockConnect = mock.method(tls, 'connect')
+  const server = createServer()
+  await once(server.listen(0), 'listening')
+
+  const client = new Client(`https://localhost:${server.address().port}`, {
+    allowH2: true,
+    connect: { ca, servername: 'agent1', preferH2: true }
+  })
+  after(() => client.close())
+
+  const { statusCode } = await client.request({ path: '/', method: 'GET' })
+  t.equal(statusCode, 200)
+  t.deepStrictEqual(mockConnect.mock.calls[0].arguments[0].ALPNProtocols, ['h2', 'http/1.1'])
+
+  await t.completed
+})
+
+test('without preferH2 the default ALPN order [http/1.1, h2] is preserved', async (t) => {
+  t = tspl(t, { plan: 2 })
+
+  const mockConnect = mock.method(tls, 'connect')
+  const server = createServer()
+  await once(server.listen(0), 'listening')
+
+  const client = new Client(`https://localhost:${server.address().port}`, {
+    allowH2: true,
+    connect: { ca, servername: 'agent1' }
+  })
+  after(() => client.close())
+
+  const { statusCode } = await client.request({ path: '/', method: 'GET' })
+  t.equal(statusCode, 200)
+  t.deepStrictEqual(mockConnect.mock.calls[0].arguments[0].ALPNProtocols, ['http/1.1', 'h2'])
+
+  await t.completed
+})

test/types/connector.test-d.ts

@@ -25,7 +25,9 @@ expectAssignable<buildConnector.BuildOptions>({
   checkServerIdentity: () => undefined, // Test if ConnectionOptions is assignable
   localPort: 1234, // Test if TcpNetConnectOpts is assignable
   keepAlive: true,
-  keepAliveInitialDelay: 12345
+  keepAliveInitialDelay: 12345,
+  allowH2: true,
+  preferH2: true
 })
 
 expectAssignable<buildConnector.Options>({

types/connector.d.ts

@@ -7,6 +7,7 @@ declare function buildConnector (options?: buildConnector.BuildOptions): buildCo
 declare namespace buildConnector {
   export type BuildOptions = (ConnectionOptions | TcpNetConnectOpts | IpcNetConnectOpts) & {
     allowH2?: boolean;
+    preferH2?: boolean;
     maxCachedSessions?: number | null;
     socketPath?: string | null;
     timeout?: number | null;