feat: add support for request no-cache directive (#416)

* Add support for request no-cache directive

* fix tests

* fix: ensure `is_corrupted` coroutine is awaited (#417)

Author: karpetrosyan

hishel/_core/_spec.py

@@ -1207,6 +1207,7 @@ def next(
         - Unsafe methods (POST, PUT, DELETE, etc.) are written through to origin
         - Multiple matching responses are sorted by Date header (most recent first)
         - Age header is updated when serving from cache
+        - Request no-cache directive forces revalidation of cached responses
 
         Examples:
         --------
@@ -1229,6 +1230,18 @@ def next(
         >>> next_state = idle.next(get_request, [cached_pair])
         >>> isinstance(next_state, NeedRevalidation)
         True
+
+        >>> # Need revalidation - request no-cache forces validation of fresh response
+        >>> idle = IdleClient(options=default_options)
+        >>> no_cache_request = Request(
+        ...     method="GET",
+        ...     url="https://example.com",
+        ...     headers=Headers({"cache-control": "no-cache"})
+        ... )
+        >>> cached_pair = CompletePair(no_cache_request, fresh_response)
+        >>> next_state = idle.next(no_cache_request, [cached_pair])
+        >>> isinstance(next_state, NeedRevalidation)
+        True
         """
 
         # ============================================================================
@@ -1388,7 +1401,31 @@ def fresh_or_allowed_stale(pair: Entry) -> bool:
         ready_to_use, need_revalidation = partition(filtered_pairs, fresh_or_allowed_stale)
 
         # ============================================================================
-        # STEP 7: Determine Next State Based on Available Responses
+        # STEP 7: Handle Request no-cache Directive
+        # ============================================================================
+        # RFC 9111 Section 5.2.1.4: no-cache Request Directive
+        # https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.1.4
+        #
+        # "The no-cache request directive indicates that a cache MUST NOT use a
+        # stored response to satisfy the request without successful validation on
+        # the origin server."
+        #
+        # When a client sends Cache-Control: no-cache in the request, it's explicitly
+        # requesting that the cache not use any stored response without first validating
+        # it with the origin server. This is different from the response no-cache directive,
+        # which applies to how responses should be cached.
+        request_cache_control = parse_cache_control(request.headers.get("cache-control"))
+
+        if request_cache_control.no_cache is True:
+            # Move all fresh responses to the revalidation queue
+            # This ensures that even fresh cached responses will be validated
+            # with the origin server via conditional requests (If-None-Match,
+            # If-Modified-Since) before being served to the client.
+            need_revalidation.extend(ready_to_use)
+            ready_to_use = []
+
+        # ============================================================================
+        # STEP 8: Determine Next State Based on Available Responses
         # ============================================================================
 
         if ready_to_use:

hishel/_core/_storages/_async_sqlite.py

@@ -340,8 +340,8 @@ async def _batch_cleanup(
             await connection.commit()
 
         async def _is_corrupted(self, pair: Entry, cursor: anysqlite.Cursor) -> bool:
-            # if entry was created more than 1 hour ago and still has no response (incomplete)
-            if pair.meta.created_at + 3600 < time.time() and not self._is_stream_complete(pair.id, cursor):
+            # if entry was created more than 1 hour ago and still has no full response data
+            if pair.meta.created_at + 3600 < time.time() and not (await self._is_stream_complete(pair.id, cursor)):
                 return True
             return False
 

hishel/_core/_storages/_sync_sqlite.py

@@ -340,8 +340,8 @@ def _batch_cleanup(
             connection.commit()
 
         def _is_corrupted(self, pair: Entry, cursor: sqlite3.Cursor) -> bool:
-            # if entry was created more than 1 hour ago and still has no response (incomplete)
-            if pair.meta.created_at + 3600 < time.time() and not self._is_stream_complete(pair.id, cursor):
+            # if entry was created more than 1 hour ago and still has no full response data
+            if pair.meta.created_at + 3600 < time.time() and not (self._is_stream_complete(pair.id, cursor)):
                 return True
             return False
 

tests/_core/_async/test_sqlite_storage.py

@@ -379,6 +379,7 @@ async def mock_connect(*args, **kwargs):
 
 
 @pytest.mark.anyio
+@travel(datetime(2024, 1, 1, 0, 0, 0, tzinfo=ZoneInfo("UTC")))
 async def test_incomplete_entries() -> None:
     """Test incomplete entries"""
     storage = AsyncSqliteStorage(connection=await anysqlite.connect(":memory:"))
@@ -412,7 +413,7 @@ async def test_incomplete_entries() -> None:
     id              = (bytes) 0x0000000000000000000000000000000a (16 bytes)
     cache_key       = (str) 'incomplete_key'
     data            = (bytes) 0x85a26964c4100000000000000000000000000000000aa772657175657374... (186 bytes)
-    created_at      = 2025-11-08
+    created_at      = 2024-01-01
     deleted_at      = NULL
 
 TABLE: streams

tests/_core/_sync/test_sqlite_storage.py

@@ -379,6 +379,7 @@ def mock_connect(*args, **kwargs):
 
 
 
+@travel(datetime(2024, 1, 1, 0, 0, 0, tzinfo=ZoneInfo("UTC")))
 def test_incomplete_entries() -> None:
     """Test incomplete entries"""
     storage = SyncSqliteStorage(connection=sqlite3.connect(":memory:"))
@@ -412,7 +413,7 @@ def test_incomplete_entries() -> None:
     id              = (bytes) 0x0000000000000000000000000000000a (16 bytes)
     cache_key       = (str) 'incomplete_key'
     data            = (bytes) 0x85a26964c4100000000000000000000000000000000aa772657175657374... (186 bytes)
-    created_at      = 2025-11-08
+    created_at      = 2024-01-01
     deleted_at      = NULL
 
 TABLE: streams

tests/_core/spec/test_idle_client.py

@@ -736,6 +736,44 @@ def test_multiple_stale_responses_all_included_in_revalidation(self, idle_client
         assert isinstance(next_state, NeedRevalidation)
         assert len(next_state.revalidating_entries) == 2
 
+    def test_request_no_cache_forces_revalidation_of_fresh_response(self, idle_client: IdleClient) -> None:
+        """
+        Test: Request no-cache directive forces revalidation even for fresh responses.
+
+        RFC 9111 Section 5.2.1.4: no-cache Request Directive
+        "The no-cache request directive indicates that a cache MUST NOT use a
+        stored response to satisfy the request without successful validation on
+        the origin server."
+
+        Even if a cached response is fresh, the request no-cache directive
+        forces the cache to revalidate it with the origin server.
+        """
+        # Arrange
+        # Request with no-cache directive
+        request = create_request(headers={"cache-control": "no-cache"})
+
+        # Fresh cached response: age 1800s < max-age 3600s
+        fresh_response = create_response(
+            age_seconds=1800,
+            max_age_seconds=3600,
+            headers={"etag": '"abc123"'},
+        )
+        cached_pair = create_pair(request=request, response=fresh_response)
+
+        # Act
+        next_state = idle_client.next(request, [cached_pair])
+
+        # Assert
+        # Despite being fresh, response must be revalidated due to request no-cache
+        assert isinstance(next_state, NeedRevalidation)
+        assert next_state.original_request == request
+        assert len(next_state.revalidating_entries) == 1
+        assert next_state.revalidating_entries[0] == cached_pair
+
+        # Verify conditional request is created with validators
+        assert "if-none-match" in next_state.request.headers
+        assert next_state.request.headers["if-none-match"] == '"abc123"'
+
 
 # =============================================================================
 # Test Suite 4: Edge Cases and RFC 9111 Compliance