[bengl]

Summary

Adds an http2.client.request.headers diagnostics channel that lets subscribers add or modify outgoing HTTP/2 client request headers before they are serialized. This gives tracing instrumentation (OpenTelemetry and friends) a supported way to propagate context headers like traceparent on node:http2 client requests, which today requires monkey-patching ClientHttp2Session#request().

Why a new channel instead of changing the existing ones

http2.client.stream.created and http2.client.stream.start cannot serve as the injection point:

• request() serializes the headers (prepareRequestHeadersObject/prepareRequestHeadersArray call buildNgHeaderString) before the created publish fires, and on an already-connected session requestOnConnect submits the HEADERS frame before the publish too. Mutating the published sentHeaders object has no effect on the wire.
• Publishing created earlier with the live headers object would change what existing subscribers see. They currently get the post-defaults snapshot, including the :method, :scheme, :authority, and :path defaults. It would also require moving header validation after stream creation, which changes error timing. Existing subscribers that treat the payload as read-only must not observe a change, so those channels are left alone.

The new channel is published at the top of ClientHttp2Session#request(), before header validation and serialization, on both the connecting and already-connected session paths. Subscribers get { headers, session }, where headers is a shallow copy of the object or array the caller passed to request() (with sensitiveHeaders preserved), or a newly created object when no headers argument was given. Headers must be mutated in place for the change to take effect. Injected headers go through the same validation as headers passed directly to request(), so an injected unknown pseudo-header still throws synchronously.

Behavior notes

• created and start payloads, timing, and contents are unchanged. Mutating their published headers still has no effect. The new channel is the intended injection point.
• Subscribers mutate a shallow copy of the caller's headers, so the caller's object, including its sensitiveHeaders list, is never modified. Header reuse across requests is unaffected.
• When there are no subscribers the channel is not published at all, so there is no overhead and no behavior change.

Tests

test/parallel/test-diagnostics-channel-http2-client-request-headers.js covers:

• injected header reaches the server when request() is called while the session is still connecting
• the caller's headers object and array (including sensitiveHeaders) are not modified by the subscriber, in both object and raw array form
• injected header reaches the server on an already-connected session
• injection when request() is called with no headers argument
• injection into raw array headers
• a subscriber that does not mutate leaves the request unchanged
• injected headers hit the same validation as caller-provided headers

Also ran the full test-http2 and test-diagnostics-channel parallel suites locally (364 tests, all passing), plus make lint-js and make lint-md on the changed files.

[nodejs-github-bot]

Review requested:

• @nodejs/http2
• @nodejs/net

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/78738/

[pimterry]

This exposes the caller's original headers param. If you mutate that, you'll unexpectedly mutate values in user code, not just this request. E.g. if a user builds headers then passes them into multiple requests or anywhere else, they'll be passing around the mutated values between separate requests unexpectedly. If the app is proxying and passes incoming headers to upstream requests, you've modified their incoming header data.

If you clone headers here instead you can avoid that. Would need to handle both arrays & object forms and preserve sensitiveHeaders in both cases.

[bengl]

Good call. Fixed in latest rev.

[pimterry]

Why not http2.client.stream.headers, which would match all the other methods here? No strong feelings here myself, just a bit surprising.

[bengl]

The channel fires before the stream exists and the payload has no stream, so http2.client.stream.* felt wrong for it. It also lines up with the http.client.request family on the http/1 side. Happy to rename if you'd rather.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.70%. Comparing base (75191c4) to head (fa8ffdb).
⚠️ Report is 53 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #67069      +/-   ##
==========================================
- Coverage   92.97%   90.70%   -2.27%     
==========================================
  Files         428      797     +369     
  Lines      195284   278797   +83513     
  Branches    30205    53619   +23414     
==========================================
+ Hits       181560   252881   +71321     
- Misses      13397    16284    +2887     
- Partials      327     9632    +9305     

Files with missing lines	Coverage Δ
lib/internal/http2/core.js	94.95% <100.00%> (+0.12%)	⬆️

... and 504 files with indirect coverage changes

🚀 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.