Original Header Cases API

[seanmonstar]

This is a tracking issue for the feature to allow for sending and receiving the exact casing of header names, instead of the forced lowercasing of http. In most situations, simply forcing to lowercase is the better option, as it allows for a more performant HeaderMap, and is the required format for newer versions of HTTP (HTTP/2 and 3). However, there are rare occasions when being able to see the exact casing is needed.

Some initial support is available in hyper, and is exposed in the C API. But a public Rust API is not yet available.

• Initial internal support
• Expose in C API (Initial C API for hyper #2278)
• Provide builder options to enable support in Rust, useful to proxies (Decouple preserving header case from FFI (fixes #2313) #2480)
• Design and export the public extension API

[tasn]

We've also been bitten by this unfortunately. We know and realize that HTTP headers should be lower case.

Alas, some of our customers have compatibility requirements because they've been sending them as upper case (or camel case, depending) and some of their customers rely on them being of specific casing.

I'd be really grateful for even an experimental feature that we could enable to support this, because our current (terrible) alternative is to maintain our own Hyper fork. :(

[svix-jplatte]

How about this as a public API?

pub trait HttpMessageExt {
    fn headers_case_sensitive(&self) -> CaseSensitiveHeaderMap<'_>;
    fn headers_case_sensitive_mut(&mut self) -> CaseSensitiveHeaderMapMut<'_>;
}

impl<T> HttpMessageExt for http::Request<T> { /* ... */ }
impl<T> HttpMessageExt for http::Response<T> { /* ... */ }

// CaseSensitiveHeaderMap and CaseSensitiveHeaderMapMut methods would be more or less obvious, I guess?

For CaseSensitiveHeaderMapMut to work, we'd need extra API in http to allow mutably borrowing headers and extensions simultaneously, but I think that would "just" be a matter of

// request.rs
impl<T> Request<T> {
    pub fn parts_mut(&mut self) -> (PartsMut<'_>, &mut T) { /* ... */ }
}

pub struct PartsMut<'a> {
    /// The request's method
    pub method: &'a mut Method,

    /// The request's URI
    pub uri: &'a mut Uri,

    /// The request's version
    pub version: &'a mut Version,

    /// The request's headers
    pub headers: &'a mut HeaderMap<HeaderValue>,

    /// The request's extensions
    pub extensions: &'a mut Extensions,

    _priv: (),
}

// response.rs - equivalent with slightly different fields

[seanmonstar]

Hm. What would be the specific way a user would interact with this? What would the methods of HeaderCaseMap look like?

[svix-jplatte]

Some examples

let headers = response.headers_case_sensitive();
// Check for a header using the exact provided casing
if let Some(val) = message.headers_case_sensitive().get("Foo-Bar") {
    // read val: HeaderValue
}

let mut headers = request.headers_case_sensitive();
// Insert a header using the exact provided casing
headers.insert("Foo-Bar", <header value>);

Methods-wise, I could see this type having all of the methods (not constructors of course) of HeaderMap plus even a few _ignore_case ones (if you want to check an existing header ignoring casing to insert a new one with specific casing from one map object), but starting small, these seems like the important ones:

impl<'a> CaseSensitiveHeaderMap<'a> {
    pub fn contains_key(&self, key: impl AsCaseSensitiveHeaderName) -> bool;
    pub fn get(&self, key: impl AsaseSensitiveHeaderName) -> Option<&'a HeaderValue>;
    // GetAll<'a>: IntoIterator<Item = &'a HeaderValue>
    pub fn get_all(&self, key: impl AsCaseSensitiveHeaderName) -> GetAll<'a>;
    // Iter<'a>: Iterator<Item = (&'a CaseSensitiveHeaderName, &'a HeaderValue)
    pub fn iter(&self) -> Iter<'a>;
}

impl<'a> CaseSensitiveHeaderMapMut<'a> {
    // same methods as CaseSensitiveHeaderMap
    pub fn append(&mut self, key: impl IntoCaseSensitiveHeaderName, value: HeaderValue) -> bool;
    pub fn insert(&mut self, key: impl IntoCaseSensitiveHeaderName, value: HeaderValue) -> Option<HeaderValue>;
    // also try_append, try_insert
    pub fn get_mut(&mut self, key: impl IntoCaseSensitiveHeaderName) -> Option<&mut HeaderValue);
    pub fn remove(&mut self, key: impl IntoCaseSensitiveHeaderName) -> Option<HeaderValue>;
    // IterMut<'a>: Iterator<Item = (&'a CaseSensitiveHeaderName, &'a mut HeaderValue)>
    pub fn iter_mut(&mut self) -> IterMut<'_>;
}

pub trait AsCaseSensitiveHeaderName: hdr_as::Sealed {}
pub trait IntoCaseSensitiveHeaderName: hdr_into::Sealed {}

// similar impls, sealed traits as for upstream traits

#[repr(transparent)]
struct CaseSensitiveHeaderName([u8]);