Representing HTTP headers in a `java.util.Map` is error-prone, because
the names (keys) need to be case-insensitive (per
[RFC 2616 section 4.2](https://datatracker.ietf.org/doc/html/rfc2616#section-4.2))
but this is fundamentally technically incompatible with the `Map`
interface (e.g. with headers `{"key": ["val_1", "val_2"]}` then
`get("key")` and `get("KeY")` both return the same list, but `size()`
returns `1`). It also breaks as soon as you copy the `Map` into a
non-case-insensitive (i.e. normal) `Map` implementation, e.g. Guava's
`ImmutableMap`. It's risky that a line as 'innocent' as
`ImmutableMap.copyOf(headers)` could break things so badly.
For now it's enough to keep this field unstable (it's currently the only
reference to HTTP headers in the stable API). We can consider
stabilising an improved HTTP header representation in future.
PiperOrigin-RevId: 450708598
This is a breaking change if the annotation itself is in use in Kotlin
code. It's judged that the IntDefs in this commit are unlikely to be
referred to often in Kotlin code. This is because they're either:
- Related to esoteric parts of the library, or
- In a common part of the library but only returned from methods (and
never passed to callback methods).
A follow-up change will fix the positions of existing usages to match
this new config.
#minor-release
PiperOrigin-RevId: 426410237
