feat: add a "revalidation hook" to Cache to allow for recalculation of authentication.

This commit adds a `with_revalidation_hook` method to `Cache` that
allows users to control the headers sent as part of a cache revalidation
request.

This is needed for Azure Storage where they inexplicably use conditional
request headers like `If-None-Match` as part of the authentication
signature, which breaks transparent caching middleware like this one.

With the hook, a new `Authorization` header can be calculated and then
overridden for the request to revalidate.

Author: peterhuene

crates/reqwest/src/lib.rs

@@ -43,13 +43,15 @@ pub use http_cache_stream::X_CACHE_LOOKUP;
 use http_cache_stream::http::Extensions;
 use http_cache_stream::http::Uri;
 use http_cache_stream::http_body::Frame;
+pub use http_cache_stream::semantics;
 pub use http_cache_stream::semantics::CacheOptions;
 pub use http_cache_stream::storage;
 pub use http_cache_stream::storage::CacheStorage;
 use reqwest::Body;
 use reqwest::Request;
 use reqwest::Response;
 use reqwest::ResponseBuilderExt;
+use reqwest::header::HeaderMap;
 use reqwest_middleware::Next;
 
 pin_project_lite::pin_project! {
@@ -152,6 +154,24 @@ impl<S: CacheStorage> Cache<S> {
         Self(http_cache_stream::Cache::new_with_options(storage, options))
     }
 
+    /// Sets the revalidation hook to use.
+    ///
+    /// The hook is provided the original request and a mutable header map
+    /// containing headers explicitly set for the revalidation request.
+    ///
+    /// For example, a hook may alter the revalidation headers to update an
+    /// `Authorization` header based on the headers used for revalidation.
+    ///
+    /// If the hook returns an error, the error is propagated out as the result
+    /// of the original request.
+    pub fn with_revalidation_hook(
+        mut self,
+        hook: impl Fn(&dyn semantics::RequestLike, &mut HeaderMap) -> Result<()> + Send + Sync + 'static,
+    ) -> Self {
+        self.0 = self.0.with_revalidation_hook(hook);
+        self
+    }
+
     /// Gets the underlying storage of the cache.
     pub fn storage(&self) -> &S {
         self.0.storage()

src/cache.rs

@@ -291,12 +291,31 @@ impl http_cache_semantics::RequestLike for RequestLike {
     }
 }
 
+/// Represents a revalidation hook.
+///
+/// The hook is provided the original request and a mutable header map
+/// containing headers explicitly set for the revalidation request.
+///
+/// For example, a hook may alter the revalidation headers to update an
+/// `Authorization` header based on the headers used for revalidation.
+///
+/// If the hook returns an error, the error is propagated out as the result of
+/// the original request.
+type RevalidationHook = dyn Fn(&dyn http_cache_semantics::RequestLike, &mut HeaderMap) -> Result<()>
+    + Send
+    + Sync
+    + 'static;
+
 /// Implement a HTTP cache.
 pub struct Cache<S> {
     /// The cache storage.
     storage: S,
     /// The cache options to use.
     options: CacheOptions,
+    /// Stores the revalidation hook.
+    ///
+    /// This is `None` if no revalidation hook is used.
+    hook: Option<Box<RevalidationHook>>,
 }
 
 impl<S> Cache<S>
@@ -314,12 +333,38 @@ where
                 shared: false,
                 ..Default::default()
             },
+            hook: None,
         }
     }
 
     /// Construct a new cache with the given storage and options.
     pub fn new_with_options(storage: S, options: CacheOptions) -> Self {
-        Self { storage, options }
+        Self {
+            storage,
+            options,
+            hook: None,
+        }
+    }
+
+    /// Sets the revalidation hook to use.
+    ///
+    /// The hook is provided the original request and a mutable header map
+    /// containing headers explicitly set for the revalidation request.
+    ///
+    /// For example, a hook may alter the revalidation headers to update an
+    /// `Authorization` header based on the headers used for revalidation.
+    ///
+    /// If the hook returns an error, the error is propagated out as the result
+    /// of the original request.
+    pub fn with_revalidation_hook(
+        mut self,
+        hook: impl Fn(&dyn http_cache_semantics::RequestLike, &mut HeaderMap) -> Result<()>
+        + Send
+        + Sync
+        + 'static,
+    ) -> Self {
+        self.hook = Some(Box::new(hook));
+        self
     }
 
     /// Gets the storage used by the cache.
@@ -469,7 +514,7 @@ where
     ) -> Result<Response<Body<B>>> {
         let request_like = RequestLike::new(&request);
 
-        let headers = match stored
+        let mut headers = match stored
             .policy
             .before_request(&request_like, SystemTime::now())
         {
@@ -511,6 +556,13 @@ where
             "response is stale: sending request upstream for validation"
         );
 
+        // Invoke the revalidation hook if the request will be different headers
+        if let Some(headers) = &mut headers
+            && let Some(hook) = &self.hook
+        {
+            hook(&request_like, headers)?;
+        }
+
         // Revalidate the request
         match request.send(headers).await {
             Ok(response) if response.status().is_success() => {