Expose final outbound request headers for debugging

[ZilvinasKucinskas]

Priority: P2

Describe the issue

wreq-ruby lets callers inspect the request headers they provide and the headers returned in a response, but it does not provide a simple way to confirm the final outbound request headers after wreq applies defaults, cookies, authentication, compression, redirects, and header ordering/casing.

For debugging, the useful information is limited to the final regular header names and values for each request wreq sends, in the protocol-appropriate order and casing used by wreq. Repeated header fields should remain separate.

This is not intended to be a request recorder, response history, or packet-inspection API.

Desired behavior

The exact Ruby API is intentionally left open. Reusing wreq's existing tracing or header hooks is preferable to adding new protocol machinery. A debug trace event or opt-in callback is sufficient; wreq-ruby does not need to retain request history or attach it to responses and exceptions.

One conventional Ruby shape could be:

client = Wreq::Client.new
request_number = 0

trace_headers = lambda do |headers|
  request_number += 1
  lines = headers.map { |name, value| "#{name}: #{value}" }
  warn ["request #{request_number}", *lines].join("\n")
end

client.get(
  "https://example.com",
  on_request_headers: trace_headers
)

on_request_headers: is an illustrative name. Passing the callable per request keeps its debug state local to the caller. The callback can receive an ordered Enumerable of [name, value] pairs, so duplicate fields, order, and HTTP/1 casing are not lost. A redirect or retry simply invokes the same callback again; the caller may number or store those events if needed.

• Disabled by default.
• Expose one final regular-header block whenever wreq sends a request. Redirects or retries naturally produce another event.
• Preserve duplicate fields and the order/casing used by the sender.
• Make it clear that explicitly captured headers may contain Authorization, Cookie, and other sensitive values.
• Avoid meaningful overhead when disabled.

Out of scope

• request/response history objects;
• packet bytes, HTTP/2 pseudoheaders, frames, or HPACK data;
• request or response bodies;
• response metadata, timings, or retry/redirect classification;
• automatic logging in normal operation; and
• changes to wreq-proto, http2, or other transitive dependencies.

Acceptance criteria

• Ruby callers can opt in to confirming the final outbound regular request headers.
• The observed fields match the request wreq sends, including automatically added fields where applicable.
• Duplicate headers remain separate and header order/casing is retained where the protocol permits it.
• A redirect or retry produces another header event without requiring wreq-ruby to retain a history.
• With the feature disabled, no request headers are captured or logged.
• Tests cover custom headers, repeated headers, automatically added headers, and the disabled path.

Relevant source

• wreq connection verbose tracing
• wreq-ruby request execution

[0x676e67]

This should actually be handled by the MITM proxy, not wreq 😅. No client fully tracks this at the client implementation level.