[sylvesterkaczmarek]

Summary

Expose the SDK's existing immutable header representation as Headers.asMap() and document the value guarantees of Headers.values(...).

Addresses the header-conversion portion of #664.

Problem

Custom HttpClient implementations commonly need to adapt SDK headers into another HTTP library. Today that requires a two-step traversal:

headers.names().forEach(name -> {
    List<String> values = headers.values(name);
    // adapt name + values
});

Internally, Headers already stores exactly the desired Map<String, List<String>>, with case-insensitive name lookup and immutable value lists. The public API does not expose that representation directly.

The issue discussion also notes an undocumented guarantee: names returned by names() always have at least one value, while values(name) returns an empty list only for an absent header.

Change

Add:

Map<String, List<String>> headers = sourceHeaders.asMap();

asMap() returns the same immutable, case-insensitive representation held by the Headers instance. It does not copy or flatten multi-valued headers.

Also document the values(name) absent/present behaviour.

Regression coverage

Added focused tests verifying that the returned map:

• preserves case-insensitive header lookup;
• preserves multiple values in insertion order;
• cannot be structurally mutated;
• exposes immutable value lists.

Scope

• Headers.kt: 13 additions
• one focused test file
• no header construction, equality, serialisation, or request behaviour changes
• intentionally does not address the separate request-body convenience proposal in Feat. Request: HttpRequest/HttpResponse convenience methods. #664

Validation

The branch is based on current upstream main at 81134d727946fb84cc48db98e6c8c53c8a8d22ab and is 0 commits behind upstream.

Risk

Low. This is an additive API over the immutable data structure already stored by Headers; existing behaviour is unchanged.

[sylvesterkaczmarek]

Following up after refreshing this branch to current main. It is now 0 behind, mergeable, and has no failing checks or unresolved review threads. Could a maintainer review it when convenient?

[dpiet-oai]

Thank you, Sylvester, for the proposal and tests. We built on this work in #1245, which has now merged and adds Headers.asMap(). Closing this PR as superseded by that implementation.