feat: add transport features (mTLS, DNS, multipart, zstd, charset)

[StopMakingThatBigFace]

Release Notes

Breaking Changes

• The minimum supported Node.js version is now 20+.
  The package now officially requires Node 20, which aligns engines with the library's actual runtime and public API surface, including FormData, File, Request, Response, and related web globals.

• The keepOriginalHeaderNames option has been removed.
  There is no separate flag for original header-name preservation anymore. Header tuples are now the single low-level way to control wire shape:

  • tuple order is preserved
  • original header names are preserved on the wire

• Proxy behavior has changed.
  When proxy is not provided, the client may now honor environment/system proxy settings such as HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY through the native wreq transport path.
  To explicitly disable env/system proxy detection for a request, use:

  proxy: false

Added

• mTLS / client certificate support
  Added support for client certificate authentication in both HTTP and WebSocket flows:

  • tlsIdentity: { cert, key } for PEM
  • tlsIdentity: { pfx, passphrase } for PKCS#12 / PFX

• Custom CA / trust store support
  Added custom trust store configuration:

  • ca: { cert, includeDefaultRoots }
    You can provide a single certificate or an array of certificates.

• DNS controls
  Added DNS options:

  • dns.servers for custom DNS servers
  • dns.hosts for per-host IP overrides

• Multipart uploads via FormData
  Request bodies now support FormData natively, with fetch-like behavior:

  • multipart boundaries are generated automatically
  • content-type is generated automatically
  • text fields and file parts are both supported

• Transparent zstd decompression
  With compress: true, the client now supports zstd response decoding in addition to gzip, br, and deflate.

• Charset-aware response.text()
response.text() now decodes response bodies using the charset declared in Content-Type instead of always assuming UTF-8.

• New exported types
  The package now exports:

  • TlsIdentity
  • CertificateAuthority
  • DnsOptions
  • NativeDnsOptions

Changed

• Header tuples are now the single low-level header control mechanism.
  If you pass:

  headers: [
    ['x-lower', 'one'],
    ['X-Mixed', 'two'],
  ]

  the client will preserve both tuple order and the original header names on the wire without any additional option.

• Request body dispatch is now binary-safe internally.
  Native request bodies are now passed as bytes instead of UTF-8 strings, which improves correctness for multipart payloads and other non-text request bodies.

• Request cloning and redirect handling now work correctly with multipart bodies.
  Internal request cloning and redirect rewriting now support both raw byte bodies and multipart request bodies.

Documentation

The README has been expanded to cover:

• FormData uploads
• proxy: false
• disableDefaultHeaders
• exact header order and original header names
• mTLS and custom CAs
• zstd
• DNS controls
• the Node.js 20+ requirement

Testing

Added integration coverage for:

• mTLS with PEM identities
• mTLS with PKCS#12 / PFX identities
• rejection of mTLS requests without a client certificate
• multipart uploads
• charset-aware text decoding
• zstd decompression
• per-request DNS host overrides
• env/system proxy behavior and proxy: false

Upgrade Guide

If you are upgrading from a previous version:

1. Upgrade your runtime to Node.js 20+.
2. Remove any use of keepOriginalHeaderNames.
3. If you need to bypass env/system proxy detection, set proxy: false.
4. For strict header control, use tuple-style headers.