Add revalidated extension

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## development
+
+- Add `revalidated` response extension. (#242)
+
 ## 0.0.27 (31th May, 2024)
 
 - Fix `RedisStorage` when using without ttl. (#231)

docs/advanced/extensions.md

@@ -60,6 +60,23 @@ False
 True
 ```
 
+### revalidated
+
+Every response will have a revalidated extension that indicates whether the response has been revalidated or not.
+
+!!! note
+ Note that a response could have `revalidated` set to `True` even when `from_cache` is set to `False`. This occurs when the cached entry has been updated and a new entry is downloaded during revalidation.
+
+>>> import hishel
+>>> client = hishel.CacheClient()
+>>> response = client.get("https://www.example.com/endpoint_that_is_fresh")
+>>> response.extensions["revalidated"]
+False
+>>> response = client.get("https://www.example.com/endpoint_that_is_stale")
+>>> response.extensions["revalidated"]
+True
+
+
 ### cache_metadata
 
 If `from_cache` is `True`, the response will also include a `cache_metadata` extension with additional information about 

hishel/_async/_pool.py

@@ -100,7 +100,12 @@ async def handle_async_request(self, request: Request) -> Response:
  if isinstance(res, Response):
  # Simply use the response if the controller determines it is ready for use.
  return await self._create_hishel_response(
- key=key, response=stored_response, request=request, metadata=metadata, cached=True
+ key=key,
+ response=stored_response,
+ request=request,
+ metadata=metadata,
+ cached=True,
+ revalidated=False,
  )
 
  if request_cache_control.only_if_cached:
@@ -115,7 +120,12 @@ async def handle_async_request(self, request: Request) -> Response:
  # If there is a connection error, we can use the stale response if allowed.
  if self._controller._allow_stale and allowed_stale(response=stored_response):
  return await self._create_hishel_response(
- key=key, response=stored_response, request=request, metadata=metadata, cached=True
+ key=key,
+ response=stored_response,
+ request=request,
+ metadata=metadata,
+ cached=True,
+ revalidated=False,
  )
  raise # pragma: no cover
  # Merge headers with the stale response.
@@ -130,6 +140,7 @@ async def handle_async_request(self, request: Request) -> Response:
  request=request,
  metadata=metadata,
  cached=revalidation_response.status == 304,
+ revalidated=True,
  )
 
  regular_response = await self._pool.handle_async_request(request)
@@ -141,14 +152,17 @@ async def handle_async_request(self, request: Request) -> Response:
  )
  await self._storage.store(key, response=regular_response, request=request, metadata=metadata)
 
- return await self._create_hishel_response(key=key, response=regular_response, request=request, cached=False)
+ return await self._create_hishel_response(
+ key=key, response=regular_response, request=request, cached=False, revalidated=False
+ )
 
  async def _create_hishel_response(
  self,
  key: str,
  response: Response,
  request: Request,
  cached: bool,
+ revalidated: bool,
  metadata: Metadata | None = None,
  ) -> Response:
  if cached:
@@ -159,6 +173,7 @@ async def _create_hishel_response(
  response.extensions["cache_metadata"] = metadata # type: ignore[index]
  else:
  response.extensions["from_cache"] = False # type: ignore[index]
+ response.extensions["revalidated"] = revalidated # type: ignore[index]
  return response
 
  async def aclose(self) -> None:

hishel/_async/_transports.py

@@ -141,6 +141,7 @@ async def handle_async_request(self, request: Request) -> Response:
  response=res,
  request=httpcore_request,
  cached=True,
+ revalidated=False,
  metadata=metadata,
  )
 
@@ -166,6 +167,7 @@ async def handle_async_request(self, request: Request) -> Response:
  response=stored_response,
  request=httpcore_request,
  cached=True,
+ revalidated=False,
  metadata=metadata,
  )
  raise # pragma: no cover
@@ -191,6 +193,7 @@ async def handle_async_request(self, request: Request) -> Response:
  response=final_httpcore_response,
  request=httpcore_request,
  cached=revalidation_response.status_code == 304,
+ revalidated=True,
  metadata=metadata,
  )
 
@@ -217,6 +220,7 @@ async def handle_async_request(self, request: Request) -> Response:
  response=httpcore_regular_response,
  request=httpcore_request,
  cached=False,
+ revalidated=False,
  )
 
  async def _create_hishel_response(
@@ -225,6 +229,7 @@ async def _create_hishel_response(
  response: httpcore.Response,
  request: httpcore.Request,
  cached: bool,
+ revalidated: bool,
  metadata: Metadata | None = None,
  ) -> Response:
  if cached:
@@ -235,6 +240,7 @@ async def _create_hishel_response(
  response.extensions["cache_metadata"] = metadata # type: ignore[index]
  else:
  response.extensions["from_cache"] = False # type: ignore[index]
+ response.extensions["revalidated"] = revalidated # type: ignore[index]
  return Response(
  status_code=response.status,
  headers=response.headers,

hishel/_sync/_pool.py

@@ -100,7 +100,12 @@ def handle_request(self, request: Request) -> Response:
  if isinstance(res, Response):
  # Simply use the response if the controller determines it is ready for use.
  return self._create_hishel_response(
- key=key, response=stored_response, request=request, metadata=metadata, cached=True
+ key=key,
+ response=stored_response,
+ request=request,
+ metadata=metadata,
+ cached=True,
+ revalidated=False,
  )
 
  if request_cache_control.only_if_cached:
@@ -115,7 +120,12 @@ def handle_request(self, request: Request) -> Response:
  # If there is a connection error, we can use the stale response if allowed.
  if self._controller._allow_stale and allowed_stale(response=stored_response):
  return self._create_hishel_response(
- key=key, response=stored_response, request=request, metadata=metadata, cached=True
+ key=key,
+ response=stored_response,
+ request=request,
+ metadata=metadata,
+ cached=True,
+ revalidated=False,
  )
  raise # pragma: no cover
  # Merge headers with the stale response.
@@ -130,6 +140,7 @@ def handle_request(self, request: Request) -> Response:
  request=request,
  metadata=metadata,
  cached=revalidation_response.status == 304,
+ revalidated=True,
  )
 
  regular_response = self._pool.handle_request(request)
@@ -141,14 +152,17 @@ def handle_request(self, request: Request) -> Response:
  )
  self._storage.store(key, response=regular_response, request=request, metadata=metadata)
 
- return self._create_hishel_response(key=key, response=regular_response, request=request, cached=False)
+ return self._create_hishel_response(
+ key=key, response=regular_response, request=request, cached=False, revalidated=False
+ )
 
  def _create_hishel_response(
  self,
  key: str,
  response: Response,
  request: Request,
  cached: bool,
+ revalidated: bool,
  metadata: Metadata | None = None,
  ) -> Response:
  if cached:
@@ -159,6 +173,7 @@ def _create_hishel_response(
  response.extensions["cache_metadata"] = metadata # type: ignore[index]
  else:
  response.extensions["from_cache"] = False # type: ignore[index]
+ response.extensions["revalidated"] = revalidated # type: ignore[index]
  return response
 
  def close(self) -> None:

hishel/_sync/_transports.py

@@ -141,6 +141,7 @@ def handle_request(self, request: Request) -> Response:
  response=res,
  request=httpcore_request,
  cached=True,
+ revalidated=False,
  metadata=metadata,
  )
 
@@ -166,6 +167,7 @@ def handle_request(self, request: Request) -> Response:
  response=stored_response,
  request=httpcore_request,
  cached=True,
+ revalidated=False,
  metadata=metadata,
  )
  raise # pragma: no cover
@@ -191,6 +193,7 @@ def handle_request(self, request: Request) -> Response:
  response=final_httpcore_response,
  request=httpcore_request,
  cached=revalidation_response.status_code == 304,
+ revalidated=True,
  metadata=metadata,
  )
 
@@ -217,6 +220,7 @@ def handle_request(self, request: Request) -> Response:
  response=httpcore_regular_response,
  request=httpcore_request,
  cached=False,
+ revalidated=False,
  )
 
  def _create_hishel_response(
@@ -225,6 +229,7 @@ def _create_hishel_response(
  response: httpcore.Response,
  request: httpcore.Request,
  cached: bool,
+ revalidated: bool,
  metadata: Metadata | None = None,
  ) -> Response:
  if cached:
@@ -235,6 +240,7 @@ def _create_hishel_response(
  response.extensions["cache_metadata"] = metadata # type: ignore[index]
  else:
  response.extensions["from_cache"] = False # type: ignore[index]
+ response.extensions["revalidated"] = revalidated # type: ignore[index]
  return Response(
  status_code=response.status,
  headers=response.headers,

tests/_async/test_pool.py

@@ -49,6 +49,7 @@ async def test_pool_response_validation():
  response = await cache_pool.handle_async_request(request)
  assert response.status == 200
  assert response.extensions["from_cache"]
+ assert response.extensions["revalidated"]
  assert header_presents(response.headers, b"Content-Type")
  assert extract_header_values(response.headers, b"Content-Type", single=True)[0] == b"application/json"
  assert await response.aread() == b"test"

tests/_async/test_transport.py

@@ -54,6 +54,7 @@ async def test_transport_response_validation():
  response = await cache_transport.handle_async_request(request)
  assert response.status_code == 200
  assert response.extensions["from_cache"]
+ assert response.extensions["revalidated"]
  assert "Content-Type" in response.headers
  assert response.headers["Content-Type"] == "application/json"
  assert await response.aread() == b"test"

tests/_sync/test_pool.py

@@ -49,6 +49,7 @@ def test_pool_response_validation():
  response = cache_pool.handle_request(request)
  assert response.status == 200
  assert response.extensions["from_cache"]
+ assert response.extensions["revalidated"]
  assert header_presents(response.headers, b"Content-Type")
  assert extract_header_values(response.headers, b"Content-Type", single=True)[0] == b"application/json"
  assert response.read() == b"test"

tests/_sync/test_transport.py

@@ -54,6 +54,7 @@ def test_transport_response_validation():
  response = cache_transport.handle_request(request)
  assert response.status_code == 200
  assert response.extensions["from_cache"]
+ assert response.extensions["revalidated"]
  assert "Content-Type" in response.headers
  assert response.headers["Content-Type"] == "application/json"
  assert response.read() == b"test"