hishel 0.1.5__py3-none-any.whl → 1.0.0b1__py3-none-any.whl

hishel/{beta/_core → _core}/_spec.py

@@ -9,17 +9,17 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Dict,
-    Literal,
     Optional,
     TypeVar,
     Union,
 )
 
+from hishel._core._headers import Headers, Range, Vary, parse_cache_control
+from hishel._core.models import ResponseMetadata
 from hishel._utils import parse_date, partition
-from hishel.beta._core._headers import Headers, Range, Vary, parse_cache_control
 
 if TYPE_CHECKING:
-    from hishel.beta import CompletePair, Request, Response
+    from hishel import Entry, Request, Response
 
 
 TState = TypeVar("TState", bound="State")
@@ -41,9 +41,96 @@ logger = logging.getLogger("hishel.core.spec")
 
 @dataclass
 class CacheOptions:
+    """
+    Configuration options for HTTP cache behavior.
+
+    These options control how the cache interprets and applies RFC 9111 caching rules.
+    All options have sensible defaults that follow the specification.
+
+    Attributes:
+    ----------
+    shared : bool
+        Determines whether the cache operates as a shared cache or private cache.
+
+        RFC 9111 Section 3.5: Authenticated Responses
+        https://www.rfc-editor.org/rfc/rfc9111.html#section-3.5
+
+        - Shared cache (True): Acts as a proxy, CDN, or gateway cache serving multiple users.
+          Must respect private directives and Authorization header restrictions.
+          Can use s-maxage directive instead of max-age for shared-specific freshness.
+
+        - Private cache (False): Acts as a browser or user-agent cache for a single user.
+          Can cache private responses and ignore s-maxage directives.
+
+        Default: True (shared cache)
+
+        Examples:
+        --------
+        >>> # Shared cache (proxy/CDN)
+        >>> options = CacheOptions(shared=True)
+
+        >>> # Private cache (browser)
+        >>> options = CacheOptions(shared=False)
+
+    supported_methods : list[str]
+        HTTP methods that are allowed to be cached by this cache implementation.
+
+        RFC 9111 Section 3, paragraph 2.1:
+        https://www.rfc-editor.org/rfc/rfc9111.html#section-3-2.1.1
+
+        "A cache MUST NOT store a response to a request unless:
+         - the request method is understood by the cache"
+
+        Default: ["GET", "HEAD"] (most commonly cached methods)
+
+        Examples:
+        --------
+        >>> # Default: cache GET and HEAD only
+        >>> options = CacheOptions()
+        >>> options.supported_methods
+        ['GET', 'HEAD']
+
+        >>> # Cache POST responses (advanced use case)
+        >>> options = CacheOptions(supported_methods=["GET", "HEAD", "POST"])
+
+    allow_stale : bool
+        Controls whether stale responses can be served without revalidation.
+
+        RFC 9111 Section 4.2.4: Serving Stale Responses
+        https://www.rfc-editor.org/rfc/rfc9111.html#section-4.2.4
+
+        "A cache MUST NOT generate a stale response unless it is disconnected or
+        doing so is explicitly permitted by the client or origin server (e.g., by
+        the max-stale request directive in Section 5.2.1, extension directives
+        such as those defined in [RFC5861], or configuration in accordance with
+        an out-of-band contract)."
+
+        Default: False (no stale responses)
+
+        Examples:
+        --------
+        >>> # Conservative: never serve stale
+        >>> options = CacheOptions(allow_stale=False)
+
+        >>> # Permissive: serve stale when allowed
+        >>> options = CacheOptions(allow_stale=True)
+
+        >>> # Stale-while-revalidate pattern (RFC 5861)
+        >>> # Even with allow_stale=True, directives are respected
+        >>> options = CacheOptions(allow_stale=True)
+    """
+
     shared: bool = True
+    """
+    When True, the cache operates as a shared cache (proxy/CDN).
+    When False, as a private cache (browser).
+    """
+
     supported_methods: list[str] = field(default_factory=lambda: ["GET", "HEAD"])
+    """HTTP methods that are allowed to be cached."""
+
     allow_stale: bool = False
+    """When True, stale responses can be served without revalidation."""
 
 
 @dataclass
@@ -57,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.
@@ -73,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:
     -------
