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

hishel/__init__.py

@@ -15,17 +15,20 @@ from hishel._core._spec import (
     NeedToBeUpdated as NeedToBeUpdated,
     State as State,
     StoreAndUse as StoreAndUse,
-    create_idle_state as create_idle_state,
 )
 from hishel._core.models import (
     Entry as Entry,
     EntryMeta as EntryMeta,
     Request as Request,
-    Response,
+    Response as Response,
+    ResponseMetadata as ResponseMetadata,
+    RequestMetadata as RequestMetadata,
 )
 from hishel._async_cache import AsyncCacheProxy as AsyncCacheProxy
 from hishel._sync_cache import SyncCacheProxy as SyncCacheProxy
 
+from hishel._policies import SpecificationPolicy, FilterPolicy, CachePolicy
+
 __all__ = (
     # New API
     ## States
@@ -41,12 +44,13 @@ __all__ = (
     "StoreAndUse",
     "CouldNotBeStored",
     "InvalidateEntries",
-    "create_idle_state",
     ## Models
     "Request",
     "Response",
     "Entry",
     "EntryMeta",
+    "RequestMetadata",
+    "ResponseMetadata",
     ## Headers
     "Headers",
     ## Storages
@@ -57,4 +61,8 @@ __all__ = (
     # Proxy
     "AsyncCacheProxy",
     "SyncCacheProxy",
+    # Policies
+    "CachePolicy",
+    "SpecificationPolicy",
+    "FilterPolicy",
 )

hishel/_async_cache.py

@@ -13,7 +13,6 @@ from hishel import (
     AsyncBaseStorage,
     AsyncSqliteStorage,
     CacheMiss,
-    CacheOptions,
     CouldNotBeStored,
     FromCache,
     IdleClient,
@@ -22,10 +21,10 @@ from hishel import (
     Request,
     Response,
     StoreAndUse,
-    create_idle_state,
 )
 from hishel._core._spec import InvalidateEntries, vary_headers_match
 from hishel._core.models import Entry, ResponseMetadata
+from hishel._policies import CachePolicy, FilterPolicy, SpecificationPolicy
 from hishel._utils import make_async_iterator
 
 logger = logging.getLogger("hishel.integrations.clients")
@@ -37,87 +36,121 @@ class AsyncCacheProxy:
 
     This class is independent of any specific HTTP library and works only with internal models.
     It delegates request execution to a user-provided callable, making it compatible with any
-    HTTP client. Caching behavior can be configured to either fully respect HTTP
-    caching rules or bypass them entirely.
+    HTTP client. Caching behavior is determined by the policy object.
+
+    Args:
+        request_sender: Callable that sends HTTP requests and returns responses.
+        storage: Storage backend for cache entries. Defaults to AsyncSqliteStorage.
+        policy: Caching policy to use. Can be SpecificationPolicy (respects RFC 9111) or
+            FilterPolicy (user-defined filtering). Defaults to SpecificationPolicy().
     """
 
     def __init__(
         self,
         request_sender: Callable[[Request], Awaitable[Response]],
         storage: AsyncBaseStorage | None = None,
-        cache_options: CacheOptions | None = None,
-        ignore_specification: bool = False,
+        policy: CachePolicy | None = None,
     ) -> None:
         self.send_request = request_sender
         self.storage = storage if storage is not None else AsyncSqliteStorage()
-        self.cache_options = cache_options if cache_options is not None else CacheOptions()
-        self.ignore_specification = ignore_specification
+        self.policy = policy if policy is not None else SpecificationPolicy()
 
     async def handle_request(self, request: Request) -> Response:
-        if self.ignore_specification or request.metadata.get("hishel_spec_ignore"):
-            return await self._handle_request_ignoring_spec(request)
+        if isinstance(self.policy, FilterPolicy):
+            return await self._handle_request_with_filters(request)
         return await self._handle_request_respecting_spec(request)
 
     async def _get_key_for_request(self, request: Request) -> str:
-        if request.metadata.get("hishel_body_key"):
+        if self.policy.use_body_key or request.metadata.get("hishel_body_key"):
             assert isinstance(request.stream, (AsyncIterator, AsyncIterable))
             collected = b"".join([chunk async for chunk in request.stream])
             hash_ = hashlib.sha256(collected).hexdigest()
             request.stream = make_async_iterator([collected])
-            return f"{str(request.url)}-{hash_}"
+            return hash_
         return hashlib.sha256(str(request.url).encode("utf-8")).hexdigest()
 
-    async def _maybe_refresh_pair_ttl(self, pair: Entry) -> None:
-        if pair.request.metadata.get("hishel_refresh_ttl_on_access"):
+    async def _maybe_refresh_entry_ttl(self, entry: Entry) -> None:
+        if entry.request.metadata.get("hishel_refresh_ttl_on_access"):
             await self.storage.update_entry(
-                pair.id,
-                lambda complete_pair: replace(
-                    complete_pair,
-                    meta=replace(complete_pair.meta, created_at=time.time()),
+                entry.id,
+                lambda current_entry: replace(
+                    current_entry,
+                    meta=replace(current_entry.meta, created_at=time.time()),
                 ),
             )
 
-    async def _handle_request_ignoring_spec(self, request: Request) -> Response:
+    async def _handle_request_with_filters(self, request: Request) -> Response:
+        assert isinstance(self.policy, FilterPolicy)
+
+        for request_filter in self.policy.request_filters:
+            if request_filter.needs_body():
+                body = await request.aread()
+                if not request_filter.apply(request, body):
+                    logger.debug("Request filtered out by request filter")
+                    return await self.send_request(request)
+            else:
+                if not request_filter.apply(request, None):
+                    logger.debug("Request filtered out by request filter")
+                    return await self.send_request(request)
+
         logger.debug("Trying to get cached response ignoring specification")
-        entries = await self.storage.get_entries(await self._get_key_for_request(request))
+        cache_key = await self._get_key_for_request(request)
+        entries = await self.storage.get_entries(cache_key)
 
         logger.debug(f"Found {len(entries)} cached entries for the request")
 
-        for pair in entries:
+        for entry in entries:
             if (
-                str(pair.request.url) == str(request.url)
-                and pair.request.method == request.method
+                str(entry.request.url) == str(request.url)
+                and entry.request.method == request.method
                 and vary_headers_match(
                     request,
-                    pair,
+                    entry,
                 )
             ):
                 logger.debug(
                     "Found matching cached response for the request",
                 )
                 response_meta = ResponseMetadata(
-                    hishel_spec_ignored=True,
                     hishel_from_cache=True,
-                    hishel_created_at=pair.meta.created_at,
+                    hishel_created_at=entry.meta.created_at,
                     hishel_revalidated=False,
                     hishel_stored=False,
                 )
-                pair.response.metadata.update(response_meta)  # type: ignore
-                await self._maybe_refresh_pair_ttl(pair)
-                return pair.response
+                entry.response.metadata.update(response_meta)  # type: ignore
+                await self._maybe_refresh_entry_ttl(entry)
+                return entry.response
 
         response = await self.send_request(request)
+        for response_filter in self.policy.response_filters:
+            if response_filter.needs_body():
+                body = await response.aread()
+                if not response_filter.apply(response, body):
+                    logger.debug("Response filtered out by response filter")
+                    return response
+            else:
+                if not response_filter.apply(response, None):
+                    logger.debug("Response filtered out by response filter")
+                    return response
+        response_meta = ResponseMetadata(
+            hishel_from_cache=False,
+            hishel_created_at=time.time(),
+            hishel_revalidated=False,
+            hishel_stored=True,
+        )
+        response.metadata.update(response_meta)  # type: ignore
 
         logger.debug("Storing response in cache ignoring specification")
         entry = await self.storage.create_entry(
             request,
             response,
-            await self._get_key_for_request(request),
+            cache_key,
         )
         return entry.response
 
     async def _handle_request_respecting_spec(self, request: Request) -> Response:
-        state: AnyState = create_idle_state("client", self.cache_options)
+        assert isinstance(self.policy, SpecificationPolicy)
+        state: AnyState = IdleClient(options=self.policy.cache_options)
 
         while state:
             logger.debug(f"Handling state: {state.__class__.__name__}")
@@ -132,8 +165,8 @@ class AsyncCacheProxy:
             elif isinstance(state, NeedRevalidation):
                 state = await self._handle_revalidation(state)
             elif isinstance(state, FromCache):
-                await self._maybe_refresh_pair_ttl(state.pair)
-                return state.pair.response
+                await self._maybe_refresh_entry_ttl(state.entry)
+                return state.entry.response
             elif isinstance(state, NeedToBeUpdated):
                 state = await self._handle_update(state)
             elif isinstance(state, InvalidateEntries):
@@ -152,12 +185,12 @@ class AsyncCacheProxy:
         return state.next(response)
 
     async def _handle_store_and_use(self, state: StoreAndUse, request: Request) -> Response:
-        complete_pair = await self.storage.create_entry(
+        entry = await self.storage.create_entry(
             request,
             state.response,
             await self._get_key_for_request(request),
         )
-        return complete_pair.response
+        return entry.response
 
     async def _handle_revalidation(self, state: NeedRevalidation) -> AnyState:
         revalidation_response = await self.send_request(state.request)
@@ -167,8 +200,8 @@ class AsyncCacheProxy:
         for entry in state.updating_entries:
             await self.storage.update_entry(
                 entry.id,
-                lambda complete_pair: replace(
-                    complete_pair,
+                lambda entry: replace(
+                    entry,
                     response=replace(entry.response, headers=entry.response.headers),
                 ),
             )

hishel/_async_httpx.py

@@ -14,11 +14,9 @@ from typing import (
 from httpx import RequestNotRead
 
 from hishel import AsyncCacheProxy, Headers, Request, Response
-from hishel._core._spec import (
-    CacheOptions,
-)
 from hishel._core._storages._async_base import AsyncBaseStorage
 from hishel._core.models import RequestMetadata, extract_metadata_from_headers
+from hishel._policies import CachePolicy
 from hishel._utils import (
     filter_mapping,
     make_async_iterator,
@@ -62,14 +60,14 @@ def _internal_to_httpx(
             method=value.method,
             url=value.url,
             headers=value.headers,
-            stream=_IteratorStream(value.aiter_stream()),
+            stream=_IteratorStream(value._aiter_stream()),
             extensions=value.metadata,
         )
     elif isinstance(value, Response):
         return httpx.Response(
             status_code=value.status_code,
             headers=value.headers,
-            stream=_IteratorStream(value.aiter_stream()),
+            stream=_IteratorStream(value._aiter_stream()),
             extensions=value.metadata,
         )
 
@@ -149,15 +147,13 @@ class AsyncCacheTransport(httpx.AsyncBaseTransport):
         self,
         next_transport: httpx.AsyncBaseTransport,
         storage: AsyncBaseStorage | None = None,
-        cache_options: CacheOptions | None = None,
-        ignore_specification: bool = False,
+        policy: CachePolicy | None = None,
     ) -> None:
         self.next_transport = next_transport
         self._cache_proxy: AsyncCacheProxy = AsyncCacheProxy(
             request_sender=self.request_sender,
             storage=storage,
-            cache_options=cache_options,
-            ignore_specification=ignore_specification,
+            policy=policy,
         )
         self.storage = self._cache_proxy.storage
 
@@ -184,8 +180,7 @@ class AsyncCacheTransport(httpx.AsyncBaseTransport):
 class AsyncCacheClient(httpx.AsyncClient):
     def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
         self.storage: AsyncBaseStorage | None = kwargs.pop("storage", None)
-        self.cache_options: CacheOptions | None = kwargs.pop("cache_options", None)
-        self.ignore_specification: bool = kwargs.pop("ignore_specification", False)
+        self.policy: CachePolicy | None = kwargs.pop("policy", None)
         super().__init__(*args, **kwargs)
 
     def _init_transport(
@@ -212,8 +207,7 @@ class AsyncCacheClient(httpx.AsyncClient):
                 limits=limits,
             ),
             storage=self.storage,
-            cache_options=self.cache_options,
-            ignore_specification=False,
+            policy=self.policy,
         )
 
     def _init_proxy_transport(
@@ -238,6 +232,5 @@ class AsyncCacheClient(httpx.AsyncClient):
                 proxy=proxy,
             ),
             storage=self.storage,
-            cache_options=self.cache_options,
-            ignore_specification=self.ignore_specification,
+            policy=self.policy,
         )

hishel/_core/_spec.py

@@ -9,7 +9,6 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Dict,
-    Literal,
     Optional,
     TypeVar,
     Union,
@@ -1128,12 +1127,6 @@ AnyState = Union[
 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):
     """
@@ -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,
@@ -1900,7 +1893,7 @@ class NeedRevalidation(State):
 
     def next(
         self, revalidation_response: Response
-    ) -> Union["NeedToBeUpdated", "InvalidateEntries", "CacheMiss", "FromCache"]:
+    ) -> Union["NeedToBeUpdated", "InvalidateEntries", "CacheMiss", "FromCache", "StoreAndUse", "CouldNotBeStored"]:
         """
         Handles the response to a conditional request and determines the next state.
 
@@ -2059,30 +2052,17 @@ class NeedRevalidation(State):
                     revalidation_response,
                 ),
             )
-        elif revalidation_response.status_code // 100 == 3:
-            # 3xx Redirects should have been followed by the HTTP client
-            return FromCache(
-                pair=replace(
-                    self.revalidating_entries[-1],
-                    response=revalidation_response,
-                ),
+        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,
-            )
-
-        # ============================================================================
-        # 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
+                after_revalidation=True,
+            ).next(revalidation_response)
 
     def freshening_stored_responses(
         self, revalidation_response: Response
@@ -2330,7 +2310,6 @@ class StoreAndUse(State):
         response_meta = ResponseMetadata(
             hishel_created_at=time.time(),
             hishel_from_cache=False,
-            hishel_spec_ignored=False,
             hishel_revalidated=after_revalidation,
             hishel_stored=True,
         )
@@ -2379,7 +2358,6 @@ class CouldNotBeStored(State):
         response_meta = ResponseMetadata(
             hishel_created_at=time.time(),
             hishel_from_cache=False,
-            hishel_spec_ignored=False,
             hishel_revalidated=after_revalidation,
             hishel_stored=False,
         )
@@ -2406,21 +2384,20 @@ class InvalidateEntries(State):
 class FromCache(State):
     def __init__(
         self,
-        pair: Entry,
+        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
@@ -2432,4 +2409,4 @@ class NeedToBeUpdated(State):
     original_request: Request
 
     def next(self) -> FromCache:
-        return FromCache(pair=self.updating_entries[-1], options=self.options)  # pragma: nocover
+        return FromCache(entry=self.updating_entries[-1], options=self.options)

hishel/_core/_storages/_async_sqlite.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import time
 import uuid
 from dataclasses import replace
+from pathlib import Path
 from typing import (
     Any,
     AsyncIterable,
@@ -46,10 +47,12 @@ try:
             default_ttl: Optional[float] = None,
             refresh_ttl_on_access: bool = True,
         ) -> None:
-            base_path = ensure_cache_dict()
+            db_path = Path(database_path)
 
             self.connection = connection
-            self.database_path = base_path / database_path
+            self.database_path = (
+                ensure_cache_dict(db_path.parent if db_path.parent != Path(".") else None) / db_path.name
+            )
             self.default_ttl = default_ttl
             self.refresh_ttl_on_access = refresh_ttl_on_access
             self.last_cleanup = time.time() - BATCH_CLEANUP_INTERVAL + BATCH_CLEANUP_START_DELAY

hishel/_core/_storages/_sync_sqlite.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import time
 import uuid
 from dataclasses import replace
+from pathlib import Path
 from typing import (
     Any,
     Iterable,
@@ -46,10 +47,12 @@ try:
             default_ttl: Optional[float] = None,
             refresh_ttl_on_access: bool = True,
         ) -> None:
-            base_path = ensure_cache_dict()
+            db_path = Path(database_path)
 
             self.connection = connection
-            self.database_path = base_path / database_path
+            self.database_path = (
+                ensure_cache_dict(db_path.parent if db_path.parent != Path(".") else None) / db_path.name
+            )
             self.default_ttl = default_ttl
             self.refresh_ttl_on_access = refresh_ttl_on_access
             self.last_cleanup = time.time() - BATCH_CLEANUP_INTERVAL + BATCH_CLEANUP_START_DELAY

hishel/_core/models.py

@@ -5,14 +5,18 @@ import uuid
 from dataclasses import dataclass, field
 from typing import (
     Any,
+    AsyncIterable,
     AsyncIterator,
+    Iterable,
     Iterator,
     Mapping,
     Optional,
     TypedDict,
+    cast,
 )
 
 from hishel._core._headers import Headers
+from hishel._utils import make_async_iterator, make_sync_iterator
 
 
 class AnyIterable:
@@ -96,18 +100,56 @@ class Request:
     stream: Iterator[bytes] | AsyncIterator[bytes] = field(default_factory=lambda: iter(AnyIterable()))
     metadata: RequestMetadata | Mapping[str, Any] = field(default_factory=dict)
 
-    def iter_stream(self) -> Iterator[bytes]:
-        if isinstance(self.stream, Iterator):
-            return self.stream
+    def _iter_stream(self) -> Iterator[bytes]:
+        if hasattr(self, "collected_body"):
+            yield getattr(self, "collected_body")
+            return
+        if isinstance(self.stream, (Iterator, Iterable)):
+            yield from self.stream
+            return
         raise TypeError("Request stream is not an Iterator")
 
-    async def aiter_stream(self) -> AsyncIterator[bytes]:
-        if isinstance(self.stream, AsyncIterator):
+    async def _aiter_stream(self) -> AsyncIterator[bytes]:
+        if hasattr(self, "collected_body"):
+            yield getattr(self, "collected_body")
+            return
+        if isinstance(self.stream, (AsyncIterator, AsyncIterable)):
             async for chunk in self.stream:
                 yield chunk
+            return
         else:
             raise TypeError("Request stream is not an AsyncIterator")
 
+    def read(self) -> bytes:
+        """
+        Synchronously reads the entire request body without consuming the stream.
+        """
+        if not isinstance(self.stream, Iterator):
+            raise TypeError("Request stream is not an Iterator")
+
+        if hasattr(self, "collected_body"):
+            return cast(bytes, getattr(self, "collected_body"))
+
+        collected = b"".join([chunk for chunk in self.stream])
+        setattr(self, "collected_body", collected)
+        self.stream = make_sync_iterator([collected])
+        return collected
+
+    async def aread(self) -> bytes:
+        """
+        Asynchronously reads the entire request body without consuming the stream.
+        """
+        if not isinstance(self.stream, AsyncIterator):
+            raise TypeError("Request stream is not an AsyncIterator")
+
+        if hasattr(self, "collected_body"):
+            return cast(bytes, getattr(self, "collected_body"))
+
+        collected = b"".join([chunk async for chunk in self.stream])
+        setattr(self, "collected_body", collected)
+        self.stream = make_async_iterator([collected])
+        return collected
+
 
 class ResponseMetadata(TypedDict, total=False):
     # All the names here should be prefixed with "hishel_" to avoid collisions with user data
@@ -117,9 +159,6 @@ class ResponseMetadata(TypedDict, total=False):
     hishel_revalidated: bool
     """Indicates whether the response was revalidated with the origin server."""
 
-    hishel_spec_ignored: bool
-    """Indicates whether the caching specification was ignored for this response."""
-
     hishel_stored: bool
     """Indicates whether the response was stored in cache."""
 
@@ -134,18 +173,55 @@ class Response:
     stream: Iterator[bytes] | AsyncIterator[bytes] = field(default_factory=lambda: iter(AnyIterable()))
     metadata: ResponseMetadata | Mapping[str, Any] = field(default_factory=dict)
 
-    def iter_stream(self) -> Iterator[bytes]:
+    def _iter_stream(self) -> Iterator[bytes]:
+        if hasattr(self, "collected_body"):
+            yield getattr(self, "collected_body")
+            return
         if isinstance(self.stream, Iterator):
-            return self.stream
+            yield from self.stream
+            return
         raise TypeError("Response stream is not an Iterator")
 
-    async def aiter_stream(self) -> AsyncIterator[bytes]:
+    async def _aiter_stream(self) -> AsyncIterator[bytes]:
+        if hasattr(self, "collected_body"):
+            yield getattr(self, "collected_body")
+            return
         if isinstance(self.stream, AsyncIterator):
             async for chunk in self.stream:
                 yield chunk
         else:
             raise TypeError("Response stream is not an AsyncIterator")
 
+    def read(self) -> bytes:
+        """
+        Synchronously reads the entire request body without consuming the stream.
+        """
+        if not isinstance(self.stream, Iterator):
+            raise TypeError("Request stream is not an Iterator")
+
+        if hasattr(self, "collected_body"):
+            return cast(bytes, getattr(self, "collected_body"))
+
+        collected = b"".join([chunk for chunk in self.stream])
+        setattr(self, "collected_body", collected)
+        self.stream = make_sync_iterator([collected])
+        return collected
+
+    async def aread(self) -> bytes:
+        """
+        Asynchronously reads the entire request body without consuming the stream.
+        """
+        if not isinstance(self.stream, AsyncIterator):
+            raise TypeError("Request stream is not an AsyncIterator")
+
+        if hasattr(self, "collected_body"):
+            return cast(bytes, getattr(self, "collected_body"))
+
+        collected = b"".join([chunk async for chunk in self.stream])
+        setattr(self, "collected_body", collected)
+        self.stream = make_async_iterator([collected])
+        return collected
+
 
 @dataclass
 class EntryMeta: