types(dispatcher): use OutgoingHttpHeaders for request headers

[maruthang]

This relates to...

Closes #3840

Rationale

DispatchOptions.headers (and ConnectOptions.headers, UpgradeOptions.headers, ProxyAgent.Options.headers, Socks5ProxyAgent.Options.headers) are used to set headers on outgoing requests, but the type union UndiciHeaders was built around IncomingHttpHeaders (server-side semantics). This prevented users from passing common outgoing values like { 'content-length': 42 } (numeric values), even though the runtime accepts them and coerces them to strings via template-literal interpolation in lib/core/request.js.

This change introduces an OutgoingHttpHeaders alias in types/header.d.ts (mirroring Node core's http.OutgoingHttpHeaders: Record<string, number | string | string[] | undefined>), and uses it to model UndiciHeaders and the headers option on the proxy agents. Response/incoming-side fields (ResponseData.headers, ConnectData.headers, etc.) continue to use IncomingHttpHeaders as before.

Because IncomingHttpHeaders is a subtype of the new OutgoingHttpHeaders, this is a non-breaking widening of the request-header types: any code that previously typechecked still typechecks.

Changes

Features

N/A

Bug Fixes

• Add OutgoingHttpHeaders to types/header.d.ts and use it for outgoing-request headers options:
  • Dispatcher.UndiciHeaders (DispatchOptions, ConnectOptions, UpgradeOptions)
  • ProxyAgent.Options.headers
  • Socks5ProxyAgent.Options.headers
• Update docs/docs/api/Dispatcher.md UndiciHeaders parameter docs to reflect OutgoingHttpHeaders semantics (matches the screenshot in Typing issue: headers in DispatchOptions should use OutgoingHttpHeaders #3840).
• Add tsd regression tests in test/types/header.test-d.ts and test/types/dispatcher.test-d.ts covering numeric header values and Node core OutgoingHttpHeaders interop.

Breaking Changes and Deprecations

None. OutgoingHttpHeaders is a strict superset of IncomingHttpHeaders for the value union, so existing usages continue to typecheck.

Status

• I have read and agreed to the Developer's Certificate of Origin
• Tested
• 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.11%. Comparing base (e1211a5) to head (61c74f6).
⚠️ Report is 19 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5067   +/-   ##
=======================================
  Coverage   93.10%   93.11%           
=======================================
  Files         110      110           
  Lines       35788    35788           
=======================================
+ Hits        33322    33323    +1     
+ Misses       2466     2465    -1     

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

[maruthang]

Friendly nudge — this is approved by @metcoder95 and CI is green (35/35). It's a types-only change (Dispatcher.RequestOptions['headers'] switching from IncomingHttpHeaders to OutgoingHttpHeaders), so no runtime risk. @mcollina @ronag — could one of you drop the merge-label when convenient? Thanks!