@@ -107,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
@@ -154,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
@@ -1033,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):
     """
@@ -1079,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.
@@ -1092,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:
         -------
@@ -1229,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
 
@@ -1244,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.
 
@@ -1273,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]
         ]
 
@@ -1325,18 +1406,13 @@ class IdleClient(State):
             #
             # The Age header informs the client how old the cached response is.
 
-            # Mark all ready-to-use responses with metadata (for observability)
-            for pair in ready_to_use:
-                pair.response.metadata["hishel_from_cache"] = True  # type: ignore
-
             # Use the most recent response (first in sorted list)
             selected_pair = ready_to_use[0]
 
             # 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,
@@ -1372,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,
             )
@@ -1442,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.
 
@@ -1491,20 +1567,6 @@ class CacheMiss(State):
            * an s-maxage response directive (if cache is shared)
            * a status code that is defined as heuristically cacheable"
 
-        Side Effects:
-        ------------
-        Sets metadata flags on the response object:
-        - hishel_spec_ignored: False (caching spec is being followed)
-        - hishel_from_cache: False (response is from origin, not cache)
-        - hishel_revalidated: True (if after_revalidation is True)
-        - hishel_stored: True/False (whether response was stored)
-
-        Logging:
-        -------
-        When a response cannot be stored, detailed debug logs are emitted explaining
-        which specific RFC requirement failed, with direct links to the relevant
-        RFC sections.
-
         Examples:
         --------
         >>> # Cacheable response
@@ -1513,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
 
@@ -1522,26 +1584,11 @@ 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
         """
 
-        # ============================================================================
-        # STEP 1: Set Response Metadata
-        # ============================================================================
-        # Initialize metadata flags to track the response lifecycle
-
-        response.metadata["hishel_spec_ignored"] = False  # type: ignore
-        # We are following the caching specification
-
-        response.metadata["hishel_from_cache"] = False  # type: ignore
-        # This response came from origin server, not cache
-
-        if self.after_revalidation:
-            response.metadata["hishel_revalidated"] = True  # type: ignore
-            # Mark that this response is the result of a revalidation
-
         # ============================================================================
         # STEP 2: Parse Cache-Control Directive
         # ============================================================================
@@ -1636,11 +1683,14 @@ class CacheMiss(State):
         #
         # Requests with Authorization headers often contain user-specific data.
         # Shared caches must be careful not to serve one user's data to another.
-        #
-        # This check is inverted in the current implementation and needs review:
-        # TODO: Fix logic - should be: (not shared) OR (no auth header) OR (has explicit directive)
-        # Current logic: (shared) AND (no auth header)
-        is_shared_and_authorized = not (self.options.shared and "authorization" in request.headers)
+        has_explicit_directive = (
+            response_cache_control.public
+            or response_cache_control.s_maxage is not None
+            or response_cache_control.must_revalidate
+        )
+        can_cache_auth_request = (
+            not self.options.shared or "authorization" not in request.headers or has_explicit_directive
+        )
 
         # CONDITION 7: Response Contains Required Caching Information
         # RFC 9111 Section 3, paragraph 2.7:
@@ -1710,7 +1760,7 @@ class CacheMiss(State):
             or not understands_how_to_cache
             or not no_store_is_not_present
             or not private_directive_allows_storing
-            or not is_shared_and_authorized
+            or not can_cache_auth_request
             or not contains_required_component
         ):
             # --------------------------------------------------------------------
@@ -1746,10 +1796,11 @@ class CacheMiss(State):
                         "Cannot store the response because the `private` response directive does not "
                         "allow shared caches to store it. See: https://www.rfc-editor.org/rfc/rfc9111.html#section-3-2.5.1"
                     )
-                elif not is_shared_and_authorized:
+                elif not can_cache_auth_request:
                     logger.debug(
-                        "Cannot store the response because the cache is shared and the request contains "
-                        "an Authorization header field. See: https://www.rfc-editor.org/rfc/rfc9111.html#section-3-2.6.1"
+                        "Cannot store the response because the request contained an Authorization header "
+                        "and there was no explicit directive allowing shared caching. "
+                        "See: https://www.rfc-editor.org/rfc/rfc9111.html#section-3-5"
                     )
                 elif not contains_required_component:
                     logger.debug(
@@ -1757,10 +1808,11 @@ class CacheMiss(State):
                         "See: https://www.rfc-editor.org/rfc/rfc9111.html#section-3-2.7.1"
                     )
 
-            # Mark response as not stored
-            response.metadata["hishel_stored"] = False  # type: ignore
-
-            return CouldNotBeStored(response=response, pair_id=pair_id, options=self.options)
+            return CouldNotBeStored(
+                response=response,
+                options=self.options,
+                after_revalidation=self.after_revalidation,
+            )
 
         # --------------------------------------------------------------------
         # Transition to: StoreAndUse
@@ -1769,9 +1821,6 @@ class CacheMiss(State):
 
         logger.debug("Storing response in cache")
 
-        # Mark response as stored
-        response.metadata["hishel_stored"] = True  # type: ignore
-
         # Remove headers that should not be stored
         # RFC 9111 Section 3.1: Storing Header and Trailer Fields
         # https://www.rfc-editor.org/rfc/rfc9111.html#section-3.1
