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

[Antamansid]

This relates to...

N/A — no existing issue. Affects clients talking to load balancers that select the ALPN protocol by client preference.

Rationale

The built-in connector hardcodes ALPNProtocols: ['http/1.1', 'h2'] (h1 first) after spreading user options (lib/core/connect.js), so the order cannot be overridden via the connect options. Servers that select the ALPN protocol by client preference — some load balancers do (e.g. those relying on OpenSSL's SSL_select_next_proto semantics) — then negotiate http/1.1 even with allowH2: true, forcing the client onto HTTP/1.1.

This adds an opt-in preferH2 connector option that, together with allowH2, offers ALPN as ['h2', 'http/1.1'] (h2 first), so HTTP/2 is negotiated whenever the server supports it. The default behaviour is unchanged (preferH2 defaults to false). If the server does not support HTTP/2, ALPN transparently falls back to http/1.1.

Changes

• lib/core/connect.js: accept a preferH2 build option; when set together with allowH2, offer ALPNProtocols: ['h2', 'http/1.1'] instead of the default ['http/1.1', 'h2'].
• types/connector.d.ts: add preferH2?: boolean to BuildOptions.
• docs/docs/api/Connector.md: document the new option.
• test/connect-h2-alpn-order.js: assert the offered ALPN order with and without preferH2.
• test/types/connector.test-d.ts: type-level assertion for preferH2.

Features

• New opt-in connector option preferH2 (default false) to offer HTTP/2 first in ALPN, for servers that pick the protocol by client preference.

Bug Fixes

N/A

Breaking Changes and Deprecations

N/A — the default ALPN order is unchanged; preferH2 is opt-in.

Status

• I have read and agreed to the Developer's Certificate of Origin
• Tested
• [S] Benchmarked (optional)
• Documented
• Review ready
• In review
• Merge ready

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.22%. Comparing base (f049730) to head (a6e0237).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5327   +/-   ##
=======================================
  Coverage   93.21%   93.22%           
=======================================
  Files         110      110           
  Lines       36598    36598           
=======================================
+ Hits        34115    34117    +2     
+ Misses       2483     2481    -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.