Hit cache indication (#532)

* endpoint_params

* response_hit_indication

* revert endpoint_params

* unrevert endpoint_params

* revert

* tester
change log

---------

Co-authored-by: Ido Shraga <[email protected]>
Co-authored-by: northernSage <[email protected]>

CHANGES.rst

@@ -1,6 +1,14 @@
 Changelog
 =========
 
+
+Version 2.3.0
+-------------
+
+- add indication if cache is used  in the response header.
+- Added ``response_hit_indication`` flag to ``Cache.cached`` decorator for appending 'hit_cache' headers to responses, indicating cache hits.
+
+
 Version 2.2.0
 -------------
 
@@ -18,6 +26,7 @@ Released 2024-10-08
 - Added docs and example for make_cache_key
 - support Flask 3
 
+
 Version 2.0.2
 -------------
 

src/flask_caching/__init__.py

@@ -251,6 +251,7 @@ def cached(
         cache_none: bool = False,
         make_cache_key: Optional[Callable] = None,
         source_check: Optional[bool] = None,
+        response_hit_indication: Optional[bool] = False,
     ) -> Callable:
         """Decorator. Use this to cache a function. By default the cache key
         is `view/request.path`. You are able to use this decorator with any
@@ -351,6 +352,10 @@ def get_list():
                              formed with the function's source code hash in
                              addition to other parameters that may be included
                              in the formation of the key.
+
+        :param response_hit_indication: Default False.
+                             If True, it will add to response header field 'hit_cache'
+                             if used cache.
         """
 
         def decorator(f):
@@ -406,6 +411,16 @@ def decorated_function(*args, **kwargs):
                         raise
                     logger.exception("Exception possibly due to cache backend.")
                     return self._call_fn(f, *args, **kwargs)
+                if found and self.app.debug:
+                    logger.info(f"Cache used for key: {cache_key}")
+                if response_hit_indication:
+
+                    def apply_caching(response):
+                        if found:
+                            response.headers["hit_cache"] = found
+                        return response
+
+                    self.app.after_request_funcs[None].append(apply_caching)
 
                 if not found:
                     rv = self._call_fn(f, *args, **kwargs)

tests/test_view.py

@@ -573,3 +573,17 @@ def view_works():
     # Now make sure the time for the first and third responses are the same
     # i.e. cached is used since cache will not check for source changes!
     assert third_time == first_time
+
+
+def test_hit_cache(app, cache):
+    @app.route("/")
+    @cache.cached(10, response_hit_indication=True)
+    def cached_view():
+        # This should override the timeout to be 2 seconds
+        return {"data": "data"}
+
+    tc = app.test_client()
+
+    assert tc.get("/").headers.get("hit_cache") is None
+    assert tc.get("/").headers.get("hit_cache") == "True"
+    assert tc.get("/").headers.get("hit_cache") == "True"