@@ -1779,9 +1828,9 @@ 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,
         )
 
 
@@ -1801,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:
@@ -1822,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
@@ -1837,12 +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"]:
+    def next(
+        self, revalidation_response: Response
+    ) -> Union["NeedToBeUpdated", "InvalidateEntries", "CacheMiss", "FromCache"]:
         """
         Handles the response to a conditional request and determines the next state.
 
@@ -1862,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:
@@ -1899,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"'}))
@@ -1910,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
         """
 
@@ -1949,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,
+                ),
             )
 
         # ============================================================================
@@ -1988,14 +2041,25 @@ 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),
+                ).next(
+                    revalidation_response,
+                ),
+            )
+        elif revalidation_response.status_code // 100 == 3:
+            # 3xx Redirects should have been followed by the HTTP client
+            return FromCache(
+                entry=replace(
+                    self.revalidating_entries[-1],
+                    response=revalidation_response,
+                ),
+                options=self.options,
             )
 
         # ============================================================================
@@ -2015,7 +2079,7 @@ class NeedRevalidation(State):
 
     def freshening_stored_responses(
         self, revalidation_response: Response
-    ) -> "NeedToBeUpdated" | "InvalidatePairs" | "CacheMiss":
+    ) -> "NeedToBeUpdated" | "InvalidateEntries" | "CacheMiss":
         """
         Freshens cached responses after receiving a 304 Not Modified response.
 
@@ -2038,9 +2102,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:
@@ -2101,7 +2165,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
@@ -2121,7 +2185,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]
             )
 
@@ -2139,7 +2203,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]
             )
@@ -2153,14 +2217,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
@@ -2185,7 +2255,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),
@@ -2219,9 +2289,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,
             )
 
@@ -2229,41 +2299,94 @@ 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
+    Attributes:
+    ----------
+    response : Response
+        The HTTP response to be stored in the cache.
+    after_revalidation : bool
+        Indicates if the storage is occurring after a revalidation process.
+    """
 
-    response: Response
+    def __init__(
+        self,
+        response: Response,
+        options: CacheOptions,
+        after_revalidation: bool = False,
+    ) -> None:
+        super().__init__(options)
+        self.response = response
+        self.after_revalidation = after_revalidation
+        response_meta = ResponseMetadata(
+            hishel_created_at=time.time(),
+            hishel_from_cache=False,
+            hishel_revalidated=after_revalidation,
+            hishel_stored=True,
+        )
+        self.response.metadata.update(response_meta)  # type: ignore
 
     def next(self) -> None:
-        return None  # pragma: nocover
+        return None
+
+
+# @dataclass
+# class CouldNotBeStored(State):
+#     """
+#     The state that indicates that the response could not be stored in the cache.
+#     """
+
+#     response: Response
+
+#     pair_id: uuid.UUID
+
+#     def next(self) -> None:
+#         return None  # pragma: nocover
 
 
-@dataclass
 class CouldNotBeStored(State):
     """
     The state that indicates that the response could not be stored in the cache.
-    """
 
-    response: Response
+    Attributes:
+    ----------
+    response : Response
+        The HTTP response that could not be stored.
+    pair_id : uuid.UUID
+        The unique identifier for the cache pair.
+    after_revalidation : bool
+        Indicates if the storage attempt occurred after a revalidation process.
+    """
 
-    pair_id: uuid.UUID
+    def __init__(
+        self,
+        response: Response,
+        options: CacheOptions,
+        after_revalidation: bool = False,
+    ) -> None:
+        super().__init__(options)
+        self.response = response
+        response_meta = ResponseMetadata(
+            hishel_created_at=time.time(),
+            hishel_from_cache=False,
+            hishel_revalidated=after_revalidation,
+            hishel_stored=False,
+        )
+        self.response.metadata.update(response_meta)  # type: ignore
 
     def next(self) -> None:
-        return None  # pragma: nocover
+        return None
 
 
 @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
 
@@ -2271,21 +2394,32 @@ class InvalidatePairs(State):
         return self.next_state
 
 
-@dataclass
 class FromCache(State):
-    pair: CompletePair
-    """
-    List of pairs that can be used to satisfy the request.
-    """
+    def __init__(
+        self,
+        entry: Entry,
+        options: CacheOptions,
+        after_revalidation: bool = False,
+    ) -> None:
+        super().__init__(options)
+        self.entry = entry
+        self.after_revalidation = after_revalidation
+        response_meta = ResponseMetadata(
+            hishel_created_at=entry.meta.created_at,
+            hishel_from_cache=True,
+            hishel_revalidated=after_revalidation,
+            hishel_stored=False,
+        )
+        self.entry.response.metadata.update(response_meta)  # type: ignore
 
     def next(self) -> None:
-        return None  # pragma: nocover
+        return None
 
 
 @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)