Usability issues with `Authorization` parsing

[roy-work]

Version

headers 0.4.1

Platform

Darwin [snip] 25.5.0 Darwin Kernel Version 25.5.0: Mon Apr 27 20:41:06 PDT 2026; root:xnu-12377.121.6~2/RELEASE_ARM64_T6030 arm64

Summary

It's impossible for a caller to differentiate between the cases needed.

Broadly speaking, I think there are 3 different returns from parsing this header:

1. The Authorization header is present, well-formed. (And maybe, of a type we support.) We probably want an Ok(…) here, and the caller will translate this to either 200 or 401, depending on the validity of the credentials supplied.
2. The Authorization header is missing altogether. The caller will likely want to return a 401. (Or otherwise treat the request as unauthenticated.)
3. The Authorization header is present and malformed. The caller will want to return a 400.

Distinguishing between these cases accurately with the library is tough. Err(Invalid) is returned if the header isn't parsable, so we might think that should be translated to 400. But it's also returned in the absence of the header, or if the header is present and well-formed, but we want Bearer but got Basic, or something similar. In that case, it should be a 401. But there is no means for the caller to distinguish these cases.

I've attached a test case; the assert! statements are not authoritative, since there's not really a good way to write the right asserts here.

Code Sample

#[cfg(test)]
mod tests {
    use headers::Header;

    #[test]
    fn test_no_headers() {
        let result = headers::Authorization::<headers::authorization::Bearer>::decode(&mut [].into_iter());
        println!("result = {:#?}", result);
        // This isn't an error per se — the request isn't malformed. We'll want to return a 401.
        assert!(result.is_err());
    }

    #[test]
    fn test_multiple() {
        let headers = [
            http::HeaderValue::from_static("Bearer 123"),
            http::HeaderValue::from_static("Basic dXNlcjpwYXNz"),
        ];
        let result = headers::Authorization::<headers::authorization::Bearer>::decode(
            &mut headers.iter(),
        );
        println!("result = {:#?}", result);
        // This should be an error: multiple `Authorization` headers are malformed, but this will
        // assert.
        assert!(result.is_err());
    }

    #[test]
    fn test_wrong() {
        let headers = [
            http::HeaderValue::from_static("Basic dXNlcjpwYXNz"),
        ];
        let result = headers::Authorization::<headers::authorization::Bearer>::decode(
            &mut headers.iter(),
        );
        println!("result = {:#?}", result);
        // This isn't an error per se — the request isn't malformed, but the expected header isn't
        // present. We'll want to return 401.
        assert!(result.is_err());
    }
}

Expected Behavior

A caller can accurately distinguish "wrong auth", "malformed message", and "potentially suitable auth".

Actual Behavior

There's only 1 error value, so that is impossible.

I wonder if -> Result<Option<Authorization>, _> would suffice, but I don't know if that's possible with the trait.

Additional Context

Obviously, the caller can do some pre-parsing … but what's the point of the library? 😉

I would also want a generic implementation of Authorization that can handle multiple/all types, in the case that one might accept Bearer or Basic. Yes, we can make two passes at parsing the header, but we'd repeat all the work of finding the scheme, which is a bit of a bummer.

[seanmonstar]

Yea, I'll admit, the Authorization header is likely incorrectly designed. It's one of the oldest ones. Breaking changes for the headers crate is a lot more palpable since the trait has been separated. If we could redesign it, what would it look like?