hishel 1.0.0.dev2__py3-none-any.whl → 1.1.0__py3-none-any.whl

hishel/_core/_spec.py

@@ -9,7 +9,6 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Dict,
-    Literal,
     Optional,
     TypeVar,
     Union,
@@ -20,7 +19,7 @@ from hishel._core.models import ResponseMetadata
 from hishel._utils import parse_date, partition
 
 if TYPE_CHECKING:
-    from hishel import CompletePair, Request, Response
+    from hishel import Entry, Request, Response
 
 
 TState = TypeVar("TState", bound="State")
@@ -145,7 +144,7 @@ class State(ABC):
 
 def vary_headers_match(
     original_request: Request,
-    associated_pair: CompletePair,
+    associated_entry: Entry,
 ) -> bool:
     """
     Determines if request headers match the Vary requirements of a cached response.
@@ -161,8 +160,8 @@ def vary_headers_match(
     ----------
     original_request : Request
         The new incoming request that we're trying to satisfy
-    associated_pair : CompletePair
-        A cached request-response pair that might match the new request
+    associated_entry : Entry
+        A cached request-response entry that might match the new request
 
     Returns:
     -------
@@ -195,31 +194,31 @@ def vary_headers_match(
     >>> # No Vary header - always matches
     >>> request = Request(headers=Headers({"accept": "application/json"}))
     >>> response = Response(headers=Headers({}))  # No Vary
-    >>> pair = CompletePair(request=request, response=response)
-    >>> vary_headers_match(request, pair)
+    >>> entry = Entry(request=request, response=response)
+    >>> vary_headers_match(request, entry)
     True
 
     >>> # Vary: Accept with matching Accept header
     >>> request1 = Request(headers=Headers({"accept": "application/json"}))
     >>> response = Response(headers=Headers({"vary": "Accept"}))
-    >>> pair = CompletePair(request=request1, response=response)
+    >>> entry = Entry(request=request1, response=response)
     >>> request2 = Request(headers=Headers({"accept": "application/json"}))
-    >>> vary_headers_match(request2, pair)
+    >>> vary_headers_match(request2, entry)
     True
 
     >>> # Vary: Accept with non-matching Accept header
     >>> request2 = Request(headers=Headers({"accept": "application/xml"}))
-    >>> vary_headers_match(request2, pair)
+    >>> vary_headers_match(request2, entry)
     False
 
     >>> # Vary: * always fails
     >>> response = Response(headers=Headers({"vary": "*"}))
-    >>> pair = CompletePair(request=request1, response=response)
-    >>> vary_headers_match(request2, pair)
+    >>> entry = Entry(request=request1, response=response)
+    >>> vary_headers_match(request2, entry)
     False
     """
     # Extract the Vary header from the cached response
-    vary_header = associated_pair.response.headers.get("vary")
+    vary_header = associated_entry.response.headers.get("vary")
 
     # If no Vary header exists, any request matches
     # The response doesn't vary based on request headers
