The current API is correct, and powerful, but a bit hard to use. We should offer a simpler version...

I've been using, but been quite nervous about, using unreachable!() for this code path. Could you also add some explicit clarification/guarantees on under what conditions a NotModified won't be returned?

Yes. In addition, I think we should provide an extension trait that simplifies the API and makes this clear via the type system. Something like:

pub trait CredentialsExt {
    async fn cached_headers(&self) -> Result<HeaderMap> { .... }

(and I'm also very very happy this exists, to replace the hacky code we had to use before now - also appreciate the huge amount of work that's obviously gone into it)

Thanks for saying that.

Originally posted by @coryan in #3361