Add a cache status header to the response

The header name is configurable, and defaults to `X-FastAPI-Cache`,
the value is either `HIT` or `MISS`.

Note that the header is not set at all when the cache is disabled.

tests/test_decorator.py

@@ -20,15 +20,18 @@ def init_cache() -> Generator[Any, Any, None]:
 def test_datetime() -> None:
     with TestClient(app) as client:
         response = client.get("/datetime")
+        assert response.headers.get("X-FastAPI-Cache") == "MISS"
         now = response.json().get("now")
         now_ = pendulum.now().replace(microsecond=0)  # type: ignore[no-untyped-call]
         assert pendulum.parse(now).replace(microsecond=0) == now_  # type: ignore[attr-defined]
         response = client.get("/datetime")
+        assert response.headers.get("X-FastAPI-Cache") == "HIT"
         now = response.json().get("now")
         assert pendulum.parse(now).replace(microsecond=0) == now_  # type: ignore[attr-defined]
         time.sleep(3)
         response = client.get("/datetime")
         now = response.json().get("now")
+        assert response.headers.get("X-FastAPI-Cache") == "MISS"
         now = pendulum.parse(now).replace(microsecond=0)  # type: ignore[attr-defined]
         assert now != now_
         assert now == pendulum.now().replace(microsecond=0)  # type: ignore[no-untyped-call]
@@ -38,15 +41,18 @@ def test_date() -> None:
     """Test path function without request or response arguments."""
     with TestClient(app) as client:
         response = client.get("/date")
+        assert response.headers.get("X-FastAPI-Cache") == "MISS"
         assert pendulum.parse(response.json()) == pendulum.today()  # type: ignore[attr-defined]
 
         # do it again to test cache
         response = client.get("/date")
+        assert response.headers.get("X-FastAPI-Cache") == "HIT"
         assert pendulum.parse(response.json()) == pendulum.today()  # type: ignore[attr-defined]
 
         # now test with cache disabled, as that's a separate code path
         FastAPICache._enable = False  # pyright: ignore[reportPrivateUsage]
         response = client.get("/date")
+        assert "X-FastAPI-Cache" not in response.headers
         assert pendulum.parse(response.json()) == pendulum.today()  # type: ignore[attr-defined]
         FastAPICache._enable = True  # pyright: ignore[reportPrivateUsage]
 
@@ -72,6 +78,7 @@ def test_kwargs() -> None:
     with TestClient(app) as client:
         name = "Jon"
         response = client.get("/kwargs", params={"name": name})
+        assert "X-FastAPI-Cache" not in response.headers
         assert response.json() == {"name": name}
 
 
@@ -83,20 +90,25 @@ def test_method() -> None:
 
 def test_pydantic_model() -> None:
     with TestClient(app) as client:
-        r1 = client.get("/pydantic_instance").json()
-        r2 = client.get("/pydantic_instance").json()
-        assert r1 == r2
+        r1 = client.get("/pydantic_instance")
+        assert r1.headers.get("X-FastAPI-Cache") == "MISS"
+        r2 = client.get("/pydantic_instance")
+        assert r2.headers.get("X-FastAPI-Cache") == "HIT"
+        assert r1.json() == r2.json()
 
 
 def test_non_get() -> None:
     with TestClient(app) as client:
         response = client.put("/uncached_put")
+        assert "X-FastAPI-Cache" not in response.headers
         assert response.json() == {"value": 1}
         response = client.put("/uncached_put")
+        assert "X-FastAPI-Cache" not in response.headers
         assert response.json() == {"value": 2}
 
 
 def test_alternate_injected_namespace() -> None:
     with TestClient(app) as client:
         response = client.get("/namespaced_injection")
+        assert response.headers.get("X-FastAPI-Cache") == "MISS"
         assert response.json() == {"__fastapi_cache_request": 42, "__fastapi_cache_response": 17}