@@ -242,7 +241,7 @@ def vary_headers_match(
 
         # Compare the specific header value between original and new request
         # Both headers must have the same value (or both be absent)
-        if original_request.headers.get(vary_header) != associated_pair.request.headers.get(vary_header):
+        if original_request.headers.get(vary_header) != associated_entry.request.headers.get(vary_header):
             return False
 
     # All Vary headers matched
@@ -1121,19 +1120,13 @@ AnyState = Union[
     "NeedToBeUpdated",
     "NeedRevalidation",
     "IdleClient",
-    "InvalidatePairs",
+    "InvalidateEntries",
 ]
 
 # Defined in https://www.rfc-editor.org/rfc/rfc9110#name-safe-methods
 SAFE_METHODS = frozenset(["GET", "HEAD", "OPTIONS", "TRACE"])
 
 
-def create_idle_state(role: Literal["client", "server"], options: Optional[CacheOptions] = None) -> IdleClient:
-    if role == "server":
-        raise NotImplementedError("Server role is not implemented yet.")
-    return IdleClient(options=options or CacheOptions())
-
-
 @dataclass
 class IdleClient(State):
     """
@@ -1167,7 +1160,7 @@ class IdleClient(State):
     """
 
     def next(
-        self, request: Request, associated_pairs: list[CompletePair]
+        self, request: Request, associated_entries: list[Entry]
     ) -> Union["CacheMiss", "FromCache", "NeedRevalidation"]:
         """
         Determines the next state transition based on the request and available cached responses.
@@ -1180,9 +1173,9 @@ class IdleClient(State):
         ----------
         request : Request
             The incoming HTTP request from the client
-        associated_pairs : list[CompletePair]
-            List of request-response pairs previously stored in the cache that may match
-            this request. These pairs are pre-filtered by cache key (typically URI).
+        associated_entries : list[Entry]
+            List of request-response entries previously stored in the cache that may match
+            this request. These entries are pre-filtered by cache key (typically URI).
 
         Returns:
         -------
@@ -1317,7 +1310,7 @@ class IdleClient(State):
         #
         # If a cached response has Cache-Control: no-cache, it cannot be reused without
         # validation, regardless of its freshness.
-        def no_cache_missing(pair: CompletePair) -> bool:
+        def no_cache_missing(pair: Entry) -> bool:
             """Check if the cached response lacks the no-cache directive."""
             return parse_cache_control(pair.response.headers.get("cache-control")).no_cache is False
 
@@ -1332,7 +1325,7 @@ class IdleClient(State):
         #
         # Note: Condition 5.3 (successfully validated) is handled in the
         # NeedRevalidation state, not here.
-        def fresh_or_allowed_stale(pair: CompletePair) -> bool:
+        def fresh_or_allowed_stale(pair: Entry) -> bool:
             """
             Determine if a cached response is fresh or allowed to be served stale.
 
@@ -1361,7 +1354,7 @@ class IdleClient(State):
         # "ready to use" and "needs revalidation" groups.
         filtered_pairs = [
             pair
-            for pair in associated_pairs
+            for pair in associated_entries
             if url_matches(pair) and method_matches(pair) and vary_headers_same(pair) and no_cache_missing(pair)  # type: ignore[no-untyped-call]
         ]
 
@@ -1419,7 +1412,7 @@ class IdleClient(State):
             # Calculate current age and update the Age header
             current_age = get_age(selected_pair.response)
             return FromCache(
-                pair=replace(
+                entry=replace(
                     selected_pair,
                     response=replace(
                         selected_pair.response,
@@ -1455,7 +1448,7 @@ class IdleClient(State):
             # (ETag, Last-Modified) from the cached response.
             return NeedRevalidation(
                 request=make_conditional_request(request, need_revalidation[-1].response),
-                revalidating_pairs=need_revalidation,
+                revalidating_entries=need_revalidation,
                 options=self.options,
                 original_request=request,
             )
@@ -1525,7 +1518,7 @@ class CacheMiss(State):
     Indicates whether the cache miss occurred after a revalidation attempt.
     """
 
-    def next(self, response: Response, pair_id: uuid.UUID) -> Union["StoreAndUse", "CouldNotBeStored"]:
+    def next(self, response: Response) -> Union["StoreAndUse", "CouldNotBeStored"]:
         """
         Evaluates whether a response can be stored in the cache.
 
@@ -1582,7 +1575,7 @@ class CacheMiss(State):
         ...     status_code=200,
         ...     headers=Headers({"cache-control": "max-age=3600"})
         ... )
-        >>> next_state = cache_miss.next(response, uuid.uuid4())
+        >>> next_state = cache_miss.next(response)
         >>> isinstance(next_state, StoreAndUse)
         True
 
@@ -1591,7 +1584,7 @@ class CacheMiss(State):
         ...     status_code=200,
         ...     headers=Headers({"cache-control": "no-store"})
         ... )
-        >>> next_state = cache_miss.next(response, uuid.uuid4())
+        >>> next_state = cache_miss.next(response)
         >>> isinstance(next_state, CouldNotBeStored)
         True
         """
@@ -1816,7 +1809,9 @@ class CacheMiss(State):
                     )
 
             return CouldNotBeStored(
-                response=response, pair_id=pair_id, options=self.options, after_revalidation=self.after_revalidation
+                response=response,
+                options=self.options,
+                after_revalidation=self.after_revalidation,
             )
 
         # --------------------------------------------------------------------
@@ -1833,7 +1828,6 @@ class CacheMiss(State):
         cleaned_response = exclude_unstorable_headers(response, self.options.shared)
 
         return StoreAndUse(
-            pair_id=pair_id,
             response=cleaned_response,
             options=self.options,
             after_revalidation=self.after_revalidation,
@@ -1856,7 +1850,7 @@ class NeedRevalidation(State):
     State Transitions:
     -----------------
     - NeedToBeUpdated: 304 response received, cached responses can be freshened
-    - InvalidatePairs + CacheMiss: 2xx/5xx response received, new response must be cached
+    - InvalidateEntries + CacheMiss: 2xx/5xx response received, new response must be cached
     - CacheMiss: No matching responses found during freshening
 
     RFC 9111 References:
@@ -1877,8 +1871,8 @@ class NeedRevalidation(State):
     original_request : Request
         The original client request (without conditional headers) that initiated
         this revalidation. This is used when creating new cache entries.
-    revalidating_pairs : list[CompletePair]
-        The cached request-response pairs that are being revalidated. These are
+    revalidating_entries : list[Entry]
+        The cached request-response entries that are being revalidated. These are
         stale responses that might still be usable if the server confirms they
         haven't changed (304 response).
     options : CacheOptions
@@ -1892,14 +1886,14 @@ class NeedRevalidation(State):
 
     original_request: Request
 
-    revalidating_pairs: list[CompletePair]
+    revalidating_entries: list[Entry]
     """
-    The stored pairs that the request was sent for revalidation.
+    The stored entries that the request was sent for revalidation.
     """
 
     def next(
         self, revalidation_response: Response
-    ) -> Union["NeedToBeUpdated", "InvalidatePairs", "CacheMiss", "FromCache"]:
+    ) -> Union["NeedToBeUpdated", "InvalidateEntries", "CacheMiss", "FromCache", "StoreAndUse", "CouldNotBeStored"]:
         """
         Handles the response to a conditional request and determines the next state.
 
@@ -1919,9 +1913,9 @@ class NeedRevalidation(State):
 
         Returns:
         -------
-        Union[NeedToBeUpdated, InvalidatePairs, CacheMiss]
+        Union[NeedToBeUpdated, InvalidateEntries, CacheMiss]
             - NeedToBeUpdated: When 304 response allows cached responses to be freshened
-            - InvalidatePairs: When old responses must be invalidated (wraps next state)
+            - InvalidateEntries: When old responses must be invalidated (wraps next state)
             - CacheMiss: When no matching responses found or storing new response
 
         RFC 9111 Compliance:
@@ -1956,7 +1950,7 @@ class NeedRevalidation(State):
         >>> need_revalidation = NeedRevalidation(
         ...     request=conditional_request,
         ...     original_request=original_request,
-        ...     revalidating_pairs=[cached_pair],
+        ...     revalidating_entries=[cached_entry],
         ...     options=default_options
         ... )
         >>> response_304 = Response(status_code=304, headers=Headers({"etag": '"abc123"'}))
@@ -1967,7 +1961,7 @@ class NeedRevalidation(State):
         >>> # 200 OK - use new response
         >>> response_200 = Response(status_code=200, headers=Headers({"cache-control": "max-age=3600"}))
         >>> next_state = need_revalidation.next(response_200)
-        >>> isinstance(next_state, InvalidatePairs)
+        >>> isinstance(next_state, InvalidateEntries)
         True
         """
 
@@ -2006,17 +2000,19 @@ class NeedRevalidation(State):
         # 2. Store the new response (if cacheable)
         # 3. Use the new response to satisfy the request
         elif revalidation_response.status_code // 100 == 2:
-            # Invalidate all old pairs except the last one
-            # The last pair's ID will be reused for the new response
-            return InvalidatePairs(
+            # Invalidate all old entries except the last one
+            # The last entry's ID will be reused for the new response
+            return InvalidateEntries(
                 options=self.options,
-                pair_ids=[pair.id for pair in self.revalidating_pairs[:-1]],
+                entry_ids=[entry.id for entry in self.revalidating_entries[:-1]],
                 # After invalidation, attempt to cache the new response
                 next_state=CacheMiss(
                     request=self.original_request,
                     options=self.options,
                     after_revalidation=True,  # Mark that this occurred during revalidation
-                ).next(revalidation_response, pair_id=self.revalidating_pairs[-1].id),
+                ).next(
+                    revalidation_response,
+                ),
             )
 
         # ============================================================================
@@ -2045,43 +2041,32 @@ class NeedRevalidation(State):
         elif revalidation_response.status_code // 100 == 5:
             # Same as 2xx: invalidate old responses and store the error response
             # This ensures clients see the error rather than potentially stale data
-            return InvalidatePairs(
+            return InvalidateEntries(
                 options=self.options,
-                pair_ids=[pair.id for pair in self.revalidating_pairs[:-1]],
+                entry_ids=[entry.id for entry in self.revalidating_entries[:-1]],
                 next_state=CacheMiss(
                     request=self.original_request,
                     options=self.options,
                     after_revalidation=True,
-                ).next(revalidation_response, pair_id=self.revalidating_pairs[-1].id),
-            )
-        elif revalidation_response.status_code // 100 == 3:
-            # 3xx Redirects should have been followed by the HTTP client
-            return FromCache(
-                pair=replace(
-                    self.revalidating_pairs[-1],
-                    response=revalidation_response,
+                ).next(
+                    revalidation_response,
                 ),
-                options=self.options,
             )
-
-        # ============================================================================
-        # STEP 4: Handle Unexpected Status Codes
-        # ============================================================================
-        # This should not happen in normal operation. Valid revalidation responses are:
-        # - 304 Not Modified
-        # - 2xx Success (typically 200 OK)
-        # - 5xx Server Error
-        #
-        # Other status codes (1xx, 3xx, 4xx) are unexpected during revalidation.
-        # 3xx redirects should have been followed by the HTTP client.
-        # 4xx errors (except 404) are unusual during revalidation.
-        raise RuntimeError(
-            f"Unexpected response status code during revalidation: {revalidation_response.status_code}"
-        )  # pragma: nocover
+        else:
+            # ============================================================================
+            # STEP 4: Handle Unexpected Status Codes
+            # ============================================================================
+            # RFC 9111 does not define behavior for other status codes in this context.
+            # In practice, we need to forward any unexpected responses to the client.
+            return CacheMiss(
+                request=self.revalidating_entries[-1].request,
+                options=self.options,
+                after_revalidation=True,
+            ).next(revalidation_response)
 
     def freshening_stored_responses(
         self, revalidation_response: Response
-    ) -> "NeedToBeUpdated" | "InvalidatePairs" | "CacheMiss":
+    ) -> "NeedToBeUpdated" | "InvalidateEntries" | "CacheMiss":
         """
         Freshens cached responses after receiving a 304 Not Modified response.
 
@@ -2104,9 +2089,9 @@ class NeedRevalidation(State):
 
         Returns:
         -------
-        Union[NeedToBeUpdated, InvalidatePairs, CacheMiss]
+        Union[NeedToBeUpdated, InvalidateEntries, CacheMiss]
             - NeedToBeUpdated: When matching responses are found and updated
-            - InvalidatePairs: Wraps NeedToBeUpdated if non-matching responses exist
+            - InvalidateEntries: Wraps NeedToBeUpdated if non-matching responses exist
             - CacheMiss: When no matching responses are found
 
         RFC 9111 Compliance:
@@ -2167,7 +2152,7 @@ class NeedRevalidation(State):
         # Priority 2: Last-Modified timestamp
         # Priority 3: Single response assumption
 
-        identified_for_revalidation: list[CompletePair]
+        identified_for_revalidation: list[Entry]
 
         # MATCHING STRATEGY 1: Strong ETag
         # RFC 9110 Section 8.8.3: ETag
@@ -2187,7 +2172,7 @@ class NeedRevalidation(State):
             # Found a strong ETag in the 304 response
             # Partition cached responses: matching vs non-matching ETags
             identified_for_revalidation, need_to_be_invalidated = partition(
-                self.revalidating_pairs,
+                self.revalidating_entries,
                 lambda pair: pair.response.headers.get("etag") == revalidation_response.headers.get("etag"),  # type: ignore[no-untyped-call]
             )
 
@@ -2205,7 +2190,7 @@ class NeedRevalidation(State):
             # Found Last-Modified in the 304 response
             # Partition cached responses: matching vs non-matching timestamps
             identified_for_revalidation, need_to_be_invalidated = partition(
-                self.revalidating_pairs,
+                self.revalidating_entries,
                 lambda pair: pair.response.headers.get("last-modified")
                 == revalidation_response.headers.get("last-modified"),  # type: ignore[no-untyped-call]
             )
@@ -2219,14 +2204,20 @@ class NeedRevalidation(State):
         # we can safely assume that single response is the one being confirmed.
         # This handles cases where the server doesn't return validators in the 304.
         else:
-            if len(self.revalidating_pairs) == 1:
+            if len(self.revalidating_entries) == 1:
                 # Only one cached response - it must be the matching one
-                identified_for_revalidation, need_to_be_invalidated = [self.revalidating_pairs[0]], []
+                identified_for_revalidation, need_to_be_invalidated = (
+                    [self.revalidating_entries[0]],
+                    [],
+                )
             else:
                 # Multiple cached responses but no validators to match them
                 # We cannot determine which (if any) are valid
                 # Conservative approach: invalidate all of them
-                identified_for_revalidation, need_to_be_invalidated = [], self.revalidating_pairs
+                identified_for_revalidation, need_to_be_invalidated = (
+                    [],
+                    self.revalidating_entries,
+                )
 
         # ============================================================================
         # STEP 2: Update Matching Responses or Create Cache Miss
@@ -2251,7 +2242,7 @@ class NeedRevalidation(State):
             # while excluding certain headers that shouldn't be updated
             # (Content-Encoding, Content-Type, Content-Range).
             next_state = NeedToBeUpdated(
-                updating_pairs=[
+                updating_entries=[
                     replace(
                         pair,
                         response=refresh_response_headers(pair.response, revalidation_response),
@@ -2285,9 +2276,9 @@ class NeedRevalidation(State):
 
         if need_to_be_invalidated:
             # Wrap the next state in an invalidation operation
-            return InvalidatePairs(
+            return InvalidateEntries(
                 options=self.options,
-                pair_ids=[pair.id for pair in need_to_be_invalidated],
+                entry_ids=[entry.id for entry in need_to_be_invalidated],
                 next_state=next_state,
             )
 
@@ -2295,28 +2286,12 @@ class NeedRevalidation(State):
         return next_state
 
 
-# @dataclass
-# class StoreAndUse(State):
-#     """
-#     The state that indicates that the response can be stored in the cache and used.
-#     """
-
-#     pair_id: uuid.UUID
-
-#     response: Response
-
-#     def next(self) -> None:
-#         return None  # pragma: nocover
-
-
 class StoreAndUse(State):
     """
     The state that indicates that the response can be stored in the cache and used.
 
     Attributes:
     ----------
-    pair_id : uuid.UUID
-        The unique identifier for the cache pair.
     response : Response
         The HTTP response to be stored in the cache.
     after_revalidation : bool
@@ -2324,16 +2299,17 @@ class StoreAndUse(State):
     """
 
     def __init__(
-        self, pair_id: uuid.UUID, response: Response, options: CacheOptions, after_revalidation: bool = False
+        self,
+        response: Response,
+        options: CacheOptions,
+        after_revalidation: bool = False,
     ) -> None:
         super().__init__(options)
-        self.pair_id = pair_id
         self.response = response
         self.after_revalidation = after_revalidation
         response_meta = ResponseMetadata(
             hishel_created_at=time.time(),
             hishel_from_cache=False,
-            hishel_spec_ignored=False,
             hishel_revalidated=after_revalidation,
             hishel_stored=True,
         )
@@ -2372,15 +2348,16 @@ class CouldNotBeStored(State):
     """
 
     def __init__(
-        self, response: Response, pair_id: uuid.UUID, options: CacheOptions, after_revalidation: bool = False
+        self,
+        response: Response,
+        options: CacheOptions,
+        after_revalidation: bool = False,
     ) -> None:
         super().__init__(options)
         self.response = response
-        self.pair_id = pair_id
         response_meta = ResponseMetadata(
             hishel_created_at=time.time(),
             hishel_from_cache=False,
-            hishel_spec_ignored=False,
             hishel_revalidated=after_revalidation,
             hishel_stored=False,
         )
@@ -2391,12 +2368,12 @@ class CouldNotBeStored(State):
 
 
 @dataclass
-class InvalidatePairs(State):
+class InvalidateEntries(State):
     """
-    The state that represents the deletion of cache pairs.
+    The state that represents the deletion of cache entries.
     """
 
-    pair_ids: list[uuid.UUID]
+    entry_ids: list[uuid.UUID]
 
     next_state: AnyState
 
@@ -2405,18 +2382,22 @@ class InvalidatePairs(State):
 
 
 class FromCache(State):
-    def __init__(self, pair: CompletePair, options: CacheOptions, after_revalidation: bool = False) -> None:
+    def __init__(
+        self,
+        entry: Entry,
+        options: CacheOptions,
+        after_revalidation: bool = False,
+    ) -> None:
         super().__init__(options)
-        self.pair = pair
+        self.entry = entry
         self.after_revalidation = after_revalidation
         response_meta = ResponseMetadata(
-            hishel_created_at=pair.meta.created_at,
+            hishel_created_at=entry.meta.created_at,
             hishel_from_cache=True,
-            hishel_spec_ignored=False,
             hishel_revalidated=after_revalidation,
             hishel_stored=False,
         )
-        self.pair.response.metadata.update(response_meta)  # type: ignore
+        self.entry.response.metadata.update(response_meta)  # type: ignore
 
     def next(self) -> None:
         return None
@@ -2424,8 +2405,8 @@ class FromCache(State):
 
 @dataclass
 class NeedToBeUpdated(State):
-    updating_pairs: list[CompletePair]
+    updating_entries: list[Entry]
     original_request: Request
 
     def next(self) -> FromCache:
-        return FromCache(pair=self.updating_pairs[-1], options=self.options)  # pragma: nocover
+        return FromCache(entry=self.updating_entries[-1], options=self.options)

hishel/_core/_storages/_async_base.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import abc
+import time
+import typing as tp
+import uuid
+
+from ..models import Entry, Request, Response
+
+
+class AsyncBaseStorage(abc.ABC):
+    @abc.abstractmethod
+    async def create_entry(self, request: Request, response: Response, key: str, id_: uuid.UUID | None = None) -> Entry:
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    async def get_entries(self, key: str) -> tp.List[Entry]:
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    async def update_entry(
+        self,
+        id: uuid.UUID,
+        new_entry: tp.Union[Entry, tp.Callable[[Entry], Entry]],
+    ) -> tp.Optional[Entry]:
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    async def remove_entry(self, id: uuid.UUID) -> None:
+        raise NotImplementedError()
+
+    async def close(self) -> None:
+        pass
+
+    def is_soft_deleted(self, pair: Entry) -> bool:
+        """
+        Check if a pair is soft deleted based on its metadata.
+
+        Args:
+            pair: The request pair to check.
+
+        Returns:
+            True if the pair is soft deleted, False otherwise.
+        """
+        return pair.meta.deleted_at is not None and pair.meta.deleted_at > 0
+
+    def is_safe_to_hard_delete(self, pair: Entry) -> bool:
+        """
+        Check if a pair is safe to hard delete based on its metadata.
+
+        If the pair has been soft deleted for more than 1 hour, it is considered safe to hard delete.
+
+        Args:
+            pair: The request pair to check.
+
+        Returns:
+            True if the pair is safe to hard delete, False otherwise.
+        """
+        return bool(pair.meta.deleted_at is not None and (pair.meta.deleted_at + 3600 < time.time()))
+
+    def mark_pair_as_deleted(self, pair: Entry) -> Entry:
+        """
+        Mark a pair as soft deleted by setting its deleted_at timestamp.
+
+        Args:
+            pair: The request pair to mark as deleted.
+        Returns:
+            The updated request pair with the deleted_at timestamp set.
+        """
+        pair.meta.deleted_at = time.time()
+        return pair